code review 这件事，我是在吃过亏之后才真正重视起来的。那时候团队里上线了一个订单模块，代码合并得相当丝滑，一路绿灯，结果第二天线上就出了事故：一个 NULL 指针异常直接让下单入口挂了半小时。翻开 Git 日志一查，问题代码在被 review 的时候其实已经有人提了一句“这里是不是要判空”，但那条评论淹没在十几条讨论里，没人跟进，合代码的人没注意，就这么带上线了。从那时候起，我就下定决心，要把 code review（代码审查）这件事变成一套自动化、可度量、不容易漏掉关键问题的流程。后来我慢慢整理出了一个开源项目，就是今天要聊的 open-code-review。

这个项目说白了，是做一整套代码审查工作流的开源方案：它能把 PR 里的变更自动拉下来跑规则检查，能识别高风险代码模式，能在关键位置自动评论甚至 block 合并，也能把审查数据沉淀成图表，让团队知道“到底哪些文件最容易出问题”。它解决的是我在上面那次事故里遇到的核心痛点：人眼 review 容易漏、规则不统一、经验没有沉淀。适合正在搭建或者优化 code review 流程的团队参考，也适合那些想自己写一套审查机器人但不想从零开始的开发者。

文章不会只讲项目本身，我会把背后的设计思路、技术选型、部署步骤、踩坑记录都拆开讲清楚。你拿到之后可以照着自己的团队情况去改，也可以把它当成一个完整的工程案例来读。

1. 从为什么需要代码审查说起

1.1 一次事故背后的流程漏洞

先回到开头那次事故。问题代码长这样：某个接口从缓存里取用户信息，里面有一段是直接读取user.getAddress()，但缓存可能命中一个空对象，根本没初始化 address。Review 的时候有同事评论说“这段要不要判空”，但那个 PR 有 40 多个文件，改动量很大，评论被折叠在中间，作者当时回复了一句“后面统一加”，然后就忘了。没有人设置 blocker，没有自动化检查，于是带着隐患的代码就合入了主干。

复盘的时候我们整理出了三个环节的漏洞：

• 第一，人眼审查覆盖不全。40 个文件、几百行 diff，靠几个人逐行看，漏掉一处很常见。
• 第二，审查意见没有被强制执行。Git 平台上的评论只是“文字意见”，不是“系统规则”，作者可以选择忽略。
• 第三，经验没有沉淀。这次发现的“缓存空对象要判空”问题，下次还会在别的模块出现，但没人把它固化成一个自动检查规则。

1.2 代码审查的真正收益是什么

很多人觉得 code review 就是“互相挑毛病”，其实它是团队里成本最低的缺陷发现手段。一个逻辑错误如果在编码阶段发现，修复成本可能就是几分钟；如果是审查阶段发现，多花一次讨论和修改；要是不幸流到线上，那就是日志分析、紧急回滚、用户赔偿、团队熬夜。越是往后走，成本越是成倍增长。这也是为什么代码审查在成熟团队里从来不是可选流程，而是合入代码前的必经关卡。

除了发现缺陷，code review 还有一层隐性收益：知识传递。新人对业务不熟，通过 review 可以快速了解那些不好写在文档里的设计决策。老手在解释“为什么这里要加索引”的过程中，也是在把经验从个人记忆转变成团队资产。审查记录本身就是最好的技术文档，因为它记录了真实场景下的取舍过程。

1.3 传统 review 流程为什么总翻车

痛点其实很集中：

• 变更太大，审查流于形式。一个 PR 几百个文件，reviewer 根本看不过来，最后只是机械地点 Approve。
• 全局规则缺失。团队里有人喜欢用双引号，有人用单引号；有人要求每个函数都要有注释，有人觉得没必要。没有统一的标准，review 就成了争论战场。
• 人员瓶颈。核心模块往往只有一两个人看得懂，别人只能走过场，真正的问题没人发现。
• 没有反馈闭环。这次 review 发现的问题，没有追踪到下一次就不会再犯；统计报表更是没有，团队不了解自己的质量状态。

这些痛点如果只靠“加强认真程度”根本解决不了。人不是机器，注意力就是会分散，标准就是会漂移。所以我才想做一个开源方案，把能自动化的事情全部交给程序，让人把注意力集中在程序看不出来的那些设计问题上。

2. open-code-review 整体设计思路

2.1 项目定位与设计理念

