从零搭建开源代码审查方案：open-code-review实践指南

我做代码审查差不多十年了，经历过"审查五分钟，开会两小时"的传统评审会，也经历过"每个PR都要等三天才有人理"的线上协作，但真正让我决定搞一套自己的开源代码审查方案的，是2023年下半年的一次线上事故——一个本该在上线前被拦住的空指针问题，因为在代码审查阶段被秒approve放行了，结果凌晨两点被线上告警吵醒。团队里不是没有审查流程，流程都有，制度也都写了，但就是没人仔细看。这让我意识到一个问题：代码审查的真正难题，从来不是"有没有流程"，而是"流程有没有被真正执行，以及有没有一套东西能把人和人的注意力聚到最关键的地方"。

这个念头最终落地成了一个我到现在还在持续迭代的开源实践项目，就是标题里的 open-code-review。严格来说它不是某个大厂出的重量级框架，而是一套把开源审查工具编排起来、配合规则和流程规范的最小可用方案。它解决的是中小团队最常见的三个人痛点：PR没人认真看、审查意见停留在"格式修正"层面、合并门禁形同虚设。全文不涉及任何商业闭环，纯粹是从一线工程视角出发，告诉你我从零搭这套东西的时候，做了哪些选型、踩了哪些坑、最后沉淀下来哪些可以直接抄走的配置和习惯。

如果你也受够了"审查全靠自觉"的日子，或者你在纠结要不要引入代码审查工具链但怕太重，这篇东西应该能帮你省下不少试错成本。

1. 为什么我决定自己组建一套代码审查工具链

1.1 团队里的三个"审查死角"

很多人以为给GitHub或者GitLab配上了Protected Branch，再装一个Dependabot或者SonarQube，代码审查就算完事了。实话说，这些工具单个拿出来都很好，但组合在一起之后，一般团队会碰到三个特别隐蔽的死角。

第一个死角是"审查意见停留在表面"。在没有规则引擎介入的情况下，人类审查者会把大多数精力花在看缩进、命名、有没有多余的空行这种低级问题上。不是说这些不重要，而是当一个人药铺把80%的注意力耗在这些机械性问题上的时候，真正需要人脑判断的逻辑漏洞、并发隐患、业务边界问题反而被漏掉了。我自己就吃过亏：一次Pull Request里有400多行改动，其中300行是格式化插件自动改出来的，审查者翻了几页看到全是格式变化，就不自觉地放松了警惕，结果一个嵌套事务的边界条件被漏掉了，上了生产之后偶发数据不一致。

第二个死角是"合并门禁是假的"。很多团队的GitHub分支保护规则只设置了"至少一个Approval"，但并没有限制"谁可以审批"，也没有要求"审查者必须不是提交者本人"。于是经常出现的情况是：张三提交了PR，自己点了个Approve，然后合并按钮就亮了。这种门禁不仅没有质量把关作用，还会慢慢摧毁团队的审查文化——因为大家发现规则就是摆设。

第三个死角是"审查的知识没有沉淀"。口头审查完、书面评论也提了，但三个月后问起来，大家都不记得当时为什么这么改、为什么拒绝那个方案。代码仓库里的commit message写得像日记，"fix bug""update style"这种占了一大半。

正是这三个死角，让我开始认真考虑一个问题：能不能在现有Git托管平台的基础上，加一层轻量的"审查编排层"，让机械的事情自动跑，让人的注意力集中在真正需要人判断的地方，同时把每一次审查的结论结构化地沉淀下来？这就是open-code-review这个项目最初的核心动机。

1.2 商业SaaS和自建开源方案的取舍

当时我试过几款商业SaaS的产品，比如市面上比较成熟的代码质量平台。客观说，它们的自动化分析能力和Dashboard都很成熟，开箱即用的体验很好。但我当时有三个顾虑。

第一是代码安全合规的问题。公司内部的代码不能随意往第三方云服务上送，尤其是涉及核心业务算法的仓库。要找安全评审、签NDA、走采购流程，那周期不是一两个星期能搞定的。

