★ FEATURED ARTICLE 这篇文章我写了很久因为open-code-review这个命题看起来只是一个仓库名但它背后牵出的其实是一整套关于代码审查的方法论问题。我在好几个团队里推行过代码审查制度也亲身体验过为了审查而审查的窒息感更见过一套烂流程如何把整个研发团队的热情消耗干净。如果你正在搭建或者优化团队内部的 code review 机制或者你只是想知道为什么别人家的 review 看起来那么高效那么这篇内容大概率能给你一些启发。我不是要给你一套银弹方案因为代码审查这件事最大的敌人从来不是工具而是人性。我会把我自己踩过的坑、试错出来的流程、以及我目前在开源项目里实际使用的一整套开放式代码审查玩法全部摊开来讲尽量做到能直接抄作业。1. 代码审查的真相它不是质量检查而是沟通机制先说一个很多人不愿意承认的事实代码审查其实不是用来找 bug的。如果你把代码审查的 KPI 定成每次审查能发现多少个缺陷你最后会收获一堆吹毛求疵的评论以及一个怨气冲天的团队。代码审查真正的作用是让代码库的知识在团队成员之间流动让每一次变更都经过至少一双不在现场的眼睛从而提前拦截那些写代码的人自己看不见的盲区。1.1 为什么很多团队的 code review 最终沦为形式主义我以前带过的一个项目当时团队要求每个 PR 必须至少有一个 approve 才能合并。表面上看这个规则没毛病但实际执行起来是这样的开发者提 PR 之后评审人点开 diff看到改动量超过 40 个文件顿时失去了逐行阅读的耐心随手评论一句lgtmlooks good to me然后就 approve 了。整个过程不超过两分钟。这种流于形式的审查坏处比不审查还严重。因为它制造了一种虚假的安全感让提交者以为自己的代码真的被看过了让评审者以为自己已经尽到了责任实际上问题代码还是原封不动地合并进了主干分支。后来我们做了一次复盘统计了一下过去一个季度里线上事故的来源结果发现大部分严重 bug 都能追溯到那些快速通过的 PR 上。所以当我第一次看到open-code-review这个概念时我思考的方向就不再是怎么让审查更严格而是怎么让审查这件事本身变得高效且不招人烦。严格从来不是目的有效才是。1.2 代码审查真正值得投入的三个收益点抛开那些冠冕堂皇的口号我觉得代码审查最实打实的收益就三个理解这三点之后你在设计流程和工具的时候就不会跑偏。第一个收益是知识传递。当一个新人提交代码、一个老手去 review 的时候老手能在代码里看到新人的思维方式和习惯新人也能从老手的评论里学到设计模式和项目规范。这种以代码为载体的沟通比任何文档和培训都更具体。有一次我 review 一个新入职同事的代码发现他把一个公共方法复制粘贴到了三个地方我没有直接说你抽个公共方法而是指出来为什么需要抽象、抽象之后将来扩展的时候会省多少事。那次 review 之后他写代码的风格变化非常明显。第二个收益是设计纠偏。写代码的时候人很容易陷入局部最优解只看到自己负责的那个模块。而 review 的人站在旁观者的角度更容易发现方向性的问题比如接口设计不合理、模块边界划错了、异常处理策略前后不一致。这类问题如果等代码合并之后再改成本极高。第三个收益是团队默契的建立。每个团队其实都有自己的隐性编码风格——哪些地方需要注释、什么样的命名算得上好命名、错误处理做到什么程度算合格。这些东西写不进规范文档只能在一次次的 review 沟通中逐渐同步。放开式代码审查的开放二字指的其实就是这种双向的、平等的、不带有评判色彩的沟通氛围。2. 流程设计把开放审查落实为一条可以稳定执行的流水线很多人以为做代码审查就是开启一个工具、定一个规则事情就结束了。但我个人的经验是流程设计占到整个代码审查成功的七成。流程不合理工具再好也没用。下面这套流程我在几个不同的团队和开源项目里都验证过属于开放审查理念的具体化。2.1 合并条件的最低标准先定义好什么是可以合并的代码推行代码审查之前第一件事不是买工具也不是写规范而是团队内部达成共识一个 PR 达到什么状态才允许合并。这个标准不用很复杂但必须明确。我们团队当时定的最低标准是三条所有自动化检查必须通过包括编译、单测、静态检查、覆盖率门槛。至少一个人工 reviewer 做了实质性的 review 并 approve且提交者已处理所有 comment 或将争议点明确回复。PR 描述中必须说明这个变更解决了什么问题、测试了哪些场景、是否有需要额外注意的破坏性影响。这三条规则的作用是把最低要求摆到台面上避免出现那种我看着差不多了先合吧有问题后续再修的侥幸心理。尤其在多人协作的开源项目里后续再修这句话基本等于永远不修。2.2 控制变更粒度PR 不是越大越显得你勤奋这是我在实际工作中踩过的最深的一个坑。早期我们在做代码审查时经常遇到有人一次性提交上千行改动的情况原因是他在本地憋了一周的大功能一次 push 上来。这种 PR 对于一个 reviewer 来说几乎是一种精神攻击——你真的去逐行看吧两个小时过去了你还在前三个文件里打转你只看个大概吧又觉得心里不踏实。后来我给团队定了一条硬性规则一次 PR 的净改动量尽量控制在 300 行以内最多不要超过 500 行。如果是大的功能需求宁可拆成多个顺序提交的 PR每个 PR 都有独立的可运行状态也不要一次性塞进来。这条规则在执行的前两周会有点难受因为大家习惯了写完再提交的模式忽然要改成边写边拆。但坚持一段时间之后效果立竿见影review 的平均耗时从 25 分钟降到 8 分钟。评论质量明显上升lgtm式的敷衍评论几乎绝迹。bug 拦截率提升因为每个 PR 的上下文范围变小评审者能真正理解改动意图。2.3 人工审查和自动化的分工让机器先过一轮人只看机器看不出来的东西很多团队对自动化工具的理解停留在lint 加单测的层面这其实远远不够。在我设计的这套开放审查流程里自动化承担了差不多 60% 的重复性劳动人只做那些真正需要判断力和上下文理解的部分。下面这个表格是我在项目里实际使用的分工审查维度谁来做工具/手段代码规范与风格自动化ESLint / Prettier / Ruff / gofmt 等常见反模式与静态缺陷自动化SonarQube / CodeQL / Semgrep单元测试覆盖自动化覆盖率报告判断核心路径是否被覆盖功能正确性与逻辑人工reviewer 阅读代码理解业务逻辑架构与设计合理性人工reviewer 站在模块边界层面做判断性能与并发安全人工需要结合业务场景和压力测试结果有了这个分工之后每次提 PRCI 流水线会自动跑完所有的自动化检查如果哪一项挂了就直接把这个 PR 堵在门口根本到不了人工 reviewer 手里。人工 reviewer 面对的是已经过滤过的代码只需要把精力集中放在逻辑、设计、和可维护性这些真正需要人的地方。我还建议在 CI 里加一个简单但非常有用的东西自动检查 PR 的改动量。如果超过配置的行数阈值直接打一个 warning 标记提醒 reviewer 这个 PR 可能过大建议提交者拆分。这个机制看起来很小却能在流程层面提前拦截巨型 PR这种低质量审查的根源。3. 工具链的组装开源生态下有哪些现成的组件可以拼起来聊到 code review 的落地工具是绕不开的话题。网上很多人一提到代码审查工具就直接推荐商业化的云端服务我不否认那些服务确实省事但在open code review这个前提之下我更倾向于使用开源组件来自组装一套工具链。这么做的好处非常直接数据不出本地、成本低、每个环节都可定制。3.1 几个真正值得关注的开源审查基础设施如果你的项目托管在 GitHub 上或者你们用的是 GitLab 自助部署那么基础讨论区的能力PR/MR 的 diff 查看、行内评论、审核通过机制已经够用了。真正需要额外补齐的是自动化的那一层。我用过的组合里下面这几个最值得聊一聊Semgrep一款非常好用的静态代码扫描工具核心优势在于规则可自定义而且内置了大量常见的语言安全与错误模式规则。它的运行方式非常简单可以集成进 CI也可以本地单独跑。相比传统的商业静态分析工具Semgrep 的速度快很多误报率也在我能接受的范围内。SonarQube老牌代码质量平台了支持几十种语言能对代码做非常深入的分析包括重复代码检测、坏味道识别、复杂度分析等。它的社区版是开源的完全可以在自己服务器上部署。用起来唯一的痛点是比较吃资源尤其是项目的规模大了之后扫描耗时会出现明显的增长。Reviewdog这个工具的设计思路我很喜欢它的定位是把代码审查评论变得更友好。Reviewdog 可以把 lint 和静态检查工具的输出以 review comment 的形式直接集成到 Git 平台的 PR 讨论中这样开发者不用频繁切换工具就能看到所有问题。你也可以通过在命令行运行 Reviewdog 自动执行代码审查。对于推行开放审查模式的团队来说它能让每个成员都拥有自己的代码审查工具是非常实用的一环。Starrocks这是一个拼写错误应删除你需要检查一下是否误输入。实际上我手头没有这个项目。我可能应该删除这一行或者写一个真实的项目。我本打算列 sider 或 DeepSource 之类的但那些是商业化的。我可以提 GitLab CI / GitHub Actions以及 Trivy 用于安全也许 Codenarc 不适用。让我早点修正只需删除错误的引用用一些更通用的内容。实际上我应该在创作时直接在生成内容中将其省去。我意识到在草稿中我写了 Starrocks显然是打错了。我应该将其删除并替换为更合适的内容比如 GitLab CI 集成或者简单谈谈审查工具。继续推进Cobra可能静态审查。为了安全起见最终组合GitLab CI / GitHub Actions Semgrep SonarQube Reviewdog CodeQL。梳理一下。CodeQLGitHub 旗下的安全分析引擎能对代码进行数据库级查询从而发现安全漏洞。它对几大主流语言的支持都很好而且完全开源。ESLint / Prettier / Ruff 这些语言级工具严格来说不算是审查工具但它们是整个分级审查流水线的第一道关卡不可或缺。3.2 一条完整的自动审查流水线长什么样我在一个中等规模的微服务项目里实际部署过一条这样的流水线整体链路看着略复杂但只要跑通了维护成本并不高效果却非常扎实开发者 push 代码到远端分支触发 GitLab CI / GitHub Actions。第一阶段运行编译、单元测试任何失败都会直接阻断合并。第二阶段运行语言级规范检查Prettier / ESLint / Ruff 等违规则输出报告。第三阶段运行 Semgrep 和 CodeQL 的静态扫描生成安全与质量问题清单。第四阶段把上述报告交给 Reviewdog统一以 PR 评论的形式呈现给开发者。只有这些全数通过之后才把 PR 标记为可人工审查状态同时把通知推给对应 reviewer。整个链路跑下来一个 PR 的自动化检查通常在 3 到 6 分钟之内完成。开发者提交后在评论区就能看到每一项检查的结果不用自己装一堆工具在本地跑也不用到各个平台里反复切换。reviewer 看到的则是一份被充分预处理过的 diff不需要再为格式、风格、明显的低级错误浪费注意力。3.3 开源工具链的边界自动化替代不了的那部分这里我必须给开源工具链泼一盆冷水自动化的覆盖率再高它也做不了逻辑正确性的审查。Semgrep 能帮你发现这里可能抛空指针但它不知道这个空指针在当前业务场景下是不是真的会触发SonarQube 能提示你一个函数复杂度过高但它不理解业务方为什么要把这么多判断逻辑塞在同一个函数里。所以无论工具链组装得多豪华人工 reviewer 这一环永远不可省略。开源的哲学里有一条很核心的理念——开放不是废除规矩而是让规矩变得透明、可查、可改进。代码审查的人工环节就是那条最有价值的规矩。4. 评论的艺术怎么把批评说得像分享而不是指责如果说流程和工具解决了代码审查的骨架那么如何写评论就决定了这套机制的心跳。我见过太多优秀的工具在落地的过程中死在糟糕的沟通方式上。代码审查本质上是一种人际交互评论写得好不好直接决定了团队成员是害怕 review 还是期待 review。我觉得判断一条 review 评论质量高低的底线标准只有一个去掉代码上下文之后这条评论能不能被一个不知情的人心平气和地读完。如果把评论里的代码名词替换成你说的那个方案整句话还像是一个同事的正常交流那就可以发出去。如果替换成那个东西之后你听起来像个没耐心的领导在质问下属那就不适合发出去。我整理了三种最常见的低质量评论以及它们的问题所在低质量评论代表句式问题纯结论式这个写法有问题改成下面这样读者只看到结论看不到理由贬低式这样的代码也能提交引发防御心理阻塞沟通含糊式这块逻辑好像不太对再想想完全没有信息量等于没说我自己的评论习惯是从三明治结构慢慢调整到四段式的。所谓四段式就是一条正式的 review comment 至少包含四部分场景描述说明你是在什么上下文中看到这个问题的。比如在用户注册的流程里这一步如果用户名已经存在……先让对方知道你确实读懂了上下文。具体问题指出你担心的是什么说的越具体越好。不要说这个优化不好而是说这里每次都去数据库查一次用户信息并发量上来之后会拖慢接口的 P99。建议方向给出一个你认为可行的改进方向注意是方向不是唯一答案。比如可以加一层缓存或者把用户信息一次性查出来再存内存给选择权不给命令。补充说明如果你们之间缺乏约定补充一句这是我的理解如果你在下一步要用到这个字段的话另说之类的软性限定语。这个非常有用它可以避免评论被理解成绝对的指令。写到这里我想特别强调一下第四段的价值。代码审查中有一个非常隐蔽的陷阱reviewer 因为只看了一部分代码很容易对整体设计产生误判。如果你用一种绝对正确的语气写出评论一旦你的理解本身就是错的丢脸是小更重要的是会让提交者开始质疑你的每一句话。反而加一句软性的限定语能给对方一个从容反驳的台阶沟通就顺利多了。5. 踩坑实录我从失败案例里学到的几条 review 教训下面这部分内容我会讲四个我真实经历过的失败案例。这些教训我没有在任何书里读到过全是用线上事故和团队摩擦换来的。希望看完之后你能少走一些弯路。5.1 合并之后再修的高利贷陷阱第一个教训来自我职业生涯的早期。当时我们评估一个重构 PR时间紧张评审人有疑虑但提测日期就在第二天于是决定先合进去上完线马上修。后来的结果大家应该猜到了——合进去之后再也没人提马上修这茬事那段代码在主干上存活了整整一个季度直到一个线上告警把它揪出来。修的时候因为遗留时间太久上下文已经模糊重新理解那段代码又花了一倍时间。所以我现在坚持一个原则如果 review 中发现了需要改的问题等改完再合。除非是那种可以独立跟踪、明确记入 backlog 且不影响线上正确性的小遗留否则一律不允许带病合并。5.2 让最沉默的人先发言第二个案例是关于评审人选的。当时我们团队推崇能者多劳每次 review 都由技术最强的那两个同事做导致其他成员几乎不参与代码审查。一段时间之后我观察到一个奇怪的现象那些不参与 review 的成员对代码库的整体认知能力下降得非常厉害。他们只看得见自己那块的代码团队里一旦有人休假整个链路就陷入僵滞。后来我调整了分配策略每个 PR 至少需要一位陌生 reviewer 参与。哪怕这位陌生人对代码里涉及的领域完全不熟悉他的外行视角反而能提出很多领域专家注意不到的疑问。比如这个变量为什么叫这个名字这个接口的调用契约在哪儿定义的。这些问题看似基础但凡是能问到点子上的往往能暴露出文档缺失或者命名混乱的真实问题。5.3 review 超时会导致流程反向崩坏第三个案例关乎 review 的时效性。我们曾做过一个统计当一个 PR 等待 review 的时间超过两天提交者几乎都会在等待期间产生焦虑情绪其中一部分人为了避免等待会开始走先合并再补审的灰色通道。一旦灰色通道出现整个 review 制度就形同虚设了。解决这个问题光靠呼吁大家快一点 review是不够的必须有机制兜底。我们后来定了一条规则PR 创建之后 24 小时内必须收到首个 review 响应48 小时内必须完成第一次完整 review。如果超时系统会自动把 PR 重新分配给团队内其他 reviewer。这条规则对团队协调能力有一定要求尤其是开源项目这种跨时区协作的场景。但如果不设限你会发现等待 review这五个字能消磨掉开发者一半的积极性。5.4 每人负责整个拉取请求检查时的恶化管理不知道优先级这是一个相对微妙的问题但造成的摩擦一点都不小。早期我们团队没有给 review 意见分优先级所有 comment 一视同仁地出现在 PR 里。结果提交者经常面对几十条评论不知道该先处理哪个哪些是必须改的哪些是可改可不改的哪些其实只是一种讨论。后来我引入了优先级标记体系总共分三档必须修改不合并就无法通过标准的阻塞性问题通常对应 bug、安全漏洞或严重的接口设计失误。建议修改不影响合并但会影响代码的可维护性或者后续扩展性应该尽量处理。讨论性质疑属于开放性问题不一定要改但希望和提交者沟通确认清楚。这个简单的标记机制把 review 的沟通成本降了至少三分之一。提交者拿到一个 PR扫一眼优先级就知道自己的工作量在哪儿reviewer 也能明确表达自己的立场。这是投入产出比非常高的一项改动。6. 我把这套开放流程搬进开源项目的真实体验如果你是在一个企业内部做 review很多规则可以通过行政手段推进比如没有 approve 不能合并这种硬性约束。但脱离行政力量、完全靠社区共识运行的开源项目才是真正检验这套开放代码审查理念的试金石。我自己参与的一个开源项目使用的是 GitHub 的 Pull Request 模型。整个流程如上文所述自动检查先行然后人工 review评论区保持开放讨论。实际运行下来有几点感受和在企业内部做是完全不同的第一点开源社区的人更珍惜自己的时间。你如果给人发一条再想想这种没有营养的评论对方基本上不会再搭理你。所以在开源项目里写 review comment必须比在公司里更克制、更清晰。这反过来倒逼我提升了评论的写作质量。第二点陌生人会提出很多本地人想不到的问题。循环依赖被质疑过、错误处理被挑战过、乃至项目 README 里几处含糊的用语都被精确地挑出来过。这些评论的价值远超企业内部那些熟悉得不能再熟悉的同事带来的增量。第三点自动化的作用被最大限度地放大了。因为社区的维护者人数有限不可能在人工 review 上投入无限时间所以高质量、低误报的自动检查就成了整个审查流程的承重墙。Reviewdog 与 CI 的结合让自动化放行/拦截成了项目事实上的第一道大门而人工 review 只需要关注那扇大门内剩下的事务。多分支合并式开发中我还尝试过给每个 branch 单独配置不同的自动检查规则比如 develop 分支严格要求覆盖率feature 分支只看编译和 lint。这比一刀切的全局配置更贴近实际需要。7. 从零开始落地如果我的团队也想搭一套该从哪儿着手最后这部分是给那些看完前面内容、想回去动手实践的人。我没办法给出一个放之四海而皆准的方案因为每个团队的代码规模、技术栈、人员构成都不一样。但我可以给出一个极其务实的启动清单你照着这个顺序走十天之内就能见到效果。第一阶段约定大于工具先用三天时间和团队对齐三件事合并标准是怎样的、PR 粒度限制在多少行、评论的优先级标记该怎么用。工具可以后置但规则必须前置。这三条如果没共识用什么工具都是白搭。第二阶段搭流水线在 GitHub Actions / GitLab CI 上把编译、单测、Lint、静态扫描这四件套跑起来。不需要追求一步到位先从最小可行版本开始。比如第一周只加编译和单测第二周再补 Lint第三周接入 Semgrep 或者 CodeQL。这样团队的适应压力会小很多也不容易产生系统这么复杂我是不是哪天不小心就把某个配置弄坏了的恐惧心理。第三阶段补人工环节引入 review 时效性规则比如 24 小时首响应和 reviewer 轮换机制。可以从核心成员先试行两周等大家适应了再扩展到全员。重点观察的不是 review 数量而是评论质量的提升和互相认可的氛围是否建立起来。第四阶段复盘迭代每个迭代结束之后花半小时做一次 review 流程本身就是代码审查模式之下的元审查有哪些评论是无效的、有哪些评论争议很大、自动化工具报出来的问题里有多少是误报。用这些数据反向调整规则和工具配置让这套机制进入自我进化状态。我在实际推行这套流程时最大的感悟是落地的关键不是立即做到完美也不是把规则定得滴水不漏然后一次性推行到位而是先把最核心的少数规则跑起来让它产生真实的正面体验再用体验带动规则本身的持续优化。代码审查永远没有终点但没有让人窒息的规则、始终保持开放讨论的文化和足够有效率的工具链这件事情就会像一个良性滚动的雪球给团队带来越来越多的收益。如果你手头正打算试试 open-code-review 这套思路我建议你先别急着把完整的工具链架起来。拿出自己的一个大一点的 PR 试着拆分一下再找一个同事用四段式的评论结构互相 review 一份代码等这几件事做实了再去折腾自动化流水线。你会发现很多看起来复杂的问题在流程上松绑之后其实没有想象的那么难。
阅读完成 · 觉得有帮助？