open-code-review 一开始就是想解决上面说的那些问题。它的定位不是取代人，而是一个“审查助理”——干的是盯规则、查风险、催进度、出报告这些重复劳动，把 reviewer 从琐事里解放出来，让他们专注在真正的设计评审上。

设计理念可以总结成一句话：规则进代码库，审查进流水线，经验进数据。

• 规则进代码库：所有审查规则不是写在某个管理后台，而是以配置文件的形式跟项目代码放在一起。规则随代码走，可以针对不同仓库配置不同的标准。
• 审查进流水线：PR 一旦创建或更新，工具自动在 CI 环境里运行，把结果以评论的形式贴回 PR 页面。
• 经验进数据：每一次审查结果都结构化存储，形成趋势数据，方便团队复盘。

2.2 核心架构拆解

整体架构分成四个模块：

• 采集器（Collector）：负责从 Git 平台拉取 PR 的变更数据，包括文件列表、diff 内容和提交记录。这是所有后续分析的基础。
• 规则引擎（Rule Engine）：把采集到的 diff 和代码快照放进规则集里逐条匹配。规则集分为内置规则和自定义规则两层，内置规则覆盖常见的高风险模式，自定义规则允许团队按需扩展。
• 执行器（Executor）：规则引擎产出的问题列表在这里做过滤、去重、分级，然后调用 Git 平台的 API 在 PR 上生成评论，或者设置检查状态。
• 聚合器（Reporter）：把一段时间内的审查记录汇总成报告，输出到控制台或者 Postgres 数据库，供团队查看趋势。

2.3 技术选型分析

我在选型上其实没有用太花哨的东西。核心是 Python 写的，原因很简单：团队里后端同学基本都会 Python，代码容易维护，扩展自定义规则的门槛也低。Git 操作直接用系统命令加 GitPython 封装，不搞自己的一套 Git 实现，稳妥优先。

数据库用了 Postgres，主要是考虑到之后要做趋势分析和图表展示，Postgres 的查询能力够用，而且部署简单。和 Git 平台的交互走 REST API，没有用 Webhook 做常驻服务，而是设计成命令行触发模式。这么选有一个好处：整个工具无状态，部署成本极低，挂到 CI 里就是一个普通 job。

有人可能会问，为什么不直接用一个现成的商业审查工具？说实话，商业工具在特定生态里确实很好用，但一旦你需要定制内部规范、对接自建的代码托管平台，或者想把审查逻辑嵌进公司内部的发布系统，闭源方案就非常难受。开源的好处在于，你可以把规则引擎换成自己的实现，也可以把它嵌入到任意 CI 流程里，自由度完全不同。

3. 核心功能与使用场景落地

3.1 内置规则集：先解决 80% 的常见问题

内置规则是整个项目里最实用的部分。我根据自己团队踩过的坑，整理了一批高频高风险模式，把它们做成了开箱即用的规则：

你可能会说：“这不就是 linter 吗？”确实有一部分重叠，但 linter 重点管语法和风格，open-code-review 更关注变更上下文和合入门禁。比如 no-hardcoded-secret 是直接对 diff 里的字符串做模式匹配，一旦发现形如sk-开头或者password = "..."的赋值，立刻把 commit 标记为失败。这在涉及密钥管理的项目里特别实用。

规则全部用 YAML 配置，示例长这样：

rules: - name: no-debugger pattern: "\\bdebugger\\b" level: error message: "检测到 debugger 语句，请移除后再提交" file_filter: ["*.js", "*.ts", "*.py"] - name: no-print-in-prod pattern: "console\\.log\\(" level: warning message: "生产代码中不建议保留 console.log，请确认是否需要清理" - name: hardcoded-secret pattern: "(?i)(password|secret|token)\\s*=\\s*['\"][^'\"]{6,}['\"]" level: error message: "疑似硬编码密钥，请使用环境变量或密钥管理服务"

规则匹配其实用的是正则表达式，没有上机器学习模型。有段时间我研究过用静态分析 AST 来检测更复杂的逻辑问题，但后来放弃了。原因很现实：AST 分析对语言的绑定太深，要同时支持 Java、Python、Go、JavaScript 意味着维护成本爆炸，而正则匹配虽然“笨”，但覆盖 80% 的场景已经足够了，而且规则的可解释性非常强。

如果团队有自定义规则的需求，可以单独写一个 Python 文件，放到 rules 目录下，框架会自动加载。自定义规则的接口很简洁：

