代码审查这件事几乎所有团队都会喊要做但真正坚持下来的不多。我见过太多项目上半年还在认认真真过 Code Review下半年就退化成“LGTM”打卡甚至有人直接点完 Approve 连代码都没打开过。问题不完全出在团队态度上流程设计本身太重才是根源人工逐行看代码太耗精力机器能发现的低级错误又在反复消耗评审人的耐心。我做这套 open-code-review就是想解决这个结构性矛盾——把审查从“纯靠人肉”变成一套开放、透明、自动化的流水线用开源工具沉淀规则让机器先挡掉一层人只做机器做不了的事。这篇文章完整记录了我从理念到落地的全过程包括工具选型、配置示例、踩坑记录和团队落地节奏适合正在折腾 Code Review 流程、或者觉得现有流程走不下去的团队参考。1. 想清楚再动手什么是能跑起来的开放式代码审查1.1 传统 Code Review 为什么经常走不远先说一个我观察到的普遍现象大多数团队的 Code Review 核心依赖“某个经验丰富的人”。老张眼睛毒每次都能在别人提交的代码里一眼看出缺少空指针判断、发现 import 写错、看出某个边界条件没处理。于是大家都习惯性地等老张来审老张自己也觉得这是分内事。但这里有个致命问题老张的经验全部存在他自己的脑子里没变成团队的资产。一旦他请假、离职或者被其他项目拖住整个 review 的质量就肉眼可见地往下掉。更糟的是新人进来以后没有任何“预培训”就直接开始审代码面对一个几百行的 PR 完全不知道该看什么要么不敢说话要么只敢提一下格式问题。这种模式走不远的第二个原因是反馈太慢。等 PR 合进去之后才发现当时漏掉的问题再回头修的成本比现场提出要高好几倍。可现实是多数团队把 review 当成一种“事后仪式”只要 CI 通过、只要评审人点了 approve 就算完事根本没人在意评审的质量和反馈的闭环。第三个问题则是审查结果完全不沉淀。今天有人指出“这里应该用 Optional 判空”明天另一个 PR 又出现同样的写法后面还是有人犯一样的错。因为这些问题只存在于一次性的对话里没人把它抽象成规则、没人把它写进检查工具于是团队就在同一个坑里反复摔倒。1.2 开放的审查体系到底“开”在哪我给这套方案取名 open-code-review核心就在“开放”这两个字上。它对应三个层面的意思任何一个团队都可以直接套用。第一是流程开放。审查过程不能是某个人的黑箱判断而要有明确的检查项、确定性的执行路径。每一次代码变更提交之后哪些检查是自动跑的、哪些检查需要人来判断、判断的标准是什么全部有据可查。这样即使是最新加入团队的成员也能立刻理解审查的基本规则不用靠猜。第二是规则开放。审查规则本身应该以配置文件的形式放进代码库允许被讨论、被修改、被记录。每条规则从哪来、当初为什么加都有 commit 历史可追溯。这就好比把老张脑子里的经验一条条写成了团队手册而且这个手册可持续演进。第三是反馈开放。机器检查的结果不是只丢在 CI 日志里吃灰而是以评论的形式直接出现在 PR 页面上。人工评审的意见也一样留在同一个位置。这样整个审查过程中的所有讨论都沉淀在代码平台里变成可检索的知识库。三个月以后再回来看你完全能还原当时某个决定是基于什么考虑做的。打个生活化的比方。以前的做法像是家里长辈口头告诉你“出门前要关水电”完全靠人传开放式的审查体系则是把这些提醒写成一张挂在门口的检查清单而且清单本身还能随季节变化不断更新。人总有忘的时候清单不会。1.3 机器检查和人工判断的边界得分清做自动化审查最容易犯的错就是想把所有问题都丢给机器。真这么干的结果往往是规则集臃肿庞大误报率高到没人看最终整个自动化形同虚设。所以我建这套体系时就先划了一条明确的边界什么该交给机器什么必须保留给人。机器擅长的是有确定性答案的检查代码格式、未使用的变量、明显的空指针风险、调试代码残留、依赖包安全漏洞、重复代码块、复杂度超过阈值。这些检查项标准明确、结果可复现用工具来跑又快又不会累。人擅长的是没有标准答案的判断架构设计是否合理、业务逻辑是否覆盖了真实场景、有没有更简单的实现方式、边界条件是否考虑全、可测试性好不好、后续维护成本是高是低。这类问题机器学不会硬塞给它只会产出大量没人信的“建议”。检查维度机器人工代码格式与风格处理稳定高效不该管浪费精力明显缺陷空指针、未清理资源处理能拦截大部分可抽查兜底安全与依赖风险处理通过漏洞库扫描关注业务层面的安全架构合理性暂不处理主要关注业务逻辑正确性暂不处理主要关注可读性与可维护性可作为规则辅助核心判断性能与并发风险复杂规则有限参与重要判断这条边界的意义在于给机器规定“只管对它看得准的事情”给人明确“机器替代不了的那部分才是你的重点”。分工清楚自动化和人工才不会互相拖后腿。2. 工具链与规则集审查自动化的核心选择2.1 Reviewdog把检查结果变成 PR 评论的桥梁我第一次把 ESLint 接入 CI 的时候效果其实非常差。工具确实跑起来了每次提交都会输出一大堆告警但现实是根本没人去看 CI 日志里那几百行输出。大家只在 CI 变红的时候才会点进去瞄一眼黄橙橙的 warning 直接忽略。这让我意识到光有检查工具远远不够问题出在检查结果的“呈现路径”上。后来引入 Reviewdog 才算真正打通了这层窗户纸。这个名字可能有人不熟简单说它是一个桥接工具能把各类检查工具的输出来到代码托管平台GitHub、GitLab 都支持以评论的形式贴在对应代码行的旁边。最关键的参数是 filter_mode它决定了哪些检查结果会被“放出”。filter_mode 有几种取值。added 表示只检查新增的行这是最严格的增量模式diff_context 除了新增行还会带上 dff 上下文里的旧代码一起看file 是把检查范围放宽到整个被修改的文件no_filter 就是完全不过滤所有告警全量展示。实际落地时我用的是 diff_context。原因很简单只查新增行可能漏掉“新增代码与旧代码交互”产生的问题而查整个文件又会被存量告警淹没。diff_context 在两者之间取了一个平衡既能发现新增代码自身的问题又能看出它跟周围既有代码是不是协调。安装和接入本身很简单。它在社区里有现成的 action比如 reviewdog/action-eslint直接在 GitHub Actions 里声明一下就能用。关键是要理解它解决了什么问题检查工具负责“发现问题”Reviewdog 负责“把问题送到人眼前”。忘了这层自动化做得再多也等于白做。2.2 ESLint 与 SonarQube增量扫描和全量复盘的分工团队的技术栈主要是 JavaScript/TypeScript所以静态检查第一选择自然是 ESLint。但这里我想提醒一点ESLint 这类工具属于“轻量增量检查”适合每次 PR 都跑一遍它能很快反馈大多数明显的代码问题。可它并不擅长跨文件的架构级分析也不会主动发现模块边界越权、循环依赖、重复率持续恶化这类宏观问题。解决宏观问题我用 SonarQube。但 SonarQube 不能一上来就塞到每次 PR 里否则全量扫描的耗时和巨量存量告警会让所有人崩溃。我的做法是把它放在定时任务里每天晚上跑一次全量分析结果汇总到质量平台的看板上。团队每周五看一眼趋势按优先级处理新增的“债务”项。这样做的好处是把“检查频率”和“检查深度”做了分离。PR 级别的检查讲究快、准、跟 diff 相关性强周期性的全量检查讲究广、深、能反映系统整体的健康度。两者配合才是完整的自动化体系只靠任何一种都有明显的盲区。此外我还在流程里加了一层安全扫描用 gitleaks 扫描密钥和敏感信息有没有被误提交用 npm audit 检查依赖包有没有已知漏洞。这一层极其重要而且往往是被团队忽略的。我见过不止一次有人在代码里硬编码了数据库连接字符串然后提交到仓库这种情况只有靠自动化扫描才能第一时间拦住。2.3 审查规则要从项目场景里“长”出来规则集的设计是整个 open-code-review 成败的关键也是我踩过最多坑的地方。最典型的一个错误是为了“省事”一开始就直接套用社区流行的规则全家桶比如 Airbnb 的 ESLint 配置。结果一跑输出上千条告警里面大量是既有历史代码的风格问题。开发者的第一反应不是“哎呀我错了”而是“这工具根本不理解我们的项目全是在瞎报”。信任感一旦崩塌后续怎么维护都难。我的建议非常明确规则集不要移植要从项目自己的代码审查记录里长出来。具体操作方法是拉取近三个月所有 PR 的 review 评论做好两个统计——评论里出现频次最高的问题是什么以及这些问题里哪些可以被工具自动检测。然后按这个优先级去查对应工具的规则文档把规则一条条启用。这个过程听起来慢实际上两周内就能完成而且产出的规则集准确性远超盲搬全家桶。规则启用之后我还会做分档管理。error 级别给到那些必须阻止合并的问题比如调试器残留、空指针隐患、明显的安全问题。warning 级别给到应该修复但不至于阻挡发布的建议性问题比如重复代码、函数体过长、命名不清晰。还有一类我称为“讨论项”的通过自定义规则在代码里标记出来不强制修改只是提醒人工评审人重点关注某个位置。{ rules: { no-debugger: error, no-console: [warn, { allow: [warn, error] }], eqeqeq: [error, always], max-lines-per-function: [warn, { max: 120 }], no-unused-vars: [error, { argsIgnorePattern: ^_ }], typescript-eslint/no-floating-promises: error } }这套分级设计很关键。它避免了“一刀切”带来的对抗情绪级别最低的规则像是温和的建议级别最高的规则则是不可触碰的红线。机器管得既不过松也不过紧。2.4 自定义规则把经验变成可执行的代码平台自带规则覆盖不了所有问题。比如我遇到过团队里反复出现的“在循环里同步调用外部接口”的写法还有“把整张表查出来再在内存里过滤”的低效操作。ESLint 和 SonarQube 的默认规则都不管这类问题它们属于高度依赖业务场景的模式识别。这种情况下我选择写自定义规则。写到后来我总结出一个经验自定义规则的价值不是为了抓一大堆问题而是为了把“团队里已经形成共识的经验”固化下来。每次在 review 里看到一个新的高频问题我就想能不能把它变成规则。如果模式很清晰、能用 AST 描述就写一条自定义规则如果模式模糊、更像是一时的风格偏好就不写宁可继续用人工 review 去把控。写自定义规则确实有门槛但从见效最快的“搜索特定 API 使用方式”“检查是否缺少某个函数调用”“标记禁止的编码模式”这几类入手并不算太难。而且一旦写出来整个团队以后都不需要再为同样的问题争论。这种“把讨论结果固化进工具”的操作才是规则开放最核心的体现。3. 一步步接入 CI可以在团队复现的完整配置3.1 初始化规则集从历史 Review 记录里提炼首批规则真正动手配置之前先花两天时间把团队的存量问题盘清楚。这个步骤很多人都跳过但它是保证后续不翻车的前提。具体操作是把近三个月的已合并 PR 全部过一遍逐个打开 review 评论列表把每条评论按类型归类。比如“漏了判空”记到空指针类“函数太长了”记到可读性类“这里不应该用 any”记到类型安全类。统计完你会发现大概能有几十条有价值的评论但其中真正高频的往往集中在几个类别里。我当时的项目统计下来排前三的分别是空指针与未处理异常、复杂度过高、可读性不佳。于是第一批规则就围绕这三个类别去 ESLint 和 SonarQube 里找对应的规则项开启。这一步不要贪多。第一批规则宁可少而准也不要多而乱。以 ESLint 为例我最初只启用了二十几条规则绝大部分是 error 级别剩下的在 warning 级别先放着。目标是先让团队适应“机器会拦我”这件事而不是一上来就铺几百条规则让人产生疲劳感。3.2 接入 GitHub Actions配置一个能自动评论的机器人规则集就绪之后下一步就是把审查流水线接到仓库的 CI 流程里。以 GitHub 为例我直接在 .github/workflows 下新建了一个 code-review.yml 文件每次有 PR 提交或更新时自动触发。下面是我最初使用的完整配置你可以直接复制改成自己的项目。name: code-review on: pull_request: types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest steps: - name: Check out repository code uses: actions/checkoutv4 - name: Set up Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install dependencies run: npm ci - name: Run ESLint and post review comments uses: reviewdog/action-eslintv1 with: reporter: github-pr-review level: warning filter_mode: diff_context fail_on_error: true逐个解释一下关键点。reporter 字段我设置成 github-pr-review意思是让问题以“一行一条评论”的形式直接出现在 PR 的代码页面上开发者在自己的提交下面就能直接看到。level 设置成 warning表示 warning 和 error 都会输出。filter_mode 设置成 diff_context意思是只针对本次变更涉及到的上下文做检查避免存量告警干扰。fail_on_error 是我故意加上的硬性约束。error 级别的告警一旦出现CI 直接就红了这条 PR 不允许合并。这个字段配合后面的分支保护规则就构成了质量门禁的第一道闸门。如果你用的是 GitLab配置思路完全一样。Reviewdog 提供了 gitlab 相关的 reporter只需要在 .gitlab-ci.yml 里声明对应的 job把检查结果通过 API 变成 Merge Request 的评论就行。3.3 质量门禁让自动化审查结果真正拦住合并动作只在 CI 里跑检查还不足以形成约束力因为很多团队习惯是“CI 红就重跑一下碰碰运气看能不能绿”。要让机器审查的结果有约束力必须把质量要求写进代码托管平台的分支保护规则里。在 GitHub 上我给需要保护的主干分支设置了三项硬性要求。第一状态检查必须全部通过也就是 code-review 这个 workflow 必须跑完且没有 error 级别告警。第二必须至少有一名人工 reviewer 明确 approve机器人再严格也不能替代人的判断。第三PR 里的所有 review 对话必须 resolve避免出现“讨论了半天最后不了了之”的情况。这三条配在一起效果立竿见影。前两周团队里还有些人想绕过规则发现分支保护根本合不动之后就老老实实地改完再提交了。自动化审查的价值不在于“跑了一次检查”而在于“检查不过就不能往前走”没有这个闭环工具跑得再欢也形同虚设。3.4 人工审查流程也要同步调整机器把格式、明显缺陷、安全漏洞这些低层次问题都拦掉之后人工审查的工作量实际上减少了很多。这时如果不重新约定人工 review 的侧重点评审人很容易变成“机器人审完我随便看看就 approve”的橡皮图章。我调整后的流程是这样的每次 PR 的新增代码尽量控制在 200 到 300 行以内超过就打回重拆。这个限制不是拍脑袋定的评审人能在一次 review 里保持高质量注意力的代码量是有限的超过这个量之后很多问题就是走马观花。变更控制在合理范围内人工 reviewer 才有可能真正逐行看进去。同时 PR 描述模板也做了硬性要求必须写明三件事这次改动的背景是什么、具体的实现思路是什么、预期的行为变化和影响范围有哪些。这些信息是人工评审的基础没有它们的 PR 我直接打回。让 reviewer 靠猜上下文去审代码是对评审人时间最大的浪费。4. 落地过程中的坑实测问题与排查方法4.1 机器人叫得欢PR 照样被合自动化刚上线那两周出现过一种尴尬情况机器人在 PR 里洋洋洒洒评论了一堆问题结果开发者和评审人都没当回事该合还是合了。后来我查了一下根源在于 reviewdog 的评论并不会改变 CI 的状态码它本质上只是一个“消息提醒”不是“状态检查”。很多开发者早已习惯忽略 PR 页面的评论噪音自然就没人理。解法就是把我前面说的 fail_on_error 先打开再配合分支保护。只要 error 级别告警存在CI 状态就必须失败平台层面直接禁止合并。这一步做完团队才真正正视机器人的存在。但这里也有一个需要注意的度。如果 warning 级别的问题也用 fail 去卡团队会因为频繁被拦而反感。我当时把 warning 定位为“建议项”只在 PR 页面上显示不做硬性阻断。error 是无条件红warning 是礼貌提醒这样分级既保住了底线又不至于让开发者觉得被管死。4.2 规则升级后存量告警大爆炸新版 ESLint 发布或者规则集调整之后最容易出现的场景是存量代码里突然冒出来几千条告警把增量检查也淹没了。很多人第一次遇到这个场面会慌然后下意识把新规则直接回滚。正确做法分三步。第一步保留 diff 过滤机制不动让新规则只对新增或修改的代码生效绝不因为存量问题阻塞日常开发。第二步针对存量告警单独建一个待办池在 SonarQube 里建一个技术债务清单定期按优先级清理。第三步每清理完一个目录的存量告警就在规则配置里把该目录从豁免名单里移掉让覆盖率逐步推进。这么做的好处是渐进式治理。新代码不断保持高质量老代码在稳定的节奏下一点点消化。如果反过来一上来就要求全仓库清零那基本等于让团队停工。4.3 CI 审查时间太长排队排到怀疑人生自动化流程刚配好的头一周我发现 PR 的 CI 整体运行时间长了非常多高峰期经常要等四五分钟才能出结果。全量 lint、全量测试、加上安全扫描挤在一起随着仓库变大只会越来越慢。我的优化思路是拆分成多个并行 job把 lint、测试、安全扫描分开跑它们互不依赖在 GitHub Actions 里天然支持并发。另外把 npm ci 的依赖缓存打开避免每次安装所有依赖都要重新下载。再就是把 lint 的目标限制在变更文件上用 yarn 或 eslint 的 --changed 参数配合 git diff 来实现只查有改动的文件。整套优化下来单次跑完基本压到两分钟以内。这里想特别提醒一句审查工具是给人用的如果它慢到消耗开发者耐心再强的规则也没人愿意配合。性能优化不是锦上添花而是自动化能否持续跑下去的基础保障。4.4 机器审多了人工审查被架空怎么办自动化程度太高之后新的问题又冒了出来评审人开始过分依赖机器觉得“反正机器查过了逻辑上应该没问题”。这种心态其实非常危险因为机器不会判断架构合理性不会考虑扩展性也不会质疑业务逻辑对不对。为了对抗这种心态我给人工评审人准备了一份“机器管不了”的检查清单贴在 PR 模板里每次评审时逐条过一遍这个改动有没有破坏现有的隐式约定错误处理路径是否完备有没有考虑并发和重试场景新增功能的可测试性如何有没有引入不必要的依赖或过度设计同时在团队约定里明确了一条原则robot 的评论只负责回答“对不对”的问题人工 reviewer 必须回答“好不好”的问题。两条线并行缺一不可。如果 PR 里只有机器评论、没有人类 reviewer 提出任何有实质意义的反馈我会在周会时专门拿出来复盘提醒大家 review 不是刷存在感而是要真正看完代码再说话。5. 半年实践后的一些真实体会整个 open-code-review 跑起来半年多我最直观的感受是团队关于代码质量的争论变少了共识变多了。以前一个问题要几个人来回讨论几个小时才能定论现在大部分重复性争议在规则层面就已经解决掉了大家把省下来的精力放到真正需要讨论的架构和实现方案上。规则集本身也一直在长。从最初二十几条到现在四十多条每一次新增都是某次真实 review 里讨论出来的结论。这个过程让我确信代码审查工具不应该是一成不变的死配置而应该跟着项目的实际需求一起演进。规则越贴合团队现实审查流程就越让人信服也越不容易变成走过场。最后再分享一个小技巧每周五下午花半小时做一次 review 复盘。不需要看全量记录只看当周讨论最激烈的几条评论把大家一致认可的方向沉淀成规则把还没定论的问题留到下次继续讨论。这套轻量级的机制看起来不起眼但它保证了规则集始终是活的持续在吸收团队的智慧而不是某个领导拍脑袋定的条条框框。