★ FEATURED ARTICLE 1. 为什么我最终决定把 Code Review 从人肉流程变成自动化流水线做了这么多年开发我有个很深的感触Code Review 是代码质量最后一道防线但也是团队里最容易流于形式的一道工序。忙起来的时候 review 就是点个 approve不忙的时候又容易翻来覆去纠结变量命名这种细枝末节。我一直想找到一个方案能把 Code Review 这件事真正落地从走过场变成可量化、可追踪、有产出的工程环节所以我启动了open-code-review这个项目。先解释一下open-code-review的核心思路是什么。它不是要替代人工 review而是要做人工 review 的前置过滤器和质量看门人。自动抓取变更内容、跑静态扫描、做增量检查、出报告、卡合并、留记录这一整套流程跑完之后真正需要人来看的就只是那些机器判断不了、需要结合业务上下文决策的问题。这样 review 的效率和质量都能上一个台阶。这篇文章适合谁看如果你正被下面这些问题困扰那这篇内容对你应该有帮助团队 review 流于形式approve 按钮按得飞快线上事故照样频发每次 Merge Request 动辄几百上千行变更人肉看真的看不过来想要引入自动化 review 能力但不知道从哪一步开始也不知道选哪套技术方案公司用的代码平台五花八门GitLab、GitHub、Gitea 都有希望能有一套统一的接入方案我会从整体设计、技术选型、核心功能实现、踩坑记录这几个维度把open-code-review从零到一的过程完整讲一遍。其中会包含可以直接抄作业的配置和代码也会讲清楚每个关键决策背后的理由。如果你正准备自己动手做一套类似的系统这篇文章应该能帮你少走不少弯路。2. 整套系统设计思路不是在加功能而是在改流程任何一个工具类项目如果只是堆功能到最后大概率会变成一个谁都不想用的负担。我在设计open-code-review的时候第一件事不是写代码而是先想清楚一个问题这套系统在开发流程里应该站在哪个位置我的答案是它应该站在代码从开发完成到合入主干的必经之路上当一个自动化的质检员。开发提交代码系统自动开始检查然后把结果反馈给开发者和 reviewer。2.1 系统的三层架构接入层、分析层、反馈层整个系统我分成了三层每一层各司其职互不干扰接入层负责和不同代码平台的对接。无论是 GitLab 的 Merge Request、GitHub 的 Pull Request还是 Gitea 的 Pull Request接入层统一把它们抽象成一次变更事件。这样上层逻辑不需要关心请求来自哪个平台只需要处理一个统一的变更对象即可。这个设计帮我省了很多事后面接新平台时只需要写一个新的适配器核心分析逻辑完全不用动。分析层是整个系统的核心做三件事。第一是变更内容分析获取本次变更涉及的文件列表、变更行数、diff 内容等基础数据。第二是静态扫描调用工具链对变更代码做语法和规范层面的检查。第三是智能识别针对一些常见但难以通过纯静态规则发现的问题用自定义规则做模式匹配比如检查调试代码是否遗留是否有明显的安全隐患。反馈层是系统能否落地的关键。分析结果不能只是躺在日志里必须主动推送到对应的 Merge Request 评论区、更新检查状态甚至通过消息机器人通知到相关人。反馈的质量直接影响开发者愿不愿意看这份报告。2.2 关键设计决策为什么核心引擎要做得与平台无关上面说到的三层架构很多人第一反应可能是这不就是一个多平台适配的封装吗。但真正做起来你会发现最容易翻车的地方恰恰在这里。我见过不少类似的项目为了快速上线直接在代码里写死了 GitLab 的 API。等到团队迁移到 GitLab 的自建版本或者想接入 GitHub 时只能推倒重来。为了避免这个问题我从一开始就定了两条铁律。第一核心引擎绝不直接调用任何平台的 API。分析层只面向一个标准变更模型编程这个模型包含文件路径、变更类型、补丁内容、变更作者等字段。具体怎么从各个平台把这些数据拉出来接入层说了算。第二平台适配器是可插拔的。每个平台对应一个独立的模块通过配置文件启用或禁用。新平台接入时只需要实现几个固定的接口方法比如获取变更列表获取变更详情提交评论更新检查状态。这么做确实在前期要多写一点代码但带来的好处是长期的。open-code-review目前已经接入了 GitLab 和 GitHub后续接 Gitea 时核心引擎一行都不用改只需新增一个适配器模块。对于想二开这个项目的人来说这个设计也能让上手门槛低很多。2.3 数据模型设计变更对象、检查任务、检查报告数据模型是整个系统的骨架。我设计了三个核心实体变更事件ChangeEvent是最顶层的抽象代表一次代码合并请求。它的字段包括来源平台、仓库路径、目标分支、源分支、变更唯一标识、触发者等。检查任务CheckTask基于触发策略产生。一次变更事件可以触发多个检查任务比如每次变更触发一轮基础检查仅当变更涉及前端文件时额外触发一轮前端专项检查。检查报告CheckReport是检查任务执行完毕后的产物记录了检查结果摘要、问题列表、修复建议、检查耗时等信息最终会被反馈层呈现给用户。这三者之间是一对多的层级关系落到数据库里也容易建模逻辑非常清晰。3. 技术选型的真实考量对比多个方案之后为什么选了 GitLab CI 做主力运行环境技术选型这种事光看技术本身强不强没用关键看它和你现有的基础设施、团队习惯合不合拍。下面这套选型是我基于两套方案实测后的结果分享出来供你参考。3.1 第一版方案独立常驻服务灵活但太重最开始我设想的是把open-code-review做成一个常驻的 Web 服务监听 GitLab 或 GitHub 的 Webhook 事件收到事件后异步执行检查任务处理完再通过 API 把结果回写到平台上。这套方案的优点是调度能力强可以做复杂的任务编排和并行执行。但缺点也很明显需要额外部署和运维一套服务还要考虑高可用成本偏高Webhook 的签名校验、重试机制、事件去重这些基础设施都得自己搭和公司现有的 CI/CD 体系是割裂的开发者要额外登录一套系统才能看到检查结果3.2 第二版方案优先吃透 CI 生态能力把核心逻辑做成可执行 CLI在动手写常驻服务之前我花了两天时间仔细看了看 GitLab CI 的能力边界发现其实大部分需求它天然就支持。于是我把方案改成了核心逻辑封装为 CLI 工具 由 CI 调度执行的形态。GitLab CI 允许你在.gitlab-ci.yml里定义专门的 review job让它只在我们关心的 MR 事件上运行。CI 运行时会自动带出大量上下文信息比如项目 ID、MR 的 IID、当前提交的 SHA 等这些信息都通过预定义环境变量直接读到大大简化了接入层代码。此外CI 本身天然支持基于规则的触发、超时控制、并发限制、执行日志归档这些都不用自己实现了。对于核心的 CLI 工具我选择用 Python 编写。原因是 Python 在这种胶水型工具场景下效率极高配合类型标注和单元测试后期维护成本也可控。优点在于部署成本几近为零只需要把这个 CLI 发布成 Python 包并在 CI 里执行pip install或直接拉取含工具链的镜像即可。运行环境由 CI 隔离出问题不会拖垮宿主机。3.3 两个方案实测后的取舍结论我实际把两套方案的骨架代码都写了出来跑了几个 Demo 对比之后总结出了下表对比维度常驻服务方案CI 调度 CLI 方案部署运维成本高需要维护常驻进程低CI 容器即用即弃调度能力强任务编排灵活中依赖 CI 固有机制但规则够用平台资产复用度低需自建事件体系高CI 变量、Webhook 均由平台托管历史报告追踪直接存数据库查询方便依赖 CI Job 日志和评论记录也可以配合调用平台 API 保存上手门槛中高低改造现有.gitlab-ci.yml即可接入结论很明确对于大多数中小团队来说CI 调度 CLI 方案是性价比最高的选择。常驻服务方案更适合需要极细粒度调度、有复杂编排需求的场景但对于做 review 自动化这件事来说有点杀鸡用牛刀了。4. 核心功能拆解从能跑起来到真正好用架构和技术选型定下来之后才能真正进入功能开发的阶段。这章我挑几个关键功能的实现细节讲重点说为什么这么设计以及踩过的坑。4.1 标准变更模型的设计与实现标准变更模型是整个系统的地基。它需要统一表达来自不同平台的代码变更下面是一个简化版的 Python 类设计from dataclasses import dataclass, field from enum import Enum from typing import List, Optional class ChangeStatus(str, Enum): ADDED added MODIFIED modified REMOVED removed RENAMED renamed class ChangeSource(str, Enum): GITLAB_MR gitlab_mr GITHUB_PR github_pr GITEA_PR gitea_pr dataclass class FileChange: file_path: str old_path: Optional[str] None status: str ChangeStatus.MODIFIED patch: str additions: int 0 deletions: int 0 dataclass class ChangeEvent: source: ChangeSource ChangeSource.GITLAB_MR project_id: str repo_url: str source_branch: str target_branch: str change_id: str title: str description: str author: str changes: List[FileChange] field(default_factorylist)ChangeEvent中包含的是和平台无关的纯数据。GitLab 适配器要把 MR 的changes接口返回的数据转换成FileChange结构GitHub 适配器则要把 PR 的files接口数据做同样转换。转完之后后续所有分析逻辑看到的都是同样的对象不关心你用的是diff --git还是 .patch。4.2 触发规则的配置化设计触发规则我优先设计成了配置驱动而不是代码驱动。这样使用者不需要改任何代码仅靠修改 YAML 配置文件就能决定哪些变更需要跑哪些检查。一个典型的配置文件如下triggers: - name: base_lint on_branch: [main, develop] paths: - **/*.py actions: [python_lint, secrets_scan] - name: frontend_lint on_branch: [main] paths: - frontend/** - **/*.ts - **/*.tsx actions: [eslint_check, tsc_check]例如第二条规则只有目标分支是 main且变更涉及frontend目录或.ts、.tsx文件时才会触发前端专项检查。这样能极大节省计算资源也能避免给开发者刷屏无意义的检查结果。路径匹配用的是pathspec这个 Python 库支持 gitignore 风格的通配符。一开始我尝试过直接用fnmatch但遇到**/frontend/**这种模式时表现不稳定换了pathspec之后匹配语义就和日常用的 gitignore 完全一致了心智负担也小了很多。4.3 静态检查工具链的集成静态检查的执行是有严格先后顺序的。先做最基础的语法检查再做风格和规范检查最后再跑自定义的安全扫描。每一层发现的问题如果足够严重后续层可以选择跳过避免在错误的代码上做无用功。以 Python 项目为例我集成的是ruff和bandit这两个工具。ruff执行极快能覆盖 E、F、W 等常见规范问题bandit专门做安全扫描能识别eval、不安全的yaml.load、硬编码密码这类问题两个工具都支持 JSON 格式输出非常方便程序解析集成代码的核心逻辑大致是这样import json import subprocess def run_ruff(files: list[str]) - list[dict]: result subprocess.run( [ruff, check, --output-formatjson, *files], capture_outputTrue, textTrue, ) if result.returncode not in (0, 1): # ruff 返回码0 无问题1 有问题其他视为执行异常 raise RuntimeError(fruff 执行异常: {result.stderr}) return json.loads(result.stdout)这里有个细节值得说一下。很多人都以为检查工具返回非零退出码就代表失败实际上不同工具对退出码的约定并不完全一致直接根据返回码去判断结果会埋坑。我需要做的是把工具的 JSON 输出统一解析成内部的问题对象再根据问题严重程度决定是否把 MR 状态置为失败而不是让某个工具自身的返回码直接决定 CI 结果。4.4 自定义问题识别规则的实现除了跑现成工具open-code-review还内置了一套自定义规则引擎。原因是现成工具抓不到一类很难受的问题调试残留。比如说某人在print调试完成后忘了删这种代码能通过所有静态检查但对生产环境来说是很糟糕的卫生问题。为了抓这类问题我写了一些简单但很有效的正则规则CUSTOM_PATTERNS [ { name: debug_print_leak, pattern: r^\s*print\s*\(.\)\s*$, severity: warning, message: 检测到疑似调试用 print 语句建议移除或替换为日志输出, }, { name: pdb_breakpoint, pattern: rbreakpoint\(\)|pdb\.set_trace\(\), severity: error, message: 检测到断点调试代码不应提交到版本库, }, ]正则匹配看起来很简单但要注意不要在整份 diff 里直接搜只应该搜索新增的代码行。我维护了一个新增行的集合只对这些行做正则匹配否则很容易误伤。比如已有代码里本来就有print()本次 MR 只是改动了它下面一行按整文件扫描就会把这个报出来开发体验非常糟糕。4.5 报告生成与 MR 评论回写为了让报告不招人烦我反复调了很多版。最开始我把每个问题单独发一条评论结果一个 MR 能被刷出几十条消息开发者看到就头大。后来改成了汇总式评论一次 MR 只会有一条机器人评论而且如果后续有更新同一评论会被编辑更新不会产生冗余噪音。评论的格式设计也很重要。我不只列哪里有问题还给出为什么可能是问题以及怎么改。格式示例### open-code-review 检查报告 **检查范围**3 个文件46 / -12 行 #### 问题列表 1. **[错误]** app/services/user_service.py:42 — 检测到断点调试代码 - 说明: 检测到 breakpoint() 或 pdb.set_trace() 调用 - 建议: 删除调试断点改用日志或调试器断点 2. **[警告]** app/utils/logger.py:17 — 使用 print 输出日志 - 说明: 生产代码中不建议使用 print应使用标准日志模块 - 建议: 替换为 logging.info(...) 或 logger.debug(...) --- 报告生成时间2024-06-30 14:30:22 更多详情请查看 CI Job 日志。评论里的严重级别和文件行号都是可点击的锚点reviewer 可以直接跳转到对应代码位置不用再手动去找。5. 完整实战配置一次 MR 自动化检查的全过程说再多设计理念不如直接跑通一遍。我自己在 GitLab 上用一个实验项目完整走了一遍流程从配置到跑通的每一步下面原样分享给你。5.1 环境准备清单动手之前需要准备好这些东西项目要求说明GitLab 版本12.0需要在 MR 中添加评论需要配置 Bot 用户的 TokenPython 运行环境3.10CLI 工具的本地运行需要目标代码仓库任意语言本文以 Python 为例CI Runner可用即可Runner 需要能访问内网依赖源提示如果你用的是 GitLab 自建实例需要确认 Runner 是否有外网访问权限。若不能访问 PyPI需要提前把依赖包推送到内网源。5.2 创建机器人账号并配置 Token这一步很关键。我强烈建议不要用个人账号的 Token来跑自动化检查应该单独创建一个 Bot 用户。原因是职责隔离代码检查和你的个人开发操作不会混淆权限可控只需要给 Bot 配置api和read_repository权限出问题时影响面小可追溯所有自动评论都挂在这个账号下一眼就能认出来具体流程在 GitLab 管理界面创建一个新用户比如叫code-review-bot给该用户配置 Personal Access Token勾选api和read_repository权限在目标项目中把 Bot 添加为 Developer 或 Maintainer取决于你希望它有怎样的评论权限把 Token 填入 GitLab 项目的 CI/CD Variables 中命名如REVIEW_BOT_TOKEN并勾选Masked和Protected选项5.3 编写 .gitlab-ci.yml 中的 review Job下面的配置是我在实验项目中实际用到的最小可用版本stages: - review review: stage: review image: python:3.11-slim only: - merge_requests script: - pip install open-code-review0.1.0 - python -m open_code_review scan \ --provider gitlab \ --project-id $CI_PROJECT_ID \ --mr-iid $CI_MERGE_REQUEST_IID \ --token $REVIEW_BOT_TOKEN \ --gitlab-url $CI_SERVER_URL artifacts: when: always paths: - report.json解释几个关键配置only: merge_requests的意思是这段 Job 只在 MR 事件上运行push 到分支不会触发避免资源浪费CI_PROJECT_ID、CI_MERGE_REQUEST_IID、CI_SERVER_URL都是 GitLab CI 预置的变量不用手动传artifacts配置是为了把生成的report.json保存下来方便看流水线页面直接下载也有存档价值5.4 完整执行过程与日志解读提交 MR 后CI 会自动触发。日志的关键输出如下所示我加了注释方便理解$ python -m open_code_review scan --provider gitlab --project-id 123 --mr-iid 5 ... [INFO] 检测到 GitLab MR !5目标分支 main提交 3f9a2b7 [INFO] 变更文件: 3 个总变更行数 46 / -12 [INFO] 触发策略匹配: base_lint (匹配所有 .py 文件) [INFO] 运行静态检查: ruff [INFO] ruff 检查完成: 发现 2 个问题 [INFO] 运行安全扫描: bandit [INFO] bandit 检查完成: 发现 0 个问题 [INFO] 运行自定义规则: debug_print_leak / pdb_breakpoint [INFO] 自定义规则检查完成: 发现 1 个问题 [INFO] 正在回写评论到 MR !5 ... [INFO] 评论回写完成评论链接: https://gitlab.example.com/.../notes/123456 [INFO] 正在更新 MR 检查状态 ... [INFO] 全部流程执行完毕如果你实际跑的时候看到[ERROR] 无法获取 MR Changes大概率是 Token 权限不足或者CI_MERGE_REQUEST_IID被错误地传成了别的值。这时候优先检查两处Token 是否具备read_repository权限以及项目 ID 对应的仓库是否允许当前用户访问。5.5 执行结果验证与效果对比流程跑通后MR 下方多了一条自动评论CI Pipeline 上多了一个 review 状态。这时候我做了个效果对比改造前一个包含 3 个文件的 MR两个人 review每人看一遍大概 20 分钟能发现的主要是业务逻辑问题改造后同样的 MR机器先跑完一轮检查把 3 个问题直接贴在评论里人去 review 时只需要聚焦业务逻辑和架构问题时间压缩到 10 分钟以内也就是说这套系统不是一个额外的负担而是真正帮人节省了时间。它能帮你自动盯住规范、调试残留这类琐碎问题人的精力就能放在更重要的设计评审上。6. 从能用到好用地狱模式我踩过的三个大坑这章不含教学全是实战后留下的血泪经验。其中有些问题你在文档里根本找不到网上也几乎没有讨论分享出来是为了让你别在同一个地方栽跟头。6.1 问题一CI 环境下 git diff 的行为和本地不一致这是我踩的第一个坑。open-code-review内部需要自行计算增量变更。最初版本在本地测试正常但放到 GitLab CI 里运行时拿到的 diff 总是为空或者缺文件。排查了很久才弄清楚原因GitLab CI 默认克隆的是不带完整历史记录的分支信息也受限。本地仓库里的git diff target...source能用但 CI 环境里可能是 shallow clone浅克隆甚至没有显式检出目标分支所以 diff 算不出来。解决方案有两个方向在 Job 里增加GIT_DEPTH: 0禁用浅克隆确保有完整历史更稳妥的做法直接调用平台 API 获取 MR 的 changes而不是依赖本地 git 命令我最终方案是两者结合优先尝试从 API 获取变更失败时回退到git fetchgit diff的组合拳。这样即使平台 API 临时出问题也能兜底运行。6.2 问题二机器人评论刷屏引发团队反感工具刚上线时有一次改动量大我在评论里放了几十条检查结果结果这个 MR 的评论区直接爆炸。开发者的反馈很直接这工具能不能关掉这次经历让我意识到一个问题自动化工具是给人用的不是给人添堵的。如果结果噪音太多再强大的检查能力也没意义。后续我做三件事来优化汇总评论一个 MR 只发一条评论持续更新而不是每条问题一条评论分级展示必须修改的问题是 error 级别可以讨论的是 warning 级别纯建议是 info 级别。error 会要求 MR 检查状态置为 failedwarning 和 info 只在报告中展示不阻塞合入路径过滤不在本次 MR 改动范围内的历史遗留问题一律不报调整之后评论可读性大幅提升团队接受度也回来了。6.3 问题三静态检查工具误报率过高导致狼来了ruff和bandit这类工具默认规则集里有些规则和项目实际情况并不匹配。比如某个内部项目很依赖try-except吞异常bandit 就经常会报 warning再比如ruff默认对import排序非常严格老代码根本达不到那个标准。如果一上来就把所有规则全部打开检查报告会变成狼来了开发者看一眼全是误报自然就不信这个系统了。我的解法是在项目配置文件里对默认规则做裁剪和自定义。用pyproject.toml举例[tool.ruff] select [E, F, W, I, N] ignore [ E501, # 行宽限制和项目既有风格不匹配 N801, # 类命名规范与项目内部约定不同 ]bandit则是通过skips参数跳过确认误报的规则再针对高风险规则单独开进度跟踪。总之规则要对齐自己团队的事实标准达成共识后再逐步加严。7. 未来的进阶方向与扩展思路如果说当前版本的open-code-review解决的是规范检查自动化那它未来更值得探索的方向是智能审查辅助。这个方向分成两块一块是我已经动手做了的一块是还在规划的。7.1 已有实践基于增量数据的文件热度分析我做了个实验性的小功能统计历史上哪些文件被修改得最频繁然后把这些高热度文件设为重点审查对象。当一个 MR 改动涉及这些文件时检查等级自动提高相关规则也放得更宽更高要求。实际价值在于这类文件往往是系统的瓶颈或业务核心改出问题的概率高、影响面大值得投入额外的关注。通过机器把这些文件筛出来交给 reviewer比 reviewer 自己翻项目历史高效得多。7.2 规划方向接入大模型做语义级检查静态规则能处理代码像什么样但处理不了代码要做什么。一个函数虽然有命名和注释但它实际行为是否符合业务预期静态规则是判断不了的。所以下一步计划是接入大模型的代码理解能力在静态检查无异常的基础上把 diff 内容交给模型做语义级审查。比如判断某个条件判断是否需要考虑空指针、某个新接口的调用顺序是否合理、对异常处理遗漏给出建议等。这个方向想法很美好落地难点也很明显成本控制、响应延迟、识别的稳定性、评审标准的统一性。我自己也在持续关注和尝试等有阶段性成果了再写一篇专门的文章来讲。最后分享一点个人体会。做自动化 review 工具这件事技术难点从来不是我担心的重点真正的难点在于让一个工具在团队的协作流程里找到自己合适的位置。工具再强如果它让流程变得繁琐、让开发者感到不信任最终一定会被抛弃。现在整套系统跑起来之后我最开心的事情不是又抓到几个 BUG而是团队里开始有人主动说这个 MR 先等检查过了再叫我 review。这说明流程已经变成团队的习惯了。如果你也正在做类似的事情记住这句话好的工具不是制造规则的而是帮人省下时间去做真正有价值的判断。
阅读完成 · 觉得有帮助？
