1. 从零搭建代码评审机器人的真实动机

代码评审这件事，做过团队协作的人都有体会。一个人写完功能，提交合并请求，然后眼巴巴等着同事来审。同事手头一堆活儿，可能拖到第二天才看，看完提几条意见，改完再等一轮。一个不大的改动，来回折腾两三天是常事。更麻烦的是，有些问题其实很机械——变量命名不规范、函数太长、缺少边界判断、日志打得不合理——这些完全可以用工具自动查出来，却占用了大量人工评审时间。

我所在的团队大概十来个人，后端前端都有，项目迭代节奏快的时候一天能提十几个合并请求。评审压力最大的时候，资深工程师半天时间全花在看别人的代码上，自己的活儿只能加班干。时间一长，大家都有怨气。我就琢磨着，能不能做一个自动化的代码评审工具，把那些“看一眼就知道有问题”的毛病先过滤掉，让人工评审只关注真正需要判断力的部分，比如架构设计是否合理、业务逻辑是否有漏洞、接口定义是否清晰。

这个想法就是“open-code-review”项目的起点。它的核心定位很明确：一个开源的、可自行部署的代码评审辅助系统，对接代码托管平台的合并请求，自动拉取差异内容，跑一遍预设的检查规则，把发现的问题以评论形式回写到合并请求里。它不追求替代人工评审，而是做人工评审的“第一道筛子”。

适合谁来参考这篇内容呢？如果你是小团队的技术负责人，正被评审效率问题困扰；或者你是对自动化工具感兴趣的开发者，想了解这类系统怎么从零搭起来；又或者你只是想给自己的项目加一个自动检查的环节，那接下来的内容应该都能帮到你。我会从整体设计思路讲起，然后拆解核心模块的实现方式，再分享实际跑起来之后踩过的坑和调整过程。

2. 整体架构与核心模块拆解

2.1 为什么选择“事件驱动 + 规则引擎”的组合

做自动化评审工具，第一个要决定的就是触发方式。最简单的做法是定时轮询，每隔几分钟去代码托管平台拉一次最新的合并请求列表，发现有新的就处理。但这种方式有两个明显问题：一是延迟高，提交之后可能要等好几分钟才有反馈；二是浪费资源，大部分轮询都是空跑。

所以我选了事件驱动的方式。代码托管平台基本都支持Webhook，当有新的合并请求创建或者更新时，平台会主动发一个HTTP请求到我们配置的地址。我们的服务收到请求后，解析出项目标识、合并请求编号、源分支和目标分支这些信息，然后触发后续的评审流程。这样响应及时，资源消耗也小。

但光有事件驱动还不够，评审逻辑本身需要一套规则引擎来支撑。规则引擎的作用是把“检查什么”和“怎么检查”分开。检查什么由规则定义，比如“函数行数不超过80行”“禁止使用某些不推荐的API”“新增代码必须有对应的单元测试文件”。怎么检查由引擎负责，它遍历所有启用的规则，对差异内容逐条执行，收集结果。

这种分离带来的好处是扩展性强。后面想加新规则，只需要写一个规则描述文件，注册到引擎里就行，不用改核心流程。团队里不同的人可以负责不同的规则集，比如后端组维护Java相关的规则，前端组维护JavaScript和CSS的规则，互不干扰。

2.2 差异内容获取与解析的关键细节

评审的基础是拿到代码差异。代码托管平台的API通常提供两种获取差异的方式：一种是直接返回统一格式的diff文本，另一种是返回结构化的文件变更列表。我一开始用的是diff文本，因为看起来简单，直接解析就行。但实际用下来发现坑不少。

diff文本的格式虽然标准，但不同平台在细节上有差异。比如有的平台在文件头会加额外的元信息，有的平台对重命名文件的表示方式不一样，还有的平台在二进制文件变更时给出的标记不统一。更麻烦的是，当差异内容很大时，diff文本会非常长，解析起来性能很差。

后来我改成了用结构化接口。以常见的代码托管平台为例，获取合并请求的变更列表时，返回的是一个数组，每个元素包含文件路径、变更类型（新增、修改、删除、重命名）、新增行数、删除行数，以及具体的差异块。每个差异块里又有旧文件行号、新文件行号、变更内容这些字段。这样解析起来就清晰多了，不用去猜文本格式。