第二是费用问题。商业平台基本按人头或按仓库数收费，团队规模超过一定数量以后，这笔钱其实不少。特别是一些内部工具仓库，活跃度很低，但按人头算一个不少，性价比很差。

第三是定制化不够灵活。商业平台的分析规则是通用样板，对特定业务场景的支持往往要等官方更新。而一般的开发团队用的语言、框架、目录结构、commit规范差异极大，通用规则往往有大量误报，团队对平台的信任度降低之后，就干脆不看报告了。

相比之下，自建基于开源工具的组合方案，虽然要自己花时间去搭、去调，但至少有三个明显的好处：代码不出私网、成本可控、规则完全可以按团队自己的需求调。这也是open-code-review最核心的一条设计原则：不追求一次性搞定所有事情，而是先搭一个能跑通的最小闭环，再不断迭代。

1.3 open-code-review的定位：轻量自动化审查编排层

说了这么多，我得先给open-code-review一个明确的价值定位。它不是要替代GitLab或者GitHub的Code Review功能，也不是要替代SonarQube这种独立的静态分析平台。它更像是一个"编排层"——负责在提交PR或MR的时候，把一堆已有的开源工具按照正确的顺序跑起来，然后把各自的输出汇总成一份统一的审查报告，再把这份报告附到MR discussion里面，同时把结论同步给相关的人。

这套方案里，审查被拆成三个层次：

• 自动化层：处理那些机器可以明确判断的问题——格式规范、潜在Bug模式、依赖安全、代码覆盖率变化。
• 人工层：负责处理自动化层给不出的结论——逻辑正确性、架构合理性、业务语义一致性。
• 沉淀层：将每一轮审查的结论、拒绝原因、修改要求记录下来，生成索引，方便后续复盘与检索。

这个分割方式，是一线团队最需要但往往最失控的部分。很多团队自动化层几乎为零，把一切都压在人身上；也有一些团队过于依赖自动化，结果一屋子机器人提出一堆不痛不痒的comment，人类审查者干脆全Ignore。open-code-review在设计的起点上，就是想给这三层找到合理的配比。

2. 工具链选型踩坑：从Gerrit到GitLab+ReviewBot

2.1 我对比过的几套方案

在正式介绍我最终落地的技术栈之前，有必要说说我在选型阶段踩过的坑，以及为什么没有选择某几个非常主流的东西。

第一套考虑过的是Gerrit。Gerrit在开源社区地位非常高，尤其很多大厂内部用的都是它的某种变体，它把"Patch Set"和"Verified + Code Review"的分级流水线做到极致，对Android这种大仓多补丁的场景特别合适。但如果只是给一个几十人的团队做PR审查，Gerrit的问题是它需要把整个代码流转模式都改掉——它用的是基于Push的新Change模型，跟GitHub/GitLab的Fork + Merge Request模型很不一样。团队要重新学习一套交互模型，迁移成本超出了我当时能承受的范围。

第二套是GitLab自带的Merge Request Approvals和Code Quality功能。如果你的团队已经在用GitLab，这套东西的普及成本最低，开箱即用，权限模型也成熟。但GitLab自带的能力偏"流程控制"而非"审查辅助"——它能告诉你"这个MR需要一个人批准"，却不能告诉你"这份代码里这个函数是不是写复杂了"。我必须再叠加一层静态分析工具，才能达到我要的效果。

第三套是GitHub之上的一套组合：eslint + reviewdog + GitHub Actions。这个组合在JS/TS项目里非常顺滑。Reviewdog这个工具尤其强大，它可以把linter的输出转化为PR上的Inline Comment，审查者在PR里直接看到"这一行有这个错误"。但它的问题是对多语言支持不够均匀，我团队里还有Go和Python的仓库，就得再搭一层。

第四套是SonarQube。它是老牌的静态分析平台，支持几十种语言，有很强的规则定义能力和历史数据追踪能力，CI集成起来也很方便。但它的部署和维护相对偏重，需要一台单独的服务器跑PostgreSQL+SonarQube实例，而且规则配置项多到眼花缭乱。对一个小团队来说，投入产出比不太划算。

