自研代码审查辅助工具：从规则引擎到私有化部署的工程实践

我团队维护的代码库持续膨胀之后每周的 PR 评审积压量开始成倍增加。与其继续靠人海战术熬夜重审我们决定做一个内部代号为 open-code-review 的代码审查辅助服务用自动化手段把高重复性的检查工作前置。这套东西说穿了不复杂但对团队提效非常明显这篇文章把从设计到落地的完整过程摊开讲清楚包括核心架构、规则引擎、部署接入以及上线后踩过的两个大坑。1. 为什么团队需要一个自研代码审查工具1.1 从一次漏网之鱼说起我们线上有一个支付相关的老服务代码量中等但改动频繁。某个周五下午一位同事提了一个很小的 PR给 Redis 连接池加一个自定义超时参数。改动本身只有三四行reviewer 看得很认真也确实把正确性、兼容性都过了一遍但还是让一个隐藏问题漏过去了——异常分支里没有把连接归还回连接池。这个 bug 在周一的线上流量高峰时被触发排查了大半天才定位。那次复盘最扎心的不是 bug 本身而是我们发现这段代码的错误模式是完全可以被自动识别出来的。它属于典型的资源获取后未释放模式如果有一双机器眼睛能盯住这类模式reviewer 就能把精力全部留给真正需要人脑判断的架构和业务逻辑问题。当天我们内部开始讨论能不能自己造一个轻量的代码审查辅助工具把这些高重复、低智力含量的检查固化下来。这里要说明open-code-review 这个名字当时是在内部仓库里随便起的代号后来用顺了就没改。它的定位不是要取代 code review而是给 review 过程装一个过滤器。这篇文章面向的读者是那些正在被 PR 积压、review 漏检、规范反复讲解所困扰的研发团队尤其是对代码数据私有化有要求、且愿意投入少量开发资源做基建的团队。1.2 现有流程的四个痛点在动手之前我们先认真盘点了一下现有 review 流程里的痛点因为如果痛点不清晰后面做出来的工具一定是四不像。第一个痛点是注意力漂移。一个认真的 reviewer 连续看五个 PR 之后对第六个 PR 的敏感度明显下降常见的错误类型容易漏看。机器没有注意力周期它可以对每一次 PR 都保持同样的检查密度。第二个痛点是高重复劳动。我们团队有内部约定禁止使用可变默认参数、禁止裸except、日志不能直接打印敏感字段、TODO 必须带工单号。这类规则是确定的、可枚举的但每次都要靠人工在字里行间去找效率低而且常漏。第三个痛点是反馈链路太长。人工 review 通常要等 CI 跑完、等人安排时间。一个风格问题可能要来回两个循环才能消掉一个 PR 花在等待上的时间往往比实际审查时间多好几倍。第四个痛点是经验沉淀为零。老同事在 review 时发现的很多坑最后只存在于即时聊天记录里新同事完全接触不到。等到老同事休假同样的坑会以新的形式再次出现。这四个痛点决定了我们的工具边界它不需要理解复杂的业务意图只需要可靠地识别可枚举的坏模式并把识别结果以最自然的方式嵌入现有 review 流程。1.3 给自研一个明确边界在立项讨论时我们内部其实吵过一轮有人觉得应该做成一个能自动修代码的工具有人觉得应该做成一个 CI 门禁。最后我们把边界收得比较窄——open-code-review 只做三类事第一在 PR 提交时自动扫描变更范围跑一组可配置的规则第二把命中行以 inline comment 的形式回写到 PR 上同时在 GitHub Actions 的 Check 面板里给出一个明确的结论第三把每一轮的扫描记录和规则命中情况落到数据库里方便统计和回溯。不做自动修复、不直接合并 PR、不给人下结论。这个边界很重要它避免了我们陷入系统的判断是不是比人更权威这种争论。机器只负责提醒人永远拥有最终的决定权。边界清晰的另一个好处是每个阶段的交付物都可验证、可回退后面推进起来阻力会小很多。2. open-code-review 的整体架构与设计取舍2.1 架构总览与技术选型整体架构是一个典型的异步任务处理模型。服务端用了 Python 3.11 FastAPI任务队列是 Redis Celery持久层选的是 PostgreSQL。选择这套组合的理由很实际Python 的 AST 生态在同类语言里最成熟标准库自带ast模块可以解析 Python 代码tree-sitter 的 Python 绑定也能丝滑集成我们第一批规则全部聚焦在 Python 代码库这个语境下没有比 Python 更顺手的工具。FastAPI 接 GitHub webhook 非常轻量Celery 处理需要异步完成的扫描任务也很省心。整个处理链路是这样的GitHub 的pull_request事件通过 webhook 推送到 FastAPI 网关网关校验签名后立刻返回 200同时把事件转发到 Redis 队列。工作 worker 从队列里拿到任务后先通过 GitHub API 拉取这个 PR 的变更文件列表和统一 diff然后按文件类型做解析逐个应用规则最后把结果汇总起来——内联评论走 review comments API门禁结论走 checks API两者各写一份到 PostgreSQL。pull_request webhook ↓ FastAPI 网关验签、幂等 ↓ Redis 任务队列 ↓ Celery Worker拉 diff → 解析 AST → 执行规则 → 汇总 ↓ GitHub API内联评论 Check 结论 / PostgreSQL落库选型时也考虑过 Go但最后还是放弃了。原因是规则引擎需要大量操作语法树Python 的 AST 节点类型和遍历方式最直观团队同事也更熟悉 Python与其为了一点性能优势放弃生态优势不如先把功能跑通。事实上在我们这种单次扫描 30 秒以内的场景里Python 的性能完全不是瓶颈。2.2 关键设计取舍有几个设计决策值得展开讲因为它们直接影响了后面所有的使用体验。同步响应 异步执行。webhook 接口必须在 3 秒内返回否则 GitHub 会判定超时并自动重试。我们把请求处理和真正扫描完全解耦收到事件先落一条 review_runs 记录状态是 pending然后立即返回worker 扫描完成后通过 Check API 把状态更新为 completed。这样既不会把扫描时间压得太短也天然获得了重试能力和消息缓冲。内联评论为主、汇总报告为辅。我们默认是给命中行打内联评论因为 review 时上下文最自然的就是在对应代码行旁边看到问题提示。但内联评论刷屏严重的话会很烦所以我们在配置里加了一个 summary 模式把一批低优先级的问题合并成一条总结评论。这个切换是仓库级别的很多仓库跑了一段时间后都会切到 summary 模式只有高优先级规则保持内联。仓库级配置覆盖全局。工具支持一个全局默认配置文件也允许每个仓库放一份.open-code-review.yaml。仓库配置文件里的规则开关和参数会合并覆盖全局配置。这个设计让单个团队可以按自己的技术债情况渐进式落地而不是一上来就要全公司统一规范。门禁做成软门禁。我们最开始想过让工具在发现问题时直接让 PR 合并按钮变红但这个想法很快就放弃了。规则误报和规则本身的 bug 都会导致开发被无意义阻塞一旦出现几次工具卡了我半天结果是误报的情况团队对工具的信任就崩了。所以我们的设计是error 级别默认阻塞warn 和 info 只提醒不阻塞并且仓库可以配置开启或关闭阻塞。2.3 数据模型设计数据模型不复杂但每个表都有存在理由。repositories 表存仓库元数据包括仓库名、默认分支、启用的规则集、门禁配置。pull_requests 表存每个 PR 的基本信息包括作者、基础分支、目标分支、当前 head SHA。review_runs 表是整个系统的主干一次 webhook 触发对应一条 runrun 的状态从 pending 到 running 到 completed一个 PR 可能有多次 run因为每次 push 新 commit 都会生成新的 run。findings 表存每次 run 里命中的每一条问题记录包括文件路径、行号、规则 ID、严重级别、修复建议。rules 表是我们本地维护的规则注册表记录每个规则的名字、描述、适用语言、默认开关状态。review_runs - id : uuid - repo_id : bigint FK - repositories - pr_id : bigint FK - pull_requests - head_sha : char(40) - status : pending / running / completed - conclusion : success / failure / neutral - started_at : timestamptz - finished_at : timestamptzfindings 表的结构同样简单最关键的字段是 position——GitHub diff 里的行号位置。后面写内联评论时需要把文件行号映射成 diff position这个映射细节在第三部分展开。另外我们一开始忘记在 findings 表上给 head_sha 建索引PR 更新一频繁历史 run 的统计查询直接把数据库拖慢了。这个表的查询模式非常固定建一个 (repo_id, head_sha) 联合索引就能解决 90% 的性能问题。3. 核心模块拆解从提交到结论的完整链路3.1 触发与数据采集open-code-review 依赖 webhook但并不是所有pull_request事件都需要响应。我们过滤了 action 类型只在opened和synchronize时触发closed、reopened、labeled这些事件不触发主流程。synchronize对应的是 PR 分支有新 push这是最频繁的触发源也是造成重复评论的源头。拿到事件后第一步是从 GitHub 拉取 PR 的完整元数据。这里有个容易忽略的点webhook payload 里自带的 pull_request 对象字段并不完整特别是 files 列表需要额外调用接口拉取。我们通过 GraphQL 接口一次性拿到 files、commits、reviews 三个维度的数据比 REST 接口一个文件一个文件地拉高效很多。随后把每个文件的 patch 字段按文件路径拆开后续解析只针对 patch 里出现的代码片段。这里就引出一个核心问题扫描范围是整仓还是变更范围我们坚定选择变更范围diff 驱动。整仓扫描虽然能发现更多历史问题但会产生大量和本次 PR 无关的噪音评论而且扫描时间会随仓库规模线性增长。变更范围扫描既符合 review 的上下文又能控制单次运行的时间在 1 分钟以内。对历史债务的清理我们后续专门用定时任务做了全量扫描但那是一套独立流程和 PR 触发的主链路完全分开。3.2 规则引擎与静态分析器规则引擎是工具的心脏。为了降低规则编写门槛我们没有搞复杂的 DSL而是直接用 Python 函数作为规则载体每一条规则就是一个独立的注册函数。函数签名统一rule( rule_idPY001, target_langpython, severityerror, description函数定义时不该使用可变默认参数, ) def check_mutable_default_arg(file_ast, diff_context, config): findings [] for node in ast.walk(file_ast): if isinstance(node, ast.FunctionDef): for default in node.args.defaults: if isinstance(default, (ast.List, ast.Dict, ast.Set)): findings.append({ line: node.lineno, message: 可变默认参数易导致跨调用共享状态建议改用 None 哨兵值, }) return findings每个规则接收三样东西AST、diff 上下文、仓库配置。返回一个 findings 列表。框架负责把 findings 里的行号映射到 diff position并按严重级别决定评论方式。规则从实现机制上分三类。第一类是纯 AST 规则适合检查结构性问题比如导入顺序、废弃 API 调用、可变默认参数、重复的 except 分支。第二类是正则规则适合检查命名风格、魔法数字、TODO 标记这些局部文本问题。第三类是交互式规则需要调用外部命令或者读取仓库元数据比如检查依赖锁文件里是否有已知的高危版本或者检查是否存在绕过 review 的强制推送记录。设计这套规则接口时我特别强调了一个原则规则必须是无副作用的纯函数。不允许规则直接去调用 GitHub API不允许规则修改文件不允许规则依赖全局状态。这个原则保证了规则的执行顺序无关、可重复执行也为后面做规则的单元测试和并行执行铺平了路。规则库单独维护每次新增规则都要求附带一个最小的正例和负例测试用例合入规则库的 PR 同样要过 review。3.3 评论与门禁策略评论环节最容易出问题的地方是行号映射。GitHub 的 inline review comment 用的是 diff 里的 position 字段而不是文件的真实行号。GitHub REST API 接收的是以 patch 行为基准的位置新加的代码行对应 patch 里的 hunk 行号。从 AST 拿到的 node.lineno 是文件里的绝对行号必须通过 diff 的 hunk 信息做一次映射把绝对行号换算成 diff position。映射逻辑不复杂解析每个文件的 patch把 hunk header如 -12,6 12,8 里的新旧行号区间记下来然后对新文件里每一行判断它是否落在某个新增 hunk 区间内如果是就根据 hunk 内的偏移算出 position。如果 AST 命中的行恰好是未修改的上下文行就没有对应的 diff position这时候我们会降级处理——把评论挂到该 hunk 的第一行新增位置上去或者干脆放到 summary 报告里。门禁策略我们用了一个配置矩阵规则严重级别是 error、warn、info策略是 block_review、notify_only 或 off。error block_review 的组合是默认阻塞门禁会通过 Checks API 把 check run 的 conclusion 置为 failure从而阻止合并。其余组合只写 comment不影响合并。严重级别阻塞开关默认评论方式errorblock_review开内联warnnotify_only关内联/汇总infonotify_only关汇总这套矩阵的好处是直观仓库 Owner 一眼能看懂改配置时不容易出歧义。4. 本地部署与配置实战4.1 环境准备与最小部署部署本身不复杂我们团队内部是直接用 Docker Compose 起的四个服务webhook 网关、worker、Redis、PostgreSQL。本地复现的最小配置如下services: gate: image: open-code-review:latest ports: [8080:8080] environment: GITHUB_TOKEN: ${GITHUB_TOKEN} DATABASE_URL: postgresql://ocr:ocrdb/ocr REDIS_URL: redis://redis:6379/0 WEBHOOK_SECRET: ${WEBHOOK_SECRET} depends_on: [db, redis] worker: image: open-code-review:latest command: [celery, -A, app.tasks, worker, --concurrency4] environment: GITHUB_TOKEN: ${GITHUB_TOKEN} DATABASE_URL: postgresql://ocr:ocrdb/ocr REDIS_URL: redis://redis:6379/0 db: image: postgres:16 environment: POSTGRES_USER: ocr POSTGRES_PASSWORD: ocr POSTGRES_DB: ocr redis: image: redis:7-alpineGITHUB_TOKEN 是必须的环境变量没有它服务连 GitHub API 都调不通。WEBHOOK_SECRET 是 webhook 验签的共享密钥部署的时候一定要随机生成不要用默认值。首次启动后先去数据库里执行迁移脚本把表结构建好然后跑一次健康检查接口确认服务本身没有启动失败之后才能开始接 webhook。4.2 配置项逐项说明仓库根目录放一份.open-code-review.yaml下面这份配置覆盖了我们在多数仓库里的惯用设置version: 1 rulesets: python: enabled: true severities: PY001: error PY002: warn PY003: off javascript: enabled: false paths: skip: - **/generated/** - **/vendor/** - **/*.pb.go review: mode: inline max_inline_comments: 20 summary_group: warn, info gate: block_on: [error] allow_bot_author: false几个关键配置的解释rulesets 段是按语言启停规则集合目前只启用了 Python 和少数 JavaScript 语法检查因为规则引擎的 AST 解析器主要围绕 tree-sitter 的 python、typescript grammar 在写。severities 覆盖了规则默认级别仓库可以根据自己的容忍度把某条规则降级或关闭。paths.skip 是全局忽略路径的匹配规则处理自动生成代码、vendor 目录这类不该扫的地方。review.max_inline_comments 是防刷屏的保险丝一个 PR 内联评论超过 20 条后后续问题自动切成汇总评论。gate.block_on 是阻塞级别列表error 级别的命中会直接让 check 结论置为 failure。提示paths.skip 的匹配模式用的是 gitignore 风格的 glob 规则而不是正则。写/generated/和写**/generated/**的效果完全不一样前者只匹配仓库根目录下的 generated后者匹配任意层级的 generated。我们第一次部署时就因为写错匹配规则导致 proto 生成的目录被反复扫描整个 PR 评论刷了几百条。4.3 与代码托管平台的集成代码托管平台这边要配置三样东西webhook、token 权限、Check 上报。webhook 在仓库的 Settings - Webhooks 里添加Payload URL 指向 open-code-review 的/webhook/github路径Content type 选 application/jsonSecret 填 WEBHOOK_SECRET 对应的值事件类型勾选 Let me select individual events 里的 Pull requests 即可其他事件都不需要。token 权限是我们踩过坑的地方。最开始我们用的是 Fine-grained personal access token但只勾了 Pull requests 的读权限结果内联评论写不上去报 422。后来把权限升级到 Pull requests: Read and write 才解决。如果用 GitHub App 方式集成则需要给 App 申请 Pull requests: Read and write 和 Checks: Read and write 两种权限。Check 上报走的是 Checks API主要用来把工具的运行状态显示在 PR 的 checks 面板里开始扫描时创建一个 check run状态为 in_progress扫描完成后把 conclusion 更新为 success没问题或 failure有 error 级命中。这样开发者在 PR 页面就能看到 open-code-review 的状态而不需要跳出 GitHub 去查日志。5. 接入团队工作流后的实测数据与坑位记录5.1 六周试运行的结果接入团队工作流之后我们记录了一个六周的小样本数据虽然没有严格的对照实验但趋势能说明问题。合并前被自动捕获的问题数量是 47 个其中真正会被合并进主干的问题占了一大半。这里面有 9 个是资源未释放类问题是我们最看重的一类有 11 个是敏感信息泄漏类比如日志里打印了完整手机号或身份证号其余的多是风格一致性、废弃 API 使用这类相对低危的问题。单看绝对数量不大但结合平均评审时长来看更有意义工具上线后一个普通 PR 的平均评审时长从 1.8 小时降到了 1.2 小时左右降幅不是特别夸张但积压的 PR 数量明显减少了。还观察到一个间接收益新同事的 PR 第一轮被怼的评论数量少了很多。因为很多基础问题在提交时就被自动评论指出来了他们自己改完再提交human reviewer 看到的代码已经比较干净带新人的挫败感也随之下降。5.2 踩坑排查链路一误报潮与规则阈值调优第一个大坑是上线第二周出现的误报潮。现象是某个仓库的 PR 上突然多了大量看起来完全不合理的内联评论比如把正常的列表推导式判成逻辑复杂度过高把合法的 with 语句标成资源未释放。我们没有直接去改规则代码而是先复现。具体做法是本地起一个临时环境把那个仓库的最新 PR 拉下来逐个规则单独跑输出命中行号和 AST 片段。跑了一轮发现所有异常命中都集中在那条资源未释放规则上。再深挖这个规则最初是靠判断 with 语句的上下文来推理资源生命周期的但它只识别了 with 语句是否出现却没有判断 with 语句里是否明确调用了资源的 close 或 release 方法。一些第三方库的上下文管理器语义本身就不一样比如有的库的 with 只是创建临时会话并不持有底层连接把它判成资源未释放就是误报。修复方案分三层第一层是调整规则本身增加对上下文管理器是否返回资源对象的类型判断第二层是在规则配置里增加 allowlist允许仓库把特定第三方模块干脆排除出去第三层是给规则增加 confidence 字段低置信度的规则最多打 warn不允许直接配成 error。这三层下来误报率从最初的接近 40% 降到了 5% 左右。我们后来也形成了规矩任何新规则上线前必须先拿至少 20 个历史 PR 做回放验证命中率低于 80% 的规则不允许默认开启。5.3 踩坑排查链路二并发触发导致的服务抖动第二个坑是性能问题。某个周一早上同事集中合并了一批 PR每个 PR 又都带了好几次 pushwebhook 像瀑布一样灌进来。我们的 worker 并发数是 4每个任务又要拉文件、解析 AST、跑规则还要调 GitHub API 写评论。几分钟后GitHub API 的 rate limit 被打满了所有 worker 的 API 调用开始报 403大量评论和 Check 上报失败。排查链路很清楚先看日志发现错误码清一色是 403再看指标GitHub API 的剩余配额直接被烧到了 0而且在请求日志里看到同一秒内发起了远超平时峰值的并发请求。根因有两个一是 webhook 进来时没有做 token 层面和单仓库层面的限流单个仓库的 burst 直接消耗掉了整个账号的配额二是 Check API 的创建操作发生在所有扫描完成之后失败重试时的退避策略又太激进把剩下的配额也打光了。修复方案是组合拳。入口侧加了一个基于 Redis 的令牌桶按仓库维度限流单仓库同时只允许 2 个扫描任务超出的任务排队等待API 调用侧做了一个全局限流器所有 GitHub API 调用统一走这个限流器rate limit 余量低于阈值时自动触发背压让 worker 先歇一歇重试策略改成指数退避加抖动。改完之后并发高峰期再也没有打满过配额。教训集成类工具最容易出问题的不是主流程而是对上游 API 资源配额的管理。任何需要调用外部 API 的服务上线前一定要把限流、配额、退避三件事想清楚否则一波流量就能让工具变成负面资产。6. 对比现成方案为什么我们没有直接用现成工具6.1 现成工具的能力边界很多朋友会问市面上现成的代码审查工具一抓一大把SonarQube、CodeQL、Reviewdog、Codacy、DeepSource为什么还要自己造轮子这个问题我们在立项时也认真调研过结论是现成工具各有各的能力边界。工具定位主要成本不适合我们的原因SonarQube全量代码质量平台服务端维护重、规则定制要走插件几十个仓库的团队运维成本偏高CodeQL语义级漏洞挖掘QL 语言学习曲线陡文科团队用它属于大材小用Reviewdoglinter 输出转 review 评论本身不提供规则还需要自己配置维护 linter商业 SaaS开箱即用代码数据出网私有化部署需求无法满足坦白说如果团队用的语言生态已经很成熟比如 Java 配 SonarQube、前端配一套 ESLint Reviewdog现成方案完全够用。我们选择自研是因为团队主力语言是 PythonPython 的静态分析生态相对分散没有一个开箱即用、又能完全私有化部署的轻量方案同时我们对规则的可控性和扩展性要求比较高。6.2 自研的成本账自研的成本账一定要算清楚否则容易做出一个维护成本远高于收益的玩具。我说一下我们这边的实际数字给想动手的团队一个参考。开发成本两个人三周时间从零到第一个可用版本。第一批规则覆盖了大约 18 条全部聚焦在 Python 代码的高频问题上。这个成本不低但考虑到后面省下的都是每次 PR 反复出现的时间两周多的开发投入在半年内就回收了。维护成本每月大概 4 到 8 个小时主要是规则库的迭代升级。新语言支持会带来一次性的较大投入我们目前还没做但用 tree-sitter 接新语言的成本比从头写解析器低得多预计一周左右能接一门新语言。隐性收益配置完全自主任何团队规则可以在半小时内变成一条自动规则数据全部留在公司内部不需要为代码出网问题扯皮。这两点在真正的落地过程中远比省下的开发成本重要。6.3 适合场景与后续扩展思路最后聊聊什么情况下适合用 open-code-review 这类自研方案。在我看来三个条件都满足时比较值得动一是团队有稳定可枚举的工程规范这些规范反复在 review 中被提起二是代码托管平台和 CI 基础设施允许你做深度的自动化接入三是团队成员愿意在规则质量上投入而不是写几条规则就一劳永逸。如果这三个条件不满足我更建议去用现成工具把精力放在规则配置和流程推广上。工具本身不是目的减少重复劳动、提高 review 质量才是。后续扩展的方向我们目前在看的还有三个第一个是把规则引擎从 Python 语言扩展成多语言重点支持 Go 和 TypeScript第二个是做一个基于历史命中的学习面板看看哪些规则最常被触发、哪个团队的技术债最集中第三个是把 scan 结果回推到内部的知识库平台让开发在提交前就能预览可能被 flag 的问题。这些都是锦上添花的活不影响核心链路但我们觉得它们和一个成熟的审查工具应该共同成长。我在实际维护 open-code-review 的过程中最大的体会是工具的核心价值不是替代人而是把团队的注意力从重复劳动里释放出来让人去做真正需要人的判断力的事情。如果你也在为 code review 的效率和漏检率头疼不妨先用一个周末搭一个最小版本拿你们仓库最近一个月的 PR 回放一下看看它能帮你拦下多少问题。很多时候答案比想象中来得快。