1. 代码审查这件事为什么我最后选择了开放式的做法先交代一下背景。我在团队里负责过好几年的代码质量基础设施从最早的互相口头 review到后来搭 GitLab MR 流程再到引入独立审查工具踩了不少坑。说实话代码审查这个事听起来简单——不就是让别人看看你写的代码吗但真正落地过的人都知道这里面的门道远比想象中多。open-code-review这个项目标题乍一看像是一个工具名称但其实它代表了一整套思路开放式的代码审查。所谓“开放”我理解有三层含义。第一层审查流程本身要开放不局限于某一个人、某一个角色而是让所有相关的人都能参与第二层审查工具要开放尽量用开源的、可扩展的方案而不是被某个商业平台绑死第三层审查标准要开放团队里的规则不是某个人拍脑袋定的而是大家共同维护、持续演进的。这篇文章我想完整梳理一下围绕“开放式代码审查”这个主题从核心痛点、方案选型、落地步骤、常见问题这几个维度展开。无论你是在带技术团队还是想优化自己项目的协作方式这篇内容都会对你有实际帮助。我尽量把那些文档里不会写的细节也翻出来毕竟这些东西才是真正影响落地效果的关键。2. 先把审查的底层逻辑想清楚再来谈工具2.1 代码审查到底在审什么很多人对代码审查的理解停留在“找 bug”上这个认知偏差很大。我在实际推动审查流程时发现如果团队把审查的核心目标定成“抓错”那这个流程很难持久。因为人会本能地抵触被挑错尤其当审查方式不当的时候抵触情绪会更重。代码审查真正应该关注的核心我总结下来有这么几类设计合理性这个改动从架构上是不是正确的方向有没有过度设计或者设计不足可读性与可维护性下一个接手这段代码的人能不能在三分钟内看懂它的意图一致性这个改动和项目里已有的风格、约定、模式是否一致安全隐患与性能隐患有没有明显的安全漏洞、性能瓶颈、资源泄漏风险测试覆盖新增代码对应的测试是否充分边界情况有没有考虑到你会发现风格类的问题比如缩进、命名习惯其实是审查里最不值得花时间的东西因为这些完全应该交给格式化工具和 lint 检查来自动处理。但很多团队的审查还停留在人工盯这些琐碎问题的阶段这本质上是对人力的浪费。我记得有一次团队里一个后端同学提交了一个接口改动从功能测试来看完全正常。但负责审查的同事在代码里发现这个接口在异常分支里会吞掉错误信息只返回一个统一的失败提示。从测试角度这个改动是“通过”的但从可维护性角度看这会让线上问题排查变得极其痛苦。这种问题只有有经验的人做设计层面的审查才能发现单纯的自动化测试替代不了。2.2 为什么“开放”是审查质量的关键变量传统意义上代码审查往往是一个“关卡”而非一个“过程”。提交者写完代码找一个负责人看一下通过就合并不通过就打回。这是最经典的审查模式但它的弊端也很明显整个链条是线性的、封闭的知识只在两个人之间流动其他人既看不到也学不到。我推动的开放式审查核心改变在于把审查从“关卡”变成“过程”。具体来说有几点第一审查对所有团队成员开放不局限于固定的人员。只要对这个模块有兴趣、有经验的人都可以参与讨论。后端同学可以看前端的改动测试同学可以看开发的逻辑。很多时候不同视角带来的意见价值会超出预期。第二审查过程中的讨论记录对全团队可见。这意味着什么意味着每一个设计决策的来龙去脉都被沉淀下来了。新人入职后去看历史审查记录就能快速理解项目里各种设计选择背后的原因这比任何文档都真实。第三审查标准本身是开放式维护的。团队把常见的审查要点沉淀成 checklist但这个 checklist 不是某个人定的而是大家在审查过程中不断补充、修订的。每次审查中发现新的典型问题就把它加到清单里发现某个清单项已经不适合现在的项目阶段了就讨论着把它改掉。如果你只是想在团队里快速搭一个能用的审查流程那闭不开放其实差别不大。但如果你希望代码审查能长期沉淀价值变成一个团队学习、质量保障、知识管理的综合载体那就必须走开放式的路线。2.3 一线实践中的审查节奏把握这里我想聊一个比较细节但很容易影响体验的问题审查的节奏。很多团队遇到的问题不是“要不要审查”而是“审查拖得太慢”导致 feature 分支和主干分叉越来越大合并冲突越来越多最后大家为了赶进度大量改动带着风险直接合入。我个人的经验是审查的响应时间是有黄金窗口的。一个 pull request 提交后如果在半小时到两小时内有第一轮反馈提交者会保持在一个连续的工作状态里修改效率很高。如果拖到第二天甚至第三天才开始审查提交者可能已经切换到其他任务上再回头改代码的心理成本就会明显增高。所以搭建开放式审查流程的时候不要只想着“怎么让审查更严格”也要思考“怎么让审查更快”。我见过一些团队审查规范和流程都搭得很完善但就是响应太慢到最后大家宁可绕过流程偷偷合并代码。这不是人的问题是流程设计的问题。3. 搭建自己的一套开放式审查基础设施3.1 工具选型从 GitLab MR 到独立审查平台的取舍市面上做代码审查的工具不少大的有 GitHub/GitLab 自带的 Pull Request/Merge Request 功能专业的有 Gerrit轻量部署的有 Gitea 搭配第三方插件还有一些在线服务类的如 Reviewable 等。我自己的项目经历里GitLab、Gerrit、Gitea 这几个都实际用过这里说说我的感受。先说 GitLab MR。这个是目前中小团队用得最多的方案它的优势很明显和代码仓库本身紧密结合创建 MR、评论、讨论、审批、合并一条链路下来体验很顺。但对于开放式审查来说GitLab MR 有几个局限。第一它本质上是围绕“合并请求”设计的而不是围绕“代码审查”设计的。MR 挂了之后讨论还在但讨论的沉淀和检索能力比较弱。第二它的权限模型比较固化想做更细粒度的审查角色划分需要配置很多东西而且改起来麻烦。再说 Gerrit。Gerrit 是我个人比较喜欢的一个工具它某种程度上就是为“开放式代码审查”这个概念量身定做的。它的核心工作流是开发者把本地 commit push 到 Gerrit 的特殊 ref 上系统生成一个 review 请求审查者逐条查看变更、打分不同分数表示不同的审查意见打完之后点击 Submit 才会真正合入目标分支。这个模型和 Git 本身结合得非常紧密而且它的访问控制和标签系统很灵活能做很多细粒度的权限配置。Gerrit 的问题是学习曲线比较陡。第一次用的人会对它的 refs/for/master 这种 push 方式很不适应而且它的 UI 是出了名的“工程师审美”功能强大但不怎么好看。但如果你的团队能跨过这个门槛Gerrit 在开放式审查这个场景下的表现力是很强的。还有一类是纯工具的方案比如 Reviewable它可以挂在 GitHub 之上提供更结构化的审查体验。不过我用得不多这里就不展开讲了。结合我这些年折腾下来的体会如果你团队规模不大、追求快速见效GitLab MR 足够用了重点是流程设计而不是工具。如果你对审查质量有更高追求、团队也愿意付出学习成本那 Gerrit 是值得认真考虑的选项。3.2 用 Gitea Drone 自建一套轻量级审查环境如果你想完全掌控审查链路不想被 GitHub/GitLab 这类平台限制我推荐一个我实际搭建过的组合Gitea 做代码托管Drone 做 CI然后用 Gitea 的 Pull Request 功能配合自定义分支保护规则来做审查管理。Gitea 是一个极轻量的 Git 托管服务Go 语言写的单二进制文件部署资源占用非常小。我自己在 2 核 4G 的云服务器上跑 Gitea Drone MySQL带二三十个人的开发团队完全无压力。相比 GitLab 动辄几个 G 的内存占用Gitea 的轻量优势非常明显。搭建步骤其实很简单核心就这么几步第一步装 Gitea。下载对应平台的二进制文件准备一个数据库SQLite 也能用但团队规模大一点建议上 MySQL初始化配置之后就能跑了。Gitea 的配置文件在 custom/conf/app.ini端口、数据库、域名这些都可以在这里配置。第二步配置仓库分支保护。这是开放式审查的关键配置。在仓库设置里开启“Protected Branch”选好你要保护的分支一般是 main 或 master然后勾选“Enable Pull Request”和“需要审查通过才能合并”。这里有几个小细节设置最少审查人数。对于核心仓库我建议至少 2 人。开启“阻止未解决讨论的合并”确保所有对话都被处理完毕。如果有 CI 的话勾选在合并前检查 CI 状态避免坏代码合入主干。第三步接入 Drone 做自动化门禁。Drone 和 Gitea 的集成非常顺滑在 Gitea 的应用设置里创建 OAuth 应用拿到 client id 和 secret填到 Drone 的配置里即可。Drone 的 pipeline 配置写在项目根目录的 .drone.yml 里。我常用的一个最小配置大概长这样kind: pipeline type: docker name: default steps: - name: lint image: golang:1.21 commands: - go vet ./... - gofmt -w . - git diff --exit-code - name: test image: golang:1.21 commands: - go test ./... -race -coverprofilecoverage.out这个配置干了什么第一步做静态检查和格式检查如果代码没格式化或者有 vet 报错pipeline 直接失败这就把流程里最不值得人工看的那些东西自动化掉了。第二步跑测试带竞态检测和覆盖率输出。两个步骤都过了MR 才有资格被合并。这套组合下来的效果是机器负责所有机械化的检查人只负责真正需要人判断的事情——设计合理性、可维护性、可读性。审查的负担大幅降低审查的质量和意愿自然就上来了。3.3open-code-review场景下的工具扩展如果你是奔着“open-code-review”这个项目名来的你可能会想除了上面这些通用工具有没有专门面向开放式审查的扩展工具。我梳理一下我用过和了解过的一些审查辅助类的工具有几类。一类是针对多语言项目的静态分析集成比如在 CI 流程里接入 SonarQube它能把代码中的异味code smells、重复代码、复杂度问题直接扫描出来审查者打开页面就能看到质量指标。这个对开放式审查特别友好因为新加入审查的人不一定了解项目的坑质量扫描能给他们一个快速了解代码健康度的起点。另一类是差异化的审查辅助比如 codecov 这种覆盖率服务。它能在 MR 的 diff 上直接标注哪些行没有被测试覆盖到这样审查者一眼就能看到新增代码的测试死角不用自己一行行去对照。还有一类是知识沉淀类的工具比如我见过一些团队会用 Confluence 同步整理审查中发现的典型问题形成团队自己的审查模式库。虽然这不是一个严格意义上的“工具”但在开放式审查里这种知识的持续积累比任何工具都重要。我目前的项目群里有一套约定凡是审查中发现的、具有普适性的问题都会在审查结束后提炼成一条“模式说明”格式是问题描述—影响—建议做法—示例代码。按月汇总一次内部分享。三个月下来团队里重复踩坑的次数明显下降了。4. 审查流程落地的核心细节与实操要点4.1 从项目初始化阶段就开始设计审查规则很多人是在项目跑起来之后才想起要搭代码审查流程这时候往往已经积累了大量“历史遗留代码”想补审查规则也难下手。我个人的建议是审查规则一定要在项目初始化阶段就同步设计因为那个时候的改变成本最低。具体来说我在新项目启动时会做这么几件事在仓库根目录放一个 CONTRIBUTING.md写清楚提交代码的流程、审查要求、checklist、合入门禁条件。这个文件就是团队的审查契约。配置好分支保护规则从一开始就不允许直接 push 主干。搭好最基础的 CI 流程哪怕只是跑一下编译和 lint也能保证 MR 不至于带进来一堆低级问题。定好小组规模。审查分散到太多人会导致责任稀释太少人又会形成瓶颈。我一般按模块划分每个模块指定 2-3 名核心维护者做默认审查人但其他同事随时可以参与讨论。这里面最常见的一个坑是项目一开始没有配置任何保护措施等代码库大了再想强推流程阻力会大得多。因为大家已经习惯了自由修改突然多出强制门禁第一反应一定是抵触。4.2 让提交被“更容易看懂”是提升审查效率的另一半开放式审查的效率不只在审查者这边也在提交者这边。我说句实在话很多 MR 让人不想 review不是因为改动太大而是因为提交本身太混乱了。一个 MR 里混着三个不相关的功能、十个随意的“fix typo” commit、没有写清楚背景和目的描述——这种提交再负责的审查者也会头疼。所以我定的规矩是MR 本身也要被审查。这里说的“审查 MR”不是指审查代码而是审查提交信息和变更范围的清晰度。具体要求有三条第一一个 MR 只做一件事。如果改动涉及多个功能拆成多个 MR。这个习惯对回滚友好对 Code review 更友好。review 一个 100 行改动的 MR 和 review 一个 1000 行改动的 MR付出的精力完全不是一个量级。第二MR 描述里必须写清楚“为什么”。我要求团队在描述里写明这个改动要解决什么问题为什么选这个方案而不是另一个有没有考虑过替代方案这些信息对于审查者理解代码上下文至关重要。实际上很多时候写了这段描述之后提交者自己就会发现原本的方案有漏洞。第三保持提交历史清晰。这个可以通过 rebase 的方式整理在 MR 合并前把一堆“wip”、“fix”、“test” 的中间提交压缩成几个有意义的提交每个提交都能独立通过 CI。4.3 审查意见的沟通原则开放式审查做得久了你会发现一个规律技术问题通常不是最难解决的最难的是沟通问题。代码是写给人看的审查意见也是写给人看的。同样一个意见表达方式不同对方接受的程度完全不同。这些年我积累下来的审查沟通经验可以浓缩成几条用提问代替断言。“这里是不是应该考虑并发情况”比“这里有严重的并发 bug”更容易让对方进入思考状态。给出修改建议时尽量附上示例代码。光说“这样写不好”是没用的给出“可以这样写”的参考才能真正帮助对方。夸和批要平衡。审查者如果只提问题从不说好话时间长了提交者会本能地防御。我看到好的设计、优雅的处理会明确表达出来。区分“必须改”和“建议改”。这两个如果不区分对方会把所有意见都当成必须改最后要么疲于应付要么对真正重要的意见也失去敏感度。如果审查意见比较尖锐最好私下同步沟通一下而不是在公开评论里直接开炮。公开场合的评论是给全团队看的要想着看的人的感受。这一块我特别想强调的是开放式审查意味着讨论记录会长期留存在团队知识库里。每一条评论既是在对当下这个人说话也是在给未来所有翻看这段记录的人看。所以言简意赅、就事论事尽量少用反讽和玩笑这些东西在文字沟通里太容易被曲解了。5. 实操过程与核心环节实现5.1 以 Gerrit 为例的完整审查流转配置前面提到 Gerrit 是开放式审查的工具里非常独特的存在这里我用它走一遍完整的配置流程方便想尝试的同学有一个清晰的参考。环境准备。最简单的方式是用 Docker 装一个带 PostgreSQL 的 Gerrit。我之前用过官方镜像配合 docker-compose 的方式基础的 docker-compose.yml 大概是这样的version: 3 services: postgres: image: postgres:13 environment: POSTGRES_USER: gerrit POSTGRES_PASSWORD: gerrit POSTGRES_DB: reviewdb volumes: - pgdata:/var/lib/postgresql/data gerrit: image: gerritcodereview/gerrit:3.8 ports: - 8080:8080 - 29418:29418 depends_on: - postgres volumes: - git-volume:/var/gerrit/git - index-volume:/var/gerrit/index - cache-volume:/var/gerrit/cache environment: CANONICAL_WEB_URL: http://localhost:8080 GERRIT_INIT_ARGS: --install-pluginchecks-api登录认证配置。Gerrit 默认支持 OpenID 模式但对于团队内部使用我一般建议配置 LDAP 或者直接 http 认证。如果只是小团队试用可以先开启auth.type DEVELOPMENT_BECOME_ANY_ACCOUNT方便快速体验生产环境千万别这么干。分支与权限配置。这是 Gerrit 和 GitLab 差异最大的地方。Gerrit 里要配置refs/for/*的 Push 权限允许开发者提交审查然后在目标分支比如 refs/heads/master上设置Push权限为不允许直接操作Submit权限只开放给有集成权限的人。这是审查流程得以强制实施的关键。审查标签。在项目配置里定义标签比如 “Code-Review” 和 “Verified”。Code-Review 标签就是人工审查打分2 表示可以合并1 表示关注意见-1 表示有问题-2 表示严重问题阻断合并。Verified 标签一般由 CI 系统自动打跑绿了打 1跑红了打 -1。Gerrit 的规则是只有同时满足 Code-Review 2 且 Verified 1或必要条件时Submit 按钮才可点击。这个机制就把“人工审查”和“机器检查”巧妙地结合到了一起。完整推送到审查的流程。当一个开发者完成本地修改后提交并推送到 Gerritgit push origin HEAD:refs/for/master这个命令的本质是把提交推送到 master 的审查队列里而不是直接写入 master。Gerrit 会为它生成一个 review 变更其他审查者登录网页就能看到。审查通过后点击 Submit提交才会真正合入 master。如果是多 commit 的情况Gerrit 还会把它们按 Change-ID 组织成同一个变更集方便整体审查。5.2 如何把自动化检查和人工审查衔接起来任何一套审查工具光靠人工盯是不行的自动化门禁是质量底线。我之前深度用过的方案是把 SonarQube 和 Gerrit 衔接起来。SonarQube 扫完代码后会生成报告通过 Gerrit 的 sonar 插件把 issue 直接关联到对应的代码行上审查者写评论时可以直接引用这些 issue。这样新人做审查时不用从零开始找问题先看机器标出来的点再看机器漏掉的部分上手效率会高很多。除了扫描还有一个关键的自动化是格式检查。我推荐用 pre-commit 在本地先挡住一部分问题。每个项目加一个 .pre-commit-config.yamlhook 里跑 clang-format、black、eslint 这类工具本地提交前就强制格式化。这样走到审查阶段时代码已经很“干净”了审查者不会再被无意义的格式问题分心。5.3 审查清单的实际用法最后分享一份我们团队实际在用的审查 checklist它不是死的条文而是随着团队反馈不断调整的动态清单。你可以直接拿这个作为起点结合自己的项目语境去改。功能正确性改动逻辑是否正确处理了正常分支和异常分支边界输入有没有考虑并发情况下的行为是否可控性能影响这个改动会带来多少额外的 CPU/内存/网络开销有没有更轻量的实现方式安全性用户输入是否校验有没有注入风险敏感数据是否泄露到日志里错误信息会不会暴露内部实现细节可读性变量名、函数名是否准确表达含义注释是否解释了“为什么”而不仅是“是什么”函数是否过长、有没有明显可以拆分的地方可测试性新增代码是否有对应的单测测试是否覆盖了核心场景和边界情况测试本身有没有把实现细节耦合死导致后续重构很容易坏测试依赖管理新增的依赖是否必要版本是否锁定许可证和项目适配吗你可以看到这份清单里没有一条是“缩进对不对”、“命名规不规范”这类琐碎的东西。因为格式和风格问题早就被自动化工具解决了人工清单就应该聚焦在有判断空间的部分。6. 常见问题与排查技巧实录6.1 审查者的“不敢说不”困局这里先讲一个我在多个团队都见过的现象审查流于形式。具体表现是MR 也有人看评论也有人发但发的都是“LGTM”、“1”、“没问题”。代码合入之后线上出了事故往回翻记录才发现当时那条关键的代码逻辑根本没人真正审过。为什么会这样我总结下来有几个原因。一是审查者觉得自己资历不够怕提了问题被笑话二是项目复杂度高审查者看不懂但不好意思说三是团队节奏太快大家默认审查只是个流程过场不愿意在这上面多花时间。应对方法上面说过一部分这里再补充一个更实际的在团队里明确区分“审查通过”和“理解充分”这两件事。我定的规矩是如果审查者没有看懂某个改动绝对不能只给“1”了事。看不懂不是丢人的事提交者有义务解释清楚。如果提交者解释不清楚那大概率说明代码本身就有表达问题。所以“看不懂”应该是一个要求进一步解释的信号而不是一个默默放行的理由。6.2 提交者与审查者的争议僵局另一种常见问题是提交者和审查者对某个方案意见不一致公说公有理婆说婆有理最后僵在那里。有的团队处理方式是“谁资历高听谁的”有的团队是“谁提了 MR 谁最终拍板”。这两种我都不太认同。我习惯用的方式是引入“决策记录”机制。如果审查争议发生先把争议点完完整整地写进 MR 的评论里写明双方观点和依据。然后约定一个时间范围比如一天如果一天内还没有达成一致就升级给更了解相关模块的技术负责人或架构师拍板并且拍板的理由必须公开写回审查记录里。这个机制的核心是争议本身不可怕可怕的是争议没有闭环导致热情消耗和内耗。6.3 关于自动化门禁的误报与噪音自动化检查用起来之后另一个问题就来了误报太多人就不信了。我见过一个团队SonarQube 扫出来的 issue 有一半是误报或者不涉及当前改动的问题导致审查者每次打开 MR 都要先在一堆噪音里翻找真正有价值的内容久而久之机器检查就形同虚设。解决这个问题的思路是分层处理。第一层CI 里的检查只阻断绝对确定有问题的比如编译失败、测试挂掉、安全高危漏洞其余的只记录不阻断。第二层SonarQube 这类静态分析的规则集要按项目实际情况裁剪把不适合项目的规则关掉把团队踩过的坑的规则打开。第三层定期做规则评审把误报率高的规则调阈值或者直接下线。总结一句话自动化的目的是给人工减负不是给人工添乱。如果自动化带来的噪音大于价值那就是配置需要调整了而不是继续让团队硬扛。7. 一些工具上的横向对比与选型建议关于工具选型很多朋友私信问我到底哪一个最好用我没办法给一个绝对的答案因为最终取决于你的场景。这里做一个我自己的主观对比仅供参考。维度GitLab MRGerritGitea CI部署成本中高依赖较重中有 Docker 镜像低单二进制部署学习曲线平缓陡峭平缓审查粒度文件级评论 行级评论基于提交补丁的逐行审查文件级评论 行级评论权限模型角色固定配置灵活非常灵活细粒度角色固定配置灵活与 CI 集成好通过插件实现好原生支持 Drone适合场景面向协作的主流团队对质量有执念的团队资源有限、想自建的人群Gerrit 让我最喜欢的一点是它把“代码审查”这件事变成了一个“面向提交”的过程而不是“面向 MR 的评论”。每一个 commit 都可以被独立审查审查记录和 commit 绑定在一起历史可追溯性极强。但它的确不太适合想要“即开即用”体验的团队。如果你现在的项目规模不大、团队协作方式灵活我建议从 GitLab MR 或 Gitea 起步把流程和规范跑顺再去追求更重的工具。工具永远只是流程的载体真正决定审查质量的是人的投入度和规则的合理性。最后分享一点实在的体会花了这么多篇幅讲方案、讲工具、讲流程最后想讲点更底层的感受。代码审查这个事做成什么标准算“成功”我自己的判断标准只有一个团队里每个人在提交代码时都真心希望有人能帮自己看一眼而不是把审查当成必须通过的关卡。当提交者主动期待被审查的时候这个流程就已经不是“负担”而是一个互相学习、互相补位的平台了。我推动开放式审查这几年最大的收获其实不是质量指标的提升而是团队讨论问题的氛围发生了变化。以前是出了问题大家互相甩锅现在是大家会翻审查记录看看当时的决策是怎么做的。这种变化一时半会儿看不出来但长期积累下来对一个团队的技术底蕴影响是很大的。如果你也在打算在团队里推动代码审查我的建议是先别急着选工具、定规则先和团队成员聊一聊看看大家最顾虑的是什么。把顾虑解决了规则自然能执行下去。
