从零搭建代码评审机器人：AST解析与规则引擎实战

1. 从零搭建代码评审机器人的真实动机代码评审这件事做过团队协作的人都有体会。一个人写完代码提交上去如果没人看问题就留到了测试甚至线上如果有人看评审者往往要花大量时间理解上下文来回沟通的成本比写代码本身还高。我所在的团队曾经统计过一组数据一个中等规模的迭代周期里评审者平均在每个合并请求上花费的时间是写代码时间的1.6倍其中超过一半的时间花在了“理解这段代码要干什么”而不是“判断这段代码写得对不对”上。这个痛点催生了一个想法能不能让机器先做一轮初筛把那些明显的问题——命名不规范、缺少边界判断、重复代码、潜在的空指针——先标出来让人只关注真正需要判断力的部分这就是我启动open-code-review这个项目的初衷。它不是一个要替代人类评审者的工具而是一个“预审员”把机械性的检查自动化把人的精力释放到架构合理性、业务逻辑正确性这些机器搞不定的地方。这个项目适合几类人参考一是团队里负责代码质量基础设施的工程师想给自己的仓库加一道自动化防线二是对静态分析和代码评审流程感兴趣、想自己动手做一个类似工具的开发者三是技术管理者想了解这类工具的能力边界避免对它抱有不切实际的期望。整篇文章我会从架构设计、核心检测逻辑、集成方式、误报处理、性能优化几个角度把我在这个项目里踩过的坑和总结的经验完整讲一遍。2. 整体架构为什么选择“规则引擎AST”而不是纯正则2.1 纯正则方案的天花板在哪里最开始我图省事想用正则表达式直接扫代码文本。比如检测“函数过长”就数一数两个function关键字之间的行数检测“魔法数字”就匹配所有独立的数字字面量。这个方案两天就写完了原型但一放到真实项目里就崩了。问题出在正则根本不理解代码结构。举几个我实际遇到的例子字符串里出现的if会被误判成条件语句注释里写的数字会被当成魔法数字跨行的函数调用链会让行数统计完全错位。更致命的是正则无法区分“这个变量是在当前作用域声明的”还是“从外部引入的”导致大量误报。我统计过纯正则方案在一个两万行的项目上跑出了四百多条告警人工筛完之后真正有价值的不到三十条误报率超过九成。这种工具没人会用因为信任成本太高了。2.2 AST 解析带来的结构性理解转向 AST抽象语法树之后情况完全变了。AST 把代码解析成一棵结构化的树每个节点都有明确的类型——函数声明、变量声明、条件分支、循环体、调用表达式。基于这棵树做检测判断“函数体有多少行”就是数一数函数节点下的子节点跨度判断“变量是否在使用前声明”就是遍历作用域链。准确性是正则方案没法比的。我选用的解析方案需要支持多语言因为团队里同时有 JavaScript、Python 和 Go 的仓库。这里有个关键决策是每种语言各写一套解析器还是找一个统一的中间表示我最终选择了前者原因是不同语言的语法差异太大强行统一抽象层反而会丢失语言特有的信息。比如 Python 的缩进语义、Go 的 goroutine 关键字这些在统一抽象里很难保留。所以架构上我设计了一个语言适配层每种语言实现同一套接口上层检测规则只跟接口打交道。2.3 规则引擎的分层设计整个系统分成三层。最底层是解析层负责把源码文件转成 AST并附带行列号、作用域等元信息。中间层是规则层每条规则是一个独立的检测单元输入是 AST 和文件上下文输出是若干条告警。最上层是报告层负责把告警去重、排序、格式化输出成评审评论或者命令行报告。规则层我做了个重要的设计规则之间不共享状态每条规则只读 AST不修改。这样做的好处是规则可以并行执行而且新增规则不会影响已有规则的行为。代价是有些跨规则的关联分析做不了比如“这个函数既太长又缺少注释”这种组合判断需要额外写一条独立规则来覆盖。实测下来这个取舍是值得的因为并行带来的速度提升非常明显。3. 核心检测规则的设计逻辑与实现细节3.1 命名规范检测为什么不能一刀切命名规范看起来简单实际上是最容易引发争议的规则。我一开始定了一套严格的命名规则——变量必须小驼峰、常量必须全大写下划线、类名必须大驼峰——结果团队里怨声载道。有人习惯用下划线分隔的变量名有人觉得缩写词应该全大写。后来我意识到命名规范的本质不是“哪种风格更好”而是“同一个项目里保持一致”。所以我把命名检测改成了可配置的一致性检查。工具会先扫描整个项目统计各种命名风格的使用频率然后找出那些“少数派”——比如项目里百分之九十的变量用小驼峰某个文件里突然出现几个下划线命名的变量这些就会被标记出来。这样检测的不是“你违反了某条规定”而是“你和周围不一致”接受度高了很多。配置上我提供了naming.convention参数可以指定基准风格也可以设为auto让它自动推断。3.2 复杂度检测圈复杂度的计算与阈值选择圈复杂度是衡量代码逻辑复杂程度的核心指标计算方式是统计函数内独立路径的数量。具体来说每个if、else if、case、、||、?都会让复杂度加一基础值为一。我在实现时严格按这个定义来遍历 AST 节点时对每种分支节点计数。阈值的选择是个经验活。业界常见的建议是单函数复杂度不超过十但我实测下来这个值偏严。一个包含五六个if-else分支的业务函数很容易就到十了但它未必难维护。我最终把默认阈值定在十五同时提供了分级告警复杂度十五到二十是“建议关注”二十到三十是“建议重构”超过三十是“强烈建议拆分”。这样评审者可以根据告警级别决定投入多少精力。另外我还加了一个嵌套深度的独立检测因为深层嵌套比单纯的分支数量更影响可读性。嵌套超过四层的函数会被单独标记。3.3 重复代码识别基于语法树的相似度比对重复代码检测是最有技术含量的部分。简单的文本比对会把格式不同但逻辑相同的代码漏掉比如一个用for循环写的求和和一个用while循环写的求和文本上完全不同但逻辑上高度相似。我的做法是把 AST 序列化成一种规范化的字符串——去掉变量名、去掉注释、统一格式——然后对序列化结果做相似度比对。相似度算法我用的是编辑距离的变体但做了性能优化。全量两两比对在大型项目上会爆炸所以我先用哈希做粗筛把每个函数的规范化 AST 切成固定大小的片段计算片段哈希只有哈希重合度超过阈值的函数对才进入精细比对。这个两阶段策略把比对耗时从几十分钟压到了几分钟。阈值方面相似度超过百分之八十五的标记为“疑似重复”超过百分之九十五的标记为“高度重复”。实测中百分之八十五这个线会有些误报比如两个简单的 getter 函数天然相似所以我加了一条豁免规则函数体少于五行的不参与重复检测。3.4 边界与空值检查静态推断的能与不能空指针和数组越界是运行时最常见的崩溃原因。静态检测这类问题的难点在于很多情况下变量的值在编译期无法确定。我的策略是只检测高置信度的场景宁可漏报也不误报。具体来说以下几种情况会被标记函数参数没有做空值判断就直接调用方法数组访问的索引来自一个没有上界检查的循环变量可选链操作符后面直接跟了非可选的属性访问。这里有个重要的经验不要试图做全程序的空值流分析。我试过实现一个简单的数据流分析来追踪变量的空值状态结果复杂度失控而且跨函数的分析需要构建调用图工程量远超预期。最终我退回到“局部模式匹配”的方案——只在单个函数体内做有限的推断跨函数的一律不报。这样虽然漏报多了但每一条报出来的都是真问题用户信任度反而更高。4. 与代码托管平台的集成方式与踩坑记录4.1 Webhook 触发与增量分析工具要真正用起来必须集成到代码提交流程里。我的方案是通过 Webhook 监听合并请求的创建和更新事件触发分析。这里第一个坑是全量分析太慢。一个十万行的仓库全量跑一遍要十几分钟评审者等不了。所以必须做增量分析——只分析本次变更涉及的文件和函数。增量分析的实现依赖差异比对。我拿到合并请求的 diff 之后解析出变更的行号范围然后把这些行号映射到 AST 节点上。只有与变更行有交集的函数才会进入检测流程。这里有个细节如果一个函数被修改了即使修改只有一行整个函数也要重新检测因为复杂度、重复度这些指标是函数级别的。映射逻辑我写了个专门的模块处理各种边界情况比如变更发生在函数签名上、变更跨越多个函数等。4.2 评论发布的去重与更新策略分析结果要以评论的形式发到合并请求上。这里遇到的坑是重复评论。每次提交更新都会触发分析如果每次都发新评论页面上很快就会堆满重复内容。我的解决方案是给每条告警生成一个稳定的指纹——基于文件路径、规则名称、代码片段的哈希——然后在发布前查询已有评论相同指纹的评论做更新而不是新建。另一个坑是评论定位。代码托管平台的评论 API 通常要求指定文件路径和行号但行号在 diff 里和在完整文件里是不一样的。我踩过一次坑把 diff 里的行号直接当成文件行号传过去结果评论全部错位。正确的做法是解析 diff 的 hunk 头信息把 diff 行号映射回文件行号。这个映射逻辑我封装成了一个独立函数处理了新增行、删除行、上下文行三种情况。4.3 大仓库下的性能瓶颈与优化在超大仓库上跑性能问题会集中爆发。我遇到过的瓶颈有三个。第一个是文件读取逐个文件读太慢改成批量读取加缓存后好了很多。第二个是AST 解析这是最耗时的环节我的优化是只解析变更涉及的文件而且解析结果按文件哈希缓存文件没变就不重新解析。第三个是规则执行前面提到的并行执行在这里发挥作用我把规则分成若干组用工作池并发跑实测在八核机器上能有三到四倍的加速。还有一个容易被忽略的点是内存占用。AST 对象很占内存一个大型文件解析出来的树可能有几十万个节点。如果同时缓存太多文件的 AST内存会爆。我的做法是设置一个缓存上限超过之后按最近最少使用策略淘汰。这个上限我设的是五百个文件实测在十六 G 内存的机器上比较安全。5. 误报治理让工具从“烦人”变成“有用”5.1 误报是工具死亡的第一原因我见过太多内部工具因为误报太多被弃用。开发者被无关紧要的告警打扰几次之后就会形成“这个工具报的东西不用看”的心理定势然后所有告警都被忽略包括那些真正重要的。所以误报治理不是锦上添花而是生死攸关的事。我的策略是分级加抑制。分级前面提过把告警分成建议、警告、严重三档默认只把严重档发成评论其他档只在命令行报告里展示。抑制则是提供多种忽略机制可以按规则忽略、按文件忽略、按代码行忽略。忽略配置写在项目根目录的一个配置文件里跟代码一起版本管理这样团队可以共同维护。5.2 基于历史反馈的规则调优光靠人工配置抑制还不够我加了一个反馈学习机制。评审者可以对每条告警标记“有用”或“无用”这些标记会被记录下来。工具定期统计每条规则的有用率有用率低于某个阈值的规则会被自动降级或者建议关闭。这个机制运行了几个月之后我发现有几条我原本觉得很有价值的规则实际有用率很低比如“函数参数过多”这条因为很多框架的回调函数天然就是多参数的标记出来也没法改。这条规则后来被我默认关闭了。5.3 上下文感知减少噪音很多误报源于工具不理解上下文。比如“魔法数字”检测在业务代码里标记if (status 3)是合理的但在测试代码里标记expect(result).toBe(3)就是噪音。我的做法是引入文件类型感知测试文件、配置文件、生成的代码文件走不同的规则集。测试文件放宽魔法数字和重复代码检测配置文件完全跳过复杂度检测。这个改动让整体误报率下降了大约四成。6. 规则扩展机制让团队自己写检测规则6.1 规则接口的设计一个工具不可能覆盖所有团队的特定需求。有的团队可能想检测“所有数据库查询必须带分页参数”有的团队想检测“日志里不能出现用户敏感信息”。这些规则太具体内置不现实所以必须提供扩展机制。我的规则接口设计得很简单一个规则就是一个函数接收 AST 节点和上下文对象返回告警数组。上下文对象里包含文件路径、语言类型、配置参数等信息。规则用 JavaScript 编写放在项目的一个特定目录下工具启动时自动加载。这样团队里任何会写 JavaScript 的人都能贡献规则不需要了解工具的内部实现。6.2 规则测试与调试支持写规则最怕的是写完不知道对不对。我提供了一个规则测试框架给规则写测试用例输入一段代码断言应该产生哪些告警。测试用例用 YAML 描述跟规则放在一起。工具跑测试的时候会解析这些用例执行规则比对实际输出和预期输出。这个框架让规则的迭代变得很安全改完规则跑一遍测试就知道有没有破坏已有行为。调试方面我加了个--debug-rule参数指定某条规则后工具会打印出这条规则遍历过的所有 AST 节点和判断结果。这个功能在排查“为什么这条规则没报出来”的时候特别有用。我印象很深的一次是某条规则在本地跑得好好的在 CI 上却不报最后用调试模式发现是 CI 环境的文件编码跟本地不一样导致解析出来的 AST 有细微差异。6.3 规则市场的可能性与边界我考虑过做一个规则共享市场让不同团队交换规则。但仔细想了想这个方向有个根本问题规则的适用性高度依赖技术栈和团队习惯。一个适合某团队的“接口命名规范”规则换个团队可能就是纯噪音。所以最终我没有做市场而是把重点放在降低写规则的门槛上。现在写一条新规则从构思到测试通过熟练的话半小时就能搞定这个成本已经足够低了。7. 实际部署中的运维经验7.1 分析服务的资源规划如果要把这个工具做成常驻服务资源规划很重要。我的经验是CPU 是主要瓶颈内存次之磁盘基本不是问题。解析和规则执行都是计算密集型任务一个中等规模的合并请求分析大概需要两到四核 CPU 跑十几秒。内存方面前面提过 AST 缓存是主要消耗建议按每百个并发分析预留两 G 内存来规划。磁盘主要是日志和缓存增长很慢。我建议用容器化部署每个分析任务跑在独立的容器里跑完就销毁。这样做的好处是资源隔离一个任务的内存泄漏不会影响其他任务。缺点是容器启动有开销不过对于分钟级的分析任务来说几秒的启动时间可以接受。7.2 分析结果的持久化与趋势追踪光看单次分析结果还不够团队还需要看趋势——代码质量是在变好还是变差。所以我把每次分析的结果存进了数据库记录时间戳、仓库、告警数量和分布。基于这些数据可以画出趋势图比如“最近三十天严重告警数量的变化”。这个功能对技术管理者特别有用能直观看到质量改进措施有没有效果。存储方面我用的是轻量级的嵌入式数据库单机就能跑不需要额外部署数据库服务。数据量方面一个活跃仓库每天产生几百条记录一年也就十几万条完全在嵌入式数据库的处理能力范围内。7.3 与持续集成流水线的衔接最后一步是跟 CI 流水线打通。我的做法是在流水线里加一个步骤调用分析工具的命令行接口根据返回的退出码决定是否阻断合并。退出码的规则可以配置比如严重告警超过零条就阻断或者警告以上超过十条才阻断。这个阈值需要根据团队的实际承受能力来调太严了会拖慢交付节奏太松了又起不到作用。我踩过的一个坑是超时设置。分析任务偶尔会因为大文件或者复杂规则跑很久如果 CI 步骤没有设超时整个流水线会被卡住。后来我加了硬性超时默认五分钟超时后返回一个特殊退出码流水线继续往下走但会发一条提醒。这样既不会卡住交付又能让团队知道有分析任务没跑完。8. 我在这个项目里学到的最重要的几件事做这个项目一年多最大的体会是工具的价值不在于它能检测多少问题而在于它报出来的问题有多少人愿意改。我早期追求规则的覆盖面和检测的严格程度结果做出来的东西没人用。后来把重心转到误报治理和体验优化上使用率才慢慢起来。第二个体会是增量思维。不管是分析范围还是功能迭代都不要想着一步到位。先做最小可用的版本让团队用起来根据反馈再逐步加规则、加功能。我第一版只做了三条规则但因为在真实流程里跑起来了收集到了大量有价值的反馈后续的迭代方向都很明确。第三个体会是关于配置的哲学。工具应该提供合理的默认值让用户开箱即用同时保留足够的配置空间给有需要的团队。默认值的选择需要大量实测数据支撑不能拍脑袋。我为了定圈复杂度的默认阈值在十几个不同规模的项目上跑了统计最后才定在十五这个值。这个工作很枯燥但值得。如果让我给想做一个类似工具的同行一句建议那就是先想清楚你要解决的是谁的什么问题然后确保你的工具在解决这个问题时不会制造新的问题。代码评审工具制造的新问题就是噪音和打扰把这个问题解决好工具就成功了一大半。