★ FEATURED ARTICLE 聊到代码审查很多团队的现状其实是这样的Code Review 主要靠人肉合并请求一挂就是半天reviewer 要么忙得没空看要么扫一眼就 Approve等代码上了生产出了问题才回过头来懊恼。我今年在维护一个中大型项目时被这种“人肉审查”卡得实在难受于是抽空折腾了一个开源的代码审查工具名字就叫 open-code-review。它的核心思路并不复杂把代码审查从“等人看”变成“机器先看一遍、人再看重点”通过差异分析、规则引擎和语义分析在 MR 提交的第一时间自动生成结构化的审查意见让 reviewer 不用从头到尾逐行读 diff而是直接去看机器标注的风险点和有争议的地方。对于项目里有几十号开发、每天几十个 MR 的团队来说这东西能省下的时间非常可观。这篇博文我就把整个项目的设计思路、核心实现、部署接入和一些实际踩坑经验完整分享一下适合想自建代码审查体系的开发者、对工程效率工具感兴趣的技术负责人也适合刚接触这类工具的读者照着搭一套。1. 为什么要自建代码审查系统团队里的真实痛点1.1 人工审查的瓶颈在哪里先说一个我观察了很久的现象大部分人做 Code Review 的时候真正花在“思考代码逻辑”上的时间其实不到三分之一。剩下三分之二的时间都耗在“看 diff 上下文”“找变更文件”“判断这行改动会不会影响别的模块”这些重复劳动上。尤其当 MR 改动了几十个文件reviewer 打开页面看到一屏红色绿色第一反应往往是头疼然后快速滑动滚轮最后只对几个大文件留下几句不痛不痒的评论。这种模式的瓶颈不是人不够聪明而是人的注意力本身就是稀缺资源。一个 200 行以内的小 MR 还好一旦到了 500 行以上审查质量就直线下降。我统计过团队最近三个月的 MR 数据超过 300 行的 MR平均每个文件被提出有效问题的概率不到 20%也就是说大部分改动其实是在“裸奔”状态下合入主干的。这不是某个人态度有问题而是流程设计上就存在漏洞没有在第一轮用机器做一遍基础的、确定性的检查把人的精力留给真正需要判断力的地方。1.2 open-code-review 解决的问题open-code-review 要解决的就是上面说的“确定性问题”和“注意力分配”问题。它能做的第一件事是在 MR 创建的时候自动把 diff 拉下来解析出每个文件的新旧版本算出新增行、删除行、修改行然后基于这些变化去做分析。举个例子一个函数从“接收两个参数”改成“接收三个参数”如果只靠人眼你可能要看到调用处的报错才能反应过来。但 open-code-review 可以在分析阶段就发现这个函数的签名变了而某个调用点没跟着改于是自动在该调用点下打一条评论提示“函数入参数量不匹配”。这种检查不需要人思考机器做得又快又准。另外它可以自动识别高风险文件——比如改动涉及鉴权、支付、数据库事务、并发锁等逻辑就会把这些文件标记为“建议必须人工重点审查”并附上理由。我一开始做这个项目的时候也犹豫过现在市面上有 CodeRabbit、Snyk 这些商业工具为什么还要自己写一个后来想明白了商业工具通常是黑盒规则不透明而且很难跟团队内部的规范完全对齐。自建工具最大的价值是规则、阈值、输出格式全部掌握在自己手里今天发现一个新的坏味道模式明天就能写进规则库里立刻生效。1.3 和现有方案的对比选择如果你也在考虑引入代码审查自动化我建议你先想清楚一个核心问题你要的是“审查意见的数量”还是“审查意见的质量”如果只追求数量商业工具确实开箱即用但如果你希望工具能真正贴合团队的编码规范、能处理私有仓库里的特殊逻辑那自建一套规则引擎反而更省心。方案上手成本规则可定制性数据隐私与内部规范对齐商业 AI 审查工具低中弱代码出库一般纯人工 Review低高强强open-code-review 自建中高强全本地强我最终选择自建还有一个原因是隐私。团队里有一部分项目是客户私有化部署的代码绝不能出内网。open-code-review 可以完全跑在本地或内网 CI 服务器上不需要把代码传给任何第三方服务这一点在 To B 项目里是刚需。2. 整体架构与核心设计思路2.1 系统模块划分整体架构我拆成了四个模块变更采集模块、差异解析模块、规则分析模块和报告输出模块。这四个模块各自独立通过标准的数据结构串起来这样做的好处是后续想换掉任何一块都不用动其他代码。变更采集模块负责跟 Git 仓库打交道执行 diff 命令拿到两次提交之间的变更列表。差异解析模块则把 diff 文本解析成结构化数据——哪个文件的哪一行新增了什么、删除了什么、上下文是什么函数这些信息都会被打上标记。规则分析模块是核心它拿到结构化变更数据后会遍历所有激活的规则逐条进行匹配。报告输出模块比较简单就是把分析结果整理成 Markdown 或 JSON方便回写到 Git 平台的评论区。我用 Python 写这个项目原因很朴素Python 在文本处理和 AST 解析这块生态太成熟了。tree-sitter 可以直接把多种语言解析成语法树不需要每个语言单独写一套 parser。整个系统的入口是一个命令行工具支持open-code-review review --base main --head feature这样的调用方式方便在 CI 里直接跑。2.2 为什么选择基于语义分析而不是纯正则匹配刚开始我也走过弯路第一版用了大量的正则表达式来匹配“可疑代码”。比如查TODO、FIXME、调试用的print确实简单粗暴。但正则很快暴露了局限它只能在文本层面做匹配完全看不懂代码结构。举一个我实际遇到的例子。一个正则规则想查“所有直接调用dangerous_call()的地方”用正则dangerous_call\s*\(确实能匹配到调用点。但如果这个函数被包了一层wrapper(() dangerous_call())正则只能匹配到内层却没法判断外层是不是已经做了异常处理。这时候就需要语义分析看 AST 节点看这个调用点的父节点是什么类型的语句有没有被try-catch包裹。tree-sitter 提供了完整的语法树我可以拿到每个函数调用的精确位置、参数列表、函数签名甚至能查到某个变量在当前作用域里是怎么定义的。这就能做很多更智能的检查比如变量遮蔽检测内层作用域定义了一个跟外层同名的变量在大型项目里这种问题很难一眼看出来但语法树一对比就清清楚楚。2.3 设计时重点考虑的场景在设计规则分析模块的时候我明确锁定了三个高频场景优先支持。第一个是接口变更波及分析。函数签名变了调用点没跟着改这个问题在多人协作的项目里几乎每天都会出现。通过 AST 解析所有函数定义和调用关系一旦发现某个被引用多次的函数签名发生变化就自动去查调用点把不匹配的列出来。第二个是配置项硬编码检测。团队内部规范要求敏感信息必须走配置中心但总有人图省事直接在代码里写死。这个用语义分析做也很方便先通过 AST 找字符串常量再跟规则库里的敏感变量名比如password、api_key、secret做匹配命中就报警。第三个是错误吞没检测。空except: pass或者catch (Exception e) { }这种写法是线上问题排查时的噩梦。解析语法树后如果发现异常处理块里面没有任何日志输出或者重新抛出的逻辑就直接标记为“错误被吞没”。这三个场景覆盖了团队里大部分“机器能发现的低级问题”把人的精力真正解放出来。3. 核心实现细节解析3.1 变更采集与差异计算变更采集的输入是 Git 仓库和两个 commit 引用。实际执行的时候我用的是git diff加--unified0参数这样输出的 diff 只包含变更行不包含上下文解析起来更轻量。但这里有个坑没有上下文的 diff 在做语义分析时不够用。比如我要判断一个删除行是不是位于某个 try 块内部必须拿到这个删除行附近的完整代码上下文。所以我实际采集了两层数据第一层用git diff --name-status拿变更文件列表第二层对每个变更文件单独执行git diff -U10 base head -- file保留足够的上下文行。然后再用 tree-sitter 把新旧版本的文件都解析成语法树这样每一个变更行都能对应到语法树上的具体节点能知道它属于哪个函数、哪个类、哪个控制流块。差异计算的另一个容易忽略的点是行号映射。git 的 diff 输出里有 -12,7 12,9 这种 hunks 头需要正确解析出新旧行号之间的映射关系。我维护了一个双向映射表旧文件第 12 行到第 18 行对应新文件第 12 行到第 20 行。分析引擎查询“新文件第 15 行发生了什么变化”时可以立刻通过映射表找到对应的旧文件行号以及这行的变更类型是新增还是删除。3.2 规则引擎的设计与实现规则引擎是整个项目里最有意思的部分。我把每条规则设计成两个部分元信息和检测函数。元信息包含规则名称、适用语言、风险等级、描述文本检测函数则是一个接收语法树节点和变更信息、返回命中告警的函数。规则文件用 YAML 或 Python 模块来定义团队想加规则不用改主程序只需要新增一个规则文件并注册即可。举个例子空异常捕获规则的检测函数逻辑大致是这样遍历语法树中所有try语句找到它的except或catch子句检查该子句内部是否有日志调用、是否有raise、是否有返回错误值的语句。如果子句体为空或者只有pass就命中规则。规则分析完成后每条告警会带上文件路径、行号、规则 ID、严重级别和人类可读的描述。这个数据结构是统一的后续无论是输出成 Markdown 表格还是转成 GitLab 评论或者是发到企业微信机器人都很方便。3.3 报告生成与审查体验优化报告输出我做了两个版本本地命令行版本输出到终端和 Markdown 文件CI 版本则会读取GITLAB_TOKEN或GITHUB_TOKEN直接把审查意见以评论的形式发到 MR 对应的 diff 行上。这样开发者不用跑到 CI 日志里翻结果直接在 MR 页面就能看到“第 45 行这里可能有空异常捕获”。这里有一个产品细节我觉得值得分享告警不要全部冲到 MR 评论里一定要做降噪和分级。我设置了三个级别Block阻断、Warning警告、Info提示。Block 级别的意见会直接标记为“必须处理”比如接口调用不匹配、密钥硬编码Warning 级别需要人工确认比如空异常捕获Info 级别则只是提示比如“这个函数过于复杂建议拆分”。为什么会这样设计因为我发现如果机器每次在 MR 上挂 30 条评论开发者的第一反应是“这工具疯了”然后把所有评论一键忽略。反过来如果平均只挂 3 到 5 条而且每条都言之有理大家才愿意认真看。所以我在报告模块里专门做了一个聚类去重逻辑同一个文件里相同规则的相邻命中合并成一条避免刷屏。4. 实操部署与接入 CI/CD 流程4.1 环境准备与安装步骤open-code-review 依赖 Python 3.10 以上版本还需要 Git 和 tree-sitter 对应的系统库。安装很简单直接从源码仓库 clone 下来后执行pip install -r requirements.txt即可。我建议用虚拟环境别直接装到系统 Python 里不然之后升级依赖会遇到一堆莫名其妙的版本冲突。需要的核心依赖我列一下tree-sitter、tree-sitter-language-pack、PyYAML、requests。tree-sitter-language-pack 这个包很关键它把常见语言的 grammar 都打包好了不用自己逐个去编译。我第一次折腾的时候不懂一个个去装 grammar C 扩展折腾了大半天后来发现一个包就能搞定。安装完成后执行open-code-review --help能看到命令行工具已经可用。这里有个小提示如果是在 CI 环境里用建议把依赖固化成 lock 文件避免某一天某个依赖库更新导致行为变化。我自己就被这个坑过一次一个 grammar 版本升级后解析结果变了导致同一个 MR 前后两次审查意见不一致。4.2 快速启动与本地验证流程安装好后先在本地仓库里跑一遍验证效果。我通常的做法是开一个测试分支故意改几个有明显问题的代码片段比如加一个空异常捕获、硬编码一个密钥、改一个函数签名但不改调用点。然后执行open-code-review review --base main --head test-branch --format markdown --output report.md命令跑完后打开report.md看结果。如果规则没问题你会看到每条问题记录都带文件路径、行号和具体描述。遇到没有命中预期规则的情况先用--debug参数跑一遍查看解析器是否把目标代码正确识别成了对应的语法节点大部分规则失效的问题都出在这一步。我还建议在本地用一个小脚本模拟 CI 环境保证环境变量注入后行为一致。因为 CI 里的工作目录往往是干净的 clone没有本地未提交的更改执行 diff 的结果跟本地可能会有差异。我遇到过一种情况本地因为有一些未提交改动导致 diff 范围异常工具把不该审查的文件也拉进来了审查报告里出现了一堆跟本次 MR 无关的告警。4.3 接入 GitLab CI 和 GitHub Actions接入 CI 是整个项目落地最关键的环节。我现在主要用 GitLab CI流程很简单在.gitlab-ci.yml里加一个 stageMR 创建或者更新时触发跑一个自定义镜像里的审查脚本最后把生成的报告提交到 MR 评论区。GitLab CI 的核心配置大概是这样的code-review: stage: review image: python:3.11-slim only: - merge_requests script: - pip install -r requirements.txt - open-code-review review --base $CI_MERGE_REQUEST_TARGET_BRANCH_SHA --head $CI_MERGE_REQUEST_SOURCE_BRANCH_SHA --gitlab-token $GITLAB_TOKEN --project-id $CI_PROJECT_ID --mr-iid $CI_MERGE_REQUEST_IID artifacts: paths: - report.mdGitHub Actions 的接入思路完全一致只是环境变量名不同。要注意的一点是GitLab CI 里$CI_MERGE_REQUEST_TARGET_BRANCH_SHA这种变量指向的是分支的最新 commit而不是分支名。用 commit SHA 做 diff 比用分支名更可靠因为分支名是动态的前后两次流水线拉到的 commit 可能不一样导致审查结果对不上。当然这里有一个前提代码仓库必须允许 CI 运行时有权限读取 MR 的元数据并调用平台 API 写评论。GitLab 需要在 CI 里配置一个具有api权限的 tokenGitHub 则需要配置GITHUB_TOKEN并赋予pull-requests: write权限。权限这块别给太大最小够用就行毕竟 token 泄露的后果谁都不想面对。5. 规则自定义与模型调优5.1 规则引擎的自定义配置实践默认规则集只是一个起点真正让工具发挥价值的是自定义规则。团队内部的规范五花八门比如“禁止直接 new Date()必须使用统一时间工具类”“所有 RPC 调用必须设置超时时间”“日志必须包含 traceId”。这些规范写成规则其实都逃不出几类模式查 AST 节点类型、查函数调用名、查某个作用域的属性访问。规则文件我设计成 YAML 格式看起来是这样的- id: no-raw-date name: 禁止直接使用 Date 构造器 languages: [javascript, typescript] severity: warning message: 请使用 utils/time.ts 中的统一时间函数替代直接 new Date() pattern: call_expression filter: function_name: Date有了这种自定义能力规则库是可以积累的。团队里每出现过一次线上事故我们就复盘它能不能通过静态规则提前发现。能就把它变成一条新规则。这是我认为自建工具最大的长期价值——它是一个会成长的过程资产。不过自定义规则也有主板写规则你一定得理解语法树节点的结构。我建议先用 tree-sitter 的 playground 把目标代码解析出来看节点长什么样再写过滤条件。别指望一次写对规则调试基本是个反复试错的过程我第一条规则就改了四版才稳定。5.2 结合大模型生成智能审查意见静态规则做到后面你会发现有些问题它确实抓不到比如“这个函数名字叫 fetchData但里面实际在写文件”这种语义层面的问题需要真正理解代码意图。为了补上这块短板我在 open-code-review 里加了一个可选的“大模型分析”模块通过调用大模型 API把变更文件的摘要和关键 diff 发送给模型让它生成自然语言审查意见。这个模块的接入方式是配置llm段指定 provider 和模型名称。分析流程上我先用静态规则筛掉低价值文件只把“高风险文件”和“变更超过 100 行的文件”送给模型这样能控制 token 消耗又不至于漏掉大改动。模型返回的意见会经过后处理和静态规则的结果合并输出。用下来我的感受是大模型对“代码坏味道”的嗅觉确实敏锐比如“这个方法职责太多了建议拆分”“这段删除操作没有幂等保护”这类意见是静态规则写不出来的。但也有翻车的时候模型偶尔会幻觉出一些不存在的变量所以在报告里我会把大模型意见标记为“AI 建议”不设 Block 级别只作为参考。5.3 控制误报率的几个实用技巧误报率是代码审查工具的生死线。最开始我在团队里推广的时候被人吐槽最多的就是“这工具太吵了”几乎每周都有人在群里艾特我说某个规则误报了。后来我总结出三个控制误报率的技巧。第一规则必须支持排除路径和文件。比如某些生成代码目录client/models、migrations本来就是自动生成的审查毫无意义。我在配置里加了exclude_paths和include_paths两个选项优先级高于规则本身。第二减少规则里的“凭感觉”判断。比如“函数太长”这种复杂度规则一开始我定的是“超过 50 行就报警”结果大量既有代码命中开发体验极差。后来改成“新变更新增的代码导致函数超过 80 行”才报警只针对增量不针对存量大家才觉得合理。第三建立误报反馈渠道。每一条告警都允许开发者标记“忽略”或“误报”。我每月拉一次数据看看哪些规则被忽略率超过 30%这种规则要么修改要么直接下线。规则不维护迟早变成一支报警大队。6. 常见问题与实战排查记录6.1 常见问题速查表我把实际使用中高频出现的问题整理成了速查表方便后来者排查。现象可能原因处理方式审查结果为空diff 范围错误base 和 head 指向了同一 commit检查 CI 里传入的 SHA 变量是否正确评论没有发到 MR 上token 权限不足或者项目 ID 配错确认 token 有 api 权限核对 project IDtree-sitter 解析报错语言 grammar 版本过旧升级 tree-sitter-language-pack 到最新版同一个 MR 重复告警每次 push 都触发没有做去重在报告模块里按 commit SHA 缓存结果大模型分析超时并发请求太多或 diff 太大限制单次分析的 diff size加入超时重试6.2 三个让我印象深刻的坑第一个坑是 diff 上下文不完整导致报告“张冠李戴”。当时我用--unified0拿精简 diff 做分析发现某条告警指错了行号。排查半天才发现没有上下文的 diff 在解析和谐映射时容易错位尤其是文件中有大量空行变动的时候。后来我改成保留 10 行上下文还专门为行号偏移写了单元测试这个问题才算解决。第二个坑是语法树缓存失效。一开始我在长驻进程里缓存了所有文件的 AST明显提升了大仓库的分析速度。但 Git 分支切换后文件内容变了缓存没跟着失效导致分析结果还是旧版本代码的。现在我的策略是以 diff 中每个文件的 head commit SHA 作为缓存 key一旦 SHA 不匹配就重新解析彻底避免了脏缓存。第三个坑跟 CI 环境有关。GitLab CI 默认的工作目录是浅克隆历史只有最近一次提交。执行git diff base head时如果 base 所处的 commit 不在浅克隆范围内就直接报错。我甚至在流水线日志里看到过“fatal: bad object”这种让人一头雾水的错误。解决方法是在 CI 配置里加上GIT_DEPTH: 0或者使用git fetch --unshallow确保完整克隆。6.3 下一步可以怎么扩展open-code-review 目前的版本已经满足了我们团队的日常需求但我心里清楚还有很多可以扩展的地方。第一个方向是支持多语言的语言服务器协议LSP这样可以直接复用编辑器的诊断能力比如 TypeScript 的 type check 结果、Python 的 mypy 结果都可以汇总到审查报告里。第二个方向是做增量规则学习。现在规则还是靠手动积累我理想的状态是工具能从历史告警和人工标注的误报里自动总结规律推荐新的规则组合。这个工程量大一些但方向是对的。第三个方向是打通更多平台和通知渠道。目前只接入了 GitLab 和 GitHub但很多团队用的是自研代码平台或者需要把审查结果同步到飞书、钉钉、企业微信。报告模块的输出是标准 JSON理论上接一个新渠道只是写一个推送函数的事。最后再分享一点实际操作中的体会如果你正在犹豫要不要自建这样一个工具我的建议是先小范围试起来。不用一上来就把所有规则、所有语言都配齐选一个核心仓库、选三种左右的高价值规则跑两周看看效果。我见过太多团队想一步到位结果把自己卷进复杂的配置里最后什么也没落地。工具是服务于流程的审查工具最大的作用不是替代人而是让人把注意力放到真正有价值的事情上。动手搭一套跑起来再慢慢调你会发现它的价值会随着规则的积累越来越明显。
阅读完成 · 觉得有帮助？
