一個好的組件應該是什么樣的？

作者：阿里技術 2020-04-24 10:02:44

隨著”微前端“概念的不斷醞釀，越來越多的團隊開始將自己的業務處理為不同的組件，編排到一個業務頁面中去，因此對組件的維護將會變得越來越重要。對于大部分前端在組件開發上都會遇到的問題和痛點，本文將分享作者在組件開發上的一些思考以及應該如何維護自己的組件庫。

背景

19 年 6 月左右，我發布過一篇文章《Bit 初體驗》。在梳理這篇文章的過程中，我可以說深度體驗了一把 bit 所提出的概念和做法，就像一顆種子種在我的腦海中，一開始我覺得這東西沒什么。

我還記得我第一次與我的同事分享 bit 后，他說：

emm，雖然你講了這么多，但是我覺得好像沒有那么...有體感?

感覺沒什么卵用?

啊，emm，既然你說了，就像你說的。我覺得我們現在如果引入 bit 會不會對我們的日常工作帶來很多額外的工作量。

這種反應很正常，我是在 18 年初，就在 Vue 的官網見到過 bit ，當時我點進去大致瀏覽過一下。我當時的感受就是，沒什么卵用，無非就是 " 前端垂直領域的 git "。對國內的支持情況還不咋地，連一篇像樣的中文文檔都找不到。

在我們的團隊中一下子直接切換到 bit 的工作流，這確實不現實，在公司有那么多的基礎建設都不知道 bit 這么個玩意。

但是，bit 的做法和概念，卻是非常非常有價值和可以借鑒的!

所以，我想做一件事情，一步一步的把 bit 的玩法用我們熟悉的方式引入進來甚至有所延伸擴展，讓大家認同其中的好處和價值。

認識組件

隨著近些年”微前端“概念的不斷醞釀，越來越多的團隊開始著手將自己的業務處理為不同組件，然后通過一些微前端做法，編排到一個業務頁面中去。

那么對于組件的維護就會變得越來越重要。所以，先來看看現在大多數團隊是怎么維護組件的吧!

大庫型，Antd、Element 標準的大庫型
一次型，完全業務組件，用完一次再也不維護
高復用型，一看就應該單獨封裝以后給其他人用，比如：視頻播放器
項目融合型，與業務項目在一起，混合 store，不分你我

我暫時能想到的就這幾種類型的組件，如果你的團隊也在維護自己的一套組件庫，那么應該很容易理解我上面所說的。

我相信，既然這么做了，肯定有這么做的理由和好處，沒有人會閑著沒事找麻煩做不是，那么這些做法都有什么好處和痛點呢?我從幾個方面入手分別分析一下。

方便、快捷

組件嘛，當然是最快能跑起來，最方便能看到效果最好咯。就這點來講，還有什么比直接在業務項目里擼組件更快的方式嗎!?

現在用個展示的面板，立馬去 components 目錄擼一個。

數據?不是有 store 嗎?引入進來不就拿到數據了!

所見即所得，現在改完馬上看到頁面上的效果!無法反駁..

這么看確實開發這個組件是好快了，但是從整個業務需求實現來看，這么做真的是最快的嗎?如果這樣的做法是最快捷的，那為什么那么多團隊在強調沉淀、封裝、抽象呢?

其實很多組件當時看起來，這輩子就只可能用一次，不用封裝。可是往往交互稿過來的時候就會發現，這個樣式好像我在哪里見過。然后去各種業務項目里一頓翻，哇終于找到了，復制過來發現各種爆紅，定睛一看，store???

所以，聰明的團隊早已洞察這一切，讓我們把組件都維護到同一個地方，然后大家寫好文檔，用的時候從庫里面取就可以了，有 Bug 的話統一修復就是，棒 ??!

可維護性

于是乎，大家便如火如荼的開始的組件抽象，組件整改的浩大工程。

一開始，一般會有一個團隊中較為靠譜、能力突出的小伙子(嗯?怎么是我?)去把 Webpack、Babel、TypeScript、Sass\Less、目錄結構、單元測試結構、代碼規范、Review 規范、發布規范這些梳理好，然后寫一個標準的組件出來，最后再強調一下大家一定要按照規范認真維護組件，書寫文檔，編寫單元測試。

從維護性上來講，大家把組件都寫在一個庫里面，然后再用到的項目中直接引入，業務上的問題逐漸被分為組件問題還是項目問題，甚至有些需求可以用這個交互在組件庫中有相似的，用那個組件就可以了，來反駁產品和設計 ??。

就在大家用的不亦樂乎的時候，有一天發現，呀，我們的組件庫怎么打包出來有 10M 啊 ??!

然后找一個靠譜、能力突出的小伙子(沒錯又是我)就去查了下，這個庫是誰引入的?這個組件不是已經有一個了嗎?lodash 不是這么用的呀!這個組件是干什么的，怎么沒文檔?

面對上百個業務組件，只能感嘆一聲業務迭代的可真快啊。

所以，大庫維護固然有大庫維護的好處和適用場景，大家能夠有這樣的抽象思維已經是技術上的突破了，現在只是遇到了另外一個問題，解它!

