)
rea這個項目名乍一看確實容易讓人一頭霧水三個字母沒有官方解釋也沒有配套文檔。我最早接觸它是在某次接手一個遺留系統(tǒng)的時候——代碼倉庫里躺著一個叫rea的目錄里面全是一堆以rea_開頭的腳本文件。當時的第一反應是“這是什么鬼”翻了兩天之后才明白它是一個被團隊內部用慣了但從來沒正式命名過的代碼結構梳理工具。后來我花了兩周時間把它重寫、補全、做成一個可復用的命令行工具再后來它就成了我自己日常開發(fā)中離不開的一個小工具箱。我在博客里分享過不少項目但這是第一次認真復盤rea本身的來龍去脈。如果你正在做一個代碼量失控的項目、需要一個能快速看清全局的工具或者你也想打造一個屬于自己、貼合自己工作習慣的開發(fā)者工具這篇文章應該對你有用。我會把從最初的需求分析、到核心模塊實現(xiàn)、再到上線后踩過的一堆坑全部串起來講盡量給你一份能直接照著落地的參考方案。1. 項目整體設計與思路拆解1.1 它到底解決什么問題先說最核心的那個問題為什么需要一個叫rea的東西。當時那個遺留系統(tǒng)技術棧不算復雜Spring Boot 后端加一個 Vue 前端代碼規(guī)模也不到十萬行。但問題在于這個項目經歷了多輪維護前后好幾個團隊都往里加過東西目錄結構已經變得非常混亂。具體表現(xiàn)有這么幾種同一個功能模塊的代碼分散在四五個不同的目錄里彼此之間通過相對路徑互相引用。有些類文件明明已經沒人在用了但因為沒人敢刪就一直躺在deprecated目錄里占據(jù)空間。前端的資源文件命名完全沒有規(guī)范新建文檔(最終版).js這種名字都能出現(xiàn)。最讓人頭疼的是沒有人能說清楚整個項目的依賴關系到底長什么樣。我當時的任務是在這個系統(tǒng)上加一個新功能。按理說這是一個很常規(guī)的開發(fā)任務但實際花費的時間里有一半以上都用在了“找代碼”而不是“寫代碼”上。每改一個地方都要先在 IDE 里搜半天上下游調用生怕漏掉哪個隱式依賴導致上線出問題。rea最初的形態(tài)就是為解決“理清項目結構”這個痛點而寫的一個命令行工具。它的作用很簡單遞歸掃描項目的所有源文件提取每一個文件中定義的函數(shù)、類、變量同時分析文件之間的引用關系最后生成一份結構化的報告告訴你項目里有哪些關鍵節(jié)點、哪些模塊被依賴得最多、哪些文件是無人問津的死代碼候選對象。1.2 為什么不直接用現(xiàn)成工具聊到這里可能有人會問代碼覆蓋率工具、依賴分析工具、SonarQube 這些,市面上不是有大把現(xiàn)成的嗎為什么還要自己造輪子這個問題的答案我認為恰恰是rea這個項目最有價值的地方?，F(xiàn)成的工具確實功能強大但它們普遍存在兩個問題。第一個問題是重量級很多分析工具需要你把整個項目導入、配置數(shù)據(jù)庫、等待后臺任務跑完才能看到結果。對于一個只想快速搞清楚一個項目大概結構的開發(fā)者來說這個流程太笨重了。第二個問題是不靈活工具輸出的是它定義好的指標體系而不是你當下最關心的那幾個問題。我當時需要的其實是一個非常輕量、能按需擴展、結果一眼能看懂的東西。rea的設計哲學由此確定單命令、無配置、純靜態(tài)掃描、輸出可讀性優(yōu)先。它不需要在項目里安裝任何插件不需要建立索引數(shù)據(jù)庫也不需要聯(lián)網。你在命令行里對項目根目錄執(zhí)行一條命令幾秒鐘之后就能拿到一份簡潔的報告。這個設計思路就像你家里工具箱里那把最常用的螺絲刀——不需要電動不需要一堆替換頭就是一把趁手、順手、永遠不會壞的工具。1.3 技術選型背后的思考技術選型上我選擇了 Node.js 作為運行環(huán)境用純 JavaScript 實現(xiàn)不依賴任何第三方庫?，F(xiàn)在回頭看這個決定大致是合理的但中間也走過一些彎路。一開始我其實考慮過用 Python 寫因為 Python 處理文本和正則表達式確實方便而且我本人也更熟悉 Python。但后來想清楚了兩個問題目標用戶包括我自己日常主要工作在 Node 生態(tài)里用 Node 寫出來的工具后續(xù)如果要擴展成 IDE 插件或者對接前端構建流程會順暢得多。Node 在文件系統(tǒng)操作方面擁有非常完善的 API對讀取目錄樹這類需求支持得很好。至于為什么不依賴第三方庫理由就更實際了這個工具的核心功能就是讀文件、做匹配、統(tǒng)計計數(shù)、輸出結果這些用 Node 自帶模塊完全可以搞定。每引入一個依賴都意味著未來的維護成本、安全風險、版本兼容問題。為了這么一個小工具去引入依賴樹實在劃不來。這里補充一個我后來才意識到的問題。純 JavaScript 腳本在遇到大項目時性能確實會成為一個瓶頸。印象最深的一次是在一個大型電商系統(tǒng)上跑rea源文件總數(shù)超過五萬個直接跑崩了。后來我用 Worker 線程池做了并發(fā)掃描改造才把耗時控制在一個可接受的范圍內。這個優(yōu)化過程我在后面的實操部分詳細講。2. 核心功能拆解與實操要點rea的功能并不花哨核心就是三件事掃描、分析、報告。下面一個一個拆開說。2.1 文件掃描模塊的設計文件掃描是整個工具的基石。這一步做不好后面所有的分析都是空中樓閣。掃描模塊的核心需求有三個能遞歸遍歷目錄、能按規(guī)則過濾掉不需要分析的文件、能采集到足夠多的文件元數(shù)據(jù)。第一版的實現(xiàn)非常簡單就是用fs.readdirSync配合fs.statSync做一個深度優(yōu)先遍歷。核心邏輯說出來大家都能懂const fs require(fs); const path require(path); class Scanner { constructor(projectRoot, ignoredPatterns) { this.projectRoot projectRoot; this.ignoredPatterns ignoredPatterns; this.fileList []; } walk(dir) { const entries fs.readdirSync(dir, { withFileTypes: true }); for (const entry of entries) { if (this.shouldIgnore(entry.name)) continue; const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { this.walk(fullPath); } else if (entry.isFile()) { this.fileList.push({ path: fullPath, ext: path.extname(entry.name), name: entry.name, size: fs.statSync(fullPath).size }); } } } shouldIgnore(name) { return this.ignoredPatterns.some((pattern) pattern.test(name)); } }這套實現(xiàn)足夠應對大多數(shù)中小型項目。但在這里我要提一個實際踩過的坑把同步遍歷寫進一個遞歸函數(shù)里一旦項目文件層級特別深很容易爆棧。我們當時那個項目里有一個測試目錄嵌套層級最深的地方超過了四十層遞歸調用的時候棧幀積累得非?？?。雖然一開始沒有直接崩潰但性能明顯下降掃描耗時達到了二十多秒。后來我改成了顯式使用棧數(shù)據(jù)結構來遍歷而不是依賴函數(shù)調用棧walk(root) { const stack [root]; while (stack.length 0) { const currentDir stack.pop(); const entries fs.readdirSync(currentDir, { withFileTypes: true }); for (const entry of entries) { if (this.shouldIgnore(entry.name)) continue; const fullPath path.join(currentDir, entry.name); if (entry.isDirectory()) { stack.push(fullPath); } else if (entry.isFile()) { this.fileList.push({ path: fullPath, ext: path.extname(entry.name), name: entry.name, size: fs.statSync(fullPath).size }); } } } }這里我想多啰嗦一句很多新手容易忽略withFileTypes: true這個參數(shù)。如果不用這個參數(shù)readdirSync返回的是字符串數(shù)組你得對每個路徑單獨調用fs.statSync來判斷它是文件還是目錄。這相當于多了一次系統(tǒng)調用在文件數(shù)量龐大的時候損耗非?？捎^。用了withFileTypes之后Dirent對象直接提供了isFile()、isDirectory()方法節(jié)省了額外一次stat的開銷。2.2 依賴分析模塊的算法選擇掃描到文件列表之后緊接著要做的事情是分析依賴關系。這里所謂的依賴不單指代碼里的import或require語句還包括自定義函數(shù)之間的調用。對于 JavaScript 項目要精準分析函數(shù)級調用關系難度非常大,因為 JavaScript 是動態(tài)語言運行時綁定、回調函數(shù)、閉包這些特性都讓靜態(tài)分析變得很費勁。所以我在第一版設計時做了一個戰(zhàn)略取舍不做精確的函數(shù)調用分析只做模塊級的依賴分析。具體來說就是用正則表達式把每個文件中出現(xiàn)的import ... from ...、require(...)、const xxx require(...)、import(...)這幾種常見的引用形式全部提取出來再對引用路徑做規(guī)范化處理最終生成一張以文件為節(jié)點、以引用關系為邊的依賴圖。這個思路的好處用一個詞概括就是“夠用”。我需要的不是一張完美的代碼架構圖而是一個能告訴我在改動某個文件時哪些地方可能需要聯(lián)動調整的清單。這個場景下解析到模塊級別足夠了。提取引用關系的邏輯大致是這樣const IMPORT_PATTERN /(?:import\s[\s\S]*?from\s*[]([^])[]|require\s*\(\s*[]([^])[]\s*\))/g; function extractDependencies(sourceCode) { const deps []; let match; while ((match IMPORT_PATTERN.exec(sourceCode)) ! null) { const rawPath match[1] || match[2]; if (rawPath !rawPath.startsWith(.) !rawPath.startsWith(/)) { continue; // 第三方包不做深入分析 } deps.push(normalizePath(rawPath)); } return deps; }這里有一個細節(jié)值得注意我在匹配第三方包時直接跳過了。因為rea關注的永遠是項目內部模塊之間的關系node_modules里的依賴再復雜也不是這個工具要管的范疇。強行分析第三方包既浪費性能又會讓報告變得嘈雜難讀。規(guī)范化路徑這步也很關鍵。假設一個文件位于src/utils/helpers.js它引用了../constants.js那么我在報告里應該展示的是src/constants.js而不是../constants.js否則后面做聚合統(tǒng)計的時候就無從下手了。路徑規(guī)范化的實現(xiàn)const path require(path); function normalizePath(rawPath, currentFilePath) { if (rawPath.startsWith(/)) { return path.normalize(rawPath); } const absolutePath path.resolve(path.dirname(currentFilePath), rawPath); return path.relative(process.cwd(), absolutePath); }用path.resolve先把相對路徑轉為絕對路徑再用path.relative把絕對路徑轉為相對于項目根目錄的路徑。這樣整理出來的依賴關系每一行都是可追溯、可點擊的。2.3 報告生成的人性化設計分析做完以后如何呈現(xiàn)結果是一個非常值得琢磨的問題。我見過不少工具分析做得很深入但輸出結果是一大堆 JSON開發(fā)者看完之后依舊一頭霧水。rea從一開始就明確了一件事最終交付物必須是人類可讀的純文本報告。第一版報告長這樣Project: demo-shop Generated at: 2025-06-14 10:23:01 規(guī)模概況 Total files: 1,234 Total lines of code: 78,942 Total dependencies (internal): 3,215 高風險模塊 Top 10 1. src/order/service.js (127 inward refs) 2. src/user/session.js (98 inward refs) 3. src/payment/gateway.js (76 inward refs) ... 孤立文件候選 - src/legacy/migrate_old.js (no inward refs, 0 outward refs) - src/pages/UnusedPage.vue (no inward refs, 0 outward refs) ...這個報告看起來不復雜但需要在背后完成兩件很重要的事。第一件事是統(tǒng)計每個文件的被引用次數(shù)。這就需要一個從目標路徑到引用來源列表的反向映射表構建方式很簡單在收集依賴關系的時候每發(fā)現(xiàn)一條引用就在目標文件對應的集合里加一個來源。第二件事是判斷“孤立文件”。如果某個文件在內部分析中既沒有被其他文件引用它本身也沒有引用任何內部文件那么它極大概率是從某個版本的迭代中殘留下來的廢棄代碼。注意這只是“候選”——因為動態(tài)加載、反射調用、配置文件引用這些情況靜態(tài)分析是捕捉不到的。所以報告里會用“候選”這個詞提醒使用者不要直接照單全收。2.4 并發(fā)掃描的優(yōu)化方案如果你只在小項目上用過rea那你可能永遠不會遇到這一節(jié)要講的問題。但一旦跑大型項目性能問題就會立刻浮現(xiàn)。我前面提到在一個五萬文件的電商項目上第一版rea直接跑崩了。這里所謂的“崩”不是內存溢出而是耗時長得不可接受。當時我用計時器量了一下掃描耗時就占了兩分多鐘而理想狀況下一個命令行工具是不應該在交互時讓人等待這么久的。性能瓶頸主要出在fs.statSync這個調用上。當年我在遍歷目錄的時候每遇到一個文件都會調用一次fs.statSync獲取文件大小。五萬個文件就意味著五萬次同步的系統(tǒng)調用這個開銷非?？捎^。優(yōu)化方案有兩個方向可以選擇一個是改用fs.promises做異步 IO另一個是用 Worker 線程池做并行掃描。我最終把兩個方向結合了。用 Worker 線程池改造的思路是主線程把項目根目錄下的頂層子目錄分發(fā)給若干個 Worker每個 Worker 負責掃描自己分到的子目錄把結果序列化后傳回主線程。這個過程有點像把一個大倉庫的盤點工作分給幾組人同時做每組只負責自己的片區(qū)最后再把匯總結果合起來。這里我給出一個簡化版的線程池實現(xiàn)思路const { Worker } require(worker_threads); function parallelScan(roots) { const workers roots.map((root, index) new Promise((resolve, reject) { const worker new Worker(TASK_FILE, { workerData: { root, index } }); worker.on(message, resolve); worker.on(error, reject); })); return Promise.all(workers); }不過要提醒大家Worker 線程用起來隨手就能寫但序列化和反序列化fileList的開銷也不小。當時測試下來文件數(shù)量在三千以下時單線程和線程池的耗時幾乎沒有區(qū)別甚至線程池還更慢一些。只有文件數(shù)量超過一萬時線程池的收益才明顯體現(xiàn)出來。所以如果你的項目規(guī)模沒到這個量級沒必要盲目上并發(fā)先看看是不是被其他低效操作拖了后腿。3. 實操過程與核心環(huán)節(jié)實現(xiàn)理論部分說完了接下來是實戰(zhàn)環(huán)節(jié)。我的經驗是做工具類項目先搭一個可以用起來的骨架再逐步加功能比一開始就追求大而全要高效得多。3.1 環(huán)境準備與項目初始化rea的運行環(huán)境要求是 Node.js 14 及以上原因很簡單舊版本不支持fs.readdirSync的withFileTypes參數(shù)其實這個參數(shù)在 10.10 就引入 了但我建議直接給個更寬松的底線。項目初始化用的是npm init -y它會自動生成一個package.json。我習慣在項目里加上bin字段這樣就能通過npm link把命令安裝成全局命令{ name: rea, version: 0.1.0, description: A lightweight static analysis tool for project structure, main: src/index.js, bin: { rea: src/index.js }, engines: { node: 14.0.0 } }文件目錄結構我采用了很常見的模式rea/ ├── src/ │ ├── index.js # 入口文件命令分發(fā) │ ├── scanner.js # 目錄掃描模塊 │ ├── analyzer.js # 依賴分析模塊 │ ├── reporter.js # 報告生成模塊 │ └── utils.js # 通用工具 ├── test/ │ └── fixtures/ # 測試用的臨時項目 └── package.json入口文件的寫法非常簡單就是解析命令行參數(shù)然后按指令調用不同模塊#!/usr/bin/env node const { scanner } require(./scanner); const { analyzer } require(./analyzer); const { reporter } require(./reporter); async function main() { const projectRoot process.argv[2] || .; const scanStart Date.now(); const fileList await scanner.scan(projectRoot); const analysis analyzer.analyze(fileList); const elapsed Date.now() - scanStart; console.log(reporter.render(projectRoot, analysis, elapsed)); } main().catch((err) { console.error([rea] Error:, err.message); process.exit(1); });這一版沒有引入 commander 之類的參數(shù)解析庫。因為它目前只需要一個參數(shù)項目路徑。將來如果增加了更多命令再考慮引入?yún)?shù)解析框架也不遲。我一直堅持一個原則不過早引入復雜度。3.2 依賴分析模塊的完整實現(xiàn)依賴分析模塊是這個工具的核心大腦。這里我貼出完整實現(xiàn)并逐行解釋關鍵邏輯。class Analyzer { constructor(fileList) { this.fileList fileList; this.nodeMap new Map(); // 存儲每個文件節(jié)點 this.edgeList []; } analyze() { for (const file of this.fileList) { const source this._readFile(file.path); const deps extractDependencies(source, file.path); file.deps deps; this.nodeMap.set(file.path, file); } this._buildReverseMap(); return { nodes: this.nodeMap, edges: this.edgeList }; } _readFile(filePath) { try { return fs.readFileSync(filePath, utf-8); } catch (err) { return ; } } _buildReverseMap() { for (const [targetPath] of this.nodeMap) { this.nodeMap.get(targetPath).inwardRefs []; } for (const file of this.fileList) { for (const dep of file.deps) { // 只統(tǒng)計存在對應文件節(jié)點的依賴 if (this.nodeMap.has(dep)) { this.nodeMap.get(dep).inwardRefs.push(file.path); this.edgeList.push({ from: file.path, to: dep }); } } } } }這里有幾個需要特別留意的點。第一個_buildReverseMap里的inwardRefs初始化放到了外層循環(huán)里。如果你直接把inwardRefs初始化寫進_readFile那一步那么每個文件被訪問的先后順序就會影響最終結果這是典型的初始化順序陷阱。第二個import解析用的是正則表達式必然存在誤報和漏報的可能。比如代碼中有被注釋掉的require語句或者寫在字符串里的import字樣正則都會把它們誤判為真實依賴。如果是做嚴謹?shù)纳暇€檢查這顯然不合格但如果目標是快速生成一份“值得人工查看的候選清單”這個精度足夠了。當工具的目標定位是提供線索而不是給出裁決時不完美是可以接受的。第三個我在正則里特別處理了動態(tài)導入import()因為現(xiàn)代代碼中按需加載的場景太常見了忽略它會漏掉很多真實的運行時依賴。3.3 報告渲染引擎的實現(xiàn)報告部分的目標是盡量保持簡潔同時信息密度足夠高。我不建議直接輸出一個超大表格開發(fā)者在終端里滾動幾百行體驗很差。所以我做了一套“摘要 重點列表”的結構。渲染邏輯的核心其實是一個排序與截斷的過程function renderReport(projectRoot, analysis, elapsed) { const nodes [...analysis.nodes.values()]; const totalFiles nodes.length; let totalLines 0; for (const node of nodes) { totalLines countLines(node); } const lines []; lines.push(Project: ${projectRoot}); lines.push(Generated at: ${new Date().toLocaleString()}); lines.push(); lines.push( 規(guī)模概況 ); lines.push(Total files: ${totalFiles.toLocaleString()}); lines.push(Total lines of code: ${totalLines.toLocaleString()}); lines.push(Total internal edges: ${analysis.edges.length.toLocaleString()}); lines.push(); const sortedByInward nodes .sort((a, b) b.inwardRefs.length - a.inwardRefs.length); lines.push( 高風險模塊 Top 10 ); for (const file of sortedByInward.slice(0, 10)) { lines.push(${file.path} (${file.inwardRefs.length} inward refs)); } lines.push(); const isolatedFiles nodes.filter( (file) file.inwardRefs.length 0 file.deps.length 0 ); lines.push( 孤立文件候選 ); if (isolatedFiles.length 0) { lines.push((none)); } else { for (const file of isolatedFiles.slice(0, 20)) { lines.push(- ${file.path}); } } lines.push(); return lines.join(\n); }這個渲染函數(shù)雖然看起來很長但邏輯非常簡單聚合數(shù)據(jù)、排序、取前 N 個、拼接字符串。它的設計目標就是讓使用者在十秒鐘之內抓住項目的核心風險點。3.4 從第一版到可發(fā)布版本的過程寫第一版只用了兩三個小時但rea真正變成可用的工具是經歷了比較長的迭代之后。第一版跑通后我遇到的最大問題其實不是技術難點而是“輸出結果讓人看不明白”。比如報告里出現(xiàn)的孤立文件候選有接近一半其實是前端項目在構建時期引用的less變量文件——它們雖然不被任何 JS 文件直接引用但是在編譯期起著非常重要的作用。如果我只簡單地輸出一個候選列表使用者大概率會誤判。為了解決這個問題我在分析階段加入了一個“文件類型分組”的維度。針對特定的文件擴展名如.less、.scss、.md、.json打上特殊標簽在報告中用不同的標記提示使用者這些文件不適用“孤立”判斷。這個改動雖然不復雜卻極大地提高了報告的實用價值。另一個重要的迭代是支持.reaignore文件類似于.gitignore的機制。因為有些目錄比如自動生成的 mock 數(shù)據(jù)目錄根本不應該參與分析強行分析只會制造噪音。這個功能寫起來很簡單就是多讀一個配置文件把其中的每個模式追加到忽略列表里。4. 實操過程記錄一次真實的使用案例光講原理不落地總感覺少了點什么。這里我復盤一次用rea分析一個實際項目以下代稱為模擬項目X的完整過程包括中間遇到的小狀況。4.1 準備階段搭建一個棘手項目模擬項目X 是一個典型的早期 Web 應用體量中等偏下但結構非常雜亂。它的源代碼目錄長這樣project-x/ ├── src/ │ ├── api/ │ ├── components/ │ │ ├── core/ │ │ └── legacy/ │ ├── pages/ │ ├── styles/ │ ├── utils/ │ └── vendor-patches/ # 放了一些從網上復制來的第三方補丁 ├── scripts/ │ ├── build.js │ └── deploy.sh ├── mock/ └── docs/我預想中的難點有兩個vendor-patches目錄里的補丁代碼引用了很多古老的文件路徑mock目錄里有一大堆自動生成的數(shù)據(jù)文件它們不參與運行但會干擾依賴分析。我在項目根目錄創(chuàng)建了.reaignore文件mock/ vendor-patches/然后把rea工具放到 PATH 中準備執(zhí)行掃描。4.2 第一次運行結果與分析執(zhí)行命令rea ./project-x輸出的報告節(jié)選如下Project: ./project-x Generated at: 2025-06-14 10:23:01 規(guī)模概況 Total files: 846 Total lines of code: 51,239 Total internal edges: 1,082 高風險模塊 Top 10 1. src/api/request.js (124 inward refs) 2. src/components/core/Table.js (78 inward refs) 3. src/pages/dashboard/index.js (61 inward refs) 4. src/styles/theme.js (54 inward refs) 5. src/components/core/Form.js (50 inward refs) ...看到這個結果我基本可以判斷模擬項目X的核心問題在哪了src/api/request.js被一百多個文件直接引用這意味著任何對這個文件的小改動都可能波及全項目所有的 API 調用。用《重構》里的術語來說這就是典型的“霰彈式修改”高危點。順著這個線索我抽查了幾個引用request.js的頁面組件發(fā)現(xiàn)它們確實共用了一個全局的請求實例而且這個實例硬編碼了一些業(yè)務參數(shù)。后面如果要改造項目這個文件必然是第一優(yōu)先級。4.3 深入排查孤立文件候選的甄別接著往下看報告中的孤立文件候選 孤立文件候選 - src/styles/dark-theme.css - src/pages/settings/profile_v2.js - src/pages/settings/profile_v1.js - src/utils/legacy_format.js注意最后這兩個文件profile_v1.js和profile_v2.js。二者都不被引用但顯然存在一個版本切換關系。通過查看git log我發(fā)現(xiàn)profile_v1.js確實已經被替代而profile_v2.js是通過路由懶加載方式引用的所以靜態(tài)分析掃不到。這個案例很好地說明了一個問題孤立文件候選不是終點而是下一步人工排查的起點。如果自動化工具能直接告訴你哪些代碼可以被刪除那它就不再是輔助工具而是代碼庫的替代者了。4.4 針對模擬項目X的優(yōu)化建議基于rea生成的報告我很快就整理出了幾條優(yōu)化建議將request.js中的基礎 API 封裝拆分為獨立的小函數(shù)同時增加對全局請求實例的注入方式。刪除profile_v1.js以及與其相關的樣式文件。把utils/legacy_format.js中有價值的方法合并到utils/format.js確保沒有邏輯重復。在mock數(shù)據(jù)入口處增加統(tǒng)一的出口配置避免散落各處導致的認知負擔。這些建議談不上高大上但他們建立在完整掃描結果之上因此每一處改動都有明確的依據(jù)減少了憑空猜測帶來的風險。5. 常見問題與排查技巧實錄工具開發(fā)到后期我陸陸續(xù)續(xù)遇到并解決了一些典型的工程問題。這里挑幾個最有代表性的問題做個速查表也方便你將來使用或仿寫類似工具時能夠繞開這些坑。問題原因排查技巧解決方案掃描大目錄耗時過長同步 IO 操作過多用perf_hooks分階段計時定位耗時集中在掃描還是分析切換到異步 IO 或 Worker 線程池報告中有大量誤報的孤立文件靜態(tài)分析無法覆蓋動態(tài)引用抽樣核查個別文件檢查是否存在import()或配置式引用引入文件類型分組和.reaignore機制require路徑解析 alias 導致依賴匹配不上構建工具里配置了模塊別名在報告里輸出一條“未匹配 dependency”匯總在工具里增加別名映射配置文件運行環(huán)境 Node 版本過低導致崩潰使用了較新的 API查看堆棧信息定位具體 API明確最低環(huán)境要求啟動時做版本檢查文件編碼不統(tǒng)一導致亂碼GBK 編碼的文件被當 UTF-8 讀取觀察到輸出中文亂碼時不應盲目跳過讀取時嘗試多種編碼解碼并在報告中標記編碼識別結果Worker 線程數(shù)據(jù)序列化開銷大傳輸海量文件列表對比單線程與線程池在閾值前后的表現(xiàn)低于閾值時自動退化為單線程模式除了這些常見問題之外再分享幾個我平時用得比較多的小技巧。第一個技巧在調試rea時我喜歡先用一個小型 fixture 項目做驗證而不是直接跑真實大項目。fixture 項目里就放三五個人為制造的依賴關系比如 a 引用 bb 引用 cc 又引用 a用來驗證循環(huán)依賴是否能被正確識別。用這種微型案例調試效率遠高于在大項目里糊里糊涂找 bug。第二個技巧輸出中間態(tài)調試信息。我在工具中加了一個--debug參數(shù)它會額外打印出掃描階段的文件數(shù)量、每個階段耗時、依賴解析失敗的路徑列表。這些信息在定位問題時價值極高。第三個技巧把工具的源碼納入自己的日常代碼習慣之中。rea雖然是一個工具項目但它同樣需要版本管理、測試用例、代碼風格統(tǒng)一。我把它推到一個私有倉庫里每次修復完 bug 都加一個針對性的測試防止后續(xù)改其他地方時把修好的問題又帶出來。第四個技巧也是我認為最重要的不要把工具的定位搞錯。rea的產出是線索不是結論。我在最初幾版的使用中曾因為過度信任“孤立文件候選”列表差點把一個動態(tài)組件給刪了。從那以后我堅持在報告首頁頂部加一句提示所有分析結果均需人工復核。這句話雖然簡單卻在很大程度上避免了使用者過度依賴工具帶來的災難。6. 后續(xù)擴展方向與個人經驗總結rea目前能做的事情已經足夠解決我百分之八十的結構梳理需求但它的擴展空間依然很大。如果時間允許我大概率會在三個方向繼續(xù)打磨。第一個方向是支持更多語言。目前依賴解析主要針對 JavaScript 和 TypeScript 生態(tài)輸出報告的時候也會刻意區(qū)分.js、.jsx、.ts、.tsx。但實際項目里很可能一個倉庫同時包含 Java、Python、甚至 Go 代碼。只要針對每種語言補充對應的解析規(guī)則rea就可以變成一種真正意義上的多語言項目結構分析工具。第二個方向是輸出可視化的依賴圖。現(xiàn)在終端文本報告雖然好讀但面對大型項目時一張能夠讓用戶拖動、縮放、聚焦的交互式圖表會帶來更直觀的體驗。我計劃在未來版本中把分析結果同時輸出一份 JSON 或 DOT 格式方便接入其他可視化工具。第三個方向是提供增量掃描能力。每次全量掃描雖然已經足夠快但如果在 git 提交后只想分析本次變更涉及了多少上下游文件增量模式會實用得多。最后說一點個人體會。我做過不少工具rea不是技術含量最高的一個但它是我認為“性價比”最高的一個。它解決的問題非常具體非常貼近日常開發(fā)的真實痛點而且它本身并不復雜——一個會點 Node.js 的開發(fā)者幾天時間就能寫出類似的工具。如果你正在為“看不懂項目結構”而頭疼我的建議是先別急著重構或換框架花點時間寫一個像rea這樣的小工具把項目的真實面貌摸清楚。很多所謂架構混亂的問題在理清依賴關系之后往往會自動暴露出清晰的解決路徑。你自己寫出來的工具以后改起來也特別順手因為它的每一行代碼都貼合你自己的腦回路。還有一個我始終忘不掉的經驗。在我第一次重寫rea的那個周期里我曾因為想加一個“自動重構建議”功能而差點把工具本身給拖垮。后來我把它砍掉了因為這個功能需要的智能程度遠超一個命令行工具的范疇。做工具最忌貪多一個工具能專注地把一件事做好就已經非常出色了。這句話我現(xiàn)在送給所有在造輪子的朋友也包括未來的我自己。 rea：一個輕量級項目結構分析工具的設計與實現(xiàn)
rea這個項目名乍一看確實容易讓人一頭霧水三個字母沒有官方解釋也沒有配套文檔。我最早接觸它是在某次接手一個遺留系統(tǒng)的時候——代碼倉庫里躺著一個叫rea的目錄里面全是一堆以rea_開頭的腳本文件。當時的第一反應是“這是什么鬼”翻了兩天之后才明白它是一個被團隊內部用慣了但從來沒正式命名過的代碼結構梳理工具。后來我花了兩周時間把它重寫、補全、做成一個可復用的命令行工具再后來它就成了我自己日常開發(fā)中離不開的一個小工具箱。我在博客里分享過不少項目但這是第一次認真復盤rea本身的來龍去脈。如果你正在做一個代碼量失控的項目、需要一個能快速看清全局的工具或者你也想打造一個屬于自己、貼合自己工作習慣的開發(fā)者工具這篇文章應該對你有用。我會把從最初的需求分析、到核心模塊實現(xiàn)、再到上線后踩過的一堆坑全部串起來講盡量給你一份能直接照著落地的參考方案。1. 項目整體設計與思路拆解1.1 它到底解決什么問題先說最核心的那個問題為什么需要一個叫rea的東西。當時那個遺留系統(tǒng)技術棧不算復雜Spring Boot 后端加一個 Vue 前端代碼規(guī)模也不到十萬行。但問題在于這個項目經歷了多輪維護前后好幾個團隊都往里加過東西目錄結構已經變得非常混亂。具體表現(xiàn)有這么幾種同一個功能模塊的代碼分散在四五個不同的目錄里彼此之間通過相對路徑互相引用。有些類文件明明已經沒人在用了但因為沒人敢刪就一直躺在deprecated目錄里占據(jù)空間。前端的資源文件命名完全沒有規(guī)范新建文檔(最終版).js這種名字都能出現(xiàn)。最讓人頭疼的是沒有人能說清楚整個項目的依賴關系到底長什么樣。我當時的任務是在這個系統(tǒng)上加一個新功能。按理說這是一個很常規(guī)的開發(fā)任務但實際花費的時間里有一半以上都用在了“找代碼”而不是“寫代碼”上。每改一個地方都要先在 IDE 里搜半天上下游調用生怕漏掉哪個隱式依賴導致上線出問題。rea最初的形態(tài)就是為解決“理清項目結構”這個痛點而寫的一個命令行工具。它的作用很簡單遞歸掃描項目的所有源文件提取每一個文件中定義的函數(shù)、類、變量同時分析文件之間的引用關系最后生成一份結構化的報告告訴你項目里有哪些關鍵節(jié)點、哪些模塊被依賴得最多、哪些文件是無人問津的死代碼候選對象。1.2 為什么不直接用現(xiàn)成工具聊到這里可能有人會問代碼覆蓋率工具、依賴分析工具、SonarQube 這些,市面上不是有大把現(xiàn)成的嗎為什么還要自己造輪子這個問題的答案我認為恰恰是rea這個項目最有價值的地方?，F(xiàn)成的工具確實功能強大但它們普遍存在兩個問題。第一個問題是重量級很多分析工具需要你把整個項目導入、配置數(shù)據(jù)庫、等待后臺任務跑完才能看到結果。對于一個只想快速搞清楚一個項目大概結構的開發(fā)者來說這個流程太笨重了。第二個問題是不靈活工具輸出的是它定義好的指標體系而不是你當下最關心的那幾個問題。我當時需要的其實是一個非常輕量、能按需擴展、結果一眼能看懂的東西。rea的設計哲學由此確定單命令、無配置、純靜態(tài)掃描、輸出可讀性優(yōu)先。它不需要在項目里安裝任何插件不需要建立索引數(shù)據(jù)庫也不需要聯(lián)網。你在命令行里對項目根目錄執(zhí)行一條命令幾秒鐘之后就能拿到一份簡潔的報告。這個設計思路就像你家里工具箱里那把最常用的螺絲刀——不需要電動不需要一堆替換頭就是一把趁手、順手、永遠不會壞的工具。1.3 技術選型背后的思考技術選型上我選擇了 Node.js 作為運行環(huán)境用純 JavaScript 實現(xiàn)不依賴任何第三方庫?，F(xiàn)在回頭看這個決定大致是合理的但中間也走過一些彎路。一開始我其實考慮過用 Python 寫因為 Python 處理文本和正則表達式確實方便而且我本人也更熟悉 Python。但后來想清楚了兩個問題目標用戶包括我自己日常主要工作在 Node 生態(tài)里用 Node 寫出來的工具后續(xù)如果要擴展成 IDE 插件或者對接前端構建流程會順暢得多。Node 在文件系統(tǒng)操作方面擁有非常完善的 API對讀取目錄樹這類需求支持得很好。至于為什么不依賴第三方庫理由就更實際了這個工具的核心功能就是讀文件、做匹配、統(tǒng)計計數(shù)、輸出結果這些用 Node 自帶模塊完全可以搞定。每引入一個依賴都意味著未來的維護成本、安全風險、版本兼容問題。為了這么一個小工具去引入依賴樹實在劃不來。這里補充一個我后來才意識到的問題。純 JavaScript 腳本在遇到大項目時性能確實會成為一個瓶頸。印象最深的一次是在一個大型電商系統(tǒng)上跑rea源文件總數(shù)超過五萬個直接跑崩了。后來我用 Worker 線程池做了并發(fā)掃描改造才把耗時控制在一個可接受的范圍內。這個優(yōu)化過程我在后面的實操部分詳細講。2. 核心功能拆解與實操要點rea的功能并不花哨核心就是三件事掃描、分析、報告。下面一個一個拆開說。2.1 文件掃描模塊的設計文件掃描是整個工具的基石。這一步做不好后面所有的分析都是空中樓閣。掃描模塊的核心需求有三個能遞歸遍歷目錄、能按規(guī)則過濾掉不需要分析的文件、能采集到足夠多的文件元數(shù)據(jù)。第一版的實現(xiàn)非常簡單就是用fs.readdirSync配合fs.statSync做一個深度優(yōu)先遍歷。核心邏輯說出來大家都能懂const fs require(fs); const path require(path); class Scanner { constructor(projectRoot, ignoredPatterns) { this.projectRoot projectRoot; this.ignoredPatterns ignoredPatterns; this.fileList []; } walk(dir) { const entries fs.readdirSync(dir, { withFileTypes: true }); for (const entry of entries) { if (this.shouldIgnore(entry.name)) continue; const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { this.walk(fullPath); } else if (entry.isFile()) { this.fileList.push({ path: fullPath, ext: path.extname(entry.name), name: entry.name, size: fs.statSync(fullPath).size }); } } } shouldIgnore(name) { return this.ignoredPatterns.some((pattern) pattern.test(name)); } }這套實現(xiàn)足夠應對大多數(shù)中小型項目。但在這里我要提一個實際踩過的坑把同步遍歷寫進一個遞歸函數(shù)里一旦項目文件層級特別深很容易爆棧。我們當時那個項目里有一個測試目錄嵌套層級最深的地方超過了四十層遞歸調用的時候棧幀積累得非?？?。雖然一開始沒有直接崩潰但性能明顯下降掃描耗時達到了二十多秒。后來我改成了顯式使用棧數(shù)據(jù)結構來遍歷而不是依賴函數(shù)調用棧walk(root) { const stack [root]; while (stack.length 0) { const currentDir stack.pop(); const entries fs.readdirSync(currentDir, { withFileTypes: true }); for (const entry of entries) { if (this.shouldIgnore(entry.name)) continue; const fullPath path.join(currentDir, entry.name); if (entry.isDirectory()) { stack.push(fullPath); } else if (entry.isFile()) { this.fileList.push({ path: fullPath, ext: path.extname(entry.name), name: entry.name, size: fs.statSync(fullPath).size }); } } } }這里我想多啰嗦一句很多新手容易忽略withFileTypes: true這個參數(shù)。如果不用這個參數(shù)readdirSync返回的是字符串數(shù)組你得對每個路徑單獨調用fs.statSync來判斷它是文件還是目錄。這相當于多了一次系統(tǒng)調用在文件數(shù)量龐大的時候損耗非?？捎^。用了withFileTypes之后Dirent對象直接提供了isFile()、isDirectory()方法節(jié)省了額外一次stat的開銷。2.2 依賴分析模塊的算法選擇掃描到文件列表之后緊接著要做的事情是分析依賴關系。這里所謂的依賴不單指代碼里的import或require語句還包括自定義函數(shù)之間的調用。對于 JavaScript 項目要精準分析函數(shù)級調用關系難度非常大,因為 JavaScript 是動態(tài)語言運行時綁定、回調函數(shù)、閉包這些特性都讓靜態(tài)分析變得很費勁。所以我在第一版設計時做了一個戰(zhàn)略取舍不做精確的函數(shù)調用分析只做模塊級的依賴分析。具體來說就是用正則表達式把每個文件中出現(xiàn)的import ... from ...、require(...)、const xxx require(...)、import(...)這幾種常見的引用形式全部提取出來再對引用路徑做規(guī)范化處理最終生成一張以文件為節(jié)點、以引用關系為邊的依賴圖。這個思路的好處用一個詞概括就是“夠用”。我需要的不是一張完美的代碼架構圖而是一個能告訴我在改動某個文件時哪些地方可能需要聯(lián)動調整的清單。這個場景下解析到模塊級別足夠了。提取引用關系的邏輯大致是這樣const IMPORT_PATTERN /(?:import\s[\s\S]*?from\s*[]([^])[]|require\s*\(\s*[]([^])[]\s*\))/g; function extractDependencies(sourceCode) { const deps []; let match; while ((match IMPORT_PATTERN.exec(sourceCode)) ! null) { const rawPath match[1] || match[2]; if (rawPath !rawPath.startsWith(.) !rawPath.startsWith(/)) { continue; // 第三方包不做深入分析 } deps.push(normalizePath(rawPath)); } return deps; }這里有一個細節(jié)值得注意我在匹配第三方包時直接跳過了。因為rea關注的永遠是項目內部模塊之間的關系node_modules里的依賴再復雜也不是這個工具要管的范疇。強行分析第三方包既浪費性能又會讓報告變得嘈雜難讀。規(guī)范化路徑這步也很關鍵。假設一個文件位于src/utils/helpers.js它引用了../constants.js那么我在報告里應該展示的是src/constants.js而不是../constants.js否則后面做聚合統(tǒng)計的時候就無從下手了。路徑規(guī)范化的實現(xiàn)const path require(path); function normalizePath(rawPath, currentFilePath) { if (rawPath.startsWith(/)) { return path.normalize(rawPath); } const absolutePath path.resolve(path.dirname(currentFilePath), rawPath); return path.relative(process.cwd(), absolutePath); }用path.resolve先把相對路徑轉為絕對路徑再用path.relative把絕對路徑轉為相對于項目根目錄的路徑。這樣整理出來的依賴關系每一行都是可追溯、可點擊的。2.3 報告生成的人性化設計分析做完以后如何呈現(xiàn)結果是一個非常值得琢磨的問題。我見過不少工具分析做得很深入但輸出結果是一大堆 JSON開發(fā)者看完之后依舊一頭霧水。rea從一開始就明確了一件事最終交付物必須是人類可讀的純文本報告。第一版報告長這樣Project: demo-shop Generated at: 2025-06-14 10:23:01 規(guī)模概況 Total files: 1,234 Total lines of code: 78,942 Total dependencies (internal): 3,215 高風險模塊 Top 10 1. src/order/service.js (127 inward refs) 2. src/user/session.js (98 inward refs) 3. src/payment/gateway.js (76 inward refs) ... 孤立文件候選 - src/legacy/migrate_old.js (no inward refs, 0 outward refs) - src/pages/UnusedPage.vue (no inward refs, 0 outward refs) ...這個報告看起來不復雜但需要在背后完成兩件很重要的事。第一件事是統(tǒng)計每個文件的被引用次數(shù)。這就需要一個從目標路徑到引用來源列表的反向映射表構建方式很簡單在收集依賴關系的時候每發(fā)現(xiàn)一條引用就在目標文件對應的集合里加一個來源。第二件事是判斷“孤立文件”。如果某個文件在內部分析中既沒有被其他文件引用它本身也沒有引用任何內部文件那么它極大概率是從某個版本的迭代中殘留下來的廢棄代碼。注意這只是“候選”——因為動態(tài)加載、反射調用、配置文件引用這些情況靜態(tài)分析是捕捉不到的。所以報告里會用“候選”這個詞提醒使用者不要直接照單全收。2.4 并發(fā)掃描的優(yōu)化方案如果你只在小項目上用過rea那你可能永遠不會遇到這一節(jié)要講的問題。但一旦跑大型項目性能問題就會立刻浮現(xiàn)。我前面提到在一個五萬文件的電商項目上第一版rea直接跑崩了。這里所謂的“崩”不是內存溢出而是耗時長得不可接受。當時我用計時器量了一下掃描耗時就占了兩分多鐘而理想狀況下一個命令行工具是不應該在交互時讓人等待這么久的。性能瓶頸主要出在fs.statSync這個調用上。當年我在遍歷目錄的時候每遇到一個文件都會調用一次fs.statSync獲取文件大小。五萬個文件就意味著五萬次同步的系統(tǒng)調用這個開銷非?？捎^。優(yōu)化方案有兩個方向可以選擇一個是改用fs.promises做異步 IO另一個是用 Worker 線程池做并行掃描。我最終把兩個方向結合了。用 Worker 線程池改造的思路是主線程把項目根目錄下的頂層子目錄分發(fā)給若干個 Worker每個 Worker 負責掃描自己分到的子目錄把結果序列化后傳回主線程。這個過程有點像把一個大倉庫的盤點工作分給幾組人同時做每組只負責自己的片區(qū)最后再把匯總結果合起來。這里我給出一個簡化版的線程池實現(xiàn)思路const { Worker } require(worker_threads); function parallelScan(roots) { const workers roots.map((root, index) new Promise((resolve, reject) { const worker new Worker(TASK_FILE, { workerData: { root, index } }); worker.on(message, resolve); worker.on(error, reject); })); return Promise.all(workers); }不過要提醒大家Worker 線程用起來隨手就能寫但序列化和反序列化fileList的開銷也不小。當時測試下來文件數(shù)量在三千以下時單線程和線程池的耗時幾乎沒有區(qū)別甚至線程池還更慢一些。只有文件數(shù)量超過一萬時線程池的收益才明顯體現(xiàn)出來。所以如果你的項目規(guī)模沒到這個量級沒必要盲目上并發(fā)先看看是不是被其他低效操作拖了后腿。3. 實操過程與核心環(huán)節(jié)實現(xiàn)理論部分說完了接下來是實戰(zhàn)環(huán)節(jié)。我的經驗是做工具類項目先搭一個可以用起來的骨架再逐步加功能比一開始就追求大而全要高效得多。3.1 環(huán)境準備與項目初始化rea的運行環(huán)境要求是 Node.js 14 及以上原因很簡單舊版本不支持fs.readdirSync的withFileTypes參數(shù)其實這個參數(shù)在 10.10 就引入 了但我建議直接給個更寬松的底線。項目初始化用的是npm init -y它會自動生成一個package.json。我習慣在項目里加上bin字段這樣就能通過npm link把命令安裝成全局命令{ name: rea, version: 0.1.0, description: A lightweight static analysis tool for project structure, main: src/index.js, bin: { rea: src/index.js }, engines: { node: 14.0.0 } }文件目錄結構我采用了很常見的模式rea/ ├── src/ │ ├── index.js # 入口文件命令分發(fā) │ ├── scanner.js # 目錄掃描模塊 │ ├── analyzer.js # 依賴分析模塊 │ ├── reporter.js # 報告生成模塊 │ └── utils.js # 通用工具 ├── test/ │ └── fixtures/ # 測試用的臨時項目 └── package.json入口文件的寫法非常簡單就是解析命令行參數(shù)然后按指令調用不同模塊#!/usr/bin/env node const { scanner } require(./scanner); const { analyzer } require(./analyzer); const { reporter } require(./reporter); async function main() { const projectRoot process.argv[2] || .; const scanStart Date.now(); const fileList await scanner.scan(projectRoot); const analysis analyzer.analyze(fileList); const elapsed Date.now() - scanStart; console.log(reporter.render(projectRoot, analysis, elapsed)); } main().catch((err) { console.error([rea] Error:, err.message); process.exit(1); });這一版沒有引入 commander 之類的參數(shù)解析庫。因為它目前只需要一個參數(shù)項目路徑。將來如果增加了更多命令再考慮引入?yún)?shù)解析框架也不遲。我一直堅持一個原則不過早引入復雜度。3.2 依賴分析模塊的完整實現(xiàn)依賴分析模塊是這個工具的核心大腦。這里我貼出完整實現(xiàn)并逐行解釋關鍵邏輯。class Analyzer { constructor(fileList) { this.fileList fileList; this.nodeMap new Map(); // 存儲每個文件節(jié)點 this.edgeList []; } analyze() { for (const file of this.fileList) { const source this._readFile(file.path); const deps extractDependencies(source, file.path); file.deps deps; this.nodeMap.set(file.path, file); } this._buildReverseMap(); return { nodes: this.nodeMap, edges: this.edgeList }; } _readFile(filePath) { try { return fs.readFileSync(filePath, utf-8); } catch (err) { return ; } } _buildReverseMap() { for (const [targetPath] of this.nodeMap) { this.nodeMap.get(targetPath).inwardRefs []; } for (const file of this.fileList) { for (const dep of file.deps) { // 只統(tǒng)計存在對應文件節(jié)點的依賴 if (this.nodeMap.has(dep)) { this.nodeMap.get(dep).inwardRefs.push(file.path); this.edgeList.push({ from: file.path, to: dep }); } } } } }這里有幾個需要特別留意的點。第一個_buildReverseMap里的inwardRefs初始化放到了外層循環(huán)里。如果你直接把inwardRefs初始化寫進_readFile那一步那么每個文件被訪問的先后順序就會影響最終結果這是典型的初始化順序陷阱。第二個import解析用的是正則表達式必然存在誤報和漏報的可能。比如代碼中有被注釋掉的require語句或者寫在字符串里的import字樣正則都會把它們誤判為真實依賴。如果是做嚴謹?shù)纳暇€檢查這顯然不合格但如果目標是快速生成一份“值得人工查看的候選清單”這個精度足夠了。當工具的目標定位是提供線索而不是給出裁決時不完美是可以接受的。第三個我在正則里特別處理了動態(tài)導入import()因為現(xiàn)代代碼中按需加載的場景太常見了忽略它會漏掉很多真實的運行時依賴。3.3 報告渲染引擎的實現(xiàn)報告部分的目標是盡量保持簡潔同時信息密度足夠高。我不建議直接輸出一個超大表格開發(fā)者在終端里滾動幾百行體驗很差。所以我做了一套“摘要 重點列表”的結構。渲染邏輯的核心其實是一個排序與截斷的過程function renderReport(projectRoot, analysis, elapsed) { const nodes [...analysis.nodes.values()]; const totalFiles nodes.length; let totalLines 0; for (const node of nodes) { totalLines countLines(node); } const lines []; lines.push(Project: ${projectRoot}); lines.push(Generated at: ${new Date().toLocaleString()}); lines.push(); lines.push( 規(guī)模概況 ); lines.push(Total files: ${totalFiles.toLocaleString()}); lines.push(Total lines of code: ${totalLines.toLocaleString()}); lines.push(Total internal edges: ${analysis.edges.length.toLocaleString()}); lines.push(); const sortedByInward nodes .sort((a, b) b.inwardRefs.length - a.inwardRefs.length); lines.push( 高風險模塊 Top 10 ); for (const file of sortedByInward.slice(0, 10)) { lines.push(${file.path} (${file.inwardRefs.length} inward refs)); } lines.push(); const isolatedFiles nodes.filter( (file) file.inwardRefs.length 0 file.deps.length 0 ); lines.push( 孤立文件候選 ); if (isolatedFiles.length 0) { lines.push((none)); } else { for (const file of isolatedFiles.slice(0, 20)) { lines.push(- ${file.path}); } } lines.push(); return lines.join(\n); }這個渲染函數(shù)雖然看起來很長但邏輯非常簡單聚合數(shù)據(jù)、排序、取前 N 個、拼接字符串。它的設計目標就是讓使用者在十秒鐘之內抓住項目的核心風險點。3.4 從第一版到可發(fā)布版本的過程寫第一版只用了兩三個小時但rea真正變成可用的工具是經歷了比較長的迭代之后。第一版跑通后我遇到的最大問題其實不是技術難點而是“輸出結果讓人看不明白”。比如報告里出現(xiàn)的孤立文件候選有接近一半其實是前端項目在構建時期引用的less變量文件——它們雖然不被任何 JS 文件直接引用但是在編譯期起著非常重要的作用。如果我只簡單地輸出一個候選列表使用者大概率會誤判。為了解決這個問題我在分析階段加入了一個“文件類型分組”的維度。針對特定的文件擴展名如.less、.scss、.md、.json打上特殊標簽在報告中用不同的標記提示使用者這些文件不適用“孤立”判斷。這個改動雖然不復雜卻極大地提高了報告的實用價值。另一個重要的迭代是支持.reaignore文件類似于.gitignore的機制。因為有些目錄比如自動生成的 mock 數(shù)據(jù)目錄根本不應該參與分析強行分析只會制造噪音。這個功能寫起來很簡單就是多讀一個配置文件把其中的每個模式追加到忽略列表里。4. 實操過程記錄一次真實的使用案例光講原理不落地總感覺少了點什么。這里我復盤一次用rea分析一個實際項目以下代稱為模擬項目X的完整過程包括中間遇到的小狀況。4.1 準備階段搭建一個棘手項目模擬項目X 是一個典型的早期 Web 應用體量中等偏下但結構非常雜亂。它的源代碼目錄長這樣project-x/ ├── src/ │ ├── api/ │ ├── components/ │ │ ├── core/ │ │ └── legacy/ │ ├── pages/ │ ├── styles/ │ ├── utils/ │ └── vendor-patches/ # 放了一些從網上復制來的第三方補丁 ├── scripts/ │ ├── build.js │ └── deploy.sh ├── mock/ └── docs/我預想中的難點有兩個vendor-patches目錄里的補丁代碼引用了很多古老的文件路徑mock目錄里有一大堆自動生成的數(shù)據(jù)文件它們不參與運行但會干擾依賴分析。我在項目根目錄創(chuàng)建了.reaignore文件mock/ vendor-patches/然后把rea工具放到 PATH 中準備執(zhí)行掃描。4.2 第一次運行結果與分析執(zhí)行命令rea ./project-x輸出的報告節(jié)選如下Project: ./project-x Generated at: 2025-06-14 10:23:01 規(guī)模概況 Total files: 846 Total lines of code: 51,239 Total internal edges: 1,082 高風險模塊 Top 10 1. src/api/request.js (124 inward refs) 2. src/components/core/Table.js (78 inward refs) 3. src/pages/dashboard/index.js (61 inward refs) 4. src/styles/theme.js (54 inward refs) 5. src/components/core/Form.js (50 inward refs) ...看到這個結果我基本可以判斷模擬項目X的核心問題在哪了src/api/request.js被一百多個文件直接引用這意味著任何對這個文件的小改動都可能波及全項目所有的 API 調用。用《重構》里的術語來說這就是典型的“霰彈式修改”高危點。順著這個線索我抽查了幾個引用request.js的頁面組件發(fā)現(xiàn)它們確實共用了一個全局的請求實例而且這個實例硬編碼了一些業(yè)務參數(shù)。后面如果要改造項目這個文件必然是第一優(yōu)先級。4.3 深入排查孤立文件候選的甄別接著往下看報告中的孤立文件候選 孤立文件候選 - src/styles/dark-theme.css - src/pages/settings/profile_v2.js - src/pages/settings/profile_v1.js - src/utils/legacy_format.js注意最后這兩個文件profile_v1.js和profile_v2.js。二者都不被引用但顯然存在一個版本切換關系。通過查看git log我發(fā)現(xiàn)profile_v1.js確實已經被替代而profile_v2.js是通過路由懶加載方式引用的所以靜態(tài)分析掃不到。這個案例很好地說明了一個問題孤立文件候選不是終點而是下一步人工排查的起點。如果自動化工具能直接告訴你哪些代碼可以被刪除那它就不再是輔助工具而是代碼庫的替代者了。4.4 針對模擬項目X的優(yōu)化建議基于rea生成的報告我很快就整理出了幾條優(yōu)化建議將request.js中的基礎 API 封裝拆分為獨立的小函數(shù)同時增加對全局請求實例的注入方式。刪除profile_v1.js以及與其相關的樣式文件。把utils/legacy_format.js中有價值的方法合并到utils/format.js確保沒有邏輯重復。在mock數(shù)據(jù)入口處增加統(tǒng)一的出口配置避免散落各處導致的認知負擔。這些建議談不上高大上但他們建立在完整掃描結果之上因此每一處改動都有明確的依據(jù)減少了憑空猜測帶來的風險。5. 常見問題與排查技巧實錄工具開發(fā)到后期我陸陸續(xù)續(xù)遇到并解決了一些典型的工程問題。這里挑幾個最有代表性的問題做個速查表也方便你將來使用或仿寫類似工具時能夠繞開這些坑。問題原因排查技巧解決方案掃描大目錄耗時過長同步 IO 操作過多用perf_hooks分階段計時定位耗時集中在掃描還是分析切換到異步 IO 或 Worker 線程池報告中有大量誤報的孤立文件靜態(tài)分析無法覆蓋動態(tài)引用抽樣核查個別文件檢查是否存在import()或配置式引用引入文件類型分組和.reaignore機制require路徑解析 alias 導致依賴匹配不上構建工具里配置了模塊別名在報告里輸出一條“未匹配 dependency”匯總在工具里增加別名映射配置文件運行環(huán)境 Node 版本過低導致崩潰使用了較新的 API查看堆棧信息定位具體 API明確最低環(huán)境要求啟動時做版本檢查文件編碼不統(tǒng)一導致亂碼GBK 編碼的文件被當 UTF-8 讀取觀察到輸出中文亂碼時不應盲目跳過讀取時嘗試多種編碼解碼并在報告中標記編碼識別結果Worker 線程數(shù)據(jù)序列化開銷大傳輸海量文件列表對比單線程與線程池在閾值前后的表現(xiàn)低于閾值時自動退化為單線程模式除了這些常見問題之外再分享幾個我平時用得比較多的小技巧。第一個技巧在調試rea時我喜歡先用一個小型 fixture 項目做驗證而不是直接跑真實大項目。fixture 項目里就放三五個人為制造的依賴關系比如 a 引用 bb 引用 cc 又引用 a用來驗證循環(huán)依賴是否能被正確識別。用這種微型案例調試效率遠高于在大項目里糊里糊涂找 bug。第二個技巧輸出中間態(tài)調試信息。我在工具中加了一個--debug參數(shù)它會額外打印出掃描階段的文件數(shù)量、每個階段耗時、依賴解析失敗的路徑列表。這些信息在定位問題時價值極高。第三個技巧把工具的源碼納入自己的日常代碼習慣之中。rea雖然是一個工具項目但它同樣需要版本管理、測試用例、代碼風格統(tǒng)一。我把它推到一個私有倉庫里每次修復完 bug 都加一個針對性的測試防止后續(xù)改其他地方時把修好的問題又帶出來。第四個技巧也是我認為最重要的不要把工具的定位搞錯。rea的產出是線索不是結論。我在最初幾版的使用中曾因為過度信任“孤立文件候選”列表差點把一個動態(tài)組件給刪了。從那以后我堅持在報告首頁頂部加一句提示所有分析結果均需人工復核。這句話雖然簡單卻在很大程度上避免了使用者過度依賴工具帶來的災難。6. 后續(xù)擴展方向與個人經驗總結rea目前能做的事情已經足夠解決我百分之八十的結構梳理需求但它的擴展空間依然很大。如果時間允許我大概率會在三個方向繼續(xù)打磨。第一個方向是支持更多語言。目前依賴解析主要針對 JavaScript 和 TypeScript 生態(tài)輸出報告的時候也會刻意區(qū)分.js、.jsx、.ts、.tsx。但實際項目里很可能一個倉庫同時包含 Java、Python、甚至 Go 代碼。只要針對每種語言補充對應的解析規(guī)則rea就可以變成一種真正意義上的多語言項目結構分析工具。第二個方向是輸出可視化的依賴圖。現(xiàn)在終端文本報告雖然好讀但面對大型項目時一張能夠讓用戶拖動、縮放、聚焦的交互式圖表會帶來更直觀的體驗。我計劃在未來版本中把分析結果同時輸出一份 JSON 或 DOT 格式方便接入其他可視化工具。第三個方向是提供增量掃描能力。每次全量掃描雖然已經足夠快但如果在 git 提交后只想分析本次變更涉及了多少上下游文件增量模式會實用得多。最后說一點個人體會。我做過不少工具rea不是技術含量最高的一個但它是我認為“性價比”最高的一個。它解決的問題非常具體非常貼近日常開發(fā)的真實痛點而且它本身并不復雜——一個會點 Node.js 的開發(fā)者幾天時間就能寫出類似的工具。如果你正在為“看不懂項目結構”而頭疼我的建議是先別急著重構或換框架花點時間寫一個像rea這樣的小工具把項目的真實面貌摸清楚。很多所謂架構混亂的問題在理清依賴關系之后往往會自動暴露出清晰的解決路徑。你自己寫出來的工具以后改起來也特別順手因為它的每一行代碼都貼合你自己的腦回路。還有一個我始終忘不掉的經驗。在我第一次重寫rea的那個周期里我曾因為想加一個“自動重構建議”功能而差點把工具本身給拖垮。后來我把它砍掉了因為這個功能需要的智能程度遠超一個命令行工具的范疇。做工具最忌貪多一個工具能專注地把一件事做好就已經非常出色了。這句話我現(xiàn)在送給所有在造輪子的朋友也包括未來的我自己。