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

背景

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

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

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

感覺沒什么卵用?

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

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

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

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

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

認(rèn)識組件

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

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

• 大庫型，Antd、Element 標(biāo)準(zhǔn)的大庫型
• 一次型，完全業(yè)務(wù)組件，用完一次再也不維護
• 高復(fù)用型，一看就應(yīng)該單獨封裝以后給其他人用，比如：視頻播放器
• 項目融合型，與業(yè)務(wù)項目在一起，混合 store，不分你我

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

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

方便、快捷

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

現(xiàn)在用個展示的面板，立馬去 components 目錄擼一個。

數(shù)據(jù)?不是有 store 嗎?引入進來不就拿到數(shù)據(jù)了!

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

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

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

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

可維護性

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

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

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

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

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

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

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

組件大小、加載性能

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

發(fā)現(xiàn)原來組件包中還有一些個組件，看上去不應(yīng)該放在大庫中進行維護，比如那種一次性組件，二次封裝型組件。

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

對于這樣的組件，最好的處理方式應(yīng)該是創(chuàng)建一個獨立的倉庫，封裝完善后，寫好 README，發(fā)布至內(nèi)網(wǎng) NPM，供業(yè)務(wù)項目使用。

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

當(dāng)然組件大小這方面也可以通過很多其他方式解決，比如：異步加載，NPM 引入，按需加載等等啦...那么，讓我們談?wù)勏旅媪硗庖粋€很重要、又很容易被忽略的部分吧。

組件說明及可索引性

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

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

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

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

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

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

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

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

??

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

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

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

對，還要單獨建庫，還要考慮配置 Webpack、Babel、TypeScript、Sass\Less、目錄結(jié)構(gòu)、單元測試結(jié)構(gòu)、代碼規(guī)范、Review 規(guī)范、發(fā)布規(guī)范這些 ??

最*實踐

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

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

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

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

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

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

• comp new：處理按照模板新建一個標(biāo)準(zhǔn)組件

• 初始化一個標(biāo)準(zhǔn)組件項目結(jié)構(gòu)，所有接入所有 comp 命令
• 初始化 Git 倉庫
• 初始化 CI/CD 云構(gòu)建配置

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

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

• comp test：處理 jest 單元測試

那么等組件初始化以后，目錄結(jié)構(gòu)就長這樣：

??

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

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

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

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

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

平時，一般就是根據(jù)設(shè)計稿，切分到組件后。

然后去創(chuàng)建組件，最后通過項目引入，一邊看著一邊開發(fā)啊。

你開發(fā)組件的時候?qū)τ谀闾峁┑?Props 是如何驗證的?

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

或者寫一個單元測試?

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

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

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

為什么他們不寫文檔?

這還用說?因為懶唄?

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

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

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

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

主要需要的一些介紹有 ：用法，Props 入?yún)ⅲ詈媚苡袀€截圖，要是有個 Demo，那簡直完美!

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

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

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

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

• 用法：組件開發(fā)過程中需要看到效果，寫過一些 mock 數(shù)據(jù)，已經(jīng)知道什么樣的 props 傳進去會產(chǎn)生什么樣的效果。
• Props 入?yún)ⅲ航M件有哪些 Props，所代表的含義是什么，每個 Props 入?yún)㈩愋褪鞘裁矗呀?jīng)在 TypeScript 的 Interface 及注釋中有體現(xiàn)。
• 截圖：有 mock 數(shù)據(jù)還不知道長什么樣?已經(jīng)看過 N 多遍了。
• Demo：根據(jù)用法和組件定義，開發(fā)調(diào)試的就是 Demo。

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

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

用法 / Usage

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

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

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

export default function(Component: typeof IComponent, mountNode) { 
   /** DOCS_START 請將Demo生成方法都寫在以下區(qū)塊內(nèi)，用于生成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 的接口輸出統(tǒng)一規(guī)范，還可以支持直接生成在 CodePen，Riddle 這些在線編輯的代碼內(nèi)容。

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

??

組件參數(shù) / Props

要收集這部分?jǐn)?shù)據(jù)就比較復(fù)雜了，我們需要深入分析 TypeScript AST 語法樹，提取出其中組件 props 的類型以及對于Interface的注釋內(nèi)容。

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

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

??

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

??

截圖 / Preview

有了組件，有了 Demo，還愁沒有截圖嗎?

直接在構(gòu)建過程中用 puppeteer ，讀取運行 docs.ts 渲染出組件，進行截圖，然后隨著云構(gòu)建 CD 過程發(fā)到 CDN，就完事了!

最后，README 中加入一些特殊標(biāo)記，在云構(gòu)建過程中進行 README 替換生成就可以啦!并不會影響 README 本身要叮囑的內(nèi)容。

??

最后，Duang !一份完整，漂亮，詳細的文檔就生成好了，整個過程我們并沒有特意寫過什么 README 方面的內(nèi)容，一切都是非常輕松標(biāo)準(zhǔn)的進行輸出。

??

結(jié)語

在上面的一整套復(fù)雜的過程中，看上去最后好像我只得到了一個自動生成 README 的功能。但實際上呢，其實 README 只是一個順帶的產(chǎn)物。

整個過程中，我已經(jīng)拿到了這個組件的所有我想要拿到的數(shù)據(jù)，它的 Props，Usage，Preview，版本信息，包名，甚至構(gòu)建過程會同步發(fā)布該組件的 UMD CDN 包及 NPM 包。

接下來，就可以圍繞這些數(shù)據(jù)和工具，建立和擴展很多功能和平臺。

舉幾個栗子：

• 建立一個 bit 一樣的，組件平臺，把團隊內(nèi)的組件收集起來，統(tǒng)一在平臺展示及索引
• 根據(jù)拿到 Props 類型信息做可視化的搭建平臺，把 Props 的傳參直接交給用戶設(shè)置，根據(jù)不同數(shù)據(jù)類型提供不同的 Form Setter
• 看似組件都分布在不同的庫中，卻可以通過組件 cli 做統(tǒng)一的構(gòu)建處理
• 非常輕松接入 微前端 框架，因為所有組件的發(fā)布構(gòu)建都是標(biāo)準(zhǔn)的構(gòu)建協(xié)議
• 通過統(tǒng)計組件發(fā)布次數(shù)，下載次數(shù)，關(guān)聯(lián) bug 數(shù)評估代碼質(zhì)量

目前在我們團隊，已經(jīng)使用該工具產(chǎn)出 100+ 的可用組件，并且發(fā)布組件已經(jīng)成功接入到我們已有的可視化編輯器中。

看一眼結(jié)合可視化設(shè)置面板后的效果吧：

??

我發(fā)現(xiàn)只要實現(xiàn)過程中，沒有給開發(fā)者帶來太多的工作量，又能帶來實時可以看到的效果，開發(fā)者會很樂意為那些 Props 做一番解釋和修飾 ??。

我們團隊目前產(chǎn)出的組件看起來一片通透，整齊明了。

我是一個熱愛生活的前端工程師!Yooh!??

【本文為51CTO專欄作者“阿里巴巴官方技術(shù)”原創(chuàng)稿件，轉(zhuǎn)載請聯(lián)系原作者】

??戳這里，看該作者更多好文??