組件大小、加載性能

接觸 Webpack 的一些周邊工具，比如 analyzer 很容易可找出具體是什么包”霸占“了這么多的流量。

發現原來組件包中還有一些個組件，看上去不應該放在大庫中進行維護，比如那種一次性組件，二次封裝型組件。

因為這種組件可能會引入一個很大的第三方依賴，比如視頻播放器、Banner Swiper 等。

對于這樣的組件，最好的處理方式應該是創建一個獨立的倉庫，封裝完善后，寫好 README，發布至內網 NPM，供業務項目使用。

But you know ，這樣做成本太高，如果有時間的話，我肯定.....balabala...(一般來說，如果你對程序員說一個更好的方案時，除非這個方案他有參與設計，否則大部分回復都是這樣 ??)

當然組件大小這方面也可以通過很多其他方式解決，比如：異步加載，NPM 引入，按需加載等等啦...那么，讓我們談談下面另外一個很重要、又很容易被忽略的部分吧。

組件說明及可索引性

老板，我們今年沉淀了組件 200+，其中有幾個組件寫的特別好，同時支撐了 20+ 項目。

哇，這么棒!來給我看看你們寫的組件長什么樣?啊，這，這樣來看看我們做的這個頁面，這個頁面里面用了這幾個組件，balabala ...

設計：聽說你們已經沉淀了 200+ 組件，能給我們看看有哪些組件嗎?我們在下次設計的時候可以參考這些組件進行輸出，減少溝通成本。

前端：@所有人這個組件我們庫里面有嗎?有，CascadeSelect。哦，怎么用的?有文檔嗎?.......看下源碼吧。well... ??

組件的說明及可索引性，其實僅次于組件的可用性，甚至更高。

試想下如果今天你寫了個巨牛的組件，復用性、接口設計和交互設計都非常棒，但是你有什么渠道能讓大家一下子就知道嗎，難道你要專門為此拉大家開個會?來今天占用大家1個小時的寶貴時間，介紹下我今天寫的巨牛組件。??

反過來想，如果我在寫組件的時候，反正我這個組件也沒啥亮點，別人應該也不會用到，就不用補充文檔了吧，應該也沒人會知道。哦豁，丸蛋 ??

索引組件，來給大家分享一張圖：

如果有一天你團隊的組件庫也能像這樣，一板一眼有圖有真相，那該是多么幸福和享受的一件事情!

我也知道這樣好啊!誰不知道!如果我有時間，我肯定會....balabala...

所以你的意思是讓我們每寫一個組件不但要補充文檔，還要補充用法說明，還要截圖!?

對，還要單獨建庫，還要考慮配置 Webpack、Babel、TypeScript、Sass\Less、目錄結構、單元測試結構、代碼規范、Review 規范、發布規范這些 ??

最*實踐

說這么多呢，主要是想帶讀者們一起思考，也是我寫作的風格(喜歡講故事)，大部分內容其實是前端er 都會遇到的問題。

接下就進入正題，說了一大堆問題，總得有點辦法來解決吧!

先看看 bit 是怎么做的吧，bit 首先自身有一定的編譯能力，內置了 Webpack 及一些插件式 loader 來解決 React、Vue 等編譯問題。

對于我們團隊來說，都是使用 React，所以咱們就先從一個編譯 React 的腳手架開始。

如果把每一個組件都作為單獨的 NPM 項目發布，首先要考慮的是，前端一系列的編譯環境。如果我有 N 個前端組件項目，每個前端組件庫的 Webpack、babel 這些都需要重復配置，那真是要頭大的事情，我只是想寫一個組件而已，為什么要考慮這些。所以我們的腳手架首先要具備一些基礎的編譯命令。

啊對了，腳手架還沒有名字，那就暫時叫它：comp 吧 ??

comp new：處理按照模板新建一個標準組件

初始化一個標準組件項目結構，所有接入所有 comp 命令
初始化 Git 倉庫
初始化 CI/CD 云構建配置

comp start：處理日常開發，附加單個組件展示及調試能力
comp watch：處理 babel 及 scss 監聽編譯，用于 npm link 場景
comp babel：處理編譯 npm 包
comp dev：處理監聽編譯 umd 包，用于代理調試
comp build：處理最后編譯過程

webpack 編譯 UMD 包
Babel 包
CI\CD 過程中自動截圖組件
CI\CD 過程中自動生成 README
其他 Hook

comp test：處理 jest 單元測試

那么等組件初始化以后，目錄結構就長這樣：

項目結構中沒有任何 webpack\babel 配置，當然如果有特殊配置需求，可以建立 comp.config.js 進行配置(此處借鑒很多已有的 cli 處理方式)。

這樣處理的好處是，在項目初始化后，用戶能見到的目錄結構非常清晰明了，項目中不有很多允許配置的地方，所有組件的編譯環境基本可以保證統一。

這都是些非常基礎的功能，當然又是不可缺少的部分，這些基礎命令我就不詳細介紹了，重點在后面。

通過這幾個問題來介紹功能：

