1. 为什么我会自己动手写一个代码评审工具

做了这么多年开发，代码评审这件事，我一直觉得是“人人都知道重要，但很难坚持做好”的环节。团队里 code review 做得松的，基本就是合并前点个通过；做得严的，又容易变成大型辩论现场，效率低还伤感情。我一直在想有没有一种方式，能让评审这件事既保持质量，又能减轻人的负担。后来我决定自己动手，才有了这个 open-code-review 项目的雏形。

这个项目不是要替代人工评审，而是做“第一道筛子”。把那些明显的低级问题、风格问题、安全漏洞在提交阶段就拦下来，让人工评审把精力放在真正的逻辑设计和架构合理性上。如果你所在的团队还没建立成熟的评审流程，或者你是一个人维护多个项目，希望有个不挑食的代码“体检员”，那这篇文章应该能给你一些启发。

项目本身是一个开源的、可自托管的代码评审辅助工具，定位介于静态检查工具（比如 ESLint、SonarQube）和人工评审之间。它最大的特点是可以对接多种代码托管平台，在 MR/PR 提交时自动触发，通过插件化的方式运行一系列检查规则，再把结果以行级评论的形式反馈到代码差异上。说白了，它就是一个“长在代码仓库里的自动评审助手”。

我用 Go 语言实现了核心框架，这样部署就只是一个二进制文件，不依赖 Node 或 JVM 那一整套环境。整套系统由三部分组成：事件解析器、规则引擎和评论适配器。事件解析器负责把不同平台的 Webhook 请求标准化成统一的评审上下文；规则引擎按配置顺序执行各类检查插件；评论适配器再把结果格式化成目标平台的行级评论。这种分层设计从第一天起就考虑到了平台多样性和规则可扩展性。

如果你也在为团队评审效率发愁，或者单纯想给自己写的代码多加一道质量关卡，这篇文章里的设计思路、核心代码、部署方式和踩坑记录，应该正好是你需要的。

2. 整体设计拆解：先想清楚“评审什么”和“怎么反馈”

2.1 三类评审目标，决定了工具的功能边界

动手写代码之前，我花了很久思考一个问题：自动化的代码评审工具，到底应该在哪些场景下真正有用？答案直接影响架构设计。

我最后把评审目标分成三类。第一类是风格统一性检查，团队里最常见的争议往往不是算法优劣，而是缩进用空格还是 Tab、变量命名是 camelCase 还是 snake_case、import 顺序是否一致。这类问题机器最擅长发现，也不需要有太多“智能”。第二类是缺陷模式检测，包括空指针风险、资源未释放、错误被吞掉等，这类问题有相对固定的代码模式，规则引擎可以做得不错。第三类是安全风险扫描，比如硬编码密钥、SQL 注入拼接、依赖版本存在已知漏洞，这些靠纯人工检查容易遗漏，而通过规则库和漏洞库联动能覆盖很大范围。

把目标想清楚之后，整个工具的功能边界也就清晰了：它不追求理解业务逻辑，只聚焦在“规则可描述、结果可验证”的检查项上。这也让规则引擎的设计变得简单而可控。后续接入新检查能力时，只需要新增一个插件，而不是改动核心框架。

2.2 插件化架构：核心处理流程“零修改”

在设计上我做了一个硬性要求：核心框架里不写任何具体的检查逻辑。所有检查能力都通过插件形式提供，每个插件只负责一件事，输入是统一标准化后的评审上下文，输出是检查结果列表。

这个决定的直接好处是扩展成本低。比如我后来想加入一个检查 Dockerfile 最佳实践的规则，只需要写一个新的插件包，在配置里注册一下，核心框架一行不用动。另一个好处是隔离性，某个插件运行时 panic 不会拖垮整个评审流程，我会在插件调用的入口做 recover 处理，单个插件失败只记录日志，不影响其他检查项。

插件之间还可以做数据共享。比如“改动文件列表”会被每个插件用到，我会在上下文对象里缓存这些数据；再比如“依赖版本清单”会被安全插件和版本检查插件共用，放在上下文属性中避免重复解析。通过一套轻量级的上下文传递机制，插件实现了“各查各的，但数据不重复计算”。

2.3 触发方式：Webhook 实时触发加定时全量扫描

评审工具要有存在感，但不能打扰人。我在触发策略上做了两种模式。