拿到结构化差异之后，还需要做一层过滤。不是所有文件都需要评审。比如自动生成的代码、第三方库文件、编译产物、锁文件这些，通常不需要人工看，也不应该触发规则检查。我在配置里加了一个忽略列表，支持按文件路径模式匹配，比如*.min.js、package-lock.json、dist/**这些。这个忽略列表是可以动态调整的，不同项目可以有不同的配置。

还有一个细节是差异块的上下文行数。代码托管平台默认返回的差异块通常只包含变更行前后各三行上下文。对于简单的规则检查够用，但有些规则需要更多上下文才能准确判断。比如检查“函数是否过长”，如果只看到函数中间几行，根本不知道函数从哪里开始到哪里结束。这种情况就需要在规则执行时，按需拉取完整文件内容来做分析。我的做法是，规则可以声明自己需要“完整文件”还是“仅差异块”，引擎根据声明来决定是否额外拉取文件内容。

2.3 规则引擎的设计与规则定义方式

规则引擎是整个系统的核心。我设计的时候参考了静态代码分析工具的思路，但做了简化，因为目标不是做全量代码扫描，而是针对变更内容做增量检查。

每条规则是一个独立的配置单元，包含几个关键字段：规则标识、规则描述、适用文件类型、检查逻辑、严重级别。规则标识是唯一的名字，比如function-length-check。适用文件类型用扩展名或路径模式表示，比如.java、.py、src/**/*.js。检查逻辑是规则的核心，我用了两种实现方式：一种是基于正则表达式的简单匹配，适合检查命名规范、禁止使用的API这类；另一种是基于语法树的分析，适合检查函数长度、圈复杂度、重复代码这类需要理解代码结构的。

严重级别分三档：错误、警告、建议。错误级别的问题会阻塞合并请求，必须修复才能继续；警告级别的问题会显示在评论里，但不阻塞；建议级别的问题只是提示，开发者可以自行决定是否处理。这个分级很重要，如果所有问题都阻塞，开发者会很快失去耐心，觉得工具在找茬。

规则的定义我用了YAML格式，因为可读性好，非开发人员也能看懂和修改。一个典型的规则定义长这样：

rule_id: function-length-check description: "函数体行数不应超过80行" severity: warning file_patterns: - "**/*.java" - "**/*.py" check_type: ast params: max_lines: 80

引擎启动时会加载所有规则文件，按文件类型分组。处理一个合并请求时，先根据变更文件的类型筛选出适用的规则，然后对每个文件的每个差异块执行规则检查。检查结果收集到一个列表里，最后统一格式化成评论内容。

这里有个性能上的考虑。如果变更文件很多，规则也很多，逐个执行可能会慢。我的优化方式是并行处理：把文件列表分成多个批次，每个批次在一个独立的线程里执行规则检查，最后合并结果。线程数根据CPU核心数动态调整，避免过度切换。实测下来，一个包含20个文件变更、启用了30条规则的合并请求，完整检查耗时在3秒左右，完全可以接受。

2.4 评论回写与结果呈现的取舍

检查出问题之后，怎么把结果告诉开发者，这个环节的设计直接影响工具的接受度。最直接的方式是在合并请求里发一条评论，把所有问题列出来。但这样做有几个问题：一是评论太长，几十个问题堆在一起，看着就头疼；二是问题和代码位置对不上，开发者还得自己去找是哪一行；三是如果每次提交都发一条新评论，评论区很快就乱了。

我最终采用的方案是“行内评论 + 汇总评论”的组合。行内评论是针对具体代码行的，代码托管平台的API通常支持在差异的指定行上创建评论。这样开发者直接在代码旁边就能看到问题，修改起来很方便。汇总评论是每个合并请求只发一条，内容包括检查概况（总共发现多少问题、各严重级别多少）、规则执行统计、以及一个提示“详细问题请查看行内评论”。汇总评论在每次检查后更新，而不是新发一条，这样评论区始终保持整洁。

行内评论的定位需要小心处理。差异块里的行号有旧文件行号和新文件行号之分，评论要挂在新增行上，所以要用新文件行号。但有些问题可能出现在删除行上，比如“删除了必要的空行检查”，这种情况没法挂行内评论，只能放在汇总评论里说明。另外，如果同一个位置有多条规则都报了问题，需要合并成一条评论，避免同一行出现多条评论显得杂乱。

