1. 为什么我要自己搭一套 open-code-review
做了一段时间的后端开发，又带过两三个项目小组之后，我对代码审查这件事的态度经历了一个很大的转变：从“觉得麻烦”到“觉得必须做”，再到“觉得不能这么做”。
多数团队的 code review 实际上是在走流程。PR 一开，负责人随手点个 approve，偶尔留一句“LGTM”。如果赶上发布日，连 LGTM 都能省，直接 merge。这种形式主义的审查，既浪费时间，又制造了一种“我们已经审过了”的假象。更难受的是，新人从这种审查里学不到东西，老手也懒得在代码里写注释，因为“反正没人细看”。
后来我维护了一个开源项目，代码完全公开在仓库里，来自不同时区的 contributor 会不定期提交 PR。这时候我发现，描述清楚“这个 PR 改了什么、为什么这么改、需要注意什么”变得异常重要，因为你的审查者可能根本不认识你，也不了解你的业务背景。
也就是从那时起，我开始花精力做一套开源风格的代码审查流程，也就是标题里说的“open-code-review”。它不是一个商业工具，而是一套可以被任何团队直接复制、配置和落地的开源审查工作流。它的核心思路很简单：把 code review 从“人工走过场”变成“规则自动挡 + 人审关键点 + 数据可回溯”的闭环。
这篇文章，我就把这套方案的完整思路、落地步骤、配置文件、常见踩坑，全部整理出来。不管你是团队里负责推流程的 tech lead，还是想提高自己 review 效率的普通开发，甚至是刚入行想搞懂 code review 到底在看什么的新人，都能从里面拿走一些直接用得上东西。
2. open-code-review 的整体设计思路拆解
2.1 传统 code review 的三个慢性病
我们先聊问题，因为不理解问题，后面所有配置都只是表面功夫。
第一个慢性病是审查范围失控。一次 PR 动辄几百上千行，有的同事习惯把重构、修 bug、加功能、改格式混在同一个提交里。这种 PR 摆在审查者面前，根本没办法细看。人脑处理复杂信息的能力有限，面对一千行混合变更，能看个大概就很不错了，更不用说提出有质量的意见。
第二个慢性病是反馈周期太长。有的人早上提了 PR，晚上才有人看，甚至隔了一两天才被 review。等到写出下一段代码时，早就忘了之前为什么要那么写。代码审查一旦失去即时性，它的价值至少打五折。
第三个慢性病是缺乏数据沉淀。到底什么类型的 bug 经常被漏掉？哪个模块的代码返工率最高？提交规范有没有被遵守？这些问题，传统流程里全靠记忆和感觉。问题没有量化，改进就只能靠“提醒大家重视一下”这类空话。
2.2 让审查“公开”起来：open-code-review 的三层设计
我理解的“open-code-review”包含三个层面的含义：开源、开放、公开。
开源，是指整个审查流程本身是可配置、可自定义的代码，不是某个平台的私有功能。你可以在自己的基础设施上部署，也可以直接作为工作流模板嵌入 GitHub、GitLab 或 Gitea。
开放，是指审查规则对团队所有人透明。谁在什么节点、依据什么标准、做出了什么样的审查决定，全部有记录。新人来了之后，不需要口口相传去问“咱们团队审查要注意什么”，看一遍配置文件和最近的历史 PR 就知道了。
公开，是指审查结果对干系人可见，审查意见本身就是团队知识库的一部分。代码为什么这么写、有什么取舍、踩过什么坑，这些内容往往只存在于 review 评论中，如果不公开沉淀下来，换个项目又得重新踩一遍。
基于这三个层面，整个方案被拆成了四个模块：变更入口规则、自动化静态检查、人工审查清单、数据统计面板。
2.3 为什么选择规则自动化优先，而不是完全取代人工
这里要特别说清楚一个原则：open-code-review 的目标不是用机器人替代人，而是用机器把那些重复、机械、容易遗漏的检查项先做掉，把人解放出来去思考那些真正需要判断力的东西。
我见过一些团队过度迷信工具，上了 SonarQube、CodeClimate 等一堆扫描器之后，就觉得审查万事大吉。但设计模式是否合理、接口边界是否清晰、业务逻辑是不是绕了远路，这些事情工具永远判断不了。恰恰是这些内容，才是 code review 最核心的价值所在。
所以我把整个流程设计成“漏斗”结构：入口规则过滤掉明显不合规的变更，自动化检查过滤掉低级错误，剩下的变更再进入人工审查环节。每一层只做自己该做的事，不越界。
3. 核心细节解析与实操要点
3.1 变更入口规则：把“提交边界”定义清楚
整个流程的第一道关卡，是限制 PR 的提交边界。规则定义得越细，后边省的事越多。我在 open-code-review 的配置里默认写了几条硬性规则，这些规则可以由机器人直接拦截，不需要人工判断。
- 单个 PR 的变更行数默认不超过 400 行，超过时自动标记为“需要合并拆分”。
- 单个提交里不能同时出现“功能变更 + 无关重构 + 格式调整”三种类型，通过检查文件名和 diff 内容来识别。
- 提交信息必须符合 Conventional Commits 规范，格式统一为
type(scope): subject。 - 所有直接推到主分支的提交一律拦截，只能通过 PR 合入。
有人可能会觉得这些规则太死板。但实际操作中你会发现，把这些边界定义清楚之后，审查者面对每个 PR 的认知负担会显著降低。写代码的人被迫把自己的变更拆得更小、描述得更清楚，这对作者本人也是一种训练。
我建议团队在落地第一天就把这些规则配上。相反，如果一开始不设限制，等大家习惯了大 PR 满天飞，再想收回来遇到的阻力会大很多。
3.2 自动化检查清单：机器人替你看什么
在人工介入之前，我让机器人自动跑一组静态检查。这组检查不是越全越好，而是围绕最容易被漏掉、又是最高频的问题来设置。
首先是编译与测试。这个不用多说，PR 提交时触发 CI，编译不过、单测挂了，直接打回。其次是代码风格，接入 ESLint 或 Ruff 这类工具，统一格式，避免团队里因为“缩进到底用几个空格”吵半天。
然后是复杂度检查。我用 ESLint 的complexity规则限定圈复杂度不超过 10，用max-lines-per-function限制函数长度，超过阈值就报 warning。这个设计很有必要，因为大量 bug 都藏在“又臭又长”的函数里面，人读不下去，机器能一眼看到。
再往后是重复代码检测，用 jscpd 扫一遍，超过 5% 的相似度就提示抽取公共逻辑。这块在很多团队是被忽略的。大家只关注“能不能跑”，不关注“维护起来痛不痛”。重复代码是维护成本的隐形杀手，越早发现越省事。
最后是安全扫描。这里只做最基础的敏感信息检测，防止有人把密钥、Token、连接串直接提交到仓库里。这是一个完全可以用正则规则覆盖的场景，比如查找类似AKIA[0-9A-Z]{16}的 AWS Access Key、-----BEGIN PRIVATE KEY-----的私钥标记，以及形如password\s*=\s*['"][^'"]+的配置项。把这些规则配置好后，机器人能在代码进入仓库之前就拦住多类高危泄露。
3.3 人工审查清单：不要凭感觉 review
机器检查完之后，剩下的是人工判断。但“人工”不是“随便看”。我给团队准备了一份标准 checklist，每次 review 时对照检查，确保覆盖面完整。
这份清单分四个维度。第一个维度是逻辑正确性：这个 PR 要解决的问题是什么，代码的处理流程是否覆盖了所有分支，异常路径有没有被处理。第二个维度是可维护性：新增代码是否遵循了项目现有的分层和命名规范，有没有制造过高的耦合，变量名是否表达真实意图。第三个维度是性能：有没有明显的 N+1 查询，循环里有没有无意间引入高开销操作，缓存策略是否合理。第四个维度是测试完备性：关键路径有没有单测覆盖，异常场景有没有测试用例，测试本身是不是在为了覆盖率而写。
这份清单不是静态的。每季度我会组织一次复盘，把近期线上事故、漏审情况汇总一次，凡是能总结成规律的，就补进清单中。清单越长，说明团队踩过的坑越多，也意味着后续同样的问题被漏掉的概率越小。
3.4 通知与协作方式：让 review 不再“有人提没人管”
审查流程中还有一个经常被忽略的环节：通知。很多 PR 长期没人看，不是因为大家不重视，而是因为通知没有精准到达。
open-code-review 的通知策略基于文件和目录的 CODEOWNERS 规则。比如src/api/**目录指定给负责接口层的同事，src/db/**目录指定给负责数据层的同事。当 PR 的 diff 中涉及这些目录时，机器人会自动 @ 对应的 owner，确保“改谁的代码谁来看”。
同时，机器人会在 PR 创建后的 2 小时、8 小时、24 小时分别发送一次提醒。如果超过 24 小时仍无人 review，自动升级到项目负责人。这里有个细节：提醒只在工作日的工作时间段发送，避免非工作时间的消息打扰。
4. 实操过程与核心环境搭建
4.1 仓库初始化与分支保护配置
因为 open-code-review 天生是为开源协作场景设计的，我优先推荐在 GitHub 上部署。下面的步骤基于 GitHub 展开，但思路完全能迁移到 GitLab 或 Gitea。
第一步，创建一个新的空仓库，然后初始化项目结构：
mkdir open-code-review cd open-code-review git init git checkout -b main第二步，配置 GitHub 的分支保护规则。在仓库的 Settings -> Branches -> Add rule 中，将 main 分支设置为“锁定”状态，要求所有合并必须通过 PR，并且至少一个 review approve。我建议把“Require status checks to pass before merging”也打开，这样 CI 如果没有跑完，merge 按钮是不可用的。
到这里，强制 PR 流程就已经生效了。接下来要做的，是把自动化检查挂载到这个流程里。
4.2 自动化工作流：GitHub Actions 配置实践
我用 GitHub Actions 来驱动整个检查流程。下面是一份可以直接用的工作流配置，保存为.github/workflows/review.yml：
name: open-code-review on: pull_request: types: [opened, synchronize, reopened] push: branches: [main] jobs: lint-and-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: 18 cache: 'npm' - run: npm ci - run: npm run lint - run: npm test -- --coverage code-quality: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Run complexity and duplicate check run: | npx eslint src --rule '{"complexity": ["error", 10]}' npx jscpd src --min-lines 5 --min-tokens 50 diff-size: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 - name: Check PR size env: BASE_SHA: ${{ github.event.pull_request.base.sha }} HEAD_SHA: ${{ github.event.pull_request.head.sha }} run: | changes=$(git diff --shortstat $BASE_SHA...$HEAD_SHA) echo "Diff stats: $changes"diff-size 这一步，实际使用中可以在脚本里解析git diff --shortstat的结果，如果新增行数超过 400，就让这个 job 失败，机器人会在 PR 下留言提示拆分。这个自动化拦截做起来很简单，但价值非常高，它从流程上逼迫大家保持小步提交。
4.3 检测规则的参数计算与阈值选择
很多团队在配置 lint 规则时习惯直接用一个别人配好的方案，但“能用”和“合适”是两回事。这里我重点讲几个核心参数值的依据。
第一个是行数阈值。400 行这个数字不是拍脑袋定的。根据我在多个项目里的统计，单个 PR 的代码量在 200 到 350 行之间时，review 者能够投入足够的精力逐行阅读；超过 400 行后，跳读和漏读的比例显著上升。如果你想要更精确的值，可以拉取团队最近 3 个月所有 PR 的 diff 行数，计算中位数，然后取中位数的 1.5 倍作为阈值。
第二个是圈复杂度上限。10 是 ESLint 的默认建议值，但它更适用于业务代码。如果是工具类纯函数库，我通常把阈值收紧到 6，因为这个领域的代码对可读性要求更高。如果是胶水层代码（比如路由分发、配置文件加载），可以放宽到 15，这类代码分支多但逻辑简单，强行拆分反而损害可读性。
第三个是重复代码检测参数。--min-lines 5表示 5 行以上的重复才报警，--min-tokens 50表示重复的 token 数至少达到 50。这两个值需要根据语言类型调整。Python 因为语法简洁，min-lines 可以设到 6；Java 样板代码多，建议设到 8，不然 getter/setter 会制造大量噪音。
4.4 审查机器人：自动审批与留言
静态检查只解决“机器能判断的事情”，但流程中还涉及大量“机器人跑腿”的环节。我在 open-code-review 里用 probot 写了一个小机器人，主要干三件事：PR 创建时自动打标签、根据 CODEOWNERS 自动指定 reviewer、在检查完成后自动把结果汇总成一条评论。
打标签的逻辑很简单：根据 changed files 的路径，匹配feature/、bugfix/、refactor/、docs/等目录模式，给 PR 标记对应的 type。标签的价值在于统计面板可以直接按类型筛选，让后续的数据分析有了维度。
指定 reviewer 的逻辑则是完全基于 CODEOWNERS 文件。项目根目录下放一个CODEOWNERS，内容和效果如下：
* @tech-lead src/api/** @api-owner src/db/** @db-owner docs/** @tech-writer当 PR 的 diff 涉及src/api下的文件时，机器人自动 @api-owner，并建议db-owner也可以作为 optional reviewer。这比手动去群里问“谁来看一下我这个 PR”要高效得多。
机器人的评论格式要注意，不能只放“检查通过”或“检查失败”。更合理的做法是给出摘要。比如：
检查结果：lint 通过；单测通过；覆盖率 87%；圈复杂度 12/10（函数
parseConfig超出阈值）；重复代码 3 处。请人工重点 reviewsrc/api/order.ts中事务边界处理。
这样的评论让审查者在打开 diff 之前就对 PR 的整体健康状况有了预判，可以直接跳到风险最高的位置。
4.5 数据统计：用报表驱动改进
流程跑起来之后，还需要回答一个重要问题：这套方案到底有没有用？如果不用数据说话，再好的流程也可能会因为“感觉没什么效果”而被废弃。
我设计了一个简单的数据面板，每周自动生成一份 review 报告。报告的核心指标有七项：PR 平均提交次数、PR 平均审查等待时间、审查通过率（一次通过/多轮修改后通过）、单个 PR 平均评论数、缺陷逃逸率（合入后两周内出现 bug 的数量）、平均变更行数、测试覆盖率变化趋势。
这里我专门强调缺陷逃逸率这个指标。它的统计口径是：某个 PR 合入主干后，两周内是否因为这个变更产生了线上问题或回滚。如果有，就记为该 PR 的缺陷逃逸。这个指标直接反映审查质量。如果缺陷逃逸率持续偏高，说明审查流于表面，策略上要加强自动化检查或者重新培训团队的审查能力。
报告本身不用自动化得很高级。每周五下午，用脚本拉取这一周的 PR 数据，生成一张 Markdown 表格，发到团队频道，顺手在高亮栏里写一句“本周重点是接口层变更较多，建议多盯一下”。这种频率和粒度，团队更容易接受，也比季度汇报那种冷冰冰的数字更有温度。
5. 常见问题与排查技巧
5.1 PR 太大被拦住了怎么办
当 diff-size 检查报错时，很多人的第一反应是“我能不能把阈值调高一点”。我的经验是：如果真的遇到无法拆分的巨型 PR，先看它属于哪种情况。
如果是“纯机械重构 + 业务代码变更”混在一起，可以先用一个 PR 只做重构，再开一个 PR 做功能。如果是“依赖某个分支的代码”导致必须一起合入，可以选择用 stack PR 的方式，把 PR 串成依赖链，让每个 PR 独立审查。如果是“自动生成代码”导致 diff 巨大，这个属于误报，需要在配置里把该目录加入 ignore 列表。
我给团队立的规矩是：任何越过阈值的 PR，必须由提出者自己说明“为什么拆不开”，写清楚之后再人工放行。你能明显感觉到，当一个人需要解释为什么拆不开时，他会更努力地想办法拆开。
5.2 机器人误报：规则噪音的治理策略
自动化检查上线两周后，最常收到的反馈是“机器人又在乱报了”。复盘这些投诉，我发现噪音主要集中在两个地方：一是重复代码检查把测试代码里的相似断言误判为重复，二是复杂度规则把某些本来就是“配置映射表”的函数标记为超标。
处理办法是给检查工具增加 ignore 规则。jscpd 里可以通过--ignore参数跳过测试目录，或者用--ignore-pattern排除特定文件；ESLint 则直接在文件头部加/* eslint-disable complexity */，但要注意这个注释必须附带理由，不能裸用。
同时我建议在机器人评论里给每条提示设置级别。只有 error 级别才会阻塞合并，warning 级别只作为提醒。这样既能保留规则的约束力，又不会因为噪音让团队对机器人产生免疫。
5.3 有人就是不配合怎么办
这是整个方案推行过程中最现实的问题。总有团队成员觉得“我代码能跑就行，你搞这些流程就是浪费时间”。
我的经验是把规则分成两个梯度来推。第一梯度是机器强制规则，比如编译、单测、复杂度这些，全部由 CI 自动卡住，不通过就合不了，不给人讨价还价的空间。第二梯度是人工约定，比如 PR 描述格式、提交信息规范这些，先在 config 文件里写好，但不强制阻断，通过机器人的自动提醒不断提示。
两三个迭代之后，你在 review 报告里把“提交信息规范遵守率从 60% 提升到 90%”“平均 PR 审查等待时间从 16 小时下降到 5 小时”这些数据贴出来，比说一百句“要重视质量”都管用。数据能说服那些只认结果的人。
5.4 审查耗时过长：如何提高效率
有的团队即使上了这套流程，审查效率依然低下。核心原因通常不是规则不够，而是审查者没有掌握快速定位风险的方法。
我一般建议 review 者按这个顺序看 PR：先看 PR 描述与变更文件列表，搞清楚改动边界；再看测试代码，确认作者对需求的理解；再看新增文件的框架结构，了解整体设计；最后只看 diff 中新增的核心业务逻辑，跳过格式调整和 IDE 自动改动。
把顺序调整之后，你会发现 review 的时间能有效缩减三分之一以上。特别是先看测试这条，很多 review 者会忽略。测试代码本质上是在描述作者对行为的预期，看完测试再看实现，会比直接看实现更容易发现问题。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| C1 跑了很久还在转 | CI 里依赖安装慢，或缓存未启用 | 配置依赖缓存，或切换到按需拉取模式的镜像源 |
| C2 diff-size 误报 | 自动生成文件混入 PR | 在配置里添加 ignore 目录，并统一使用 .gitattributes 标记生成文件 |
| C3 机器人没有自动指定 reviewer | CODEOWNERS 路径规则写得不对 | 逐一核对目录路径，注意通配符优先级，路径匹配是按最长路径优先的规则 |
| C4 重复代码检查奶噪 | 测试代码和模板代码相似度高 | 调高 token 阈值，或在 jscpd 中排除测试目录 |
| C5 单测覆盖率一直上不去 | 只对工具函数写了测试，核心业务无覆盖 | 逐个模块盘点风险最高的 3 条路径，把缺口拆成任务派到人 |
| C6 审查者只点 approve 不评论 | 缺少明确的审查预期 | 在审查清单里加入“每人至少提 1 条有效意见”的软指标 |
6. 团队文化与持续运营的心得
流程跑通了只是开始，真正难的是让团队从“应付流程”变成“主动想做好 code review”。这里分享几个我在实际运营中验证过有效的方法。
第一，代码审查要纳入绩效的正向反馈，而不是负向惩罚。不要因为谁代码被挑出问题就批评谁，反而要公开表扬那些提出高质量审查意见的人。我在团队里设了一个“本周最有价值审查意见”的小环节，每周从 review 评论里选出一条最有启发的，连同上下文和结果一起分享给全组。这能明显提升大家参与 review 的积极性。
第二，定期做“审查方案回访”。每个月和团队成员一对一聊一次，问三个问题：最近 review 中什么让你最难受？你希望机器人帮你做什么？你觉得哪个环节是纯浪费时间的？这些答案整理出来后，不要全做，只挑最重要的一两个改进点去落地。
第三，也是我特别想强调的：不要为了自动化而自动化。如果团队只有三个人且互相坐在一起，随时可以面对面沟通，那这套流程里很多东西是可以裁剪的。open-code-review 的价值在于让流程可复制、可扩展、可追溯，而不是为了套一个好看的框架。工具永远服务于人，当工具让你觉得笨重的时候，就应该去改工具，而不是去迁就工具。
另外我还想提醒一点：好的 code review 文化有一条隐形底线，叫“对代码严格，对人宽容”。审查意见写得再直白，也要保持技术讨论的边界。我在规范里加了一条硬性要求：review 评论中不允许出现人身评价类措辞，就事论事，讲代码不讲人。这条规则文字上看着很简单，但它对团队安全感的影响，远远大于任何技术指标。
7. 后续可以怎么扩展
这套流程的框架搭好之后，后续扩展空间很大。我目前在做的是两个方向的延伸。
第一个方向是接入更多语义化检查。现在的静态规则只能看结构，不能理解“这段代码的意图”。我在尝试用接口定义和类型系统做更深的检查，比如自动识别“函数声明了但从未使用”“调用链中存在明显的事务提交遗漏”这类问题。这类检查的难点在于误报率控制，目前精度还在调整中。
第二个方向是把 review 数据接入到项目知识管理里。每个 PR 的审查意见，本质上是团队踩坑记录。我打算把历史 review 评论做分类归档，按“并发问题”“事务问题”“接口设计问题”等维度打标签，形成团队的 review 知识库。以后新人碰到类似问题时，可以直接搜索历史案例分析，而不是从头踩一遍。
如果你正在为团队 code review 流于形式而头疼，我的建议很直接：别急着让所有人“认真起来”，先把能自动化的规则全部自动化，把有限的人工精力集中到真正需要人思考的问题上。当你把流程搭到足够顺滑，大家自然会发现 review 不是负担，而是一条最有效的学习路径。