第一种是事件实时触发，对接代码托管平台的 Webhook，MR/PR 创建、更新、评论时触发增量评审。这种模式反馈最快，开发者在提交代码后几分钟内就能在 MR 页面看到行级评论。第二种是定时全量扫描，对接 CI 的定时任务，对默认分支做全量代码扫描，处理那些在 MR 中没有被覆盖到的历史代码。两种模式共用同一套评审引擎，只是入口不同，这个设计让我在后续维护时省了很多心。

增量评审的计算逻辑是核心之一。事件解析器拿到 Webhook 请求后，要调用托管平台 API 获取 MR 的改动文件列表和 diff 内容，再针对每一行改动运行规则。只评改动的行，而不评整个文件，既减少噪音又提升性能。这个逻辑听起来简单，但实现时细节不少，后面我在“常见问题”里会专门聊 diff 解析的坑。

3. 核心细节解析：规则引擎、评论定位与配置体系

3.1 规则引擎：每个规则都是一个独立函数

规则引擎是 open-code-review 的心脏。我把每条规则定义成一个接口的实现，接口长这样：

type Rule interface { Name() string Severity() Severity Check(ctx *ReviewContext) ([]Finding, error) }

Check接收的是整个评审上下文，里面包含改动文件、diff 行映射、仓库配置、参与人员等。每个规则只依赖上下文里的信息，然后把发现的问题以Finding结构返回：

type Finding struct { File string Line int Severity Severity Message string RuleName string Suggestion string }

Finding中的 File 和 Line 是评论定位的关键信息，因为行级评论必须精确到文件和行号。这里我要强调一个经验：规则返回的行号必须是从 diff 中解析出来的新文件行号，而不是旧文件行号，否则评论会定位到错误的位置。这听起来是小事，但几乎所有人都在这上面踩过坑。

3.2 全局暂存区：一次改动跨多个文件共享

早期的版本里我是每个文件独立跑一遍规则，后来发现一个严重问题：跨文件分析根本没法做。比如“新增了一个函数但没有写单测”就属于跨文件规则，还有“导入了某个包但是只用于测试却放到了正式依赖里”也是。

于是我在ReviewContext里增加了一个全局暂存区（Global Store），本质是一个线程安全的 map，允许规则在自己的 Check 中写入跨文件的数据，并在后续规则中读取。比如代码覆盖率插件会把已覆盖函数名列表写入暂存区，然后“未测试新函数”检查规则从暂存区读取该列表做差集。这个机制让规则从“点状检查”升级为“面状分析”，能做的事一下子多了很多。

代价是规则之间有了隐式依赖。为了降低耦合，我在每个规则包的自述文件里明确声明“依赖哪些 Key 的暂存区数据”，并且提供统一读写接口，而不是让规则直接操作 map。这样保持了数据流清晰，就算规则之间互相调用也不会乱成一锅粥。

3.3 行级评论的定位策略与容错

行级评论是提升评审体验的关键。我第一次做评论适配器时，直接把 Finding 里的行号提交给平台 API，结果发现 GitLab 和 GitHub 的评论 API 对“行”的定义并不完全一致，GitHub 要求 line 是 diff 中的 position，而 GitLab 要求 new_line 或 old_line，品牌差异导致我在两个平台上的首版实现都翻过车。

后来我统一在核心层做行号转换，把 diff 解析后的新老行号对照表缓存下来，各个适配器只管按目标平台的规格从对照表中取相应行号。具体定位优先顺序是：新文件行号不存在就用旧文件行号，旧行号不存在就回落为文件级评论，绝不因为定位失败而丢弃整个 Finding。这种“降级策略”确保了高优先级问题一定能反馈出来，只是呈现形式可能不那么完美。

3.4 配置体系：单文件、分层覆盖、标注解释

配置模块我用的是 YAML 单文件、从上到下分层覆盖的设计。全局默认配置在文件顶部，然后支持按仓库、按目录、按文件扩展名逐层覆盖。这样团队可以在根目录放一个默认配置，子项目如果特殊需求，可以再放一个覆盖配置。

配置里的每个规则都能控制开关、严重级别和参数。比如下面这个片段：

rules: no-sql-injection: enabled: true severity: error params: patterns: ["SELECT.*FROM.*WHERE.*\\+"] require-test-file: enabled: true severity: warning params: testSuffix: "_test.go"

为什么用 YAML 而不是 JSON？我的理由是 YAML 支持注释，团队在评审配置里可以写清楚每条规则的目的和例外情况，后续维护成本低很多。配置文件的加载顺序也很有讲究，我会先加载内置默认配置，再加载仓库级配置，最后加载命令行传入的覆盖配置，优先级依次递增。这个“从宽松到严格”的设定，是为了保证开箱即用时不会因为默认规则太严而劝退使用者。