from open_code_review.rules import BaseRule class MyCustomRule(BaseRule): name = "no-assert-in-prod" level = "error" message = "生产代码中不应包含 assert 语句" def match(self, context): for line in context.added_lines: if "assert " in line: return [self.make_issue(line)] return []

3.2 自动评论与门禁控制

规则跑完以后，open-code-review 会把问题以评论的形式发回 PR。评论不是一把梭直接发，而是做了分级处理：error 级别的规则会同时把 PR 的检查状态标记为 failed，在 Git 平台上显示红色的叉号；warning 级别只发一条汇总评论，提醒 review 关注；info 级别直接记入报告，不打扰 PR 页面。

分级处理这个设计非常关键。如果所有问题都 block 合并，开发者的抵触情绪会很大，因为很多 warning 只是风格建议。但如果所有问题都不 block，硬规范又形同虚设。所以我的建议是：error 留给那些绝对不该出现的模式，比如密钥泄漏、调试语句、明显会导致崩溃的空指针调用；warning 留给需要人来判断的情况；info 纯粹作为数据沉淀。

评论模板也可以配置，默认长这样：

### 🤖 open-code-review 报告 发现 2 个 error，3 个 warning，1 条 info。 #### Error - `hardcoded-secret` 在 `src/config.py` 第 42 行 疑似硬编码密钥，请使用环境变量或密钥管理服务 请点击下方链接查看完整报告：...

这里有个细节需要注意：评论不要重复发。每次 push 都会重新触发审查，如果每次都新发一条评论，PR 页面会被刷爆。所以我在实现里加了一个 ID 匹配机制，如果新报告的问题和上一条完全一致，就不重复发；只有新增问题才追加评论，已解决的问题则在评论区标注为已解决。

3.3 趋势报告与团队度量

审查记录会同步写入 Postgres，按仓库、开发者、日期三个维度聚合。你可以跑一条命令得到最近 30 天的问题排行榜：

open-code-review report --repo my-service --days 30

输出会告诉你，哪个模块的问题密度最高、哪一类规则命中次数最多、谁的提交里 error 级别问题占比最大。这些数据不是用来问责的，而是用来发现共性问题。比如我做过一次统计，发现某个团队的问题集中在一周里改动特别大的那个文件上，说明问题不是能力，而是“需求拆分不够细”，一次合并的代码量太大，后来我们把 PR 大小限制在 400 行以内，问题率明显下降。

度量这件事我得说句真心话：数据是辅助，不是目的。如果团队为了数字好看，把大量问题降级或者绕过规则，那就本末倒置了。所以报告功能在前几个版本里刻意没加排行榜，后来也是以“趋势图”的形式放出来的，重点看的是“问题数量是否在减少”，而不是排名。

3.4 与 GitHub 和 GitLab 的集成方式

open-code-review 的输入输出都是标准的命令和文件，所以对接不同 Git 平台的核心逻辑是一样的。对于 GitHub，需要在 Settings -> Developer settings 里生成一个 Personal Access Token，权限勾选repo和pull-requests。对于 GitLab，则是在用户设置里生成 Personal Access Token，权限勾选api。本地测试的时候，可以用环境变量传 token：

export GIT_PLATFORM=github export GIT_TOKEN=ghp_xxx export GIT_REPO_OWNER=yourname export GIT_REPO_NAME=your-repo open-code-review scan --pr 123

如果用的是国内常见的自建 GitLab，只需要把 API 地址配置改一下即可。整个工具不依赖任何第三方服务，这一点对于有很多内部项目的团队来说是刚需，谁也不想把代码分析结果传到外部平台。

4. 实操：从零部署到接入流水线

4.1 环境准备与安装

部署其实很简单，项目只有一个 Docker 镜像加一个数据库。推荐用 Docker Compose 一键起服务：

version: "3" services: ocr-db: image: postgres:14 environment: POSTGRES_USER: ocr POSTGRES_PASSWORD: ocr_pass POSTGRES_DB: ocr volumes: - pgdata:/var/lib/postgresql/data ocr: image: open-code-review:latest environment: DB_HOST: ocr-db DB_PORT: 5432 DB_USER: ocr DB_PASSWORD: ocr_pass DB_NAME: ocr GIT_PLATFORM: github GIT_TOKEN: ${GIT_TOKEN} depends_on: - ocr-db volumes: - ./rules:/app/rules/custom volumes: pgdata:

如果你不想用 Docker，也可以直接 pip 安装 Python 包，在本地跑：

pip install open-code-review open-code-review init