你平時開發組件的流程是什么樣子?

平時，一般就是根據設計稿，切分到組件后。

然后去創建組件，最后通過項目引入，一邊看著一邊開發啊。

你開發組件的時候對于你提供的 Props 是如何驗證的?

最簡單的給一個 mock 看看效果唄。

或者寫一個單元測試?

那寫 Mock 的過程算不算是在寫 Usage 呢?

這個，應該也算吧，但是這些都是散落在各個項目里面，有些 mock 驗證完就刪掉了。

誰會閑的沒事在開發的時候把這些補充到 README 里面去啊。

為什么他們不寫文檔?

這還用說?因為懶唄?

那你為啥不寫?emm，那是因為....寫文檔這事兒吧，寫了不一定有人看，還費時間呀!業務需求那么多!我要是有時間的話，我肯定....balabala...

OK，那我們來看下一個問題

一個好的組件文檔需要那幾部分?

開發組件背景，注意事項啥的，這個沒啥太大的必要，有的組件需要的話就補充下，沒有的話就不用補充。

主要需要的一些介紹有：用法，Props 入參，最好能有個截圖，要是有個 Demo，那簡直完美!

還有安裝、開發、編譯的命令介紹得有吧。

錦上添花的話最好還能有幾個 badge，介紹下源碼是 TypeScript，下載量多少。

但是，要補充這些文檔是在太麻煩了，要一個一個整理，Props 這些信息，用的人可以在組件里面找到啊，我都有些注釋和類型定義的呀!

完成一輪心靈拷問之后，就會發現在整個組件的開發過程中，開發者本人之所以對這個組件這么清楚，是因為開發者其實已經為自己寫過一份 README 了。

用法：組件開發過程中需要看到效果，寫過一些 mock 數據，已經知道什么樣的 props 傳進去會產生什么樣的效果。
Props 入參：組件有哪些 Props，所代表的含義是什么，每個 Props 入參類型是什么，已經在 TypeScript 的 Interface 及注釋中有體現。
截圖：有 mock 數據還不知道長什么樣?已經看過 N 多遍了。
Demo：根據用法和組件定義，開發調試的就是 Demo。

有了這四個最重要的介紹后，相信大部分開發者也都能知道這個組件是怎么個情況了。

所以，如果我們能把上面這些數據都收集到，是不是就可以利用腳本自動生成 README 文檔了呢?

用法 / Usage

要收集用法其實很簡單，如果讓組件有獨立開發的能力，不就可以保留這些 Usage 的 Mock 數據了嗎?

有些人可能沒理解我說的”組件獨立開發的能力“是什么意思，我解釋一下下：我們平時開發一個組件，一般都是把這個組件放置于某個頁面中，一遍調試頁面一遍調試組件。獨立開發組件的意思是，直接啟動一個頁面，可以看到組件的樣子，這個頁面展示的就是圍繞組件的所有信息。

所以在腳手架中，只要在 docs.ts 中書寫需要調試組件相關的 mock 數據，頁面就可以展示出組件的樣子，同時這些 mock 數據可以保留作為 README 文檔數據。

export default function(Component: typeof IComponent, mountNode) { 
   /** DOCS_START 請將Demo生成方法都寫在以下區塊內，用于生成README及Riddle **/ 
   ReactDOM.render( 
     <Component 
       navigation={true} 
       pagination={true} 
       autoplay={true} 
       dataSource={[ 
         { 
           href: 'http://xxxxxxxx', 
           image: 'https://xxxxxxx.cdn.com/tfs/TB1jHkBmNv1gK0jSZFFXXb0sXXa-1440-343.png', 
         }, 
         { 
           image: 'https://xxxxxxx.cdn.com/tfs/TB1Y_XacrY1gK0jSZTEXXXDQVXa-1416-813.png', 
         }, 
       ]} 
     />, 
     mountNode, 
   ); 
   /** DOCS_END **/ 
 }

另外，如果保證這份 demo 的接口輸出統一規范，還可以支持直接生成在 CodePen，Riddle 這些在線編輯的代碼內容。

試想下，你的 README 中如果出現一段：點擊立即體驗，跳轉過去后可以在線編輯實時看到效果，那對于任何看到你組件的同學來說都是一種享受 ??

組件參數 / Props

要收集這部分數據就比較復雜了，我們需要深入分析 TypeScript AST 語法樹，提取出其中組件 props 的類型以及對于Interface的注釋內容。

經過一番 github，終于找到可以實現一個可以處理這件事情的小眾庫：react-docgen-typescript(https://github.com/styleguidist/react-docgen-typescript)。

在開發過程中，因為對一些注釋及類型輸出與我預期的不太一樣，所以我 fork 后做了一些修改，已經可以完成對一個完整組件的 Props 做分析后輸出一份 typefile.json 。

同樣的，通過基于該能力，可以擴展為 webpack 插件 react-docgen-typescript-loader(https://github.com/strothj/react-docgen-typescript-loader)，為組件的靜態屬性中添加 __docInfo 屬性，來聲明其屬性內容，于是組件開發過程變可以實現以下效果：