1. 为什么我决定自己动手做代码审查工具做代码审查这件事很多团队要么靠人在评审页面里逐行盯要么靠一堆静态检查脚本拼凑。我最近把自用的一套轻量审查引擎 open-code-review 整理开源了目标非常直接把重复性的、机械的审查规则变成可维护的代码把审查结论自动内联到评审流程里让人工评审只做真正需要人的判断。先说我遇到的真实场景。我们团队每周合并的 PR 大概七八十个每次人工评审平均要花二十分钟到半小时其中相当一部分时间其实是在重复看同样的问题配置文件里又出现一个疑似写死的密码某个新接口改了签名但调用方没跟着改日志代码里直接拼接用户可控的字符串。这些检查完全机械、可枚举、有明确判断标准但传统静态检查工具面对这类跨文件、跨提交的语义问题往往力不从心。它能告诉你这行代码风格不对但它不知道这个字段是接口新返回的前端没加类型校验。我最初考虑过直接用现成的商业方案但几个问题让我打消了念头一是团队代码分散在不同托管平台有些项目在私有 Git 服务器上商业工具适配成本不低二是规则表达能力有限想加一条公司特有的规范往往要写一堆平台脚本三是我不希望审查结果被锁在某一个平台里换个托管平台就得重来。最后决定自己写写完发现核心逻辑并不复杂干脆开源。于是有了 open-code-review。它的定位不是又一个强制代码风格的 lint 工具而是一个能把审查规则代码化、结果内联到评审流程里的轻量引擎。整个项目拆成三个模块规则定义层、分析上下文层、结果输出适配层。下面按设计决策的顺序把每层怎么思考的、踩过哪些坑都展开讲。1.1 现有工具链的断点到底断在哪先别急着写代码我把为什么要再造一个轮子这件事想得很清楚。市面上的方案大致分三类。第一类是语言专项检查器比如前端 lint、后端静态分析强项是语法树级别的机械检查弱项是跨文件语义和业务规范表达。第二类是 CI 平台内置的检查插件能实现不通过就不允许合并但反馈往往是一份平铺的报告开发者翻半天才知道问题出在哪一行。第三类是商业评审平台交互体验确实好但价格不便宜审查规则通常封闭换平台成本很高。我真正想要的是一个放在评审流程里像评审助理一样的东西PR 一创建它自动跑一遍规则把问题以内联评论的形式挂在对应代码行上同时给出总体结论。这个结论不等于合不合并的判断——规则只能覆盖机械问题业务正确性还得靠人。但至少它能帮我把看看这个 PR 有没有明显错误这一步自动化掉。实测下来这一步占用了评审者大约四成的时间把它省下来团队能多出很多真正讨论设计的时间。1.2 我的目标规则代码化与结果内联所以 open-code-review 的核心理念就两条规则代码化结果内联。规则代码化意味着每条审查规则都是一段可读、可测试的代码存放在项目仓库里随业务代码一起评审、一起演进结果内联意味着审查结论不是一份孤立报告而是直接出现在评审对话框里的逐行评论。这套模型的好处是规则不会躺在一个黑盒数据库里出了误报可以直接改规则还能在规则仓库里看到规则本身的 diff。如果做个类比传统静态分析像是给代码做一次全身体检拿到报告还得自己去对应科室open-code-review 更像是站在你旁边的同事看到哪里有问题当场指出来。两种方式并不冲突但在评审场景里后者明显更符合人的工作习惯。这也是后续所有设计决策的总纲——所有功能都围绕让结论出现在该出现的地方、让规则可被团队自己维护来展开。2. 规则引擎拆分审查逻辑不再是一堆难维护的 if else项目最开始那版我直接在一个入口函数里把各种检查逻辑串起来先读 diff再根据文件扩展名判断语言再按字符串内容判断关键字……写到第八条规则的时候我就意识到不对了。这个入口函数膨胀到没法测试新增一条规则要小心翼翼不碰坏其他逻辑而且检查什么和怎么输出完全耦合。重构了三次最后沉淀出下面这套三层结构后面再怎么加规则都没再动过架构规则层只回答这段变更有没有问题接收上下文返回诊断结果列表上下文层把 Git 变更解析成规则能方便读取的结构化数据适配层把诊断结果渲染成具体平台的评论格式。2.1 规则模型的参数与返回约定规则层核心是一个很简单的接口。open-code-review 的规则层最终用的是 TypeScript因为团队主要是 JS/TS 技术栈规则写起来门槛低写测试也方便// 规则接口 interface ReviewRule { id: string; severity: error | warning | info; description: string; apply(context: ReviewContext): PromiseDiagnostic[]; } // 诊断结果 interface Diagnostic { ruleId: string; severity: error | warning | info; filePath: string; line: number; message: string; snippet?: string; suggestion?: string; }这里有两个设计决策值得说。第一message 必须是一句完整、可操作的话比如检测到疑似硬编码密钥建议改用密钥管理服务并通过环境变量注入而不是发现敏感信息这种含糊描述suggestion 字段用于承载可选的修复建议能自动生成补丁提示就更好了。第二severity 分三级error 会阻塞合并warning 只提示info 是观察项。设计成三级而不是五级是为了减少使用者做决策的成本——机器人只能提供必须改、建议改、仅供参考三种立场再细分就是为难人。2.2 变更集计算diff 解析为什么是第一个坑规则要基于代码变更工作所以上下文层最重要的工作是把 Git diff 转成结构化变更集。这一步看起来简单实际坑很多。diff 的基本单位是 hunk每个 hunk 带一个 header形如 -12,5 15,7 含义是原文件从第 12 行开始的 5 行对应新文件从第 15 行开始的 7 行。解析 header 还算容易麻烦的是行号对应关系。举个例子一个 hunk 里可能包含 3 个上下文行、5 个删除行、4 个新增行。规则要报第 18 行有问题这里的行号到底指原文件还是新文件我们做了个约定所有诊断的 line 默认指向新文件行号因为评审评论是贴在新代码上的。为了实现这个映射我维护了一个逐行状态机从 hunk 的起始新文件行号开始遇到行号加一遇到-行号不变遇到空格行号加一。第一次实现时漏了上下文行也会更新行号这个细节导致一批诊断全部错位一行。这种错误在人工评审里很难被发现因为人看的是整体不会逐行对号机器人错了就很尴尬开发者会直接对你的工具失去信任。另一个坑是文件改名。Git diff 对重命名文件通常只有一行rename from / rename to没有内容正文。最初版本会把改名文件当成无变更后来改成规则层可以选择是否追踪改名文件默认追踪但只有内容真正变化的行才会被检查。还有一个现实问题是二进制文件和大文件——图片、打包产物混进 PR 时diff 正文可能是一大段乱码解析阶段如果不对文件类型做白名单过滤轻则性能劣化重则把整个 PR 阻塞住。这个过滤逻辑我放在上下文层入口规则层完全不用感知。2.3 输出适配评论驱动的报告协议诊断结果最终要落到不同平台所以适配层我做成协议式设计规则层产出统一结构的 JSON适配层负责把 JSON 变成平台评论。核心是一个 ReportAdapter 接口每个平台实现两个方法createReviewComment 和 createSummary。为什么这么做因为实际接入时你会发现不同平台的能力差别很大。有的平台支持批量创建多条行内评论有的只支持一条评论附带一堆 markdown。如果不抽象协议规则层就要写平台相关代码那就又回到最初的耦合状态。有了协议之后新增一个平台只需要写一个适配器规则层零改动。目前官方适配器覆盖了主流托管平台和通用输出格式私有 Git 服务器场景可以直接输出 markdown 或 JSON 文件由机器人定时上传。这个抽象花了蛮多心思但收益是一劳永逸以后再接入新平台我只需要面对一个接口。3. 审查流程如何落地Git 事件监听与结果推送链路规则引擎本身只是计算真正让审查跑起来的是外围流程。open-code-review 设计了三套接入方式适用不同规模的团队。3.1 三种接入方式的取舍接入方式适合场景优点缺点本地 CLI个人开发、小项目零部署一条命令出结果不会自动触发靠自觉CI 任务常规团队已有 CI 流程随构建自动执行结果内联配置稍重长耗时任务要留意配额常驻服务监听 Webhook中大型团队评审流程规范实时触发可对全量 PR 统一治理需要维护服务有安全要求最省事的是本地 CLI 模式适合还在观望的阶段装个命令在项目根目录跑一下就能看到当前变更触发了哪些规则。CI 模式是大多数团队应该采用的方案原理是把 open-code-review 作为 CI 流水线里的一个步骤PR 更新时自动运行然后把诊断提交到托管平台的评审区域。常驻服务模式我放在最后因为它要处理 Webhook 验签、并发限流、token 安全一堆事对刚起步的团队没必要。3.2 一次完整审查的流水线拆解以 CI 模式为例一次审查的完整链路是这样的CI 触发PR 创建或更新时流水线检出目标分支与合并基线计算变更open-code-review 解析出 base 与 head 之间的 diff生成变更集执行规则上下文层把变更集注入每条规则并行执行汇总诊断结果回写适配层调用托管平台 API为每条诊断创建或更新行内评论汇总结论在评审对话框留下一段总结列出本次审查的规则数、问题分布、阻塞项。这里有两个细节容易忽略。第一步骤 2 里的 base 不是简单的上次提交而是目标分支的最新提交否则机器人会把其他人刚合入的变更也算进来造成大量误报。第二重复执行会产生重复评论所以回写前要先查一遍这条规则、这个文件、这个行号是否已经存在同类评论存在则只更新内容不新增。这个幂等设计很关键否则一个 PR 改三版评审区就留下三倍评论体验直接崩。在本地调试这条流水线时我强烈建议先打开离线模式让工具只生成 JSON 结果文件不真正调用平台 API。这样你可以随便跑、随便改规则不用担心污染真实 PR也能用快照对比不同规则版本的输出差异。等到结果稳定了再开启真正回写。这个调试习惯帮我省掉了大量不必要的 API 调用和限流麻烦。安全方面常驻服务和 CI 模式都需要控制 token 权限。我的建议是单独建一个机器人账号只授予读取代码和评论的权限绝不使用管理员 token。CI 模式下 token 要注入环境变量而不是写在配置文件里这个点我在踩坑复盘里会再提。4. 规则编写实操三个典型规则的配置全过程光有引擎没有规则等于空壳。这一节我用三个真实落地的规则展示从需求到实现的完整过程。这三个规则分别对应三种典型模式内容检测、跨文件关联检测、上下文语义检测。4.1 规则一拦截疑似硬编码密钥第一个规则最简单属于内容检测。需求来自一次真实事故某同事把云服务商的密钥提交到了仓库虽然很快撤销了但密钥已经暴露需要轮换。这条规则的逻辑是扫描新增或修改的行寻找符合密钥特征的长字符串同时排除测试代码里的 mock 数据。const rule: ReviewRule { id: secret-leak-check, severity: error, description: 检测疑似硬编码的密钥或令牌, apply: async (ctx) { const diagnostics: Diagnostic[] []; for (const file of ctx.changedFiles) { if (file.path.match(/(test|spec|mock|fixture)/i)) continue; for (const line of file.addedLines) { // 简化检测长度大于 20 且形如 AK/SK 或 token if (/[A-Za-z0-9_-]{20,}/.test(line.content) /(access.key|secret|token)/i.test(line.content)) { diagnostics.push({ ruleId: secret-leak-check, severity: error, filePath: file.path, line: line.number, message: 检测到疑似硬编码密钥请改用密钥管理服务并通过环境变量注入, snippet: line.content.trim().slice(0, 80), }); } } } return diagnostics; }, };注意几个细节。第一跳过测试文件和示例文件因为测试里经常有假密钥不排除会带来大量误报第二正则匹配的是存在密钥特征词 长字符串的组合单独一个长字符串在很多场合是合法的比如提交 ID 或哈希值第三message 里给出了替代方案这是评审机器人最重要的价值——指出问题同时告诉人怎么改。后来我们还加了历史提交扫描模式对存量问题做一次性体检这个能力对刚接手的旧仓库很有用。4.2 规则二新增接口必须配套测试第二个规则属于跨文件关联检测。需求是团队约定后端新增 API 接口必须带测试但靠人提醒总会有漏网之鱼。规则逻辑是当 diff 中出现新增的 controller 接口方法时检查同一 PR 里是否有对应的测试文件变更。实现上需要一点巧劲。我先解析新增接口方法名然后推断测试文件的约定路径再去变更集里查这个路径是否出现。如果没出现就在接口方法所在行报一个 warning而不是 error——因为没写测试未必会立刻出问题但值得提醒。这条规则设计的难点在于关联怎么建立最稳。我试过两种方式按文件名后缀匹配、按接口方法名匹配。最终用的是接口方法名 测试文件名共现的组合只要新增代码里出现形如test_xxx或xxx.test.ts引用就认为测试覆盖存在。规则允许配置一个豁免列表放行那些明确不需要测试的纯转发方法。我给这条规则写了三组单元测试分别覆盖有测试无测试豁免命中三种情况。规则本身也是代码必须有测试兜底否则改错规则比没有规则更可怕。4.3 规则三识别动态拼接的 SQL 日志第三条规则是上下文语义检测的典型代表也是最容易误报的一条。需求是日志代码里不能用字符串拼接的方式输出 SQL因为 SQL 里往往包含用户可控参数拼接进日志容易留下注入隐患也容易把敏感数据打出来。规则逻辑是找到新增的包含SELECT、INSERT、UPDATE等关键字的字符串再看这个字符串是否由变量拼接而成如果是就报 warning。为什么不是 error因为很多团队的历史代码就是这么写的直接 error 会导致合并全被阻塞规则一上线就变成摆设。先 warning 观察等存量问题清了再提高等级是我强烈建议的推进方式。另外这条规则对长 SQL 模板、多行字符串要小心处理正则贪婪匹配容易把整段文件都划进问题区间。我最后用的是逐行扫描 关键字白名单 拼接符号检测的组合宁可漏检也不误报。实际中它还抓出过一个很有意思的问题有人把完整的查询语句拼到了日志里虽然不是把用户输入拼进去但里面包含订单号、金额这类业务敏感字段一样值得被提醒。4.4 误报控制路径过滤与金丝雀模式三条规则落地后我总结出一个结论规则引擎的难点从来不是能不能检测而是误报率能不能接受。一个机器人如果十条评论里有三条是错的开发者很快就会对它免疫甚至直接关闭。所以 open-code-review 内置了两个机制。第一个是路径过滤。每条规则都可以配置 includePaths 和 excludePaths比如密钥检测跳过examples/接口测试检测只看api/目录。路径过滤是最高效的降噪手段比在规则里写一堆 if 判断清爽得多。第二个是金丝雀模式也叫 dry-run。规则可以先以仅报告不评论的方式运行把诊断结果输出到日志或一个临时分支持续观察一周统计误报率等稳定了再切换成真正写评论的模式。我建议所有新规则都必须过这一关没有例外。团队里甚至立了条规矩误报率超过 15% 的规则不允许进入正式模式。5. 实测数据与踩坑复盘哪些问题只有跑到生产环境才知道工具写完和工具在团队里真正跑起来是完全两回事。我从一个十几人团队里选了两个项目组做试点跑了两个迭代这里记录一些真实数据和几个深刻教训。5.1 试点两周的效果数据指标试点前试点后单次 PR 人工评审中位耗时约 25 分钟约 14 分钟每 PR 人均评论数8.4 条3.6 条合入后被回滚的 PR 数3 个迭代1 个迭代开发者对评审机械感的抱怨较多明显减少当然这不是严格的对照实验不同周期的需求复杂度不同但趋势是一致的机器人把低水平重复评论消化掉之后人工评论里关于架构、可读性、业务逻辑的比例明显上升。有个开发者的原话是以前打开 PR 评论像开奖现在机器人先帮你筛过一遍剩下的基本都是需要人来讨论的问题。这句话基本就是我做这个项目想达到的效果。另外有个我没想到的副作用因为机器人会把密钥泄露缺少测试这类问题拦在合并之前线上事故的定位和复盘会轻松很多。以前出了问题要先翻提交记录现在直接看评审区的机器人结论就能知道哪些环节的高风险变更进来了。这对团队是一个正向循环。5.2 三个必须避开的坑坑一diff 解析的上下文边界。前面提到行号映射问题实际跑起来发现还有更隐蔽的情况当某个 hunk 的上下文行被截断diff 默认只显示三行上下文规则要报的问题行恰好落在不可见区域时行号会对应到错误的物理行。解决方式是在解析阶段显式记录当前 hunk 的可报告行集合任何诊断如果行号不在这个集合内就标记为文件级提示而不是行内评论保证不会错位。坑二平台 API 的限流与评论数量上限。第一次全量跑规则一个改动较大的 PR 一次性生成了四十多条评论直接触发了托管平台的限流后面的评论全部失败而且部分评论因为接口超时出现了重复提交。后来加了两个措施单次 PR 评论数上限为二十条超出部分按优先级合并成汇总评论所有回写操作加上重试和幂等键避免重复评论。坑三token 泄露风险。这里说的不是业务代码里的密钥而是工具本身配置不当导致机器人 token 被打印到日志或写进了仓库。有次排障时为了调试把环境变量打印了出来CI 日志里清晰可见 token 前缀虽然很快轮换掉了但让我意识到任何处理 token 的工具日志都必须默认脱敏。我在 open-code-review 里加了一个日志过滤器对所有形如密钥的值自动打码规则配置里写了明文密钥也会在启动时给出警告。5.3 规则调优的标准动作试点中我形成了固定调优流程。第一步每周导出机器人的全部诊断记录人工抽样标注有效/误报第二步把误报率超过 15% 的规则提出来看是规则逻辑问题还是过滤条件问题第三步修改规则后先跑金丝雀模式一周确认误报率降下来再切正式评论。这套流程听着笨但比拍脑袋调阈值可靠得多。我也发现一个反直觉现象有时误报不是规则太宽而是太窄——规则只匹配了关键词组合没有匹配团队特定的封装函数导致漏检。比如团队有人写了一套logQuery()封装内部就做了 SQL 拼接但规则只认原生字符串拼接于是漏掉了。后来把封装函数也纳入识别范围误报和漏报一起降下来了。这件事给我的启发是规则调优不能只围着关键词转要先理解团队的代码习惯。6. 这个工具的边界以及我下一步打算怎么扩展最后说说边界。open-code-review 做得再好也只能覆盖确定性规则——凡是能写成明确判断条件的机器人都能做凡是依赖经验、创意、业务语境的判断比如这个模块是否划分合理这个接口设计是否优雅它一概不碰。这不是缺陷是定位。让机器做机器擅长的事人做人擅长的事工具才有意义。实际情况中最好的状态是机器人的评论率逐年下降——因为团队规范已经内化代码质量在源头就好了工具退到后台只做兜底。后续扩展我主要在看几个方向。一是跨仓库规则注册表团队内部沉淀一套公共规则包新项目一键引用不用每个仓库复制粘贴规则升级也能统一生效。二是和本地编辑器的联动在开发者写代码的时候就提示比在评审阶段再提更划算等于把审查能力往前挪了一大步。三是引入 AI 辅助的启发式检查但这里有个前提AI 的判断不可靠时应该标记为仅供参考绝不能让 AI 含糊的建议直接顶替精确规则。这个原则是我在开发 open-code-review 的整个过程中最深的体会工具可以越来越聪明但边界必须越来越清晰。