我一直觉得代码审查是最被低估的工程环节。很多人写代码时思路清晰一进 review 就变成你改一下格式这里加个注释这样的碎碎念既没有体系也留不下资产。直到我开始用 open-code-review 这套思路来重新设计团队的审查流程才真正意识到审查这件事如果只靠个人经验和自觉它永远只是流程里的一个摆设但如果你把它当成一个开放式的基础设施来建设——规则公开、工具可扩展、流程透明——它能实实在在改变团队的代码质量甚至改变团队讨论代码的方式。这篇内容不是某个具体工具的官方文档而是我从零搭建一套代码审查体系的完整复盘包括设计思路、配置细节、踩过的坑和最终落地效果适合正在为 review 头疼的技术负责人、后端和前端工程师以及所有想把代码质量往前推一步的人。1. 为什么代码审查值得做成一个开放的工程1.1 从点赞式评审到真正的把关先聊一个很多团队都有的通病。代码审查在不少项目里已经变成了点赞式评审作者写完功能丢一个 Pull Request 出来CI 是绿的reviewer 扫一眼界面鼠标移到 Approve 按钮上点下去完事。没有人真的去抠边界条件没有人去验证并发场景更没有人去问这个函数为什么写了 80 行。这真不是人的态度有问题而是机制出了问题——在审查的标准、边界和工具没有铺到位之前指望每个人靠自觉去抠细节基本不现实。open-code-review 想解决的就是这个问题。它把审查从一个开发者的脑内经验变成一套可执行、可传播、可迭代的工程资产。拆开看它做的事情可以分成三层。第一层是静态约束用脚本和规则自动拦截低级的风格问题、明显的隐患比如未处理的 Promise、硬编码密钥、超长函数第二层是流程约束规定什么样的改动必须经过什么级别的验证才能合并比如核心模块必须有两个 reviewer 的确认第三层是认知约束把团队过往踩过的坑沉淀成 review 清单和自动化注释让新人在第一时间就知道这个仓库里哪些写法会被打回。我印象很深的一个数据是某个团队在引入自动化审查规则之后review 里能挑出的有效问题数量不仅没下降反而上升了。原因特别好理解机器把低级问题全部过滤掉了审查人的注意力才能放在真正需要判断的架构设计、边界条件、性能权衡上。这才是代码审查该有的样子。自动化在这里不是替代人而是替人挡掉那些不需要脑子的重复劳动。1.2 开放二字的真实含义规则透明才能建立信任为什么项目叫 open-code-review 而不是 code-review-tool我理解这里的 open 是双重含义。第一层是开源开放规则、插件、脚本全部公开可改团队完全可以根据自己的技术栈和业务特点去增删规则而不是被商业工具的预设条款绑死。第二层是流程开放不同角色、不同阶段都能参与进来不只是开发写完丢给 leader 看一眼而是从需求评审、设计评审、编码阶段就把审查的视角埋进去。我自己有个很深的体会很多团队用商业 review 平台功能确实全但规则的判断逻辑是黑盒。告警弹出来你不知道它为什么这么说也没法把不合理的规则关掉。时间一长团队就形成了条件反射——看到告警先 ignore最后整套流程形同虚设。open-code-review 的好处就是避免这一点所有检查逻辑全部放在仓库里任何一个被拦截的问题都能从规则文件里查到出处和理由。一旦可以较真大家对规则的信任度就完全不一样了。另外开放还意味着历史经验可以沉淀。团队里最资深的工程师可能换项目、离职但他写过的规则、总结过的代码模式会留在 rules 目录里成为组织资产。这比任何文档都有效因为规则是活的是直接从真实代码里长出来的约束。1.3 和商业 Code Review 工具的差异在哪有人会问现成的 Code Review 工具一大堆为什么还要自己搞一套我的观点是没有说商业工具不好而是适用场景不同。商业工具强在开箱即用弱在规则定制和透明度自建体系强在完全贴合项目弱在前期需要投入人力。对于代码量不大、团队规模小、业务迭代快的项目商业工具完全没有问题但一旦到了需要把审查和具体业务规则深度绑定的阶段比如这个目录下禁止使用 any必须是防重入锁你只能靠自定义规则实现。open-code-review 的定位更像一个框架它不强迫你用某个特定平台而是提供一套规则组织方式和流程模板让你能在已有的 Git 工作流上快速长出自己的审查体系。它和你用的代码托管平台不冲突反而可以作为现有平台的补充把更细粒度的检查、更贴合业务的规范注入进去。2. 核心设计思路与方案选型2.1 规则引擎哪些检查该交给机器哪些必须留给人做一套审查体系的第一步不是装工具而是做判断哪些检查适合自动化哪些必须人工介入。我的判断标准非常朴素——凡是能用确定性规则描述的都交给机器凡是需要上下文判断的都留给人但机器要把相关的上下文整理好摆在 reviewer 面前。适合自动化的例子包括代码风格、命名规范、重复代码、未使用变量、明显的空指针风险、函数复杂度过高、硬编码的敏感信息、不安全的依赖版本。这些都属于出问题就是出问题的确定性规则机器判断又快又准。不适合自动化的包括接口设计是否合理、模块边界是否清晰、这个改动会不会影响未来三个月要做的某个功能、异常处理策略是否符合业务预期。这些东西需要业务上下文和技术判断人必须参与。所以 open-code-review 的规则引擎在设计上要支持三级分类error 级任何触发都会阻塞合并只放绝对原则性问题比如密钥泄漏、SQL 注入、越权风险warning 级默认提醒但不阻塞适合放性能隐患、复杂度超标、重复代码这类需要人看一眼的问题info 级纯粹是信息提示比如格式建议给作者和 reviewer 一个参考。这个分级极其重要它决定了规则不会把人淹没在告警海洋里也决定了机器在流程中的权力边界——机器可以喊停原则性问题但更多的只是提醒最终决定权在人。2.2 工作流集成从提交到合并的两道闸门规则设计好后要考虑把审查嵌进 git 工作流。我的做法是采用 GitHub Flow 的变体把审查拆成提交前、提交后两道闸门。提交前的闸门靠 pre-commit hook 实现主要跑两类检查一是本地的静态检查把低级错误挡在进入远程仓库之前二是 commit message 格式检查确保提交信息符合规范。很多人觉得 pre-commit 很麻烦每次提交都要多等几秒。但它真正省掉的是push 上去、CI 跑 5 分钟、机器人打回、本地改完再 push这样一个十几分钟的循环。我实践下来配置好 pre-commit 的团队本地提交的流畅度反而是提升的因为错误在最早阶段就解决了。提交后的闸门是 CI 里跑的审查任务这也是 open-code-review 的主战场。它会生成一份结构化的 review 报告把变更的每一行代码和对应的规则、注释、修改建议关联起来然后以机器人评论的形式贴到 PR 下面。Reviewer 打开 PR先看机器人的总结再决定哪些地方需要人工复核。这个顺序必须固定先机器后人工机器产出的是给人工判断做索引而不是替代人工判断。2.3 一套可复用的仓库结构模板经常有朋友问自己搭这套体系目录应该怎么组织。这里给一个我在真实项目中用过的结构不限定语言任何技术栈都能套用open-code-review/ ├── rules/ # 所有审查规则的声明 │ ├── style/ # 风格类规则 │ ├── security/ # 安全类规则 │ └── performance/ # 性能类规则 ├── plugins/ # 自定义插件扩展规则引擎 │ ├── eslint-plugin-xxx/ │ └── review-bot/ ├── configs/ # 各工具的配置文件 │ ├── eslint.config.js │ └── commitlint.config.js ├── scripts/ # 自动化脚本 │ ├── run-checks.sh │ └── generate-report.sh └── docs/ # 规则说明与团队约定这个结构最核心的思路是把规则本身和规则的解释分开。rules 目录放机器能读的规则docs 目录放人需要读的说明。任何一条规则的增删必须同步更新文档里的理由和适用场景。否则三个月之后没人记得当初为什么立这条规则它就会变成新的黑盒团队就开始 ignore 它。我见过太多团队死在这一步规则文档没跟上最后规则成了玄学。3. 实操过程搭建与配置一次完整的代码审查3.1 环境准备与快速起步说再多概念不如直接跑一遍。我用一个 Node.js TypeScript 的示例项目演示完整配置过程。第一步准备环境Node.js 18 以上、pnpm、git。然后初始化项目安装审查相关的依赖npm init -y pnpm add -D eslint typescript-eslint/parser typescript-eslint/eslint-plugin pnpm add -D prettier eslint-config-prettier pnpm add -D commitlint commitlint/config-conventional pnpm add -D husky我特意把 commitlint 也放进来因为代码审查如果只看文件内容会漏掉一个很关键的信息源——提交信息。提交信息写得好不好直接决定将来回看历史时能不能快速定位问题。commitlint 在这里负责约束格式强制使用 conventional commits 规范比如feat: xxx、fix: xxx、refactor: xxx。这个细节看起来小作用却非常大当你在git log里能一眼看出每次提交的意图时很多排查问题的成本都会降下来。3.2 配置审查规则与自定义插件装完依赖接下来创建 ESLint 配置文件。这里我强烈建议做一次职责拆分纯格式问题交给 Prettier 自动格式化逻辑类、安全类问题交给 ESLint。两者分工明确就不会出现为了缩进风格吵架的情况。下面是一份经过调优的 eslint 配置片段可以直接抄// eslint.config.js import tseslint from typescript-eslint/eslint-plugin; import typescriptParser from typescript-eslint/parser; export default [ { files: [src/**/*.{ts,tsx}], languageOptions: { parser: typescriptParser, parserOptions: { project: ./tsconfig.json, }, }, plugins: { typescript-eslint: tseslint, }, rules: { typescript-eslint/no-floating-promises: error, typescript-eslint/no-unused-vars: [warn, { argsIgnorePattern: ^_, }], complexity: [warn, { max: 10 }], no-console: warn, }, }, ];挑几条重点说明。no-floating-promises是防丢 Promise 的很多人做 review 根本发现不了异步链路里的隐患开着它在 CI 里能直接拦下一类非常隐蔽的 bugcomplexity复杂度上限设为 10超过就给 warning强迫开发者拆函数这条规则比任何请写清晰代码的倡议都好使no-console设成 warn 而不是 error因为开发调试时打印日志是正常的只要不默认进生产就好。除了规则自定义插件是 open-code-review 最有意思的部分。我写过一个小插件专门检查 Dockerfile 里镜像标签是否写死了latest一旦发现就报错。这类规则商业工具一般不会帮你配但用自研插件十几行代码就能搞定这就是 open 带来的自由度。3.3 与 CI 流水线联动配置文件就绪后需要把审查塞进 CI。以 GitHub Actions 为例我通常在工作流里安排三个 job第一个跑 lint 和类型检查第二个跑单元测试第三个跑 review-bot 生成审查报告。name: code-review on: pull_request: types: [opened, synchronize, reopened] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 - run: pnpm install - run: pnpm lint - run: pnpm typecheck review-bot: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkoutv4 - name: Run open-code-review uses: your-org/review-botv1 with: report-level: warning ruleset: ./rules整个流程里最关键的设置是needs: lint意思是基础 lint 没过机器人根本不跑。这样 PR 页面上机器人评论的第一行永远是基础检查已通过reviewer 看到这句话就放心了大半不需要再帮作者过滤低级问题。3.4 配置 pre-commit 让问题在本地就终结CI 那层的检查相当于兜底但更高效的做法是让问题根本不出现在 PR 里。所以本地 pre-commit 的配置同样重要。用 husky 安装一个 pre-commit hook在每次 git commit 前先跑 lint-staged只检查暂存区里的文件——这样即使是一个历史包袱很重的老项目也不会因为全量检查太慢而让人想关掉它。pnpm husky-init然后在.husky/pre-commit里放这样一段pnpm lint-staged再在package.json里配置 lint-staged 的规则比如{ lint-staged: { src/**/*.{ts,tsx}: [eslint --fix, prettier --write] } }这个做法的好处是ESLint 的--fix会自动纠正格式问题Prettier 会自动排版开发者只需要处理真正没法自动修改的逻辑错误。整个提交过程几乎是无感的提交即合规而不是提交后被骂这是团队接受度提升的关键。4. 使用技巧与避坑指南4.1 切换审查视角读代码的时候到底在想什么工具搭完我发现真正让团队运转起来的是审查时视角的切换。很多 reviewer 习惯用找茬的视角看代码看到不符合自己习惯的地方就 comment最后 review 变成了个人审美的战场。而一套健康的审查应该主动切换三种视角。第一种是作者视角去想这段代码要解决的问题是什么有没有更简洁的表达方式。第二种是维护者视角想半年后有人来改这段逻辑他能不能看懂会不会在某个奇怪的地方踩坑。第三种是用户视角思考边界条件、异常情况、数据量变大时会不会出问题。这三种视角听起来很玄但操作起来有一个特别具体的技巧读完代码之后先别急着评论闭上眼睛在脑子里把关键路径跑一遍。遇到任何需要猜的地方就是应该写 comment 的地方。这个习惯帮我发现了大量逻辑漏洞数量远比规则检查拦下来的多。所以一定要明白自动化是解放注意力不是取代判断。4.2 误报处理与规则调优的三步法open-code-review 跑起来之后最常做的动作其实是调规则。误报很常见尤其是一条刚上线的规则一定会在真实代码里触发预设之外的情况。我的处理流程分成三步第一次遇到误报先记录下来看频率一周内出现超过三次就改规则改规则时不是直接把这条规则关掉而是看能不能加一个更精确的 exclude 条件。举一个真实例子。我曾经在项目里启用禁止使用 any 类型大家一开始都很遵守但很快发现测试文件里大量使用 any写测试本身就是要 mock 各种数据这里禁止 any 简直是找罪受。后来我把规则改成只对src目录生效对test目录放行因为测试里用 any 往往是对模拟数据的合理简化。这一行配置改动让团队对规则的信任度提升了很大一截。规则存在的目的是贴合实际工程形态不是制造麻烦。4.3 团队协作中的三条铁律最后说团队这一层。open-code-review 只是工具它能不能起作用取决于团队有没有几条约定。我在不同团队推行过几套约定最有效的是这三条。第一合并 PR 时作者必须回应每一条机器人 comment要么修复并在 response 里说明要么写清楚不修改的理由禁止直接忽略。第二线上紧急修复可以直接合并但必须在 48 小时内补上完整的 review 记录否则从第三天开始计入技术债。第三reviewer 的 comment 一旦被打回作者需要回复一句明确的状态比如done提交 abc123 已修复形成闭环。这三条约定刚推的时候阻力不小大家都觉得流程变重了。但跑了两周后团队里几乎每个人都感受到了好处。因为规则透明了争议反而少了。谁也不会再拿我忘记了没看到当借口所有人都知道在什么节点该做什么。5. 常见问题与排查技巧实录5.1 一批高频问题速查表我在不同团队落地过 open-code-review遇到的问题大同小异。整理成一张速查表遇到对应的现象直接对照排查现象常见原因排查与解决PR 里机器人没贴审查报告CI 中的 review-bot job 没触发检查 workflow 的 pull_request 事件类型和 needs 依赖本地 pre-commit 装了却不生效husky 的 hook 路径未初始化执行 pnpm husky install确认 .git/hooks 中有对应脚本lint 报告和本地结果不一致CI 里 pnpm 版本与本地不同在 package.json 固定 packageManager 字段或启用 corepack规则改了但效果没变ESLint 缓存导致旧配置被复用清缓存后重跑eslint --cache --cache-location /tmp/.eslintcache自定义插件加载了但静默失败插件导出格式与规则引擎不兼容用调试模式启动查看加载日志中是否有错误信息CI 全绿但 review 机器人状态显示失败机器人执行脚本时没有拉取最新代码确认 actions/checkout 的 ref 参数指向 PR 合并分支这张表是排查的起点。真实线上环境还会有各种奇怪的问题但排查思路都一样从规则是否被加载到流程是否被触发一路逐层确认不要一上来就怀疑某个特定组件。5.2 一次真实定位记录为什么机器人评论消失了分享一次真实的排障经历。某个版本上线后团队反馈 PR 里看不到审查报告了。我第一反应是 workflow 文件最近被改动过于是先打开仓库看最近的提交记录果然发现有人把on.pull_request的types列表里删掉了reopened。这个改动的本意是减少重复流程但对于一个已经关闭又重新打开的 PR不触发 workflow 意味着机器人根本不跑。定位过程只花了十分钟但如果没有从事件触发入手这个思路很多人会一头扎进脚本逻辑里去查 bug。这个案例想说明的是审查工具链出现问题很多时候不是代码写错而是流程配置和事件语义对不上。排查时先看触发条件、再看中间产物、最后看脚本本身这个顺序能帮你节省大量时间。5.3 规则数量不是越多越好关于规则数量我有一条非常强烈的建议宁缺毋滥。我在一个项目里配置过 200 多条规则结果团队成员每天花大量时间处理误报对审查系统的信任度直线下降。后来花了一个下午把所有规则重新筛了一遍砍到 40 条效果反而好了很多。为什么因为规则越少每一条规则被读到、被理解、被执行的概率越高。规则的核心指标不是数量而是能被正确理解和执行的比例。一条被团队真正理解并遵守的规则价值超过十条永远被 ignore 的规则。所以配置的时候我建议每加一条规则就问自己三个问题这条规则拦得住真实问题吗它会产生多少误报如果误报了团队能快速理解它的意图吗三个问题里有两个答不上来就不要加。6. 这套体系落地之后带来的连锁反应6.1 从人盯人到系统盯人open-code-review 落地之后我做技术管理的状态直线上升。以前每到版本合并前我都要自己把关键 diff 看一遍生怕有什么低级错误流到生产。现在系统的 error 级检查先把高风险问题拦住了warning 级规则把需要关注的点都标记出来我再去看代码时只需要关注真正的架构和业务逻辑问题。可以说系统帮我守住底线我把省下的精力花在提升上限上。这其实反映了一个更深层的转变以前的代码质量靠 leader 一个人盯现在靠一整套开放、透明的体系在盯。体系不是人际关系的替代品而是一个所有人都能依赖的公共基础设施。无论谁提交代码无论谁 review规则都一样标准都一样出问题后的反馈链路也一样。这种确定性才是一个团队质量文化的地基。6.2 对新人 onboarding 和跨团队协作的意外收获还有一个意外收益是新人的 onboarding 速度变快了。以前新人进项目要花几周时间去记各种潜规则这个项目不要用 any函数别写太长依赖版本要锁死。这些规矩散落在不同人的脑子里新人要一个一个去问。有了 open-code-review 之后新人在第一次提交代码时机器人就会告诉它这个仓库的全部规则。规则不仅拦住了他还会附上文档链接解释为什么。这种被系统教育的体验比被老员工点评轻松得多也更标准化。跨团队协作时收益更明显。不同团队的代码风格、提交规范经常不一样靠人沟通成本极高。但如果每个团队都有一套开放、可见的 rules 目录协作方直接看目录就能了解对方的审查要求协商起来也友好很多。规则写清楚人和人之间就不用互相猜了。我个人在实际操作中最深的体会是open-code-review 真正改变的其实不是代码仓库而是团队对质量这件事的讨论方式。以前 review 是你写的代码我来挑毛病现在变成了我们跟着同一套规则和标准一起来把代码变好。这个转变不是靠某一款工具实现的而是靠把规则公开、把流程透明、把工具链做厚一点一点堆出来的。如果你也正准备在团队里推进代码审查我的建议是别急着买工具、上平台先把规则写下来把流程画清楚然后让工具来承接这些规则——你会发现开放这件事本身就是最大的杠杆。