探索組件庫設計的無限可能性
1. 前言
當前端開發團隊面臨業務的不斷增長和項目數量的持續增加時,兩個主要問題逐漸凸顯：1.業務組件復用的挑戰；2. 代碼一致性和質量維護問題。前端團隊為了解決這些問題,通常會選擇構建業務組件庫。其主要目標是：
- 提高開發效率：開發人員可以在不同項目中復用組件,從而減少重復工作,提高開發效率。
- 保持一致的代碼實現：可以確保在不同項目中使用相同的代碼實現,避免了風格不一致和質量差異。
- 質量保障：組件庫中的組件經過嚴格驗證和測試,能夠提供高質量的代碼。
- 易于維護和升級：作為獨立的模塊,業務組件庫更容易進行維護和升級,使開發人員能夠更專注于組件庫本身的質量。
- 知識共享和技術積累：組件庫可以成為團隊共享技術知識和經驗的平臺,幫助提升整體的技術水平。
因此,構建業務組件庫有助于解決業務組件復用、代碼統一性和質量維護等問題,為不斷發展的業務環境提供了高效、統一和可維護的開發流程。
2. 實現分析
在構建業務組件庫時,需要深入調研和選擇適當的技術方案,驗證方案的可行性,最終將各個解決方案集成到一起,以實現高效的組件庫開發和維護。下面我們將通過整體架構、構建、質量監控、站點搭建、組件質量、組件SOP這六大模塊對我們的業務組件庫進行分析。
圖片
3. 整體架構設計
對于業務組件庫的整體架構設計而言,核心問題是業務組件庫的代碼時如何來組織和管理。首先,我們把代碼倉庫建好。業界一般會把同一類組件庫用單個倉庫的形式維護,并且把組件開發成NPM包的形式,這里的重點是,你要考慮把所有的組件打包成一個大的NPM包,還是分割是一個個獨立的小NPM包。不要小看這個問題,這兩種選擇會使倉庫的目錄結構有不小的差異,進一步又會影響到后面組件的開發,構建,發布,實現的技術設計。
業界組件庫的架構常見單包和多包兩種。單包適合簡單場景,組件集中在一個庫中。多包則將組件分成獨立包,適應多項目需求,增強靈活性和復用性。
3.1單包是什么
把所有的組件看成一個整體,一起打包發布。單個倉庫,單個包,統一維護統一管理。
? 優點
- 可以通過相對路徑實現組件與組件之間的引用,公共代碼之間的引用
- 維護成本低,只維護一套package.json配置
? 缺點
- 組件完全耦合,必須把它作為一個整體統一發包,就算只改一個非常小的功能,都要對整個包發布更新
- 搭建場景重復打包
比如說Antd,它就是作為一個整體的包來盡進行管理的。選擇使用單包架構的話,那么你就必須提供按需加載的能力,以降低使用者的成本,你可以考慮支持ESModules的Treeshaking的功能來實現按需加載的能力。當然你也可以選擇另外一種方案,叫做"多包架構"。
3.2多包是什么
每個組件彼此獨立,單獨打包發布,單個倉庫多個包,統一維護單獨管理。
? 優點
組件發布靈活,并且大然支持按需使用
? 缺點
- 維護成本高,每個組件都需要一套package配置。
- 組件與組件之間物理隔離,對于相互依賴,公共代碼抽象等場景,就只能通過NPM包引用的方式來實現。
- 多依賴多版本問題
- 常用邏輯片段/各個組件都需要的依賴和邏輯
在這些場景下的開發統一發布,相對來說沒那么方便,多包架構在業界稱之為"Monorepo"。
圖片
3.3結論
ZjDesign組件庫使用場景比較特殊,組件之間的依賴關系比較強,互相會組合形式新的組件,所以在這里選用的單包開發模式進行開發。單包開發模式可以減少我們開發維護成本,開發工作量的減少,提升組件之間的引用效率。
4. 組件庫構建
當你確定了整體架構之后,就可以開始具體的功能點實現了。業務組件庫要求整體框架提供基礎的技術能力。
4.1項目打包
提到構建工具,大家肯定一下會想到很多一堆工具：webapck、gulp、rollup等。網上有很多文章分析它們分別更適合哪些場景,webpack更適合打包組件庫、應用程序之類的應用,而rollup更適合打包純js的類庫。下面我們來對比一下webpack和rollup兩者的區別。
?rollup使用流程
- 無需考慮瀏覽器兼容問題,開發者寫esm代碼 -> rollup通過入口,遞歸識別esm模塊 -> 最終打包成一個或多個bundle.js -> 瀏覽器直接可以支持引入
- 需考慮瀏覽器兼容問題,可能會比較復雜,需要用額外的polyfill庫,或結合webpack使用
打包成npm包：
- 開發者寫esm代碼 -> rollup通過入口,遞歸識別esm模塊 -> （可以支持配置輸出多種格式的模塊,如esm、cjs、umd、amd）最終打包成一個或多個bundle.js
- （開發者要寫cjs也可以,需要插件@rollup/plugin-commonjs）初步看來
- 很明顯,rollup 比較適合打包js庫（react、vue等的源代碼庫都是rollup打包的）或 高版本無需往下兼容的瀏覽器應用程序（現在2022年了,時間越往后,遷移到rollup會越多,猜測）
- 這樣打包出來的庫,可以充分使用上esm的tree shaking,使源庫體積最小
?webpack和rollup打包比對
let foo = () => {
let x = 1;
if (false) {
console.log("never reached");
}
let a = 3;
return a;
};
let baz = () => {
var x = 1;
console.log(x);
post();
function unused() {
return 5;
}
return x;
let c = x + 3;
return c;
};
baz();測試對比兩個打包工具對Dead Code的打包結果
打包對比結果：中間是源代碼,左邊是rollup打包結果,右邊是webpack打包結果對比。
圖片
webpack打包效果（有很多注入代碼）
- 實際上,我們自己寫的代碼在最下面。上面注入的大段代碼 都是webpack自己的兼容代碼,目的是自己實現require,modules.exports,export,讓瀏覽器可以兼容cjs和esm語法
- 可以理解為,webpack自己實現polyfill支持模塊語法,rollup是利用高版本瀏覽器原生支持esm(所以rollup無需代碼注入)
具體細節rollup和webapck的源碼實現差異在這里不做過多贅述,大家可以自己深入研究。
? 構建出 esm、cjs 格式
選擇Rollup來打包組件庫,需要有幾點注意：
- 配置包格式為 esm、cjs、umd
- external 掉vue,組件庫不建議將 Vue 打包進去
rollup 配置如下：
{
input: file,
output: {
compact: true,
file: `lib/index.js`,
format: 'es',
name,
sourcemap: false,
globals: {
echarts: 'echarts',
vue: 'Vue'
}
},
external: [
'echarts', 'vue'
],
plugins: [
replace({
'process.env.NODE_ENV': JSON.stringify('production')
}),
vue({
css: false,
template: {
isProduction: true
},
modules: true,
styles: {
scoped: true,
trim: true
}
}),
postcss({
extract: true,
modules: false,
scoped: true,
sourceMap: false,
autoModules: true,
plugins: [
simplevars(),
nested(),
cssnano(),
base64({
extensions: ['.png', '.jpeg', '.jpg', '.gif'],
root: './assets/'
}),
autoprefixer({
add: true
})
],
extensions: ['.css', '.less'],
use: {
less: {
javascriptEnabled: true
}
}
}),
babel({
runtimeHelpers: true,
exclude: 'node_modules/**',
plugins: [
['@babel/plugin-proposal-optional-chaining', { loose: false }]
],
presets: [
['@babel/preset-env', { targets: '> 0.25%, not dead' }]
]
}),
url({
limit: 10 * 1024,
emitFiles: true
}),
progress(),
buble({
transforms: { forOf: false }
}),
uglify({
ie8: true
})
]
}4.2 版本控制
組件庫發布版本號的管理是很重要的,如何來維護我們的版本號？只能動手在package.json中修改嗎？其實可以在打包執行命令的時候,通過命令及參數幫助我們實現自動升級版本號的目的。比如我們在打測試環境包的時候可以使用（cross-env用來指定變量NODE_ENV的值）。
"scripts": {
"test": "npm version patch && cross-env NODE_ENV=testing node build/build.js"
}下面我們來看看npm version命令具體的使用方式：npm采用了semver規范作為依賴版本管理方案。semver約定一個包的版本號必須包含3個數字。
MAJOR.MINOR.PATCH 意思是 主版本號.小版本號.修訂版本號
MAJOR 對應大的版本號迭代,做了不兼容舊版的修改時要更新MAJOR版本號
MINOR 對應小版本迭代,發生兼容舊版API的修改或功能更新時,更新MINOR版本號
PATCH 對應修訂版本號,一般針對修復BUG的版本號
當我們每次發布包的時候都需要升級版本號：
"scripts": {
"rollup": "rollup -c rollup.config.js",
"publish:major": "npm version major && npm publish",
"publish:minor": "npm version minor && npm publish",
"publish:patch": "npm version patch && npm publish",
"publish:beta": "npm version prerelease --preid=beta && npm publish --tag=beta"
},4.3發布
npm包發布使用之家npm進行發布,發布流程如下：
1. 首先需要配置私有包，配置一次即可
$ npm config set @auto:ZjDesign http://xxxx.com/
2. 使用如下命令在私有倉庫中添加用戶（配置一次即可）
npm adduser --registry http://xxxx.com/
3. 執行打包命令
npm run rollup
4.私有包發布
npm publish --registry http://xxxx.com/5. 組件搭建實例
首先看一下我們單個組件UI設計圖。從圖中可以看出,每個組件實例demo可以看成抽象五大模塊。1.組件的title+subtitle、2.組件描述、3.多個組件形態展示、4.設計原則與頁面布局、5.單個組件形態的代碼示例。
圖片
5.1組件demo整體目錄
圖片
index.zh-CN.md： 作為靜態數據的快速輸出,包含組件名稱、描述、設計原則和API。從.md格式文件中可以使用插件md(vite插件)解析出組件需要的數據,這個在后面單獨講解實現細節。
圖片
單個組件類型文件：包含組件排序,title,描述,html。這個通過docs進行數據的解析,具體解析后面進行詳細講解。
圖片
5.2Docs插件
作用：將單例中的.vue文件中docs標簽數據進行格式處理,docs插件流程圖。
圖片
實現代碼：
export default (options: Options = {}): Plugin => {
const { root, markdown } = options
const vueToMarkdown = createVueToMarkdownRenderFn(root)
const markdownToVue = createMarkdownToVueRenderFn(root, markdown)
return {
name: 'vueToMdToVue',
async transform(code, id) {
if (id.endsWith('.vue') && id.indexOf('/demo/') > -1 && id.indexOf('index.vue') === -1) {
const res = vueToMarkdown(code, id)
return {
code: res.ignore ? res.vueSrc : (await markdownToVue(res.vueSrc, id)).vueSrc,
map: null
}
}
}
}
}vueToMarkdown函數實現：這里面使用了lru-cache進行緩存處理,對于已經解析完成的文件進行跟蹤,這樣可以加快文檔展示。通過fetchCode方法對自定義標簽內容進行獲取。
5.3 MarkDown插件
作用：將markdown文檔格式數據轉化成我們想要的vue格式化數據。
這里主要通過對第三方markdown-it,依據UI設計的要求進行定制化的修改。可以支持輸入emoji,anchor,toc分別使用markdown-it-emoji、markdown-it-anchor、markdown-it-table-of-contents插件。
? md插件實現流程
1、定義插件導出,基于vite的Plugin進行封裝：
import { createMarkdownToVueRenderFn } from './markdownToVue';
import type { MarkdownOptions } from './markdown/markdown';
import type { Plugin } from 'vite';
interface Options {
root?: string;
markdown?: MarkdownOptions;
}
export default (options: Options = {}): Plugin => {
const { root, markdown } = options;
const markdownToVue = createMarkdownToVueRenderFn(root, markdown);
return {
name: 'mdToVue',
async transform(code, id) {
if (id.endsWith('.md')) {
// transform .md files into vueSrc so plugin-vue can handle it
return { code: (await markdownToVue(code, id)).vueSrc, map: null };
}
},
};
};2、markdownToVue核心思想實現：
通過lru-cache進行解析文檔的緩存處理,使用gray-matter對docs格式數據的解析,最后生成demo-box組件格式的vue文件。
export function createMarkdownToVueRenderFn(root: string = process.cwd(), options: MarkdownOptions = {}) {
const md = createMarkdownRenderer(options)
return async (src: string, file: string): Promise=> {
const relativePath = slash(path.relative(root, file))
const cached = cache.get(src)
if (cached) {
debug(`[cache hit] ${relativePath}`)
return cached
}
const start = Date.now()
const { content, data: frontmatter } = matter(src)
// eslint-disable-next-line prefer-const
let { html, data } = md.render(content)
// avoid env variables being replaced by vite
html = html.replace(/import\.meta/g, 'import.meta').replace(/process\.env/g, 'process.env')
// TODO validate data.links?
const pageData: PageData = {
title: inferTitle(frontmatter, content),
description: inferDescription(frontmatter),
frontmatter,
headers: data.headers,
relativePath,
content: escapeHtml(content),
html,
// TODO use git timestamp?
lastUpdated: Math.round(fs.statSync(file).mtimeMs)
}
const newContent = data.vueCode
? await genComponentCode(md, data, pageData)
: `${html}${fetchCode(content, 'style')}`
debug(`[render] ${file} in ${Date.now() - start}ms.`)
const result = {
vueSrc: newContent?.trim(),
pageData
}
cache.set(src, result)
return result
}
}6. 組件沉淀-SOP
在開發組件并將其沉淀為組件庫時,建立合適的SOP機制可以提高開發效率、保持一致性,并促進團隊合作。以下是從組件設計到溝通、開發、沉淀為組件庫的SOP機制：
圖片
? 組件設計：
設計同學進行界面設計,定義組件統一規范。根據多個業務方進行公共組件的提取,確定組件的用途、功能。
?評審：
設計同學和研發同學進行組件設計UI的評審,研發同學定義組件的輸入和輸出,以及可能的配置項。并且進行編寫組件的詳細需求文檔,包括示例代碼和用法示例。
? 開發階段：
根據組件設計和需求文檔,進行組件的開發。使用規范的編碼風格和最佳實踐。在開發過程中進行單元測試和集成測試,確保組件的穩定性和正確性。
? 文檔編寫：
編寫組件的文檔,包括組件的用途、API文檔、示例代碼等。提供詳細的使用說明,幫助其他開發人員使用組件。
? CODE-REVIEW：
使用版本管理工具（如Git）來管理組件的代碼。進行代碼審查,確保代碼質量和一致性。
? 測試與驗收：
在真實項目中測試組件,確認其在不同場景下的穩定性和可用性。進行驗收測試,確保組件滿足預期要求。設計同學進行UI驗收。
? 發布：
根據版本號規則,發布組件庫的新版本。定期更新組件庫,修復bug、添加新功能等。
7. 總結
目前,ZjDesign業務組件庫正在不斷豐富中。我們努力開發具有高擴展性和低上手成本的組件。并且組件庫已有多個新項目接入,整體開發效率明顯提升,減少了重復開發。組件庫的搭建為團隊提供了一個統一的技術平臺,促進了知識分享和合作。這一系列改進加速了產品交付,并推動了整體開發流程的提升。
作者簡介
何彪
■ 主機廠事業部-技術部-數科技術團隊
■2023年2月加入汽車之家，目前任職于主機廠事業部-技術部-數科技術團隊，主要負責數科前端業務，組件庫搭建等工作。