4. 实操记录：从初始化到对接 GitHub 全流程

4.1 初始化项目与目录规划

我用 Go 模块初始化项目，目录结构刻意做得干净明确。主程序入口在最外层，内部按职责分成四块：核心引擎、插件集合、平台适配器、运维相关配置。这种分法让代码边界清晰，新人接手时一眼就能知道该往哪里加代码。

核心引擎里再分几个子包：事件解析、上下文构建、规则注册、结果聚合。插件集合则是按语言或者领域归类，比如 Go 专属规则、通用安全规则、仓库规范规则等。平台适配器里我实现了 GitHub、GitLab 和 Gitea 三个版本，都是通过各自 OpenAPI 对接评论和 MR 信息。

这里有个小建议：适配器千万别做成“写入一堆 if-else 判断平台”的巨石代码，应该让每个适配器实现统一接口，上层调度完全不知道具体平台差异。这样以后要接新的代码托管平台，只需新增一个包，注册一下自己的平台标识即可。

4.2 配置 Webhook 与密钥管理

我以 GitHub 为例，说下完整接入步骤。首先在仓库 Settings 里的 Webhooks 页面添加一个新的 webhook，Payload URL 填写部署好服务的地址加/webhook/github，Content type 选择application/json，Secret 填一个随机字符串，然后勾选 Pull requests 和 Issue comments 事件。

服务端收到请求时，代码里要通过 HMAC 校验签名，确保请求确实来自 GitHub 而不是伪造的：

func verifySignature(payload []byte, signature string, secret []byte) bool { mac := hmac.New(sha256.New, secret) mac.Write(payload) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(signature)) }

签名校验是一个很容易被忽略的安全点，很多人图方便在测试阶段跳过校验，结果服务被公网扫描器当成回调肉鸡刷了无数遍。我的建议是生产环境必须打开校验，而且 Secret 不要写在配置文件里明文存储，而是通过环境变量注入，部署平台一般都有密钥管理能力，可以自动注入。

4.3 上下文构建与事件过滤

构建评审上下文是整个流程里逻辑最重的一环。事件解析器拿到 webhook 请求后，先解析出事件类型，然后根据类型从请求中提取仓库名、MR 编号、触发人等元信息，再调用 GitHub API 获取 MR 的 diff 内容。

其中事件过滤非常重要：比如一个 MR 里只有文档改动，那就完全不需要运行规则，可以直接返回；如果一个 MR 改了 500 个文件，那后面所有插件都可能超时，需要提前做过大限制。我设置了单次评审文件数上限（默认 100 个文件），超过上限会触发告警，并把该 MR 标记为“超大 MR，建议人工拆分评审”。这个设定帮我避免了很多服务雪崩的问题。

上下文对象里还包含目标分支和源分支的快照，这可以方便某些规则做分支对比，比如检查是否把调试代码合并到了 main 分支。同时我会把此次评审的配置也塞进上下文，这样规则读取配置时不用每次重新加载文件。

4.4 评论聚合与去重策略

规则跑完之后，结果会进入聚合器。聚合器做两件事：去重和分级。去重是因为不同规则可能报同一个问题，比如安全扫描和代码规范检查可能会同时抓住“使用了不安全的函数”，如果不去重，MR 页面会刷出两条同位置评论，体验很差。

聚合器按“文件+行号+规则名”生成唯一键，相同键的评论只保留严重级别最高的一条，其他作为补充信息合并到消息里。分级则是指所有评论先按 error、warning、info 排序，然后按规则名排序，保证同级别的评论也有稳定顺序。评论内容的模板我统一用“发现的问题说明 + 具体原因 + 修改建议 + 参考文档链接”四个段落，让开发者收到评论后不需要额外搜索就能知道怎么改。

5. 常见问题与排查技巧实录

5.1 diff 行号错位的坑

第一个大坑就是 diff 行号错位。GitHub 的 diff 里 hunk 头那行@@ -l,s +l,s @@的含义是旧文件从第 l 行开始共 s 行，新文件从第 l 行开始共 s 行，两部分的行号是独立递增的。如果你只解析了新文件行号，那在新增代码场景下没问题，但在修改和删除的场景下，行号就对不上了。

我的解决办法是写一个 diff 解析函数，把 hunk 体的每一行按照“新增、删除、上下文”分类，同时维护新旧两个计数器：