2.2 选型定下来的关键标准

在把我自己手上的方案全部列在纸面上对比过之后，我给选型定了几条硬标准。不是说每一套方案都要满足所有标准，而是在这些标准上的综合分要最高。

第一条是"集成成本低压过纯流程改造"。不能为了加自动审查而让团队改变原本的MR流程，最好是原有提交流程不变，只是在MR的合并条件上加一道门槛。

第二条是"审查结果必须落在MR本身"。不能把审查结果导出到另一个系统里让开发者去查，而是要以Inline Comment的形式直接出现在MR的Diff上。人都是懒惰的，如果看一次审查报告要点三个不同的链接，坚持不下来，这个方案就没法落地。

第三条是"规则可配置且更新方便"。团队的语言占比会变、代码规范会演进，规则配置如果不能做到改一个配置文件就能生效，会很痛苦。

第四条是"有扩展能力"。不能把自己绑死在一个语言的工具链上。至少做到如果以后要加一个新语言的linter，只需要写一个适配器而已。

综合这些标准之后，我最终选择了一主一备的架构，主流程用GitLab CE + GitLab CI，配合Reviewdog + 各语言的Linter和静态分析器，再加一个我自己用Python写的小脚本把各工具结果合并成统一JSON结构，最后通过GitLab API回写MR Discussion。有条件上也考虑过GitHub Actions的版本，但由于我们主要仓库在GitLab上，基本盘就定在GitLab了。

2.3 整体技术架构

这套open-code-review的方案架构，你可以理解为三个部分：

• 触发层：开发者在本地提交分支、发起Merge Request之后，GitLab CI的Webhook会自动触发一个pipeline。
• 执行层：Pipeline里面有若干个Job，每个Job负责一种检查。比如Go代码用golangci-lint，Python代码用ruff和mypy，前端代码用ESLint和Prettier，依赖安全检查用Trivy或者npm audit。
• 汇总反馈层：每个Job跑完之后把结果转成Reviewdog的diagnostic格式，由Reviewdog统一扇向GitLab，最终以Inline Comment的形式出现在MR的Diff上。

同时我写了一个很轻的Go语言二进制工具叫review-summary，用来把所有Job的JSON结果汇总成一个Markdown报告，包含总体结论、阻塞项数量、建议项数量、覆盖率变化等，然后在MR描述里更新这个报告。这样审查者一打开MR，第一眼就能看到"哪些问题必须修，哪些问题仅供参考"。

这个架构，相比直接用一款全家桶式平台的好处是：每一项都可以被替换。比如你不想用GitLab CI，想换GitHub Actions，那只需要把执行层的调度器换掉；不想用Reviewdog，想用代码弟弟自家的Bot都可以，因为汇总层只认标准JSON格式。它像在"流水线"和"工具"之间加了一层适配，保证了组织架构和代码仓演变时的灵活度。

3. 落地部署的完整过程：从空仓库到第一份自动审查报告

3.1 先解决"审查数据从哪来"：GitLab CI的事件接入

第一步要做的，是确定GitLab CI的触发条件。我建议你的流水线至少在三种情况下运行完整的审查：合并请求发起或更新时、推送到主分支时、以及定时任务（每日凌晨）。触发方式在.gitlab-ci.yml里面配置：

workflow: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"' - if: '$CI_PIPELINE_SOURCE == "schedule"'

这里有一个很关键的点：不要在push到任意分支时就跑全套自动化检查，否则大量临时分支也会触发流水线，白白消耗CI资源。只在MR事件和main分支推送时跑，是主流团队的标准做法。

然后针对MR事件，要拿到目标分支和源分支的名字，以及MR的IID（Merge Request的编号）。通过GitLab CI的内置变量就可以获得了，比如CI_MERGE_REQUEST_IID、CI_MERGE_REQUEST_TARGET_BRANCH_NAME、CI_MERGE_REQUEST_SOURCE_BRANCH_NAME。这些变量会在触发器作用于合并请求时自动注入环境。