还有一个体验上的细节：评论内容要简洁明了。我见过一些工具，报错信息写了一大段，又是规则说明又是修复建议，开发者根本没耐心看。我的做法是每条评论只包含三部分：问题描述（一句话）、严重级别、规则标识。比如“函数体行数超过80行，当前92行 [警告] [function-length-check]”。修复建议放在规则文档里，评论里只给一个链接。这样评论短小精悍，开发者扫一眼就知道什么问题。

3. 规则集的设计与持续调优

3.1 从“什么都查”到“只查值得查的”

项目刚跑起来的时候，我恨不得把所有能想到的检查都加上。命名规范、代码格式、注释覆盖率、函数长度、圈复杂度、重复代码、魔法数字、空指针风险、资源未关闭、日志规范……林林总总列了四五十条规则。结果第一次跑真实项目，一个合并请求报了三百多个问题，开发者直接炸了，说这工具没法用。

我后来反思，问题出在“什么都查”的思路不对。自动化评审工具的价值在于过滤机械性问题，而不是制造噪音。如果一个规则报出来的问题，开发者大概率会忽略或者觉得无所谓，那这个规则就不应该默认开启。比如“注释覆盖率”这条规则，很多团队根本不要求每个函数都写注释，报了也是白报。

调整之后，我把规则分成了三组：核心组、推荐组、实验组。核心组是默认开启的，只包含那些“几乎所有人都认同应该修”的规则，比如语法错误、明显的空指针风险、资源泄漏、安全漏洞。推荐组是建议开启的，包含代码风格、复杂度相关的规则，团队可以根据自己的规范选择。实验组是默认关闭的，包含一些还在验证中的规则，比如“这个函数可能应该拆分”这种带有主观判断的。

这个分组策略效果很好。核心组规则数量控制在15条以内，一个典型的合并请求通常只会报出3到5个问题，开发者觉得有帮助而不是骚扰。推荐组由团队自行决定，我们团队后来开启了函数长度和圈复杂度两条，因为大家确实觉得长函数和复杂逻辑容易出问题。

3.2 误报处理：规则引擎最耗精力的部分

误报是规则引擎最大的敌人。一个规则如果误报率高，开发者很快就会失去信任，连带对整个工具产生抵触。我在实际运行中遇到最多的误报来自几个方面。

第一类是语法树解析的边界情况。比如检查“函数长度”时，匿名函数、Lambda表达式、内部类的方法，这些算不算独立函数？一开始我没区分，导致一个很长的Lambda被当成独立函数报了问题，但实际上它只是某个方法里的一小段逻辑。后来我在规则里加了过滤条件，只对具名方法做长度检查，匿名函数和Lambda跳过。

第二类是框架特有的写法。比如某些框架的依赖注入，字段看起来没有被赋值，但实际上框架会在运行时注入。如果规则检查“未使用的字段”，就会误报。这类问题没有通用解法，只能针对具体框架加白名单或者特殊处理。我的做法是在规则配置里加一个exclude_patterns字段，支持按注解、按继承关系、按导入包来排除。

第三类是差异块上下文不足导致的误判。比如检查“变量未使用”，如果变量在差异块之外被使用了，但差异块里只看到声明没看到使用，就会误报。这种情况需要拉取完整文件做分析，但完整文件分析又可能引入新的问题——比如文件太大导致分析超时。我的折中方案是，对于这类需要全局信息的规则，先做一次快速扫描，如果差异块内没有发现使用，再拉取完整文件确认。这样大部分情况不需要拉完整文件，性能可以接受。

误报处理是一个持续的过程。我建了一个误报记录表，每次开发者反馈误报，就记录下来，分析原因，然后决定是调整规则参数、加排除条件，还是干脆下线这条规则。运行三个月之后，核心组规则的误报率降到了5%以下，开发者基本不再抱怨了。

3.3 规则执行性能的优化实践

规则引擎的性能直接影响用户体验。如果检查要等半分钟才出结果，开发者早就切到别的页面去了。我一开始的实现比较粗暴，拿到差异内容后，对每个文件、每条规则依次执行，串行处理。一个中等规模的合并请求，大概要跑十几秒。虽然不算太慢，但还有优化空间。