func parseHunk(lines []string) []LineMapping { mappings := []LineMapping{} oldLine, newLine := 0, 0 for _, line := range lines { switch line[0] { case '@': // 解析 hunk 头，重置计数器 fmt.Sscanf(line, "@@ -%d,%d +%d,%d @@", &oldLine, _, &newLine, _) case ' ': mappings = append(mappings, LineMapping{Old: oldLine, New: newLine}) oldLine++ newLine++ case '-': mappings = append(mappings, LineMapping{Old: oldLine, New: 0}) oldLine++ case '+': mappings = append(mappings, LineMapping{Old: 0, New: newLine}) newLine++ } } return mappings }

这个函数返回的LineMapping列表就是行号对照表。每条规则返回新行号后，适配器在对照表里找对应的旧行号，再根据平台 API 要求提交。做这层转换时我还加了一个基于文件路径的缓存，避免同一个文件在多个规则里被重复解析 diff。

5.2 Webhook 超时和重试

第二个高频问题是 Webhook 超时。代码托管平台对 webhook 的响应时间限制一般很紧，GitHub 是 10 秒，GitLab 略宽松但也不会给你太久。如果你在 webhook 回调里同步跑完所有插件，基本必超时。

我的处理方式是异步执行：webhook 入口仅做签名校验，把消息写入本地队列后立刻返回 200。后台 worker 从队列拉取事件，构建上下文，运行插件，然后把结果推送到平台上。这样既避免超时，也让服务的吞吐量稳定很多。队列我用的是 Go 的内置 channel，简单可靠，没有引入额外的消息中间件。如果想把系统拆成多副本部署，后续把 channel 换成 Redis 队列或者 NATS 也很方便，因为入口和 worker 之间的数据格式已经定好了。

5.3 插件 panic 拖垮整个评审

第三个坑是插件 panic。我上线第一周就遇到一个第三方依赖在特定版本下会数组越界，只要某个规则触发到这个路径，整个评审流程直接崩掉，MR 上的评论啥也没有，用户还以为是没配置好。

从那之后我给插件调用加了 recover：

func runRuleWithRecover(rule Rule, ctx *ReviewContext) (findings []Finding, err error) { defer func() { if r := recover(); r != nil { err = fmt.Errorf("rule %s panicked: %v", rule.Name(), r) log.Errorf("rule %s panicked, stack: %s", rule.Name(), debug.Stack()) } }() return rule.Check(ctx) }

同时加了一个“熔断”机制：同一个插件在连续 5 个 MR 中都 panic 时，该插件自动禁用，并在下次事件推送时通过评论告知管理员手动恢复。这样单个插件的问题不会演变成为整体服务的故障，也方便我在后台定位到底是哪个插件不稳定。

5.4 评论噪声控制

评论太多没人看，评论太少没价值，这里有个平衡问题。我做了三条规则来控制噪声。第一，重复问题合并，同一个文件里连续三行都是同类风格问题，我会合并成一条评论，列出涉及行号范围。第二，建议类评论默认不推送到 MR 页面，而是写入一个汇总报告，通过机器人账号在 MR 下留一条“本次评审共发现 3 个潜在问题和 14 条风格建议”的总结评论，开发者按需展开查看。第三，允许用户通过评论指令控制噪声，比如在 MR 里说“skip-style-check”就能临时关闭风格类规则，这在重构场景下非常实用。

好的评审工具应该是“该说话的时候说话，该安静的时候安静”，这个原则贯穿了评论模块的全部设计。

5.5 常见问题速查表

6. 后续演进方向与个人体会

open-code-review 做到现在这个版本，已经稳定服务了我个人和几个朋友团队的日常开发。目前它支持自定义规则插件，也提供 HTTP API 手动触发评审，对于大多数团队来说已经够用了。如果接下来要让它服务更大规模的团队，我觉得有三个方向值得投入：一是引入机器学习做更智能的缺陷模式识别，二是做更细致的权限管控和评审指标统计，三是支持多仓库批量评审和跨仓库变更影响分析。

回归到最初动手做这个项目的动因，我想说的其实很简单：好的工具不一定多复杂，关键是它能不能稳定地解决一个真实问题。自动代码评审工具不会取代人，但它能把人从繁琐的低效劳动里解放出来，让评审变成一件真正有创造性和成就感的事。如果你也有类似的困扰，不妨试着搭一套自己的评审工具，从一条最简单的规则开始，逐渐让它成为你代码流转过程中最可靠的伙伴。