rea：一个只读离线的项目资源效率分析命令行工具

1. 为什么我最终决定自己写 rea 这个命令行工具1.1 一次让人头皮发麻的上线前排查上个月我接手了一个半年没人维护的老项目场景很典型客户临时要上线一个小版本要求先解决构建慢和接口超时的问题。我把代码拉下来在临时机器上启动构建磁盘空间很快就告急。打开目录一看node_modules解压完占了 800 多 MB根目录散布着二十多个几十 MB 的二进制文件里面有编译中间产物有同事周末导出的数据备份甚至还有两张 100MB 的测试截图。更麻烦的是这些文件没有规律地混在源码里没有一个直观的方式能告诉我“哪些文件是确定可以删的哪些只是体积大但被代码在跑”。这种项目并不是个案。很多项目不是等到上线才变重的而是从第一次提交开始就不断把临时产物、重复资源、无引用的历史文件带进仓库。人工检查效率太低你不可能把几万个文件按时间戳和大小挨个看直接用find按大小排序也只能得到一份“最占空间的文件清单”完全没有工程语义。那时候我就想我需要一个“体检工具”它不修改任何文件只扫一遍项目目录把可疑点按规则列出来告诉我哪里值得关注、为什么值得关注、建议怎么处理。所以就有了这个项目名字叫rea是 Resource Efficiency Analyzer 的缩写核心定位是项目资源效率分析器。它是一个纯命令行工具扫描指定目录通过一组可配置规则发现常见的资源浪费模式比如超大单文件、重复内容文件、打包残留、无引用代码、异常庞大的 lockfile 等然后输出一份带路径、规则编号和整改建议的报告。它适合三类场景接手老项目时的第一轮体检上线前的资源巡检以及在 CI 里作为一道轻量检查卡住明显的体积恶化。1.2 现有工具不是没有而是每个都只解决一小段动手之前我认真对比过现有工具。它们各有优点但放在“快速体检一个多语言混合项目”的场景里都有明显的缝隙。npm ls --duplicate能查 npm 依赖的重复版本但它只认识 npm 生态对 Go 模块、Python 虚拟环境、Docker 镜像上下文完全无感。webpack-bundle-analyzer对前端打包产物分析非常直观但它要求先完整构建一次一次构建半小时的项目根本不想为“体检”多跑一遍。文件体积分析类的工具比如ncdu、du -sh能快速列出大小排名但它们不会告诉你某个 80MB 的文件是不是 2019 年的日志残留也无法识别两个目录下面内容一致的 500KB 图片。更重的静态分析平台比如一些商业化代码质量系统确实可以做复杂检查但部署成本高适合长期稳定维护的核心仓库。对于“我临时拉了一个老项目想快速知道它脏不脏”的场景重平台根本用不上。所以rea的取舍很明确做一个只读、离线、可解释的规则引擎把“一眼能看出但人工容易漏”的资源卫生问题变成一份清单。它不去替代构建分析也不去替代代码质量平台它只负责回答一个问题这个项目的文件系统这一层有没有明显的资源浪费。2. 一个命令行工具要怎么设计才不惹人烦2.1 三条设计原则只读、离线、可解释很多开发者工具死掉不是因为功能不够而是因为“不信任”。让用户对一个工具建立信任首先就是让它别乱动东西。rea从第一行代码起就定了三条原则。第一只读。它永远不会修改、移动、删除任何文件。哪怕规则命中了“疑似过期临时文件”它也只输出一条P2级别的提示真正删不删由人决定。这样用户才敢在老项目里直接跑不用担心它自作主张。第二离线。所有检查都在本地完成不请求远程 API不上传任何路径和文件名。一方面避免了企业环境内网限制的问题另一方面也消除了隐私顾虑。一个 CLI 工具一旦需要联网它的使用场景就会大打折扣。第三可解释。每一条检测结果必须包含规则 ID、命中的文件路径、触发条件、证据信息和整改建议。不能只说“发现 24 个重复文件”还得说清楚“为什么判定为重复”否则用户无法判断这是不是误报。可解释性看起来是细节实际上决定了工具能不能被长期使用。这三条原则写进了项目根目录的 README 最顶上后续所有改动都不能违背。2.2 目录结构与配置文件长什么样rea本身用 Go 写的单二进制发布不需要运行时环境。项目结构保持了简单的层级rea/ ├── cmd/ │ └── rea/ │ └── main.go ├── internal/ │ ├── scanner/ │ │ ├── walk.go │ │ └── fingerprint.go │ ├── rules/ │ │ ├── registry.go │ │ ├── huge_file.go │ │ ├── duplicate_file.go │ │ └── ... │ ├── report/ │ │ ├── terminal.go │ │ ├── json.go │ │ └── markdown.go │ └── config/ │ └── config.go ├── rea.yaml └── README.md配置文件用简单的 YAML考虑的是可读性和可注释性。默认忽略名单覆盖最常见的重目录同时允许用户按项目情况追加ignore: - **/.git - **/node_modules - **/dist - **/build - **/target - **/__pycache__ - **/.venv - **/.idea - **/.vscode rules: R001: enabled: true threshold_mb: 50 R002: enabled: true similarity_threshold: 0.98 R003: enabled: true threshold_mb: 200 min_files: 500这里有一点特别容易踩坑忽略名单里的路径匹配必须用 glob 风格而不是简单的前缀匹配。因为node_modules可能出现在任意深度的子目录里例如packages/console/node_modules只用strings.HasPrefix会漏掉很多情况。rea内部统一用filepath.Match加上递归目录判断先跳过匹配目录再进入遍历否则扫描时间会被无关目录拖垮。2.3 为什么坚持做成一次性 CLI而不是服务或守护进程有人建议我做成一个常驻后台服务扫描完自动生成网页报告。这个想法不是不好但对这类工具来说负担太重。一次性 CLI 的好处是明确的单文件拷贝就能用没有端口冲突没有数据库迁移没有后台进程残留。在 CI 环境里你可以直接下载二进制然后执行跑完就结束不占额外资源。对于本地开发者也一样命令跑完报告输出到终端或者导出成文件随手就能丢弃不会污染环境。如果做成守护进程用户会多出很多额外问题怎么启动、怎么停止、端口被占用怎么办、要不要鉴权、数据存哪里。对于“我只是想快速看一眼项目”这个核心诉求这些全是负收益。所以我宁可牺牲一些“花哨”换一个能随时随地跑起来的工具。3. rea 的扫描器与规则引擎是怎么拆开的3.1 文件扫描与采样指纹扫描器的职责很简单从根目录开始递归读取文件把每个文件的路径、大小、修改时间、是否被忽略等元信息收集起来交给后续规则引擎处理。用 Go 的filepath.WalkDir能覆盖大部分需求但要注意WalkDir自带的目录跳过机制必须在遍历回调里判断目录名是否匹配 ignore 名单然后返回filepath.SkipDir否则还是会走进整个目录性能和预期的“跳过”完全是两回事。重复文件检测是这里的关键。一开始我想的是对每个文件算完整的 SHA-256这样最准确。实测发现根本不现实一个 20GB 的数据库备份文件光算哈希就要几十秒整个项目扫描会慢到没法用。最后改成了“采样指纹”策略。func fingerprint(path string, size int64) (uint64, error) { f, err : os.Open(path) if err ! nil { return 0, err } defer f.Close() h : fnv.New64a() buf : make([]byte, 64*1024) // 读取文件开头 64KB if _, err : io.CopyN(h, f, bufSize); err ! nil { return 0, err } // 如果文件超过 128KB再读取结尾 64KB if size 128*1024 { if _, err : f.Seek(-bufSize, io.SeekEnd); err ! nil { return 0, err } if _, err : io.CopyN(h, f, bufSize); err ! nil { return 0, err } } return h.Sum64(), nil }这个指纹不是唯一的所以规则引擎里做了双保险先比文件大小大小不同直接排除大小相同且指纹相同才算“候选重复”。对于小于 5MB 的文本和图片文件会改用完整内容哈希二次确认确保最终写入报告的结果经得起核查。这个“采样粗筛 小文件精查”的组合在准确率和性能之间找到了一个比较合理的平衡点。3.2 规则引擎用注册表而不是一堆 if-else规则引擎是rea的核心但它并没有写成一个大函数里堆if-else的结构。那样的话每加一条规则都要动主流程规则之间也无法独立开关。现在用的是注册表模式。每条规则实现同一个接口type Rule interface { ID() string Severity() Severity Check(ctx *ScanContext) []Finding }内置规则在初始化时自动注册到registry里根据配置文件决定启用和停用。Check方法接收一个只读的ScanContext里面包含了文件元信息列表、统计信息、配置项和日志句柄。这样规则之间天然隔离输出的是统一的Finding结构type Finding struct { RuleID string json:rule_id Severity Severity json:severity Path string json:path Message string json:message Evidence map[string]string json:evidence,omitempty }这个设计带来的直接好处是新增规则不需要动报告生成和主流程代码。我只需要在internal/rules/目录下加一个文件实现Rule接口然后在注册表里登记一下即可。报告端因为只认Finding自然就能输出新规则的结果。3.3 内置规则的阈值参考第一版内置了 8 条规则它们全部围绕“文件系统资源效率”这个边界。表格如下规则ID规则名称触发条件严重级别建议动作R001超大单文件单个文件超过 50MBP1确认是否仍被引用考虑归档或拆分R002重复文件大小相同且采样指纹一致的候选对P1合并路径共享同一资源R003大目录簇目录累计超过 200MB 且文件数超过 500P2重点审查是否该纳入版本控制R004疑似无引用代码源码文件中未出现 import/require/url 引用P2人工确认后清理R005打包残留存在同名.js与.min.js或dist旁存在src副本P2明确目录边界删除冗余副本R006隐式依赖配置清单中缺失但代码引用了该模块路径P1补全依赖声明R007过期临时文件扩展名匹配.tmp、.bak、.origP3确认后删除R008异常大的 lockfilelockfile 超过 2MBP3使用新版包管理器重建锁文件这些阈值不是拍脑袋来的。R001 的 50MB 来源于我扫描三个不同类型项目的统计结果普通源码项目里超过 50MB 的单个文件几乎都是二进制资源、训练数据或历史备份。R008 的 2MB 则是在一个代码量不大的前端项目里发现的它的pnpm-lock.yaml因为合并冲突被反复追加最后膨胀到了 7MB明显不健康。阈值全部放到rea.yaml里允许用户按项目实际情况调整。如果你维护的是一个游戏资源仓库50MB 的阈值可能太敏感那就可以调高到 200MB。3.4 报告聚合与打分逻辑报告输出有三种格式终端可读格式、JSON 格式、Markdown 格式。终端格式面向本地随手跑JSON 格式面向 CI 脚本解析Markdown 格式方便直接贴到合并请求描述里。打分逻辑采用“扣分制”而不是“加分制”这样更容易感知问题对总体评分的影响。基础分 100 分每条P1扣 8 分每条P2扣 4 分每条P3扣 1 分扣到 0 为止。分数只是一个参考不是某种“合格线”因为不同项目对资源敏感度差异很大。一个嵌入式项目和一个前端展示项目的“合理分数”完全不同。JSON 输出大概长这样{ summary: { scanned_files: 3280, total_size_mb: 812.4, ignored_files: 928, score: 63, elapsed_ms: 1874 }, findings: [ { rule_id: R001, severity: P1, path: assets/screenshots/full_page_2022_11_05.png, message: 单个文件超过 50MB需确认是否仍被引用, evidence: {size_mb: 102.3} } ] }聚合逻辑还要注意一个问题结果必须按路径排序否则多线程执行规则时输出顺序不稳定CI 里会触发无意义的“结果文件变化”。这个细节我一开始没注意后来在调试 CI 时才发现加了一个统一的排序步骤后就好了。4. 实测阶段误报、性能调优和 CI 落地4.1 我挑了两个不太一样的测试样本为了验证rea不是只在理想项目里自嗨我特意找了两个差异很大的样本。第一个是“模拟项目 X”一个典型的前端工程化项目代码量不大但目录里堆了很多历史遗留的编译产物和截图资源node_modules和dist都被完整提交到了仓库里整个仓库体积 1.2GB 左右。这个样本主要测试规则引擎对前端项目的敏感度。第二个是“某跨平台系统”一套使用 Go 语言编写后端、混合 Web 技术栈编写前端的系统代码量比较大文件数接近 1.3 万个但项目卫生整体较好。这个样本主要测试扫描性能和误报率。扫描时我统一使用rea scan . --format json忽略名单使用默认配置没有对阈值做额外调整。4.2 第一版扫描结果两个样本跑出来的结果如下项目扫描文件数总大小扫描耗时命中总数P1P2P3模拟项目 X28401.2GB2.1s61122821某跨平台系统12970430MB5.8s16277从数量上看rea在模拟项目 X 里的表现非常“夸张”61 条命中这符合预期因为仓库里确实混入了大量历史垃圾。但仔细检查结果后我发现里面有相当一部分是误报尤其是在 R002 重复文件和 R008 超大 lockfile 上。某跨平台系统的结果相对干净扫描耗时 5.8 秒对一个 1.3 万文件的仓库来说可以接受。不过这里的“扫描耗时”只包含文件遍历和采样指纹计算规则执行几乎是毫秒级因为规则体量很小。4.3 排除误报的三个具体过程第一个误报来自 R002 重复文件检测。第一版实现里我先按文件名分组再对同名的文件做指纹对比。结果在模拟项目 X 里两个不同目录下的index.js被重复报告但它们的实际内容完全不同。原因很直接同名文件在很多框架项目里太常见了以文件名为分组依据是错的方向。后来改为完全按“大小 采样指纹”进行分组文件名只作为展示字段不再参与判定。问题解决。第二个误报来自 R003 大目录簇。默认阈值是“目录累计超过 200MB 且文件数超过 500”。在某跨平台系统里third_party/webrtc目录正好 260MB文件数 780 个被标记为 P2。从文件数量看确实不小但这个目录是自包含的第三方依赖整个目录被引用不能建议用户删掉或移动。这里的根本问题是规则不知道“被引用”的信息。后来我给 R003 增加了一个辅助判断如果目录内存在明显的主入口文件比如README.md、BUILD.gn、package.json会降低严重级别并显示“第三方依赖目录谨慎处理”的说明。第三个是性能问题不是误报但对体验影响很大。模拟项目 X 里有一个 300MB 的 data 文件扫描器计算采样指纹时由于文件超过 128KB 会额外读取尾部 64KB这部分没问题。但问题是 R001 规则在处理大文件时为了验证是否为压缩包试图读取文件头部几个字节识别魔数这一步会引入不必要的文件打开开销。后来把所有“打开文件”的操作集中在扫描器阶段一次性把文件大小、采样指纹、头部魔数全部缓存到内存规则阶段不再重复打开文件。这样扫描耗时从 3 秒多降到了 2.1 秒。调试这些误报的过程中我最大的感触是规则引擎的“上下文”太重要了。文件系统中没有绝对的坏文件只有在特定工程语境下不合适的文件。rea能做的是尽量提供证据和上下文把最终判断交给人。4.4 接入 CI 的推荐姿势rea接入 CI 的方式很简单就是一个普通命令。但我不建议第一天就开启--fail-on P1否则在老项目上一定会直接跑红然后被迫“关掉整个工具”。更稳妥的做法是分三步。第一步先只生成报告不阻断构建。可以跑rea scan . --format json --output rea-report.json把报告作为 CI artifact 保留下来。第二步人工复核一遍 P1 列表能修的静态问题修掉不能修的路径加入rea.yaml的rules排除项。第三步等报告稳定变绿后再启用rea check . --fail-on P1让后续新增的 P1 问题直接让 CI 失败。这里有个小技巧--fail-on只针对新增问题会比较理想但在纯文件级工具里实现“新增诊断”需要依赖 git 状态。所以我把这个需求放到了rea diff子命令里基于 git 变更文件做增量检查。这个功能还没做完但方向是对的。5. 这个工具的边界以及我接下来想怎么扩展5.1 个人感受工具要保持“小而锐”折腾这个项目最大的收获不是我写了一个能用的 CLI而是我重新理解了“静态工具”的价值。rea并不聪明它不知道一个文件是不是真的没有用它只能根据命名、大小、引用频率、目录位置这些维度给出“可疑”的结论。刚开始我也想过把它做成一个真正的语义分析器解析 AST做全量引用关系分析但做到一半我发现这个方向没有尽头。项目管理工具一旦开始试图“理解一切”就会变得无比重最后没人敢碰。所以我把边界定得非常明确只做文件系统这层的资源效率分析。代码逻辑里面的坏味道交给专业代码质量平台构建产物里的大包交给 bundle 分析工具rea只回答“项目目录里有哪些资源层面的低效痕迹”。这个边界虽然窄但足够实用。在资源问题这层它确实能比人更系统、更稳定地发现问题。5.2 可以继续折腾的方向后续我想做的扩展大概有四个方向按投入产出比排序。第一个是rea diff增量扫描。结合 git 仓库状态只分析变更目录和变更文件让大仓库在 CI 里的检查时间进一步缩短。第二个是插件系统。现在的规则都是内置的用户想加“检查源码中是否存在硬编码的本地路径”这类自定义规则只能改代码。后续我计划开放插件接口让用户通过 YAML 表达简单规则比如“匹配文件名和扩展名”或“目录大小阈值”高级规则再通过 WASM 插件编写。第三个是 Docker 镜像层体积分析。文件系统的资源效率问题不止存在于仓库目录镜像分层里也经常有“删除文件但层还在”的浪费。这个方向可以复用现有的文件指纹和重复检测逻辑只是把扫描对象从本地目录换成镜像层导出文件。第四个是输出格式对接。把 Markdown 报告直接投递到代码托管平台的合并请求评论里在评审阶段就能看到资源变化比事后看 CI 日志直观得多。最后分享一个我踩过坑后的操作习惯第一次在项目上跑rea时不要只盯着报告里的“删除”建议动手。先花十分钟把 P1 对应的文件打开看一眼确认文件的上一次修改时间、被引用的位置和文件大小。尤其是 P2 和 P3 级别的问题更需要人工确认。工具能帮你把“可能的雷”挖出来但扫雷和排雷永远是两回事。