init 命令会在当前目录生成一个.ocr.yaml配置文件和rules目录，里面的注释写得很全，照着改就行。

4.2 初始化配置项解析

.ocr.yaml是核心配置文件，里面这几个字段要重点解释：

project: name: my-service language: python git: platform: github api_url: https://api.github.com token_env: GIT_TOKEN review: max_lines_per_pr: 400 block_on_error: true block_on_warning: false rules: custom_dir: ./rules ignore_paths: - "**/generated/**" - "**/vendor/**" - "*.lock"

max_lines_per_pr是一个软门禁，超过 400 行会在报告里给一条提示，建议开发者拆分 PR。我强烈建议把这个值设成一个团队公认的上限，不管多急的需求，超过这个行数就分两次合并。ignore_paths用来跳过自动生成的文件，比如前端项目里的dist目录、Go 的vendor目录。这个必须配，否则生成的代码会击穿所有规则。

4.3 接入 GitHub Actions

接入 GitHub 的时候可以直接用现成的 workflow。在.github/workflows/code-review.yml里写：

name: code-review on: pull_request: types: [opened, synchronize] jobs: open-code-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 - name: Run open-code-review env: GIT_TOKEN: ${{ secrets.GIT_TOKEN }} run: | docker run --rm \ -e GIT_PLATFORM=github \ -e GIT_TOKEN=$GIT_TOKEN \ -e GIT_REPO_OWNER=${{ github.repository_owner }} \ -e GIT_REPO_NAME=${{ github.event.repository.name }} \ -e GIT_PR_NUMBER=${{ github.event.pull_request.number }} \ -v ${{ github.workspace }}:/workspace \ open-code-review:latest scan --pr ${{ github.event.pull_request.number }}

这里有个非常重要的工作流配置，容易被人忽略：fetch-depth: 0。默认的 checkout 只拉取最新一次提交，但审查一个 PR 需要知道“这个 PR 相对于目标分支改了哪些文件”，必须拿到完整历史。如果不加这个配置，工具拿到的是不完整的 git 历史，导致 diff 计算错误，就会出现漏检。

4.4 接入 GitLab CI

GitLab 的配置方式也差不多。.gitlab-ci.yml里加一个 job：

code-review: stage: test image: docker:20.10.16 services: - docker:20.10.16-dind script: - docker run --rm -e GIT_PLATFORM=gitlab -e GIT_TOKEN=$GITLAB_API_TOKEN -e GIT_REPO_OWNER=$CI_PROJECT_NAMESPACE -e GIT_REPO_NAME=$CI_PROJECT_NAME -e GIT_PR_NUMBER=$CI_MERGE_REQUEST_IID -v $CI_PROJECT_DIR:/workspace open-code-review:latest scan --pr $CI_MERGE_REQUEST_IID only: - merge_requests

GitLab 里获取 MR 编号要特别注意，用的是CI_MERGE_REQUEST_IID，不是CI_MERGE_REQUEST_ID。IID 是当前项目的内部分支编号，而 ID 是全局数字，API 接口里如果混用会报错或者指向错误的 MR。踩过一次坑，印象深刻。

5. 常见问题与排查技巧实录

5.1 规则没有生效的排查顺序

经常有人问：“我明明在 YAML 里配置了规则，为什么没跑出来？”这个问题的排查顺序很有讲究，建议按这个思路从易到难查：

• 先确认配置文件路径。init 生成的.ocr.yaml如果不在项目根目录，工具默认不会读取。
• 再确认规则名拼写。规则文件里写的是no-debugger，但自定义规则里定义的 name 可能是nodebugger，对不上就静默跳过。
• 然后看文件过滤条件。一个规则只对*.js匹配，但你的改动文件是.ts，规则就会跳过。
• 最后看 ignore_paths 配置。如果一个文件被放进了 ignore 列表，所有规则都不会作用于它。

我见过最隐蔽的问题是：团队有人把ignore_paths配置成了["dist/**"]，结果实际路径是src/dist，这个模式匹配不上，反而让所有 dist 文件都被审查了。建议用绝对路径前缀或者先跑一遍open-code-review debug --files来看实际匹配结果。

5.2 误报太多导致团队免疫

这是推行自动审查最严重的问题。如果工具天天报一堆无关紧要的 warning，开发者就会对评论产生免疫，连真正有价值的 error 也不看了。

解决误报的核心思路是“白名单机制”。我给 open-code-review 设计了两层白名单：