如果你用的是GitLab Runner的Docker executor，建议在Runner上配置好镜像拉取策略，避免每次都重新拉几十GB的镜像。这个影响跑的速度，但更重要是不要因为权限问题导致runner拉不动私有镜像。

3.2 规则引擎的配置细节：Linter不是装完就能用的

这一步是整个方案中最花时间的部分，被很多人低估。

以Go仓库为例，golangci-lint在默认配置下，对大型仓不要说几十分钟都跑不完，而且会有大量历史存量问题冒出来，一屏红错误直接把开发者的积极性击穿。所以必须做一个动作：先跑一次全量，生成基线，然后在规则配置里只对"新增代码"做严格检查，对存量问题只提醒不阻塞。具体可以通过设置new-from-rev来实现：

linters-settings: new-from-rev: HEAD~1

意思是"只检查从上一个commit引入的新问题"。这个配置能救你的命。强烈建议第一次接入任何linter时，都优先考虑增量检查的模式，除非你的团队真的能从零开始处理存量问题。

Python仓库我用的是ruff+mypy的组合。ruff负责格式和一部分可静态判断的lint规则，mypy负责类型检查。这里要注意的是，mypy在接入初期往往会因为存量代码类型标注不全而出现大量错误。我的经验是先开一个宽松阶段的配置，比如只检查main包、忽略测试目录，跑通之后再把严格开关一点点打开。一次想全量铺开，通常以失败告终。

前端方面，ESLint其实已经是标配了，但那套经典的airbnb规则对所有新项目并不是完全适用。我的建议是，规则集的根尽量基于eslint:recommended或typescript-eslint/recommended，再根据团队自己的编码习惯加上少量的自定义规则，不要直接上大而全的规则集，否则会有大量格式类争议耗尽大家的耐心。

3.3 自动化检查与人工审查的衔接：Reviewdog的接入过程

在所有linter和静态分析器都跑出结果之后，下一步就是把结果回写到MR。Reviewdog在这个环节的价值非常大，不过它有两个细节容易踩坑。

第一个坑是使用方式。Reviewdog有两种运行模式：本地上手模式和CI模式。在CI里一定要使用-ci参数，表示它运行在CI环境中，否则它会假设自己在本地交互式终端里，行为会不同。第二，要指定reporter参数为gitlab-mr-discussion，这样评论才会落到MR的Discussion里。如果是GitHub，就把reporter换成github-pr-review。

一个典型的Job配置长这样（Go仓库）：

go-lint: stage: test image: golangci/golangci-lint:latest script: - golangci-lint run --out-format line-number | reviewdog -f=golangci-lint -name="golangci-lint" -reporter=gitlab-mr-discussion -level=warning only: - merge_requests

这里我把level设成warning，意思是这些评论不会自动阻塞合并，它们是给人类审查者参考的。真正要阻塞合并的条件，我在第4章会细说。

第二个坑是Reviewdog的token权限。很多团队图省事直接用一个读写了所有项目的Maintainer Token，这会带来安全隐患。建议为Reviewdog单独创建一个Project Access Token，权限只给该仓库的api权限（为了发评论），并且设为只读的"Report"角色。这样就算Token泄露，影响范围也就是这个仓库的评论能力，不至于影响到别的项目。

3.4 把每一次审查结论"存下来"：评论数据落库

Reviewdog把评论发到MR上面了，但如果我们不从GitLab API把评论拉出来做结构化存储，那这些结论在项目结束后就散落在各个MR里，没法检索。

我是这样做的：在Pipeline的最后一步，加一个agent任务，用GitLab API把当前MR的所有Discussion和Note拉下来，过滤出reviewdog自动生成的和审查者手动标注的，然后转存到一个PostgreSQL表里。表结构大概是这样：

这一步看似多余，但它的价值非常大。三个月之后你想统计"我们最近有多少个PR是因为并发问题被拒的"，或者"哪个模块的代码审查问题最密集"，直接从这个表里查就行了，不需要把几百个MR从头翻一遍。