第一个优化是缓存。很多规则需要解析语法树，而语法树解析是比较耗时的操作。如果同一个文件被多条规则检查，没必要重复解析。我在引擎里加了一个语法树缓存，以文件路径和文件内容哈希为键，解析结果缓存起来。这样多条规则共享同一棵语法树，解析次数从“规则数乘以文件数”降到了“文件数”。

第二个优化是规则分组执行。有些规则只需要看差异块，有些需要看完整文件。我把规则分成两组，先执行只需要差异块的规则，这些规则速度快，能快速给出初步结果。然后再执行需要完整文件的规则，这些规则慢一些，但数量少。这样即使完整文件分析还没完成，初步结果已经可以展示了。

第三个优化是增量检查。如果一个合并请求更新了，只检查变更的部分，而不是全量重新检查。代码托管平台的Webhook会带上本次更新的差异信息，我利用这个信息，只对新增的变更块执行规则，之前已经检查过且没有变化的块跳过。这个优化在合并请求频繁更新的场景下效果很明显，检查时间从十几秒降到了两三秒。

还有一个细节是超时控制。有些规则在极端情况下可能跑很久，比如检查一个几千行的文件。我给每条规则设了超时时间，默认5秒，超时就跳过并记录日志。这样避免一条规则卡住整个检查流程。

4. 部署运行与踩坑实录

4.1 服务部署方式的选择与配置要点

这个工具本身是一个HTTP服务，需要接收Webhook请求，同时要能访问代码托管平台的API。部署方式我试过两种：直接跑在物理机或虚拟机上，以及用容器编排。

物理机部署最简单，装好运行时环境，把服务启动起来，配一个反向代理处理HTTPS，然后在代码托管平台配置Webhook地址就行。适合小规模使用，维护成本低。但缺点是扩容麻烦，如果团队规模变大，合并请求量上去了，单机可能扛不住。

容器化部署更适合有一定规模的团队。我把服务打包成容器镜像，用编排工具管理。好处是扩容方便，副本数调一下就行；配置可以通过环境变量注入，不同环境用不同配置；日志收集和监控也更容易集成。缺点是初期搭建成本高一些，需要维护容器编排环境。

我最终选了容器化方案，因为团队本身就有容器编排环境，复用现有设施比较方便。配置方面有几个关键环境变量：代码托管平台的API地址和访问令牌、Webhook签名密钥、规则文件目录、日志级别、并行线程数。访问令牌的权限要控制好，只需要合并请求的读取和评论写入权限，不要给仓库的完整权限，避免安全风险。

Webhook签名验证是一个容易忽略的安全点。代码托管平台在发送Webhook请求时，通常会带一个签名头，用预共享密钥对请求体做哈希。服务端收到请求后，用同样的密钥和算法计算哈希，和签名头比对，不一致就拒绝。这一步能防止伪造请求。我一开始没做这个验证，后来安全审计的时候被指出来了，才补上。

4.2 实际运行中遇到的典型问题与排查过程

问题一：Webhook请求丢失。有开发者反馈提交了合并请求，但工具没反应。我去查日志，发现根本没有收到Webhook请求。排查下来发现是反向代理的配置问题——代理层对请求体大小有限制，而有些Webhook请求体比较大（包含完整的变更信息），超过了限制被直接拒绝了。调整代理配置，把请求体大小限制调大之后解决了。

问题二：评论重复发送。有时候同一个合并请求会收到多条汇总评论，而不是更新同一条。排查发现是并发问题——Webhook可能因为重试机制被重复发送，两个请求同时处理，都去创建了新评论。解决方案是加一个幂等键，用合并请求编号加提交哈希作为唯一标识，处理前先检查是否已经处理过，处理中则加锁。

问题三：规则执行超时导致检查不完整。有一个合并请求改了十几个文件，其中一个文件有三千多行，语法树解析花了十几秒，超过了单条规则5秒的超时限制，导致这个文件的所有规则都被跳过。后来我调整了策略：对于大文件，先做快速的行数判断，如果文件太大就只做基于正则的简单检查，跳过语法树分析。同时把超时时间改成可配置的，不同规则可以设不同的超时。

