你是不是也遇到过这种局面合并请求MR/PR挂在那里三四天没人看一眼好不容易有位同事点开了评论全是缩进不对变量名建议改一下这类边角料而真正可能导致线上事故的设计问题反而被忽略了。更让人头疼的是同样的低级问题像韭菜一样这周割完下周又长每次都要人工提醒。我就是在这种反复拉扯中动手做了个代号叫open-code-review的工具。它不是要取代人工评审而是把代码审查里那部分机械、重复、纯靠眼力的事情交给机器让人的注意力回到真正值得讨论的地方。本文会从我的设计思路、核心模块实现、接入方式到跑了一个月后的实际踩坑记录完整讲一遍。如果你也在为团队评审流于形式发愁或者想给自己的项目加一层自动化代码审查这篇应该能给你一条可以照抄的路线。1. 为什么我动手写了open-code-review从review流于形式说起1.1 多一双眼睛为什么会失效代码审查这个机制理论上是软件质量的一道重要防线。但现实里它经常变成一种仪式。我观察到的核心原因有三个。第一个是注意力带宽。一次正常的合并请求可能涉及十几个文件、上千行变更。Reviewer被要求限时给出意见时往往只能盯着关键几处逻辑剩下的全靠扫一眼带过。小问题漏掉很正常但小问题长期漏掉就会成为团队的固定债务。第二个是上下文切换的成本。很多团队的模式是有空了再review而不是这个任务你就负责review。当一个人刚写完自己的功能脑子里全是自己那套逻辑再突然切进去看别人的几百行 diff理解成本是非常高的。结果就是要么拖很久要么草草点个通过。第三个是小问题反向掩盖大问题。如果每次评审里满屏都是格式类、命名类的意见真正需要深思的架构问题反而会被淹没。评审者也是人他连着提了七八个琐碎问题后对这里并发控制可能有问题这种需要花时间思考的意见给的精力会明显下降。这三点并不是人的问题而是流程设计的问题。我当时的想法是如果把琐碎的、可量化的问题交给工具人工评审的压力就能大幅度减轻精力自然集中在高价值问题上。1.2 现成方案差在哪你可能会说代码检查不是已经有现成工具了吗静态分析、linter、格式化工具市面上太多了为什么还要自己写我不否认这些工具的价值但在代码评审这个具体场景里它们的定位和 open-code-review 不太一样。传统的静态分析工具偏扫雷——不管这段代码是谁改的、这次改动涉及了什么只要代码里有潜在问题它就会报。这带来的结果是在一个老项目里它的存量警告可能多到没人愿意看。而且它并不关心这次合并请求作为一个整体是否合理例如一个改动同时触碰了数据库字段和迁移脚本但没有同步更新这类跨文件的一致性问题静态分析工具基本管不了。商业化的评审平台或代码托管平台自带的讨论区功能解决了人在哪里评论的问题但没有解决哪些问题值得机器人先看一遍的问题。人工评审者仍然是从零开始逐行去看。所以我心里浮现的定位是open-code-review 不比赛找历史缺陷它只审这次变化。它要做的是给这次 MR 一份变化摘要 机器预审意见让人打开 MR 时不是面对一片空白而是面对一份已经整理好的待办清单。1.3 我给自己定下的三条验收标准没有目标就写代码写到最后一定是一团乱麻。动工之前我给这个工具定了三个必须满足的验收标准整个设计过程都围绕它们展开。第一低噪音。机器报出的每一条意见都应当和本次变更强相关宁可漏报不可错报。一个误报率太高的工具用不了两天就会被团队关掉。第二可配置、可扩展。团队之间的风格差异太大了有的要求新增代码必须带测试有的要求所有 TODO 关联任务单有的要求变更日志必须更新。这些规则不能写死在代码里必须做成可以插拔、可以按仓库单独配置的。第三和现有工作流共存。它应该安静地待在 CI 流水线或 webhook 里不需要强行改变团队已经习惯的流程也不应该成为阻塞发布的一个笨重关卡。跑完之后给个建议人可以听也可以不听。这三条标准在我后面所有模块的技术选型中都是第一判断依据。2. 整体设计把审查当成一条可观测的数据流水线2.1 触发与入口事件驱动而不是定时全量扫我一开始的设想是做一个定时任务每天早上扫描所有 MR。但仔细一想这会产生大量无效计算——一个 MR 只要有更新机器人就要立刻重新看一遍等一天再跑太慢了。后来我把入口改成了事件驱动。当开发者在代码托管平台创建或更新 MR 时会发出 webhook 事件。我的服务收到事件后提取仓库地址、源分支、目标分支、MR 编号这些必要信息把这个审查任务丢进一个队列里立刻返回 ACK避免阻塞平台方的请求。为什么用队列而不用同步处理原因很简单真正意义上的代码评审机器跑一遍要走拉取代码、计算 diff、跑规则、生成评论的流程最慢的步骤是代码拉取和规则执行。如果同步处理webhook 请求可能超时而且代码托管平台的 webhook 往往是串行触发的前一个没处理完后一个排队等高峰期就会积压。异步队列的任务有点像一个自助餐厅的出餐口——你排上号处理好了会端到你桌上而不是让所有人都堵在窗口。2.2 分析流水线的五个阶段整个分析链路我分成了五个阶段每阶段只做一件事输入输出通过标准的数据结构传递。这样后期替换任何一环都很方便。第一个阶段是拉取变更。使用 git 的浅克隆模式只拉取 MR 源分支与目标分支共同对应的提交区间不拉全量历史。对于比较大的仓库这一步提速非常明显。第二个阶段是解析 diff。计算源分支相对于目标分支的补丁然后把补丁拆解为文件维度、hunk 维度、行维度三层结构。这个结构后面会贯穿整个规则引擎我把它叫作 ChangeContext。第三个阶段是规则执行。所有检查项都以规则插件的方式注册每个规则接收 ChangeContext返回一条或多条机器意见。这个阶段是纯函数式的——输入一个 ChangeContext输出一个意见列表没有任何外部依赖。这也是我能对规则做单测和调优的基础。第四个阶段是合并与降噪。多条规则可能命中同一行同一个问题可能在连续几个 commit 里反复出现。这里要做聚合、去重、按严重级别排序并且把同一种类型的意见合并成一条避免评论风暴。第五个阶段是上报。把最终意见以评论、报告文件或消息通知的形式输出。这个阶段也是可插拔的可以接代码托管平台的评论接口也可以输出成 JSON 或静态 HTML 报告。2.3 存储设计历史记录比一次评论更重要我给 open-code-review 加了一个轻量级的存储层用 SQLite 保存每次审查的元数据。包括 MR 编号、提交哈希、规则版本、意见列表、审查耗时等等。为什么要有这个存储层因为单次审查的评论只能服务当下而趋势数据才能服务长期。当团队想回答我们最近半年的评审意见主要集中在哪类问题哪些文件的缺陷率偏高这类问题时如果没有历史记录你只能翻聊天记录。有了存储层这些都能通过一句简单的 SQL 查出来。另外存储层还承担了一个职责防止评论刷屏。每次 webhook 事件进来我得先查一下这个提交哈希是不是已经审查过了。如果同一个 commit 被平台重复推送了几次工具就跳过本次处理。这类幂等逻辑看起来不起眼但在真实生产环境中webhook 重复投递几乎是必然的。我把这几层拆清楚之后代码结构就非常明确了。每层之间的接口是固定的出了问题能够快速定位是拉代码慢还是规则误报不至于一片混沌。3. 落地细节diff解析、可插拔规则引擎和评论降噪3.1 变更解析怎么准确知道这次改了什么规则引擎要工作基础是准确的结构化 diff。我使用git diff --unified3拿到带上下文的补丁数据然后解析文本格式。一个朴素的 diff 文本长这样的是一个一个的文件头、hunk 头、行数据组成的。文件头告诉你改的是哪个文件hunk 头告诉你这些行在原文件和新文件里的起止位置行数据前的/-表示新增或删除。我用一个简单的状态机去解析它。这里给出核心思路的Python伪代码import re HUNK_HEADER_RE re.compile( r^ -(\d)(?:,(\d))? \(\d)(?:,(\d))? (.*)$ ) def parse_patch(patch_lines): files [] current_file None current_hunk None for line in patch_lines: if line.startswith(diff --git): # 新文件开始记录文件名 current_file _parse_file_header(line) files.append(current_file) current_hunk None elif line.startswith(): # 新的hunk开始记录新旧起始行 m HUNK_HEADER_RE.match(line) if m: old_start, old_count, new_start, new_count map( lambda x: int(x) if x else 1, m.groups()[:4] ) current_hunk { old_start: old_start, new_start: new_start, old_count: old_count, new_count: new_count, lines: [] } current_file[hunks].append(current_hunk) else: if current_hunk is not None: current_hunk[lines].append(line) return files解析完成后我还需要做一步定位工作把每一行新增代码映射到它所在的函数或类。这一步非常关键因为不少规则是函数级的比如这个函数的行数超过 80 行了而不是第 37 行超过 80 行了。定位的方式是扫描这个文件的新版本内容维护一个当前作用域的栈遇到def、class、function、{等标志性行就入栈/出栈。不同语言的语法差异很大我没有做完整的 AST 解析而是用一个可配置的作用域锚点关键词列表覆盖最常见的编程语言就够用了。3.2 规则引擎把每条团队约定变成一段可复用的代码现在到了最有意思的部分——规则引擎。我的设计是每个规则一个文件实现同样的接口。class RuleResult: def __init__(self, line, file_path, message, level): self.line line self.file_path file_path self.message message self.level level # error / warning / nitpick class Rule: name console_log_check level warning languages [javascript, typescript, python] def check(self, change: ChangeContext) - list[RuleResult]: results [] for file in change.files: if file.language not in self.languages: continue for line in file.added_lines: # 只看新增行 if console.log in line: results.append(RuleResult( lineline.number, file_pathfile.path, message发现残留的调试输出请移除或替换为日志组件。, levelwarning, )) return results规则的结果里我强制要求含严重级别error/warning/nitpick因为不同级别在 CI 里的行为完全不同。error 会阻塞合并warning 只提醒nitpick 属于可改可不改的优化建议。一个容易被忽视的设计点是languages字段。规则引擎执行时会先根据文件名后缀过滤掉完全无关的文件避免对每一个文件都跑全部规则。例如一个只检查 Python 的规则遇到.java文件可以直接跳过。这既提升了效率也避免了大量无意义的跨语言误报。实践中最受欢迎的几个规则往往是团队规范具象化的产物新增代码夹带了调试用的print/console.log变更涉及数据库字段但 MR 中没有同步的迁移脚本需要跨文件关联新增了很长的函数而没有抽分单纯统计函数体行数新增的 TODO 没有关联的任务单号修改了接口方法签名但没有同步更新调用方这些规则有一个共同特点人看一遍能发现但很费神机器看一遍几毫秒就能出来。3.3 评论降噪防止机器变成新的噪音源工具设计得再好如果最后在 MR 底下刷出 200 条评论团队一定会把你拉黑。所以在输出阶段我花了大量心思做降噪处理。几个具体的策略如下表场景处理策略原因多条规则命中同一行合并为一条评论列出全部问题点避免同一位置被评论三次同一问题在多个 commit 中反复出现只在最新 commit 上评论一次历史版本已无修改价值cutoff 阈值内如 10 行内的同类问题聚合为此处有 N 处类似问题减少刷屏感对 ignore 路径下的文件直接跳过生成文件、锁定文件不该审评论模板方面我坚持固定结构第一行是问题摘要第二行是文件路径和行号第三行是具体说明最后是规则名和级别。固定结构的好处是团队成员看多了以后一眼就能扫出这又是一条已读格式的建议处理效率会快很多。被忽略的实践是自动兜底当某个文件的建议数量超过设定阈值默认 5 条工具会停止继续评论改为在顶部发一条总结式评论。人在面对超过 5 条同质化意见时产生的烦躁感和面对 50 条时是一样的。超过了阈值之后多说的每条都是负收益。3.4 与平台交互的边界把自己做成客人而不是主人代码审查工具要工作就绕不开和 Git 托管平台的交互。交互的无非是三类接口拉取 MR 信息、提交评论、更新审查状态。要做到稳核心在于清晰界定边界。我的接口封装有一个原则所有写操作都走异步重试队列。提交评论时如果被限流或者网络抖动不会直接抛异常导致整个任务失败而是进入重试队列指数退避后再试。因为写评论属于可以迟到但不能丢失的操作和读代码不同。另外一个我在早期忽略、后来补上的细节是对抢占式更新要谨慎。开发者 push 新代码后工具会在新 commit 上重新审查并重新评论。如果实现得粗暴一点就会出现旧评论没撤回、新评论又发一遍的情况。我在按 commit 维度管理评论层面做了关联关系新 commit 出现时先撤回在旧 diff 范围内已经失去意义的评论比如旧的那行已经改掉了再发新评论。这样做以后MR 页面才真正像一个人的随手笔记而不是补丁叠补丁的历史垃圾场。4. 接入实操先让机器读报告再让机器开口说话4.1 一份能直接抄作业的最小配置接入第一步是写配置文件。我设计的原则是开箱即可跑默认规则集只启用那些在所有语言里都成立的问题其余的规则要用的时候再激活。一份最小配置长这样version: 1 repo: remote: gityour-git-host:your-org/your-repo.git default_branch: main rules: console_log_check: enabled: true level: warning todo_issue_link: enabled: true level: nitpick options: pattern: TODO[:(]?\\s*(#|TICKET-)?[A-Z]-[0-9] debugger_keyword_check: enabled: true level: error ignore_paths: - dist/** - *.min.js - vendor/** comment: max_per_file: 5 template: suggest-{rule}.mdignore_paths是高频用到的配置项。很多老项目里有大段自动生成的代码每次提交都会带上但没有任何审查价值。这个配置项配好之后报告噪音能下降一个量级。4.2 本地模式机器先闭嘴只吐报告这个工具我很推荐团队先用只读模式跑两周。所谓只读模式就是本地命令行执行生成一份报告文件不往平台上发任何评论。命令很简单类似这样open-code-review run \ --base origin/main \ --head origin/feature/xxx \ --format json \ --out review-report.json跑完之后开发者打开review-report.json或者转换出的 HTML 报告自己看有哪些建议心里有个数再决定要不要改、要不要和同事讨论。这个阶段的价值在于让团队先熟悉机器评审的脾气知道它喜欢报什么、不喜欢报什么知道哪些建议可以无视哪些建议其实有用。两周后如果大家对报告质量的认可度还行再打开自动评论也不迟。我强烈建议团队在报告模式期间把误报和噪音问题反馈回来统一调规则阈值。而不是一上来直接开评论让机器和同事互相折磨。4.3 在CI流水线里的位置当团队决定让机器开口后第二阶段是在 CI 里挂一个审查任务。我在项目 CI 脚本里加的一段逻辑是这样的# 安装工具 install_open_code_review # 运行审查输出SARIF格式结果 open-code-review run \ --base $TARGET_BRANCH \ --head $CURRENT_BRANCH \ --format sarif \ --out review-report.sarif # 上传结果给平台用于内联评论 upload_sarif review-report.sarif失败策略我可以给出一个很实用的分级方案error 级意见出现时让 CI 任务失败阻止合并warning 级意见出现时CI 通过但生成一条提醒nitpick 级只在报告里显示不产生任何动静。这套分级听起来简单但执行难度在于团队是否真的认同 error 级规则的定义。我踩过的坑是一开始把太多规则设成了 error结果 CI 天天红小伙伴怨声载道。后来我把规则级别整体回调只保留确定会导致事故或直接违反团队硬性规定的规则作为 error。红线的数量应该一只手数得过来。4.4 迭代节奏的建议接入一个新的代码审查工具最怕的是一步到位。我推荐的节奏是第一周本地只读报告第二到三周开自动评论一个月后再尝试打开 error 级阻塞。每个阶段都有明确的验证目标团队有了正反馈之后再往下走抵触情绪会小很多。还有一点是规则集的迭代不是写代码的人说了算应该让团队的资深工程师来拍板。工具只是把大家的约定变成代码约定本身必须来自团队共识。所以我给 open-code-review 配了一个简单的规则审批流程任何人提议新规则需要先在小组评审里过一遍再把规则代码提交进去。防止某一个人把自己的个人偏好强加给所有人。5. 跑了一个月后的真实体验踩坑、调参和优化5.1 命中率的起伏从五成噪音到八成有用上线后第一个月的实际数据比我想象中更能说明问题。第一周我做的工具在团队仓库里跑出的机器意见大概只有一半被人接受剩下的一半基本都是噪音。典型噪音包括不检查实际上下文就断言函数太长、对测试代码套用了业务代码的规则、把第三方依赖里的函数误判成新增代码等。这个阶段我没有急着去过滤这些噪音而是把每周的误报反馈收集起来对规则逐个调整。比如函数太长这个规则原本只要超过 60 行就报后来改成超过 100 行才报并且只在非测试文件里检查。第二周意见接受率明显上升到第四周基本稳定在接近八成。剩下的两成通常属于边界情况大家慢慢也学会了忽略。这里最深的体会是规则引擎的价值曲线不是写出来就封顶而是在和团队实际行为对齐的过程中逐步爬升的。做好心理准备前两周可能会被骂但这正是工具走向好用的必经阶段。5.2 三个性能瓶颈和对应的解法跑了几天之后我遇到了三个非常典型的性能问题。第一个是大仓库拉取代码太慢。一开始我用全量克隆的方式拉仓库一个历史悠久的仓库可能拉下来就要几分钟。改成--depth1 --branchfeature/xxx --single-branch拉取源分支再在目标分支上用git fetch origin main --depth1拉一下主干速度提升了不止一个量级。再配合git diff只算提供的两个 commit 之间的变更整个过程从几分钟压到了十几秒。第二个是规则执行的无谓开销。最初每个规则都遍历所有文件的每一行遇到大仓库时 CPU 飙高。我加了两层快速过滤文件名后缀过滤规则语言过滤。比如只有.ts文件才会进入 TypeScript 规则集其余文件直接被跳过。这轮优化之后CPU 占用基本可以忽略不计了。第三个是评论接口的限流。当一次审查发现 20 多个问题工具打算一次性发出 20 条评论时平台方会在几秒内触发限流。处理方法有两个维度一是严格执行前面讲的每文件最多 5 条同类聚合策略从源头减少数量二是写评论时加入批次控制每次并发不能超过 3 个请求批间间隔 1 秒。这两个措施组合下来限流问题再也没有出现过。还有一个很隐蔽的问题二进制文件与超大文件。如果一个 MR 里改了一个巨大的一行压缩文件diff 计算会非常吃力。我的规避方式是在 diff 阶段直接忽略超过阈值大小的文件以及无法用文本编码解码的文件。毕竟不会有人真的希望机器去检查一个压缩包里的变更。5.3 重命名和移动文件的误报告诫这个坑值得单独拎出来说。当一个文件被重命名并做了少量修改时git diff 默认会把它显示为删除旧文件 新增新文件如果规则不做处理它会同时对被删除的旧文件里的所有代码和新文件里的所有代码给出建议导致一次重命名操作刷出几十条意见。解决办法是在解析阶段显式启用重命名检测git diff --find-renames40% # 相似度超过40%视为重命名启用之后重命名文件被识别成rename 少量改动的形式工具只审查真正改动的部分而不是把整个新文件当作新增代码。这个优化对评论噪音的影响非常立竿见影团队里常见的把公共函数抽到另一个文件类提交之前是重灾区之后基本清净了。5.4 团队采纳过程里最便宜的妥协最后聊点技术之外的。即使工具再准、再快团队里一定有人抵触机器在代码评审里说三道四。我观察到的抵触理由通常是两条觉得机器在监视自己的工作觉得规则是某个人强加的约束。我的解法很朴素也给这个工具定了个软的产品基调机器意见永远只是建议人工有权否决报告里不出现提交者姓名和分数排名工具不参与绩效规则集是一个团队共同维护的库每条规则都有 owner。这套基调执行下来团队对工具的接收速度比我预期快很多。当大家发现机器承担了那些最烦人的琐碎检查而自己省下的时间可以真正用来思考设计方案时抵触自然就消失了。到后来甚至有人会主动把需求里需要的规则提出来这个场景挺常见能不能给 open-code-review 加一条——这种时候你就知道项目算是真正活下来了。我个人做完这个项目后最大的体会是代码审查工具难的不是写规则、不是解析 diff而是克制——克制自己想让机器变得全能的冲动克制把规则堆到谁都烦的地步。把它做成一个安静、快速、说人话的小助手比做成一个自以为是的守门员要有用得多。如果你也在搭类似的东西不妨先从最让你自己头疼的一条规则开始跑起来再慢慢加。工具是给人用的别让它一开始就让人想关掉。