我这个表是用Python脚本在Pipeline里写的，也可以你自己写一个简单的Webhook接收器，GitLab端设置既有的Webhook，推送成JSON格式，接收器存库。哪种方式都能用，关键是把闭环建起来。

4. 上线后必须处理的权限与门禁问题

4.1 权限模型：谁有权利批准什么

工具链跑起来之后，最容易被忽视却又最致命的是权限模型的设定。

首先是"谁可以批准MR"的问题。我见过很多团队用默认设置，仓库里所有人都可以approve，结果就是"你帮我approve一下"变成了一种人情交换。我的做法是在GitLab的项目设置中，把Approval Rules设为至少两位指定成员，其中必须包含具备相应模块所有权经验的人。如果两人有位，就把规则设为至少一人来自"后端维护者"组、一人来自"QA负责人"组。这样可以有效避免自己提交自己approve的情况。

其次是"提交者本人是否可审批"。GitLab有一个设置叫"Prevent author approval"，这个一定得打开。另外还要打开"Prevent reviewers from approving their own review"——这条很隐蔽，但非常重要，因为在某些情况下，一个模块的Owner是提交者和审批者几乎指的是同一个人，如果没有这个限制，容易产生"自己演独角戏"的审查。

我整理了一个权限清单，你可以直接参照：

• 项目Maintainer权限只给技术负责人和CI管理机器人。
• Developer权限给普通开发，允许创建分支和提交MR。
• 禁止"Author Approve"和"Self-Review"。
• MR合并权限仅限Maintainer角色，普通开发者即使有Approval也不能自己合并。
• 设置MR"过期未审查自动提醒"，72小时未处理就@相关审查者。

4.2 合并门禁策略：哪些情况必须卡住

在这个方案里，合并门禁我设置了这么几个等级，按严重程度从高到低排：

第一级是"阻塞型问题"。比如依赖中存在高危安全漏洞、引入了明确的数据竞争模式、覆盖率相比目标分支下降了超过5个百分点、mypy或TypeScript的强类型检查出现了error级别问题。这些条件触发任何一个，Merge Request的合并按钮就应该是灰的——要人工排除以后才能走。

第二级是"建议型问题"。比如代码里出现了重复片段、函数过长、某个组件的复杂度超标。这些由reviewdog发warning级别的评论，但是不阻塞合并。这个层级是正确的切入点：如果把所有lint问题都设为阻塞，一方面会导致团队去规避规则，另一方面会制造大量"修lint的commit"，没有实际价值。

第三级是"模板要求"。MR描述必须包含：改动背景、测试计划、影响范围、自测截图或日志。如果没有填写，机器人会在MR里留言提醒，但不会硬阻塞。这种软约束比硬阻塞更容易让团队接受，因为它在教大家"什么样的MR值得被审查"。

这里要专门强调一下Coverage门禁。覆盖率变化应该基于"全量项目当前覆盖率"来比较，而不是"新增代码的覆盖率"。因为后者的统计方式很容易被测试代码刷上去，并不能真实反映带风险的改动是否被覆盖到。当然这个也不是绝对的，但小团队我更建议看全量变化，噪音会小很多。

4.3 误报与噪音的治理：让工具学会闭嘴

自动化工具的灵敏度往往是个双刃剑。跑起来之后，开发者最反感的不是有问题，而是"一顿操作猛如虎，一看全是误报"。

我踩过一个非常典型的坑：有一段时间ESLint的no-unused-vars规则对TS文件里的interface某一项会偶尔误报，结果大量PR都带着一个"unused variable"的评论，开发者点过去一看又不是。这种评论持续了大概两周，团队里几个前端开发直接把reviewdog的评论当垃圾信息忽略掉了。后来我专门给这个规则加了一条exceptions配置，把误报率降到接近零，大家对工具的信任才慢慢恢复过来。

这个案例给我的教训是：在自动化工具刚上线的第一两个月，宁可少检查一些规则，也要保证每一条弹到MR讨论里面的评论都是有价值的。一旦审查工具被团队成员定性为"噪音来源"，后续想要再唤起他们的信任就很难了。