问题四：评论内容中的特殊字符导致格式错乱。代码里经常有反引号、星号、下划线这些Markdown特殊字符，直接放在评论里会把格式搞乱。比如变量名user_name会被渲染成斜体。解决方案是对评论内容做转义处理，把特殊字符用反斜杠转义，或者用代码块包裹。我选的是用行内代码块包裹变量名和代码片段，这样既清晰又不会格式错乱。

问题五：访问令牌过期导致评论发送失败。代码托管平台的访问令牌通常有有效期，过期后API调用会返回认证失败。我一开始没做令牌刷新，令牌过期后工具就静默失败了，开发者以为没问题，实际上评论根本没发出去。后来加了令牌有效期监控，快过期时自动刷新，同时如果API返回认证失败，会在日志里打错误并发送告警通知。

4.3 团队接受度与工作流融合的经验

工具做得再好，如果团队不用，也是白搭。我在推广这个工具的过程中，有几个体会比较深。

第一，不要一上来就强制。我一开始把核心组规则设成阻塞级别，结果开发者怨声载道，觉得被工具卡脖子。后来改成：第一个月只警告不阻塞，让大家先熟悉；第二个月开始，只有错误级别的问题阻塞，警告和建议不阻塞；第三个月才把部分核心规则升级为阻塞。这个渐进过程给了团队适应时间，抵触情绪小了很多。

第二，要让开发者能方便地反馈。我在汇总评论里加了一行提示：“如果认为某条规则误报，请回复本条评论并说明原因。”这样开发者有意见可以直接说，我定期收集这些反馈来调优规则。比让他们去提工单或者发邮件方便多了。

第三，规则要透明。每条规则在评论里都带规则标识，开发者可以点进去看规则说明，了解为什么会有这条规则、检查逻辑是什么。透明带来信任，如果规则藏着掖着，开发者会觉得是黑箱，不信任检查结果。

第四，和现有工作流融合。我们团队本来就有合并请求模板，要求填写变更说明和测试情况。我把自动检查的结果也整合到模板里，在合并请求页面直接显示检查状态。这样开发者不用切到别的页面就能看到检查结果，体验更顺畅。

5. 规则扩展与二次开发指南

5.1 自定义规则的编写方法与示例

内置规则不可能覆盖所有场景，团队需要能自己加规则。我把规则定义做成了插件式的，新增规则只需要在规则目录下放一个YAML文件，重启服务或者触发配置重载就能生效。

写一条自定义规则，首先要确定检查类型。目前支持三种：正则匹配、语法树查询、外部命令调用。正则匹配最简单，适合检查文本模式，比如“禁止使用System.out.println”。语法树查询适合需要理解代码结构的检查，比如“检查所有公开方法的参数个数”。外部命令调用适合集成已有的检查工具，比如把某个静态分析工具的输出解析成规则结果。

以“禁止使用System.out.println”为例，规则文件这样写：

rule_id: no-system-out-println description: "禁止在生产代码中使用System.out.println，请使用日志框架" severity: warning file_patterns: - "**/*.java" check_type: regex params: pattern: "System\\.out\\.println" exclude_patterns: - "**/test/**"

这条规则会对所有Java文件做正则匹配，发现System.out.println就报警告，但测试目录下的文件排除在外。exclude_patterns这个字段很实用，可以排除测试代码、生成代码、示例代码这些不需要严格检查的地方。

再举一个语法树查询的例子，检查“公开方法参数超过5个”：

rule_id: max-method-params description: "公开方法参数不应超过5个，过多参数建议封装成对象" severity: suggestion file_patterns: - "**/*.java" check_type: ast params: query: "method_declaration[modifier='public'][params.length > 5]" message: "方法 {method_name} 有 {param_count} 个参数，建议重构"

语法树查询的语法我设计得比较简单，支持按节点类型、修饰符、属性条件来筛选。{method_name}和{param_count}是占位符，执行时会被替换成实际值。这样评论内容可以动态生成，更具体。

外部命令调用的规则适合集成已有工具。比如团队已经在用某个代码格式化工具，可以写一条规则调用它，把格式化差异作为检查结果。配置里指定命令路径、参数模板、输出解析方式就行。这种方式的好处是复用现有工具链，不用重复造轮子。

5.2 规则优先级与冲突处理

