★ FEATURED ARTICLE 1. 项目概述为什么我决定做一个开源的 code review 工具代码审查这件事说实话每个团队都在做但真正做好的没几个。我过去几年呆过好几个团队见过用 GitHub PR 评论来回刷的见过在 IM 群里丢代码链接让大家“帮忙看看”的也见过采用 Gerrit 那套复杂权限流程结果全员抗拒的。直到我自己动手写了一个叫 open-code-review 的开源工具才觉得代码审查这件事终于有了一个既轻量又可控的解法。open-code-review 本质上是一个基于 Git 工作流、完全运行在终端环境下的开源代码审查工具。它不依赖任何商业平台也不需要额外的 Web 服务你只需要一个 Git 仓库就能在本地或 CI 环境里完成从“提交审查请求”到“记录审查意见”再到“确认是否通过”的完整闭环。适合那些不想被平台绑定、又希望把 code review 这件事真正落到流程里的个人开发者和中小团队。我把整个项目开源的时候主要思路就一句话让代码审查像 git commit 一样自然。你提交代码时用 git切换分支用 git那么发起一次审查、提一条意见、打一个通过标记也应该可以用一套命令行工具完成而不是跳去网页、点一堆按钮、还要忍受漫长的评论加载。这个项目的意义就在于把代码审查的“仪式感”降到最低把“效率感”提到最高同时把审查过程中产生的所有数据留存在本地方便追溯和统计。2. 核心设计思路与技术选型2.1 为什么不用现成的 Code Review 平台先说一个很现实的问题市面上不是没有代码审查工具GitHub Pull Request、GitLab Merge Request、Gerrit、Phabricator哪个不能用都能用。但我在实际使用中逐渐感受到几个痛点这些痛点恰恰是 open-code-review 想解决的。第一个痛点是平台锁定。代码放在 GitHub 上审查就得在 GitHub 上做代码挪到自建的 GitLab审查流程又要重新配置一遍。对于同时维护多个仓库、横跨多个平台的开发者来说这种绑定非常难受。我希望能有一套和仓库托管平台解耦的审查机制只要底层是 Git走到哪里都能带过去。第二个痛点是流程太重。GitHub PR 的全套流程——开 PR、等 CI、找人 review、处理 comment、再 push 新 commit——对于大型项目是合理的但很多内部工具、脚本、配置类的仓库改动往往很小也要走完整套流程时间成本明显不匹配。我需要的是一种“轻量审查”模式改动不大但该走的检查要有该留的记录也要留。第三个痛点是数据归属问题。审查意见、通过记录、驳回理由这些都是团队的过程资产。放在商业平台上导出和归档都相对麻烦放在本地仓库里随便 grep 一下就能出报告。从数据自主可控的角度看本地化存储反而更有优势。2.2 技术栈选择Python 与 Git 命令的配合open-code-review 选择用 Python 来实现原因很简单Python 在处理文本、解析 diff、调用外部命令方面都非常顺手而且几乎不需要编译拿到代码就能跑对使用者的环境要求也低。核心架构上我并不直接操作 Git 的内部对象而是通过 subprocess 调用系统 git 命令来完成任务。这样做的最大好处是只要机器上装了 Git工具就能正常工作不用去处理不同 Git 版本之间内部存储格式的差异。Git 本身已经是一套极其成熟的版本管理协议我不需要重复造轮子只需要在它的上层构建代码审查的语义层。整个工具的数据存储也非常朴素就落在当前仓库的 .git/review/ 目录里用 JSON 文件保存每次审查的记录。为什么不用数据库因为代码审查的数据量级根本到不了需要数据库的程度一个中型团队跑一年审查记录也就几千条JSON 文件完全撑得住而且可以直接用文本编辑器查看、用脚本处理天生就是开放格式这完全符合 open-code-review 这个名字的“open”精神。2.3 审查工作流的状态机设计任何流程类工具核心都是一套清晰的状态转换规则。open-code-review 的审查流程被我设计成四个状态pending待审查→ approved已通过 pending待审查→ changes_requested需修改 changes_requested需修改→ pending重新提交 changes_requested需修改→ approved审查者确认修改到位这个状态机非常朴素但胜在清晰。审查者看到一条记录时不需要思考“现在处于什么阶段”因为状态只有三种可能还没审、已通过、需修改。不存在“reviewing”审查中这种中间态因为实际工作中“审查中”本质上是“还没结论”用 pending 表达就够了多一个状态反而增加理解成本。工具内部用一个简洁的 Python 类来管理状态转换class ReviewState: PENDING pending APPROVED approved CHANGES_REQUESTED changes_requested # 合法的状态迁移路径 VALID_TRANSITIONS { PENDING: {APPROVED, CHANGES_REQUESTED}, CHANGES_REQUESTED: {PENDING}, APPROVED: set(), } classmethod def can_transition(cls, current: str, target: str) - bool: return target in cls.VALID_TRANSITIONS.get(current, set())状态机的好处在于它天然阻止了一些不合理的操作。比如一条已经 approved 的审查记录就不应该再被打回 pending因为在真实工作流里既然已经通过了后续改动应该开启一次新的审查而不是在同一记录里反复横跳。3. 功能实现与关键细节3.1 审查请求的创建逻辑一次代码审查的起点是执行 review request 命令。它的核心任务只有一个采集当前分支相比目标分支的代码变更并生成一条待审查记录。在实现上这个功能依赖 git diff 的输出。我封装了一个底层函数来获取变更内容import subprocess def get_branch_diff(base_branch: str, head_branch: str) - str: 获取指定分支之间的完整变更内容 result subprocess.run( [git, diff, base_branch, head_branch], capture_outputTrue, textTrue, checkTrue, ) return result.stdout拿到 diff 文本后工具会把整个 diff 拆分成逐文件的变更统计包括新增行数、删除行数、变更文件列表一并写入审查记录。这样审查者在打开记录时第一眼就能对整个改动的规模有直观印象而不是面对一大段 diff 无从下手。创建审查记录时还需要指定审查者。open-code-review 支持两种方式命令行参数显式指定或者读取仓库根目录下的 REVIEWERS 文件。如果 REVIEWERS 文件存在会优先从里面读取审查者列表如果文件不存在则退化为读取 git config user.name 作为默认审查者。这个设计兼顾了团队标准化和个人轻量使用的不同场景。3.2 自定义审查规则的引擎实现很多人觉得代码审查就是人肉看代码其实不然。大量重复性的低级问题完全可以在人眼介入之前用规则引擎先跑一遍。open-code-review 内嵌了一个轻量的规则引擎支持在配置文件中自定义检查规则。规则的配置格式是 YAML因为 YAML 的阅读和手写成本都低于 JSON 和 TOML。每个规则由四部分组成名称、优先级、匹配模式、针对的文件类型。# .codereview.yaml 配置示例 rules: - name: no-debug-print level: warning pattern: print\\(.*debug|console\\.log\\(.*debug files: - *.py - *.js message: 禁止调试用的 print/log 语句进入主干代码工具启动审查时会逐条规则去扫描 diff 中的新增代码行而不是扫描整个文件。这个设计是基于一个经验判断审查的注意力应该只放在新增和修改的代码上原有代码如果有问题那属于遗留债务不应该拦在一次小改动的审查门口。扫描逻辑通过正则表达式匹配实现核心代码非常精简import re from pathlib import Path from typing import Dict, List def scan_new_lines(diff_text: str, rules: List[Dict]) - List[str]: findings [] current_file None for line in diff_text.splitlines(): if line.startswith( b/): current_file line[6:] continue if current_file and line.startswith(): content line[1:] for rule in rules: if re.search(rule[pattern], content): findings.append( f{current_file}: {rule[level]}: {rule[message]} ) return findings这段代码的逻辑非常直观遍历 diff 文本识别文件头只挑选以 开头的内容行逐条规则做正则匹配命中就记录为一条发现问题。配合配置文件的规则扩展基本能覆盖大多数团队常见的静态检查诉求。3.3 审查意见的提交与通知机制审查意见的提交是整个工作流里最需要打磨的部分。我见过太多审查流程死在意见表达上——要么意见写得含混不清要么没有定位到具体的代码位置导致开发者和审查者来回拉扯。open-code-review 的意见格式参考了一些成熟平台的做法强制要求每条意见包含三个要素文件路径、代码行号、意见正文。命令行交互时工具会引导用户逐步输入而不是要求一次性记住所有参数$ open-code-review comment review-20250115-1630 文件路径: src/processor.py 代码行号: 42 意见内容: 这个函数在输入为空时会抛异常建议增加空值判断提交意见后工具会自动追加一条格式化的 Markdown 文本到评审记录的 comments 字段同时在终端输出提示。如果配置了 webhook 地址还会向指定 URL 发起一个 HTTP POST 请求把意见推送到团队群或消息机器人这样审查者发出意见后开发者不需要主动刷新状态就能收到通知。这里有一个实操细节值得强调webhook 的 URL 建议通过环境变量注入而不是写在配置脚本里。因为代码审查配置通常会进版本库共享给团队如果 URL 写死在配置里一旦后期更换消息机器人地址就要改代码、提交、再等 CI 跑一遍非常低效。3.4 审查记录的存储结构与查询每条审查记录对应 .git/review/ 目录下的一个 JSON 文件文件名采用 审查者名字-时间戳 的格式保证唯一性。一个典型的记录文件长这样{ id: review-20250115-1630, author: zhangsan, reviewer: lisi, base_branch: main, head_branch: feature-login-timeout, created_at: 2025-01-15T16:30:2208:00, status: pending, summary: { files_changed: 3, insertions: 48, deletions: 12 }, diff_summary: src/auth.py (35, -8), src/config.py (10, -2), test/test_auth.py (3, -2), comments: [ { file: src/auth.py, line: 42, content: 这里建议用 datetime.now(timezone.utc) 替代 datetime.utcnow()后者已标记过时 } ], status_changes: [ { from: pending, to: changes_requested, at: 2025-01-15T17:02:1108:00 } ] }用纯文本文件存储的好处是透明谁都能看懂内容结构也方便写脚本做二次分析。我见过有团队用 open-code-review 的 JSON 数据生成了月度代码审查统计报告统计每位工程师被提出的问题数量、各模块的审查通过率这在以往依赖 Web 平台时反而需要写爬虫才能做到。查询方面工具提供了 review list、review show 两个命令。list 命令支持按状态和审查者过滤show 命令则完整展示某条记录的详情包括所有历史意见和状态变更日志。状态变更日志的保留是我特别坚持的因为审查过程中意见往返也是重要的过程数据后续复盘时能看到一条意见从提出到解决花了多长时间这个数据对团队改进协作效率非常有价值。4. 完整实操从零开始用 open-code-review 落地一次审查4.1 安装与环境准备open-code-review 的安装非常简单我已经把它发布到了 PyPI一行命令就能装好pip install open-code-review安装完成后可以执行 open-code-review --version 验证是否安装成功。项目对 Python 版本的要求是 3.8 及以上因为用到了 f-string 的动态表达式和内置 typing 的部分特性更低版本会报语法错误。如果你不想通过 pip 安装也可以直接从 GitHub 仓库 clone 源码然后把它加到 PATH 里使用。源码包内只有一个核心模块和一个命令行入口文件依赖只有 requests 和 PyYAML 两个第三方库非常轻量。4.2 项目初始化与团队配置在项目根目录执行初始化命令open-code-review init这个命令会做三件事创建 .git/review/ 目录、生成一份默认的 .codereview.yaml 配置文件、在 .gitignore 中添加 review 临时文件规则。默认的配置文件内容如下# open-code-review 配置文件 rules: - name: no-debug-print level: warning pattern: print\\(.*debug|console\\.log\\(.*debug files: - *.py - *.js message: 禁止调试打印语句 - name: no-todo-comments level: warning pattern: TODO|FIXME files: - *.py - *.js - *.java message: TODO 注释不允许进入主干 - name: secret-key-detection level: error pattern: (api[_-]?key|secret|password)\\s*[:]\\s*[\][^\]{8,} files: - *.py - *.js - *.yaml - *.yml message: 检测到疑似密钥硬编码必须处理后再提交这三条规则是我根据多年经验总结的高频问题清单。第一条和第二条属于常规工程规范第三条特别重要密钥硬编码是安全事故的重灾区很多团队直到出事了才回头排查代码仓库里的明文密钥。规则引擎在扫描到 error 级别问题时会直接阻止审查请求的创建强制开发者先解决。初始化完成后你可以编辑 REVIEWERS 文件写上团队里负责审查成员的 git 用户名每行一个。这样创建审查请求时工具会自动随机选择一个审查者让团队间的审查任务分配更均匀。4.3 发起一次审查请求假设你在 feature-login-timeout 分支上完成了一个功能开发现在要发起审查合并进入 main 分支open-code-review request --base main --head feature-login-timeout --reviewer lisi执行后终端会输出审查创建的摘要信息创建审查成功 审查 ID: review-20250115-1630 变更文件: 3 新增行数: 48 删除行数: 12 审查者: lisi 状态: pending 自动扫描结果: - src/auth.py line 42: warning: 这里建议用 datetime.now(timezone.utc) 替代 datetime.utcnow()后者已标记过时 - src/config.py line 15: error: 检测到疑似密钥硬编码必须处理后再提交 警告: 存在 error 级别未解决问题建议先修复再提交人工审查注意这里规则引擎扫描出来的问题只是给开发者一个提醒真正决定审查是否通过还是由人工审查者确认。但 error 级别的规则命中会显著提醒开发者优先处理避免把明显有问题的代码送到审查者面前。4.4 审查者视角处理一条待审查记录审查者收到消息通知后可以查看待办列表open-code-review list --status pending找到对应的审查 ID 后先查看整体变更摘要和规则扫描结果再查看具体的代码 diff审查 ID: review-20250115-1630 审查者: lisi 状态: pending 创建时间: 2025-01-15 16:30 变更统计: src/auth.py 35 -8 src/config.py 10 -2 test/test_auth.py 3 -2 自动扫描发现: [warning] src/auth.py:42 建议使用 timezone-aware 的 datetime [error] src/config.py:15 疑似密钥硬编码审查者可以先查看自动扫描发现的 error 级别问题确认是否真的存在密钥硬编码。如果确认就直接提交意见并打回如果不影响合并则继续查看 diff 的整体逻辑。提交意见用的还是 comment 子命令但审查者可以一次性针对多个文件提出多条意见工具会按文件路径自动归类到对应的 JSON 记录中。如果审查者认为代码整体合格只需要微调几个点就使用以下命令提交意见并标记状态open-code-review comment review-20250115-1630 --file src/auth.py --line 42 --message 建议改用 timezone-aware 的时间处理 open-code-review status review-20250115-1630 --to changes_requested开发者看到状态变更后修复对应问题重新提交新 commit 到同一分支再执行 review request 时工具会识别到同一分支已经存在 pending 或 changes_requested 状态的记录自动将其状态置回 pending并把新生成的 diff 追加进原有记录而不是创建一条新记录。这个设计保证了一条 feature 分支的审查历史是连续的、可追溯的。4.5 CI 环境的自动化集成open-code-review 除了支持手动执行还设计了一个非常重要的场景集成进 CI 流水线。在 GitHub Actions 或类似工具中可以添加一步来调用规则引擎的扫描功能让自动化检查跑在人工审查之前name: code-review-check on: [pull_request] jobs: review-scanner: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-pythonv5 with: python-version: 3.10 - run: pip install open-code-review - run: | open-code-review ci-scan \ --base origin/main \ --head HEADci-scan 子命令是专门为 CI 场景设计的它不会创建审查记录只运行规则引擎并输出结果。如果发现 error 级别的问题命令会以非零状态码退出从而阻断流水线如果只有 warning则输出提示但不阻断。这个行为在代码里体现为def ci_scan(base_branch: str, head_branch: str) - int: diff_text get_branch_diff(base_branch, head_branch) rules load_rules() findings scan_new_lines(diff_text, rules) error_count sum(1 for f in findings if f[level] error) warning_count sum(1 for f in findings if f[level] warning) for finding in findings: print(f[{finding[level].upper()}] {finding[location]}: {finding[message]}) print(f扫描完成: {error_count} errors, {warning_count} warnings) return 1 if error_count 0 else 0接入 CI 的价值在于形成分层防护规则引擎拦截低级错误人工审查专注代码逻辑和架构设计。5. 常见问题与排查技巧实录5.1 高频问题速查表我在使用和开发过程中遇到不少问题也收到了不少使用者的反馈整理成一张速查表供遇到类似问题的朋友快速定位问题现象可能原因解决方案执行请求命令时提示“找不到 git”当前环境缺少 Git 或未加入 PATH安装 Git 并确认命令行中能执行 git --version规则引擎扫描结果为空diff 文本中新增行格式解析异常或当前分支和基准分支之间无差异检查分支名拼写确认分支间确实存在 commit 差异创建的审查记录找不到记录保存在 .git/review/ 目录可能被误删或未切换对应 Git 仓库确认当前目录属于目标仓库执行 open-code-review list --allwebhook 通知没有送达目标服务网络不可达或 URL 配置错误用 curl 手动测试 URL确认服务能收到 POST 请求CI 中 ci-scan 报错拉取代码时没有带完整历史导致 git diff 无法解析给 checkout 步骤添加 fetch-depth: 0 参数5.2 我踩过的坑规则引擎误伤怎么处理规则引擎用正则表达式做扫描最大的风险就是误报。我记得有一次给某个项目配置规则时设置了 pattern 是password\s*[:]结果项目里正好有一个测试用例的变量名叫 password_validator每次扫描都会命中搞得开发同事直接在群里喊“被误报了”。后来我给出的方案是两条线并行一是放宽正则表达式把匹配范围缩小到更接近真实密钥定义的上下文比如要求等号右侧必须是引号包裹的字符串且内容长度超过八位二是在配置文件中支持 per-rule 的 exclude_paths 字段明确指定哪些目录或文件可以跳过某些规则。比如测试目录下生成的临时配置文件中包含类似密钥的测试数据这是正常的就应该跳过。rules: - name: secret-key-detection level: error pattern: (api[_-]?key|secret|password)\\s*[:]\\s*[\][^\]{8,} files: - *.py - *.js - *.yaml - *.yml exclude_paths: - test/ - tests/ - fixtures/做了这两个改进后误报率明显下降。这也说明一个道理静态检查工具的价值在于辅助人而不是替代人。规则调得太紧会整天误报让人产生“狼来了”的麻木感调得太松又形同虚设。找到团队能接受的检查强度需要在实际使用中持续调整。5.3 数据迁移与跨仓库复用如果团队之前已经在别的平台上有代码审查记录想要迁移到 open-code-review其实也不用太纠结历史数据。我的建议是最多迁移最近三个月的记录作为参考更早的记录价值不大反而会给新流程的落地增加噪声。open-code-review 本身不提供自动导入功能但 JSON 格式的好处就是方便做数据转换。只要写一个脚本从原平台导出审查数据并映射成如下结构即可这个字段设计对其他平台的审查数据比较友好{ id: review-20241101-1200, author: zhangsan, reviewer: lisi, base_branch: main, head_branch: feature-xxx, created_at: 2024-11-01T12:00:0008:00, status: approved, comments: [] }跨仓库复用方面由于所有审查记录都存于 .git/review/ 目录且不依赖远程服务器团队完全可以把 review 记录目录纳入仓库的版本管理。这样每当有人克隆这个仓库就能看到之前的全部审查历史。不过要注意这会让仓库体积变大一些对于长期活跃的大仓库我建议还是把 .git/review/ 加入 .gitignore 中进行本地持久化同时定期通过脚本归档到团队内部的文件存储服务。5.4 多人协作时的意见冲突处理最后分享一个协作经验。当审查者是多人轮换时很容易出现前后意见不一致的情况——比如第一个审查者要求用 A 方案第二个审查者却觉得 B 方案更好开发者夹在中间很难做。我的解决方案是在意见提交时给每条意见增加一个 optional 标记表示这是建议性意见不强制修改但如果一条意见被连续两个以上审查者同时提出它就自动升级为 mandatory必改级别。open-code-review 的实现是在 JSON 记录里增加一个 agreement_count 字段每条意见被再次提及时自动加一。当 agreement_count 大于等于 2 时show 命令展示这条意见时会带上高亮标记提醒开发者这是多人共识应该优先处理。这个设计避免了“官大一级压死人”或者“谁来审谁说了算”的尴尬局面。6. 一些实操心得和个人体会从开始写 open-code-review 到现在我在自己参与的项目里已经用它完成了上百次代码审查。有个体会比较深轻量级的工具真的能提高流程的执行率。以前用 PR 流程的时候很多小改动大家嫌麻烦干脆直接 push 上去口头说一句“改好了”根本不留记录。现在用 open-code-review发起一次审查就是一条命令的事成本极低大家自然愿意走流程审查记录也就完整了。另外想说一下代码审查工具的价值不在于它能替代人去思考而在于它能让人更专注于真正的思辨。规则引擎先把低级问题拦住人工审查者看到的代码就已经相对干净他们可以把精力放在架构设计、边界条件、潜在 bug 这些真正需要人脑判断的地方。如果你正在为团队寻找一套轻量、开源、不依赖平台的代码审查方案open-code-review 值得一试。它的学习成本很低两条核心命令就能跑通整个流程配置也集中在 YAML 文件里团队统一调整规则非常方便。后续如果你想在这个项目上做二次开发从 Python 源码入手也不会觉得困难。拿它作为团队代码质量建设的第一块基石至少对我来说是过去一年做过最正确的一个技术决定。
阅读完成 · 觉得有帮助？