• 文件级白名单：某些文件整体不做规则检查，比如测试文件里的 mock 数据经常包含大段字符串，容易被误判为硬编码密钥，可以在 rules 的ignore_paths里排除。
• 行级豁免注释：在代码行尾加# noqa: ocr-rule-name注释，工具会跳过这一行；如果后来代码重构不需要豁免了，删掉注释即可。

password = "test-only-value" # noqa: ocr-hardcoded-secret

行级豁免比文件级豁免更精细，适合那种“这一行确实是故意的”情况。不过要记得定期清理历史豁免，我一般一个月跑一次全量扫描，看豁免注释还有多少是有效的，没用的全部删掉。

5.3 性能问题：PR 特别大怎么办

PR 改动量一大，扫描时间就会显著拉长。有同事反馈审查一个 2000 行的 PR 花了快十分钟，这基本没法用。优化手段我做了三个：

• 只对新增行做规则匹配。已存在的代码行不算在变更里，不参与检查。这一点很关键，因为它的核心逻辑是要发现“你这次改了啥”，而不是对整个项目做静态检查。
• 对 diff 做了分块缓存。同一个 PR 如果只 push 了一次新的提交，只扫描新增的提交块，不重复扫描整个 PR。
• 规则匹配用了多线程。不同规则之间没有依赖，可以并行执行，实测下来四核机器上扫描 500 行 diff 的耗时从 60 秒降到了 15 秒左右。

如果你的团队确实有超大 PR 的坏习惯，expect 一次扫描控制在 30 秒以内算是合理的体验，超时了就该从流程上去推“拆分 PR”，而不是让机器硬扛。

5.4 团队推不动怎么办

技术问题好解，人的问题最难。这里分享一点我的经验。推行自动 code review 最大的阻力不是技术，而是团队觉得“多了一道关卡，影响我的合并速度”。所以我的做法是分三步走：

第一步，先只加 warning 级别规则，不 block 合并，作为“温柔的提醒”。让大家先习惯 PR 上出现机器人评论，知道它不会卡你，抵触情绪就不会那么大。

第二步，一个月后出一份趋势报告，对比引入工具前后的线上缺陷数量和 review 评论量。用数据告诉团队“这个工具有用”，再讨论升级规则。

第三步，把 error 级别的规则 block 打开，同时设置例外渠道。如果确实有紧急情况必须绕过门禁，可以通过指定 label 让机器人跳过检查。有了这个逃生门，团队对强规则的接受度会高很多，因为大家都知道不是“一刀切”的强管控，而是“有纪律、有出口”的规范。

6. 从 open-code-review 到你的团队实践

我给不少团队做过代码审查流程的复盘，发现一个共通的规律：凡是 review 流于形式的团队，几乎都不是因为大家不认真，而是因为流程里缺少强制节点。review 意见只是“说了”，但没有“必须改完才能合”的约束；规则标准是口头传的，每个人理解不一样。open-code-review 解决的问题，本质上是把质量预期变成了代码里写死的事实。

如果你要从零开始落地这套方案，我建议按这个节奏走：

• 第一周：部署工具，只开 info 和 warning 规则，跑一个项目试试水。
• 第二周：复盘上一次 review 中发现的真实问题，把“以后再遇到这类问题要怎么办”固化成新规则。
• 第三周：打开 error 级别 block，同时给所有开发者发一份“规则速查表”，让他们知道哪些行为会被拦截。
• 第一个月结束的时候：跑一次报告，把所有命中最多的问题类型拿出来，在周会上逐条过一下。

还有一个小技巧想单独拿出来说：规则不是越多越好。真正的规则要简单、可解释、可执行。如果你新加一条规则，团队成员需要反复查文档才知道能不能通过，那这条规则大概率会被绕过。open-code-review 的定位是“守门员”，但它不是教练。教练的活还是得由人来干，最好的情况是机器人把所有机械问题拦下来，人在 PR 讨论区里把精力放到“这么设计合理吗”这种真正重要的问题上。

我做了这么久，最大的体会是：好的 code review 流程，不是让人更累，而是把该机器做的事交给机器，让人省下精力做更有价值的事情。如果一个工具用下来团队成员觉得“烦”，那一定是它管了不该管的事，这时候你的任务不是强推，而是去调整规则的边界，让工具从“绊脚石”变成“扶手”。这就是 open-code-review 一直希望达到的状态，也是我做这个项目最想分享给大家的一件事。