1. 為什么我會(huì)跟rea較上勁組件依賴(lài)失真的日常先交代一下背景。我之前在一個(gè)維護(hù)了三年的中后臺(tái)項(xiàng)目里天天跟幾百個(gè) React 組件打交道。那段時(shí)間最折磨人的不是寫(xiě)新功能而是改老組件——你永遠(yuǎn)不知道一個(gè)看起來(lái)人畜無(wú)害的 props 改動(dòng)會(huì)在哪個(gè)犄角旮旯的頁(yè)面里炸出類(lèi)型錯(cuò)誤。有一次我要給一個(gè)按鈕組件加個(gè)新參數(shù)全局搜了一遍引用肉眼數(shù)出十一個(gè)地方在用改完之后測(cè)試環(huán)境直接紅了四個(gè)頁(yè)面原因是有兩個(gè)組件通過(guò)一個(gè)我沒(méi)注意到的中間層間接引用了它。這種經(jīng)歷多了之后我開(kāi)始琢磨一件事團(tuán)隊(duì)嘴上說(shuō)的組件化開(kāi)發(fā)實(shí)際上對(duì)組件之間關(guān)系的理解是高度私有的。每個(gè)人腦子里都有一張模糊的依賴(lài)圖但沒(méi)人能畫(huà)出來(lái)新來(lái)的同事更是只能靠猜。文檔寫(xiě)過(guò)幾版很快就過(guò)期了IDE 自帶的結(jié)構(gòu)視圖只能看單文件跨文件關(guān)系全靠人肉。我那時(shí)候特別想要一個(gè)東西能自動(dòng)把整個(gè)項(xiàng)目的組件依賴(lài)關(guān)系摸清楚然后把結(jié)果變成一張看得懂的報(bào)表。這就是 rea 的起點(diǎn)。rea 不是那種幫你寫(xiě)代碼的框架也不是約束代碼風(fēng)格的 lint 工具它是一個(gè)面向 React 項(xiàng)目的依賴(lài)關(guān)系分析器。它能掃描一個(gè)目錄把組件之間復(fù)雜的引用關(guān)系拉成一張結(jié)構(gòu)化的網(wǎng)告訴你誰(shuí)依賴(lài)誰(shuí)、誰(shuí)在反復(fù)被引用、哪里有循環(huán)依賴(lài)、哪個(gè)組件已經(jīng)沒(méi)人用了但還在倉(cāng)庫(kù)里躺著。對(duì)維護(hù)老項(xiàng)目的人來(lái)說(shuō)它就是一次組件關(guān)系普查對(duì)剛接手代碼庫(kù)的人來(lái)說(shuō)它就是一張不用維護(hù)、永遠(yuǎn)最新的架構(gòu)地圖。我自己定義 rea 的定位是它不是代碼規(guī)范工具而是關(guān)系普查工具。規(guī)范工具告訴你該怎么寫(xiě)rea 告訴你現(xiàn)在到底是什么樣。先搞清楚現(xiàn)狀再談改進(jìn)這個(gè)順序不能反。1.1 一次改一處崩三處的實(shí)際案例具體說(shuō)說(shuō)那次讓我下決心的經(jīng)歷。項(xiàng)目里有一個(gè)UserAvatar組件最初只是在用戶列表里顯示頭像和名字后來(lái)被人擴(kuò)展了幾次增加了在線狀態(tài)、部門(mén)標(biāo)簽、跳轉(zhuǎn)鏈接等能力。我接手時(shí)顯示用戶信息這個(gè)需求已經(jīng)有三個(gè)組件在各自實(shí)現(xiàn)全都直接或間接引用了UserAvatar。我改了UserAvatar的 props 結(jié)構(gòu)把原來(lái)分散的幾個(gè)參數(shù)合并成一個(gè)user對(duì)象。結(jié)果列表頁(yè)直接引用它報(bào)錯(cuò)預(yù)期內(nèi)詳情頁(yè)的MemberCard引用了UserAvatar它自己又把 props 透?jìng)鞒鋈?bào)錯(cuò)也能理解最詭異的是ChatPanel它壓根沒(méi)寫(xiě)過(guò)UserAvatar但它的子組件MessageItem里用了MemberCard于是錯(cuò)誤一路傳上來(lái)整個(gè)聊天面板崩潰。這個(gè)問(wèn)題的本質(zhì)不是UserAvatar改得不好而是團(tuán)隊(duì)對(duì)誰(shuí)在依賴(lài)誰(shuí)這件事完全沒(méi)有共識(shí)。我當(dāng)時(shí)花了半小時(shí)翻引用、回看提交記錄、問(wèn)之前的維護(hù)人才拼出這張圖。如果有工具能在改動(dòng)前五分鐘生成一份依賴(lài)清單后面這些返工根本不會(huì)發(fā)生。1.2 大多數(shù)人是怎么理清依賴(lài)關(guān)系的我觀察了一下不同團(tuán)隊(duì)的做法大致分三種第一種是硬記派。項(xiàng)目規(guī)模小的時(shí)候還好超過(guò)五十個(gè)組件之后就全靠個(gè)人記憶離職一個(gè)人就帶走一部分地圖。第二種是文檔派。ARTS 架構(gòu)圖、Notion 頁(yè)面畫(huà)得漂漂亮亮但代碼一變文檔就沒(méi)人更新三個(gè)月之后文檔描述的系統(tǒng)跟真實(shí)代碼已經(jīng)不是一個(gè)東西了。第三種是工具派。用 IDE 的 Find Usages、用 grep 搜 import 語(yǔ)句比前兩種靠譜但只適合查單個(gè)組件做不了全量分析更發(fā)現(xiàn)不了間接引用和循環(huán)依賴(lài)。這三種做法共同的問(wèn)題在于它們都在處理人應(yīng)該怎么理解代碼而 rea 處理的是代碼之間的關(guān)系應(yīng)該怎么被計(jì)算。后者是確定性的是可以自動(dòng)化的而且是項(xiàng)目發(fā)展的過(guò)程中唯一不會(huì)撒謊的信息源——源碼本身。1.3 rea 的定位先普查再規(guī)劃我給自己定的原則很簡(jiǎn)單先把現(xiàn)狀完整地、準(zhǔn)確地呈現(xiàn)出來(lái)讓團(tuán)隊(duì)在同一個(gè)事實(shí)基礎(chǔ)上討論問(wèn)題。至于怎么重構(gòu)、怎么分層那是后面的事情。這就像接手一個(gè)老倉(cāng)庫(kù)之前你先別急著清理貨架先做一次盤(pán)點(diǎn)哪些貨有人買(mǎi)哪些貨積壓了幾個(gè)月哪些貨放在兩個(gè)不同的貨架上。rea 做的就是這件事它把組件依賴(lài)這種抽象的、藏在代碼里的關(guān)系變成一份可以打印出來(lái)、可以在會(huì)議上指著討論的清單。2. rea 三個(gè)字母背后的架構(gòu)取向項(xiàng)目起名叫 rea不是隨手敲的。三個(gè)字母分別對(duì)應(yīng)我設(shè)計(jì)的三個(gè)階段Relate、Export、Analyze。這也決定了工具的整體架構(gòu)不是一個(gè)單點(diǎn)腳本而是三條清晰的處理流水線。2.1 Relate以依賴(lài)圖為中心的關(guān)系建模Relate 階段負(fù)責(zé)回答一個(gè)問(wèn)題這個(gè)項(xiàng)目的組件之間到底有哪些關(guān)系在這個(gè)階段rea 不關(guān)心組件內(nèi)部的實(shí)現(xiàn)細(xì)節(jié)不關(guān)心樣式怎么寫(xiě)只關(guān)注一個(gè)東西引用關(guān)系。誰(shuí) import 了誰(shuí)誰(shuí)在 JSX 里渲染了誰(shuí)誰(shuí)通過(guò) React.lazy 動(dòng)態(tài)加載了誰(shuí)這些信息被統(tǒng)一收集起來(lái)形成一個(gè)以組件為節(jié)點(diǎn)、以引用為邊的有向圖。我選擇有向圖作為核心數(shù)據(jù)結(jié)構(gòu)是有原因的。第一有向圖天然能表達(dá)A 依賴(lài) B但 B 不依賴(lài) A這種非對(duì)稱(chēng)關(guān)系這個(gè)在 UI 組件場(chǎng)景里非常常見(jiàn)——底層組件永遠(yuǎn)不知道誰(shuí)在用自己。第二圖結(jié)構(gòu)方便做后續(xù)分析比如找環(huán)、算入度出度、做連通性判斷這些都是圖論里的經(jīng)典問(wèn)題不需要發(fā)明新算法。這個(gè)階段最忌諱的是把出現(xiàn)過(guò)的字符串當(dāng)成真正的依賴(lài)。比如有的組件在注釋里寫(xiě)了Button有的組件在字符串拼接里用了組件名這些都不能算數(shù)。rea 只認(rèn)兩類(lèi)東西真實(shí)的 import 語(yǔ)句以及 JSX 里實(shí)際渲染的組件標(biāo)簽。寧可漏掉一些模糊的情況也不能把假依賴(lài)混進(jìn)圖里否則后面所有分析都是臟數(shù)據(jù)。2.2 Export從源碼到結(jié)構(gòu)化報(bào)表的流水線Relate 階段產(chǎn)出的是一張內(nèi)存里的圖但人沒(méi)法直接看內(nèi)存圖所以還需要一個(gè) Export 階段。這個(gè)階段做的事是把依賴(lài)圖轉(zhuǎn)換成一系列結(jié)構(gòu)化輸出。目前 rea 支持三種格式JSON給程序讀方便二次加工Markdown 表格給人讀方便貼進(jìn)文檔或者發(fā)到群里以及一個(gè)簡(jiǎn)單的 HTML 報(bào)告用顏色和連線把依賴(lài)關(guān)系可視化出來(lái)適合在評(píng)審會(huì)上投屏講解。Export 階段有個(gè)容易被忽視的設(shè)計(jì)點(diǎn)輸出格式不能影響分析結(jié)果。也就是說(shuō)不管你是要 JSON 還是 HTML底層那張依賴(lài)圖必須是同一張。我在設(shè)計(jì) rea 的時(shí)候把 Relate 和 Export 嚴(yán)格分成了兩層中間通過(guò)一個(gè)統(tǒng)一的內(nèi)部模型傳遞數(shù)據(jù)不能讓某個(gè)輸出格式反過(guò)來(lái)影響分析邏輯。2.3 Analyze把看得見(jiàn)的關(guān)系變成說(shuō)得清的決策前兩個(gè)階段解決的是看到了什么Analyze 階段解決的是這意味著什么。同樣是一張依賴(lài)圖不同角色關(guān)心的點(diǎn)完全不同后端開(kāi)發(fā)拿到這張圖關(guān)心的是循環(huán)依賴(lài)會(huì)不會(huì)導(dǎo)致初始化死循環(huán)前端 Leader 關(guān)心的是某個(gè)底層組件被三百個(gè)地方引用改動(dòng)它是不是高風(fēng)險(xiǎn)新人關(guān)心的是這個(gè)組件能不能刪刪了會(huì)不會(huì)有什么隱形依賴(lài)繃斷性能優(yōu)化的人關(guān)心的是有沒(méi)有組件在一個(gè)頁(yè)面里被重復(fù)渲染多次是不是因?yàn)槎鄠€(gè)入口都引到了同一個(gè)子組件。Analyze 階段把這些關(guān)心點(diǎn)轉(zhuǎn)化成具體的判定規(guī)則輸出帶有傾向性的結(jié)論。比如循環(huán)依賴(lài)警告高危公共組件提示孤兒組件提示。這些結(jié)論不一定都是錯(cuò)的但至少能讓討論有一個(gè)共同的出發(fā)點(diǎn)。3. 從 JSX 到依賴(lài)圖譜rea 的解析鏈路拆解知道整體架構(gòu)之后我想把解析鏈路拆開(kāi)講一遍。理解這條鏈路你才能自己改 rea 去適配特殊項(xiàng)目或者在其他語(yǔ)言、其他框架里復(fù)現(xiàn)同樣的思路。3.1 第一層文件遍歷與入口發(fā)現(xiàn)rea 的起點(diǎn)不是某個(gè)具體文件而是整個(gè)目錄。你可以給它一個(gè)入口文件比如src/App.tsx它會(huì)順著這個(gè)入口往外擴(kuò)散也可以不指定入口直接掃描整個(gè)src目錄把所有.tsx、.ts、.jsx、.js文件都納入分析范圍。這一層有個(gè)重要參數(shù)叫--depth控制遞歸深度。默認(rèn)不限制但如果是第一次對(duì)一個(gè)老項(xiàng)目跑分析我建議先限制在四層以內(nèi)把主干關(guān)系看清楚再逐步加深。否則幾百個(gè)組件的圖展開(kāi)之后信息量太大反而抓不住重點(diǎn)。文件遍歷階段會(huì)順帶做兩個(gè)過(guò)濾node_modules目錄直接跳過(guò)測(cè)試文件和.stories.tsx文件默認(rèn)跳過(guò)但可以通過(guò)參數(shù)手動(dòng)開(kāi)啟。測(cè)試文件里經(jīng)常有 mock 數(shù)據(jù)導(dǎo)致的關(guān)系沖突故事文件依賴(lài)的引用方式也跟業(yè)務(wù)組件不一樣混在一起會(huì)污染分析結(jié)果。3.2 第二層AST 解析與導(dǎo)入聲明收集拿到文件列表之后rea 會(huì)對(duì)每個(gè)文件做詞法分析和語(yǔ)法分析。這里用的是成熟的 JS 解析器先把源碼解析成 AST抽象語(yǔ)法樹(shù)然后從中提取結(jié)構(gòu)化的語(yǔ)法事實(shí)。在這一步rea 核心收集的信息是兩類(lèi)第一類(lèi)是import聲明。不管是import A from ./A、import { B } from ./B還是import type { C } from ./C都會(huì)被抓出來(lái)。這里要特別注意區(qū)分type導(dǎo)入——它只影響類(lèi)型檢查不影響運(yùn)行邏輯如果混進(jìn)依賴(lài)圖會(huì)制造大量虛假的運(yùn)行時(shí)依賴(lài)所以 rea 把 type-only 導(dǎo)入單獨(dú)標(biāo)記默認(rèn)不計(jì)入運(yùn)行時(shí)依賴(lài)圖。第二類(lèi)是 JSX 標(biāo)簽。一個(gè)組件文件可能沒(méi)有顯式 import 某個(gè)組件但通過(guò)全局注冊(cè)或者window掛載的方式在 JSX 里使用了它。rea 會(huì)把 JSX 里出現(xiàn)的組件標(biāo)簽名跟當(dāng)前文件的 import 列表做交叉比對(duì)識(shí)別出用了但沒(méi)本地導(dǎo)入的組件這種往往是隱式依賴(lài)風(fēng)險(xiǎn)點(diǎn)。AST 這層看起來(lái)復(fù)雜其實(shí)邏輯可以用一句話概括把代碼從給人看的文本變成給機(jī)器看的樹(shù)然后在樹(shù)上做遍歷和標(biāo)記。下面這是 rea 內(nèi)部處理 import 語(yǔ)句的核心邏輯示意用 TypeScript 寫(xiě)的import { parse } from babel/parser; import traverse from babel/traverse; export function extractImports(filePath: string, source: string) { const ast parse(source, { sourceType: module, plugins: [jsx, typescript, decorators-legacy], }); const imports: Array{ source: string; importedName: string; isTypeOnly: boolean; } []; traverse(ast, { ImportDeclaration(path) { const node path.node; node.specifiers.forEach((spec) { imports.push({ source: node.source.value, importedName: spec.type ImportDefaultSpecifier ? default : spec.local.name, isTypeOnly: node.importKind type, }); }); }, }); return imports; }實(shí)際的 rea 代碼比這個(gè)復(fù)雜一些因?yàn)檫€要處理 re-export、namespace import、動(dòng)態(tài) import 等情況但核心思路就是上面的代碼解析、遍歷、收集。3.3 第三層組件識(shí)別與依賴(lài)權(quán)重計(jì)算拿到所有的 import 關(guān)系之后會(huì)得到一個(gè)非常稠密的圖。一個(gè)工具函數(shù)可能被五十個(gè)組件引用了一個(gè) UI 組件可能引用了十幾個(gè)其他組件。如果直接把這個(gè)圖鋪開(kāi)信息噪音很大。所以 rea 在第三層做了一件事給每條邊賦予權(quán)重給每個(gè)節(jié)點(diǎn)賦予角色。節(jié)點(diǎn)角色的判定規(guī)則是這樣的文件名首字母大寫(xiě)且文件里有 JSX 返回值判定為組件文件名小寫(xiě)且文件不在 UI 目錄下判定為工具模塊文件里沒(méi)有任何導(dǎo)出只包含副作用邏輯判定為副作用模塊一個(gè)文件同時(shí)導(dǎo)出組件和其他函數(shù)判定為混合模塊。邊權(quán)重的計(jì)算規(guī)則是直接引用記 1 分通過(guò) re-export 間接引用記 0.5 分通過(guò)動(dòng)態(tài) importReact.lazy或import()調(diào)用引用記 0.3 分。簡(jiǎn)單說(shuō)越是直接的、靜態(tài)的、運(yùn)行時(shí)就確定的依賴(lài)權(quán)重越高越是一層套一層的間接引用權(quán)重越低。下面這張表是 rea 對(duì)節(jié)點(diǎn)角色和邊權(quán)重的默認(rèn)設(shè)定節(jié)點(diǎn)角色判定依據(jù)風(fēng)險(xiǎn)傾向組件首字母大寫(xiě)、含 JSX作為依賴(lài)源影響下游使用者工具模塊小寫(xiě)命名、純邏輯作為被依賴(lài)方支撐多個(gè)組件副作用模塊無(wú)導(dǎo)出、有副作用邏輯導(dǎo)入即執(zhí)行隱藏風(fēng)險(xiǎn)高混合模塊組件與函數(shù)同時(shí)導(dǎo)出依賴(lài)關(guān)系模糊建議拆分類(lèi)型模塊僅導(dǎo)出類(lèi)型不計(jì)入運(yùn)行時(shí)依賴(lài)3.4 第四層環(huán)形依賴(lài)與懸空引用的判定最后這一步是 rea 最有實(shí)用價(jià)值的部分在圖里找環(huán)、找懸空引用。環(huán)形依賴(lài)指的是 A 依賴(lài) B、B 又依賴(lài) A 的情況。在 React 項(xiàng)目里環(huán)形依賴(lài)不一定立刻讓程序崩潰但會(huì)讓模塊加載順序變得不確定容易出現(xiàn)某個(gè)組件渲染時(shí)拿到 undefined的詭異 bug而且這種 bug 非常難復(fù)現(xiàn)。rea 用深度優(yōu)先搜索遍歷有向圖一旦發(fā)現(xiàn)某個(gè)節(jié)點(diǎn)出現(xiàn)在當(dāng)前遍歷路徑上就認(rèn)定存在環(huán)并輸出完整的環(huán)路鏈路。懸空引用則有兩種情況。一種是源碼里 import 了一個(gè)不存在的路徑這通常是重構(gòu)時(shí)漏改了另一種是 import 的模塊存在但里面沒(méi)有導(dǎo)出你要的那個(gè)名字這通常是導(dǎo)出的名字被改掉了。這兩種情況 rea 都會(huì)匯總成一個(gè)斷鏈清單方便你一次性修復(fù)。需要說(shuō)明的是rea 的循環(huán)依賴(lài)檢測(cè)只是針對(duì)靜態(tài)分析的運(yùn)行時(shí)動(dòng)態(tài)創(chuàng)建依賴(lài)導(dǎo)致的環(huán)它檢測(cè)不到。但實(shí)際情況里靜態(tài)層面的循環(huán)依賴(lài)已經(jīng)覆蓋了絕大多數(shù)問(wèn)題場(chǎng)景動(dòng)態(tài)依賴(lài)那部分占比很低。4. 在真實(shí)項(xiàng)目里跑一遍安裝、掃描、報(bào)表解讀說(shuō)了這么多原理下面實(shí)際操作一遍。我用一個(gè)模擬的中后臺(tái)項(xiàng)目做演示項(xiàng)目結(jié)構(gòu)大概是這樣的src/ components/ common/ # 通用基礎(chǔ)組件比如 Button、Input、Modal business/ # 業(yè)務(wù)組件比如 UserCard、OrderTable pages/ Dashboard.tsx UserList.tsx OrderDetail.tsx utils/ format.ts request.ts App.tsx4.1 安裝與前置條件rea 是一個(gè)命令行工具全局安裝就能用。項(xiàng)目本身不要求 React 版本只要源碼是標(biāo)準(zhǔn)的 JS/TS 語(yǔ)法就行。如果項(xiàng)目用了比較新的 ECMAScript 語(yǔ)法或者實(shí)驗(yàn)性的裝飾器語(yǔ)法rea 會(huì)盡量用 AST 解析器的插件去兼容。npm i -g rea-cli安裝完成后先跑一下版本驗(yàn)證rea --version如果你更希望把它作為項(xiàng)目?jī)?nèi)的開(kāi)發(fā)依賴(lài)可以局部安裝然后用npx rea調(diào)用這樣團(tuán)隊(duì)里每個(gè)人能用的版本都能鎖定避免在我電腦上能跑的問(wèn)題。4.2 第一次掃描會(huì)得到什么進(jìn)入項(xiàng)目根目錄跑第一條命令rea scan --entry src/App.tsx --out ./rea-report--entry指定入口文件--out指定輸出目錄。跑完之后會(huì)生成幾個(gè)文件rea-report/ report.json # 全量結(jié)構(gòu)化數(shù)據(jù) overview.md # 概覽報(bào)表 dependency-graph.html # 可視化關(guān)系圖 issues.md # 問(wèn)題清單第一次掃描的結(jié)果通常會(huì)讓你吃一驚。以我自己的項(xiàng)目為例第一次跑出來(lái)這些數(shù)據(jù)全項(xiàng)目一共有 87 個(gè)組件、34 個(gè)工具模塊其中 29 個(gè)組件從來(lái)沒(méi)有任何地方引用它們也就是孤兒組件檢測(cè)到 3 組循環(huán)依賴(lài)其中一組跨了 6 個(gè)文件有一個(gè)底層組件被 74 個(gè)其他組件直接或間接引用。看到29 個(gè)組件沒(méi)人用的時(shí)候我是很震驚的。它們大多是為了某個(gè)半途而廢的功能寫(xiě)的或者被替換之后忘了刪。如果不做普查這些代碼會(huì)一直躺在倉(cāng)庫(kù)里成為新人閱讀代碼時(shí)的干擾噪音。4.3 看懂三張核心報(bào)表overview.md是一張組件依賴(lài)總表按引用數(shù)量排序所以進(jìn)入這個(gè)表格第一眼就能看到高危組件。表結(jié)構(gòu)大致是這樣組件名被引用次數(shù)被間接引用循環(huán)依賴(lài)風(fēng)險(xiǎn)等級(jí)Button74132無(wú)高危Modal4588無(wú)中危UserCard2341有高危DeprecatedBadge30無(wú)低危被引用次數(shù)高意味著改動(dòng)成本高風(fēng)險(xiǎn)等級(jí)是 rea 綜合了引用基數(shù)、間接引用量、環(huán)檢測(cè)結(jié)果算出來(lái)的。這個(gè)表不能直接決定你這個(gè)組件能不能改但能告訴你改之前要花多少精力做回歸測(cè)試。issues.md則是問(wèn)題清單會(huì)列出所有檢測(cè)到的問(wèn)題包括環(huán)路由、懸空引用、孤兒組件、副作用模塊的位置。這個(gè)清單最有價(jià)值的地方在于它給了你一個(gè)可以逐條消化的待辦列表而不是一個(gè)模糊的感覺(jué)項(xiàng)目有些問(wèn)題。HTML 可視化圖適合拉到會(huì)議室里投屏。每個(gè)組件節(jié)點(diǎn)用圓形表示顏色深淺代表引用熱度箭頭代表依賴(lài)方向。人手一點(diǎn)開(kāi)看哪里是重災(zāi)區(qū)一目了然。4.4 把 rea 接進(jìn) CI 的配置示例手動(dòng)跑一次只是清理問(wèn)題真正要讓依賴(lài)關(guān)系長(zhǎng)期可控得把它接進(jìn)持續(xù)集成流程。我推薦的做法是在代碼合并前加一步檢查依賴(lài)情況跟基線報(bào)告不一致就報(bào)警讓開(kāi)發(fā)者自己在提測(cè)前就知道影響范圍。package.json里增加一條腳本{ scripts: { rea:check: rea scan --entry src/App.tsx --compare ./rea-report/baseline.json --check-cycle --check-orphan } }--compare參數(shù)會(huì)拿當(dāng)前掃描結(jié)果跟上次的基線做差異對(duì)比如果有新增的循環(huán)依賴(lài)或者新出現(xiàn)的高危組件命令會(huì)以非零碼退出CI 就會(huì)攔截這次合并。這里提個(gè)建議CI 里跑分析時(shí)盡量選一個(gè)穩(wěn)定的入口文件不要用src全量掃描作為判斷標(biāo)準(zhǔn)。因?yàn)槿繏呙鑼?duì)每次的改動(dòng)差異太敏感很容易因?yàn)橐恍o(wú)關(guān)緊要的改名導(dǎo)致整個(gè)流水線變紅時(shí)間久了大家就不看這個(gè)檢查了。入口聚焦到某幾條核心鏈路反而能形成有意義的約束。5. 實(shí)戰(zhàn)中繞不開(kāi)的三個(gè)坑工具做出來(lái)是一回事拿到真實(shí)項(xiàng)目里跑是另一回事。rea 在反復(fù)打磨的過(guò)程中遇到了三個(gè)讓我印象很深的坑這里單獨(dú)拿出來(lái)講。5.1 動(dòng)態(tài) import 與 React.lazy 造成的盲區(qū)第一版 rea 只處理靜態(tài)的import語(yǔ)句很快就在一個(gè)項(xiàng)目上栽了跟頭。那個(gè)項(xiàng)目大量使用路由懶加載所有頁(yè)面組件都寫(xiě)在React.lazy(() import(./pages/xxx))里。rea 跑完之后頁(yè)面組件全部出現(xiàn)在孤兒組件清單里因?yàn)殪o態(tài) import 抓不到這種動(dòng)態(tài)引用的關(guān)系。這個(gè)坑的本質(zhì)是靜態(tài)分析和動(dòng)態(tài)加載天然存在盲區(qū)。但這里的盲區(qū)不是一個(gè)無(wú)解的難題因?yàn)閯?dòng)態(tài) import 的路徑參數(shù)通常是一個(gè)字符串字面量還是可以從 AST 里提取的。我后來(lái)在 rea 里加了對(duì)import()調(diào)用表達(dá)式的解析能識(shí)別出React.lazy和loadable()這幾種常見(jiàn)的動(dòng)態(tài)加載封裝的參數(shù)把動(dòng)態(tài)引用也納入依賴(lài)圖。但有一種情況只能靠約定來(lái)補(bǔ)路徑變量拼接比如import(./locales/${lang})這種動(dòng)態(tài)性太強(qiáng)任何靜態(tài)分析工具都無(wú)能為力。遇到這種代碼只能用配置的方式在 rea 里手動(dòng)聲明這層關(guān)系或者干脆接受它不在依賴(lài)圖里。5.2 路徑別名與 barrel file 帶來(lái)的假依賴(lài)第二個(gè)坑是路徑別名?，F(xiàn)在主流 React 項(xiàng)目都會(huì)配路徑別名/components/Button這種寫(xiě)法到處都是。第一版 rea 直接拿絕對(duì)路徑去做匹配結(jié)果/components/Button和../components/Button指向同一文件在依賴(lài)圖里卻被當(dāng)成了兩個(gè)不同的節(jié)點(diǎn)導(dǎo)致整個(gè)圖出現(xiàn)了大量重復(fù)節(jié)點(diǎn)引用次數(shù)統(tǒng)計(jì)嚴(yán)重失真。解決思路是對(duì)路徑做歸一化先讀取項(xiàng)目的tsconfig.json或者jsconfig.json提取paths字段的別名映射再把所有 import 的路徑根據(jù)映射關(guān)系解析成真實(shí)文件路徑最后基于真實(shí)文件路徑做去重。這里有一個(gè)優(yōu)先級(jí)問(wèn)題也一并說(shuō)一下如果項(xiàng)目里同時(shí)有tsconfig.json和webpack.config.js我建議優(yōu)先信tsconfig.json的映射因?yàn)樗?TypeScript 類(lèi)型檢查實(shí)際在用的那份配置跟代碼能成功編譯的路徑保持一致。第三個(gè)坑是 barrel file也就是index.ts這種集中轉(zhuǎn)發(fā)的文件。一個(gè)目錄里的組件都通過(guò)index.tsre-export 出去其他組件再?gòu)膇ndex.ts導(dǎo)入。這在依賴(lài)圖里會(huì)形成一層很厚的中間節(jié)點(diǎn)分析結(jié)果里出現(xiàn)大量組件 A → index.ts → 組件 B的間接路徑。rea 的默認(rèn)策略是把 barrel file 當(dāng)作透明的轉(zhuǎn)發(fā)層穿透它直接連接真實(shí)的來(lái)源組件讓依賴(lài)圖更干凈。但如果你們團(tuán)隊(duì)有意把index.ts當(dāng)作對(duì)外 API 邊界不想穿透也可以關(guān)掉這個(gè)行為。我把這三個(gè)配置項(xiàng)整理成一個(gè)速查表問(wèn)題參數(shù)作用需要掃描動(dòng)態(tài)導(dǎo)入--include-dynamic解析import()調(diào)用需要自動(dòng)讀取別名--resolve-alias-from tsconfig按 tsconfig 歸一化路徑需要穿透 index.ts--resolve-barrel穿過(guò) barrel file 直達(dá)真實(shí)組件不想穿透 barrel--keep-barrel保留中間轉(zhuǎn)發(fā)層節(jié)點(diǎn)5.3 大項(xiàng)目掃描性能與緩存策略最后一個(gè)坑是性能。第一次在一個(gè)有幾百個(gè)組件的項(xiàng)目上跑時(shí)rea 全量掃描花了將近四十秒。單次跑還能接受但接進(jìn) CI 之后每次提交都等四十秒開(kāi)發(fā)體驗(yàn)很差而且很容易導(dǎo)致流水線超時(shí)。性能瓶頸主要在兩處。一是重復(fù)解析同一個(gè)工具模塊被多個(gè)組件引用每次都在 import 解析時(shí)被重新讀文件、重新做 AST這對(duì)純函數(shù)模塊來(lái)說(shuō)是純浪費(fèi)。二是級(jí)聯(lián)分析rea 需要沿著依賴(lài)關(guān)系逐層往外找模塊數(shù)量一大遞歸展開(kāi)的路徑指數(shù)級(jí)增長(zhǎng)。優(yōu)化方案做了兩個(gè)。第一個(gè)是文件級(jí)緩存基于文件內(nèi)容哈希做緩存只有內(nèi)容變了才重新解析。第二次掃描如果項(xiàng)目沒(méi)有改動(dòng)耗時(shí)直接從四十秒降到三秒以內(nèi)。第二個(gè)是定時(shí)清理緩存每次掃描時(shí)如果發(fā)現(xiàn)緩存目錄里的條目超過(guò)一定數(shù)量或者緩存文件太老會(huì)自動(dòng)重建。這個(gè)方案讓 rea 既快又不會(huì)積累垃圾數(shù)據(jù)。6. 目前正在嘗試的幾個(gè)迭代方向rea 現(xiàn)在已經(jīng)在團(tuán)隊(duì)內(nèi)部穩(wěn)定用了幾個(gè)月效果是實(shí)打?qū)嵉?。但工具這個(gè)東西用起來(lái)之后總能看到新的可能性這里列幾個(gè)我正在嘗試的方向。6.1 讓版本控制信息參與依賴(lài)決策當(dāng)前 rea 只分析源碼現(xiàn)狀不關(guān)心歷史。一個(gè)組件被引用了一百次和另一個(gè)組件也被引用了一百次對(duì) rea 來(lái)說(shuō)風(fēng)險(xiǎn)等級(jí)一樣。但實(shí)際上這兩個(gè)組件的維護(hù)成本完全可能差很多前者三個(gè)月沒(méi)動(dòng)過(guò)很穩(wěn)定后者這周已經(jīng)被改了五回每次改都牽扯一堆人。我開(kāi)始嘗試把版本控制系統(tǒng)信息接進(jìn)來(lái)比如給每個(gè)依賴(lài)關(guān)系打上最近更新時(shí)間和變更頻率兩個(gè)標(biāo)簽。標(biāo)簽不改變依賴(lài)圖結(jié)構(gòu)只是給風(fēng)險(xiǎn)等級(jí)計(jì)算增加一個(gè)維度一個(gè)高頻變更的組件如果又是高被引用的組件那它就是這個(gè)項(xiàng)目里最值得優(yōu)先重構(gòu)的對(duì)象。6.2 從分析工具變成約束工具分析工具只負(fù)責(zé)匯報(bào)約束工具還能在代碼提交前攔住問(wèn)題。我的目標(biāo)是讓 rea check 能按團(tuán)隊(duì)自定義的規(guī)則執(zhí)行循環(huán)依賴(lài)新增攔截高危組件被新增引用超過(guò) N 次攔截并提示拆分新增孤兒組件提示確認(rèn)而非直接攔截組件目錄深度超過(guò)約定層數(shù)提示檢查是否過(guò)度嵌套。規(guī)則全部寫(xiě)在項(xiàng)目根目錄的.rea.config.json里不同項(xiàng)目可以配不同的閾值。這種紅線式的約束比讓人自學(xué)規(guī)范靠譜得多。6.3 給組件的健康打一個(gè)綜合分最后一個(gè)方向比較實(shí)驗(yàn)性把依賴(lài)圖指標(biāo)和可維護(hù)性指標(biāo)合在一起算一個(gè)組件健康分。參考維度包括被引用次數(shù)、是否存在循環(huán)依賴(lài)、組件文件行數(shù)、導(dǎo)出結(jié)構(gòu)是否單一、是否在測(cè)試文件和業(yè)務(wù)文件里被同時(shí)引用。健康分不追求工程學(xué)正確只是想讓團(tuán)隊(duì)在談代碼好壞時(shí)能有一個(gè)直觀的數(shù)字抓手。把這個(gè)數(shù)字展示在組件的開(kāi)發(fā)文檔頁(yè)面里每周自動(dòng)刷新一次讓技術(shù)債變得可見(jiàn)。技術(shù)債不可怕可怕的是看不見(jiàn)。最后再分享兩個(gè)小技巧從項(xiàng)目立項(xiàng)到穩(wěn)定使用其實(shí)整個(gè)周期不到一個(gè)月但收益遠(yuǎn)超預(yù)期。最大的收獲不是那些報(bào)表本身而是團(tuán)隊(duì)開(kāi)始用同一套語(yǔ)言討論組件邊界了——這個(gè)組件是重度的動(dòng)它要小心終于有了數(shù)據(jù)支撐而不是憑感覺(jué)。最后送兩個(gè)小技巧。第一個(gè)排查老項(xiàng)目問(wèn)題時(shí)先跑rea scan --entry src/App.tsx它會(huì)產(chǎn)出一份當(dāng)下最新的依賴(lài)清單比你在代碼里一個(gè)文件一個(gè)文件地點(diǎn)要全面得多。第二個(gè)如果你的項(xiàng)目里 tsconfig 和 webpack 的別名配置不一致rea 默認(rèn)會(huì)讀取 tsconfig經(jīng)常對(duì)不上的建議把 webpack 的 resolve.alias 統(tǒng)一到 tsconfig 同源一勞永逸。依賴(lài)關(guān)系從來(lái)不會(huì)因?yàn)槟悴豢此筒淮嬖?。早一點(diǎn)把它拉出來(lái)擺到桌面上改代碼的時(shí)候會(huì)踏實(shí)很多。