当多条规则同时命中同一个位置时，需要决定怎么展示。我的处理原则是：错误级别优先于警告，警告优先于建议；同级别下，规则标识按字母序排列。这样保证重要的先展示，开发者不会漏掉关键问题。

但有时候规则之间会有冲突。比如一条规则说“函数不超过80行”，另一条规则说“函数必须包含完整的错误处理”，一个很长的函数可能同时触发这两条规则，但修复方向是矛盾的——拆函数可能让错误处理不完整，加错误处理可能让函数更长。这种情况我目前的做法是都展示，让开发者自己判断。因为工具没法理解业务上下文，强行合并或者抑制反而可能掩盖问题。

还有一种情况是规则重复。比如两条规则都在检查命名规范，只是检查的方面不同。这种情况我会在规则设计阶段就避免，确保每条规则的检查范围不重叠。如果发现重叠，就合并成一条规则，用多个检查条件来实现。

5.3 从单仓库到多仓库的配置管理

一开始这个工具只服务一个仓库，配置直接写在代码里。后来团队项目多了，需要服务多个仓库，配置管理就成了问题。不同仓库的规则集可能不一样，忽略列表也不一样，访问令牌也可能不同。

我的解决方案是引入“项目配置”的概念。每个仓库对应一个配置文件，包含该仓库的规则启用列表、忽略路径、严重级别覆盖、访问令牌引用等。服务启动时加载所有项目配置，Webhook请求进来后，根据仓库标识找到对应的配置，用该配置来执行检查。

配置文件的存储方式我选了对象存储，因为可以版本化，修改有记录，回滚也方便。配置更新后，通过一个管理接口触发重载，不需要重启服务。这样运维人员改配置不用找开发，自己就能操作。

多仓库还带来一个问题是资源隔离。如果某个仓库的合并请求特别多，可能会占用大量线程，影响其他仓库的检查。我加了一个简单的限流机制：每个仓库最多同时处理N个合并请求，超出的排队等待。N的值可以在项目配置里调整，默认是3。这样避免单个仓库把资源吃光。

6. 运行数据与效果复盘

工具跑了大概半年，积累了一些数据，可以拿出来说说实际效果。

从检查量来看，平均每天处理40到50个合并请求，每个请求平均涉及8个文件变更。规则引擎每天执行大约1200次规则检查，其中核心组规则占70%，推荐组占25%，实验组占5%。核心组规则平均每个合并请求报出2.3个问题，推荐组报出4.1个，实验组报出1.8个。

从问题类型分布来看，排在前几位的分别是：日志使用不规范（占18%）、空指针风险（占15%）、资源未关闭（占12%）、函数过长（占11%）、命名不规范（占9%）。这几类加起来占了65%，说明大部分问题确实集中在少数几个方面，规则集的设计方向是对的。

从修复率来看，错误级别的问题修复率最高，达到92%，因为会阻塞合并，不修没法继续。警告级别的问题修复率在60%左右，开发者会根据自己的判断决定是否处理。建议级别的问题修复率只有25%，大部分被忽略了。这个数据也验证了严重级别分级的必要性——如果所有问题都设成错误级别，开发者会被迫处理大量低价值问题，体验很差。

从时间节省来看，我粗略估算过，一个合并请求如果全靠人工评审，平均需要15到20分钟。引入自动检查后，人工评审时间降到了8到10分钟，因为机械性问题已经被过滤掉了，评审者只需要关注逻辑和设计。按每天40个合并请求算，每天节省的评审时间大概在4到5个小时，相当于半个多人天。对于十来个人的团队来说，这个收益还是很可观的。

当然也有做得不够好的地方。比如跨文件的依赖检查目前还比较弱，一个文件改了接口定义，另一个文件还在用旧接口，这种问题工具查不出来。还有业务逻辑层面的问题，比如边界条件处理、并发安全，这些需要理解业务上下文，自动化工具很难覆盖。所以这个工具始终是辅助，不能替代人工评审。

后续我打算在几个方向继续完善：一是增加跨文件分析能力，能追踪接口变更的影响范围；二是引入简单的机器学习模型，对历史评审评论做学习，自动识别哪些问题更可能被开发者接受，动态调整严重级别；三是支持更多代码托管平台，目前只对接了一个平台，通用性还不够。这些方向都还在探索阶段，有进展再分享。