所以我还做了一件事：利用上一章提到的评论落库表，每月跑一次统计，看看reviewdog发的评论里有多少被开发者点掉了，有多少实际触发了代码修改。按"每条评论的后续commit内是否改动同一位置"来近似判断"这条评论是否被有效处理"。对有效处理率极低的规则，直接禁掉或改成只记录不提醒。这个指标我简单实现了，样本不多但很有代表性。

5. 让团队成员从"被迫审查"到"主动审查"

5.1 审查模版的心理学设计：降低第一个评论的门槛

工具链都搭好了，接下来真正难的是人的问题。

我发现新鲜事物倒入后，最大的阻力不是工具难用，而是"不知道怎么开始"。很多开发者的第一个PR被机器人和规则一堆评论淹没之后，整个人是懵的——不是不愿意改，而是不知道从哪一条开始改。

解决办法其实很朴素：给MR设置一个"审查填空模板"。不是那种高大上的文档，而是直接在MR描述区写清楚几条引导性指令。例如：

• 背景：这个改动想解决什么问题？如果是Bug，请附上复现步骤。
• 影响面：这次改动会影响哪些模块？是否可能影响老数据？
• 测试计划：你跑了哪些测试？哪些没有覆盖？
• 自检清单：是否处理了错误路径？是否有日志帮助排查问题？
• 一句话描述示范Review的范围。

这个模板的作用是把审查者的注意力引导到"应该关注什么"，而不是让他在几百行的diff里自己找重点。如果一个MR本身就写不清楚这些，那说明它还没有准备好被审查，或者说它需要再拆分。

5.2 数据驱动：把审查指标放到共享看板上

前面提到我存了所有审查结论到PostgreSQL，那个表格的价值到这里就真正发挥出来了。我每个月会从库里跑出来一张审查健康度看板，放在团队的共享大屏上：

• 平均首个评论响应时间：从MR创建到第一个reviewdot评论的时间。目标<4小时。
• 平均合并等待时间：从MR创建到合并的时间。目标<24小时。
• 自动审查阻塞率：被自动化工具阻塞的MR占比。
• 人工评论密度：每个MR平均有效人工评论数。目标在5~15条之间。
• 有效处理率：评论被开发者后续commit呼应处理的比例。

这些指标本身不是考核工具，而是帮团队找到流程的瓶颈。比如如果人工评论密度长期为零，说明大家的Review只是走个形式；如果评论密度极高，那可能是MR拆得太大了。透明化的指标能让问题暴露出来，多数人看到数据的变化就会自动调整自己的Review习惯，比任何制度的约束都管用。

5.3 轻量化评审节奏：把审查嵌进习惯而不是做成仪式

最后一个想分享的经验，是评审节奏的"轻量化"。

我们在团队里约定了一个非常轻的节奏：不设立独立的Review会议，也不要求MR在特定时间点集中评审，而是每天上午十一点前把待审MR列表统一丢到IM群里，@对应负责人，下午四点半之前需要给出结论或明确说明"预计明天几点能审完"。

下午四点半这个时间点我特别强调，它不是硬性的deadline，而是创设了一个"默认约定"，让每个人心里有数：如果今天不处理它，就要主动告诉对方明天什么时候能处理。这比默不作声地拖到周五要好得多。这背后在用的其实是"行为经济学"里面的默认选项效应——当你不设定一个明确的预期时间，"尽快审"这个模糊概念永远不是最优时间。

回顾这大半年open-code-review的运行历程，我个人最大的感受是：这套方案并没有发明任何新技术——GitLab、Reviewdog、各种linter都是现成的——它更多的是把"该自动化的事情"和"该人来判断的事情"彻底分了层，然后用统一的反馈和沉淀机制把它们衔接起来。如果你也想在团队里搭建类似的代码审查体系，我的建议是从最小的闭环开始：先给一个主力语言仓库配上增量式lint检查加Reviewdog回写MR的pipeline，让团队拿到第一份自动审查报告，再根据这一个月里出现的高频问题决定第二步做什么。工具不在多，能让团队在合代码之前愿意多点开两次MR看评论，就已经赢了一半了。