1. 从零搭建代码评审工具：为什么我要造这个轮子
第一次接触代码评审这件事，是在一个十来人的小团队里。那时候大家提交代码基本靠自觉，谁写完了在群里喊一嗓子，有空的人就点开看看，没空就算了。结果就是线上事故频发，回滚成了家常便饭。后来团队大了，开始用商业化的代码托管平台自带的评审功能，问题确实少了很多，但新的麻烦又来了——评审意见散落在各个提交记录里，想统计一下“这个月大家一共提了多少条有效意见”“哪类问题最常出现”，几乎无从下手。
这就是我做open-code-review这个项目的起点。它不是一个要替代现有代码托管平台的工具，而是一个轻量级、可自托管、专注于评审数据沉淀与流程编排的辅助系统。核心目标很明确：把代码评审从“平台功能”变成“团队资产”。它适合那些已经有一定评审流程、但希望把评审数据用起来的中小团队，也适合想学习代码评审系统底层设计的开发者。
说白了，这个项目解决的是三个具体问题：第一，评审意见的结构化存储，让每条意见都能被检索、被统计；第二，评审流程的可配置化，不同团队对“什么算通过”的定义不一样，不能一刀切；第三，评审质量的可度量，通过数据反推流程哪里卡住了。
我见过太多团队把评审当成走过场，点个“同意”就完事。这个项目的价值就在于，它逼着你把评审这件事想清楚——你的通过标准是什么？谁来把关？意见怎么闭环？想不清楚，配置就写不出来。下面我把整个搭建和使用的过程拆开讲，包括我踩过的坑和后来总结出来的经验。
2. 核心架构拆解：评审数据到底该怎么存
2.1 为什么不用现成的数据库表结构
刚开始我图省事，直接照着代码托管平台的API返回结构建表。提交记录一张表，评论一张表，评审人一张表，看起来挺规整。跑了一个月就发现不对劲：同一个提交在不同分支上可能有不同的评审状态，同一个评论可能被多次回复形成讨论串，评审人还可能中途换人。这些关系用简单的三张表根本表达不清楚。
后来我重新设计了数据模型，核心思路是把评审事件当成不可变的日志流。每一次状态变更——提交发起评审、添加评论、修改结论、重新指派——都作为一条独立的事件记录写入。当前状态通过回放事件流计算得出。这样做的好处是，任何历史时刻的评审状态都能还原，统计口径也不会因为状态覆盖而丢失数据。
具体来说，核心表有这么几张：
| 表名 | 作用 | 关键字段 |
|---|---|---|
| review_event | 存储所有评审事件 | event_id, review_id, event_type, actor, payload, created_at |
| review_snapshot | 定期快照，加速查询 | review_id, snapshot_data, version |
| reviewer_profile | 评审人画像 | reviewer_id, expertise_tags, active_hours |
| rule_config | 评审规则配置 | rule_id, scope, condition, action |
事件类型我定义了十来种，常用的有review_created、comment_added、comment_resolved、approval_given、change_requested、reviewer_assigned。每种事件的 payload 结构不同，但都遵循同一个原则：只记录发生了什么，不记录当前是什么。这个设计决策在后面做统计报表的时候帮了大忙。
2.2 评审规则的配置化设计
不同团队对评审的要求差异巨大。有的团队要求至少两人同意才能合并，有的团队只要求一个人看过就行，还有的团队对特定目录的修改要求特定人员审批。如果把这些逻辑硬编码在代码里，每换一个团队就要改一次代码，维护成本太高。
我的做法是设计一套基于条件的规则引擎。每条规则由三部分组成：作用范围、触发条件、执行动作。作用范围可以是仓库、分支、目录甚至文件类型；触发条件可以是修改行数超过阈值、涉及敏感文件、提交者不在白名单等；执行动作可以是要求额外审批人、自动添加标签、阻止合并等。
规则配置用 YAML 格式，举个例子：
rules: - name: "核心模块双人评审" scope: paths: - "src/core/**" condition: min_changed_lines: 50 action: required_approvals: 2 notify: - "core-team" - name: "文档修改快速通道" scope: paths: - "docs/**" - "*.md" condition: max_changed_lines: 100 action: required_approvals: 1 auto_merge: true这套规则引擎的实现并不复杂，核心就是一个条件匹配器加一个动作执行器。但设计的时候要注意，规则的优先级和冲突处理必须明确。我的做法是规则按顺序匹配，第一条匹配上的规则生效，后面的不再检查。这样虽然牺牲了一些灵活性，但避免了规则冲突带来的不可预测行为。
2.3 评审意见的结构化处理
评审意见最麻烦的地方在于，它天然是非结构化的文本。一句“这里逻辑有问题”到底指的是什么？是边界条件没处理，还是变量命名不规范，还是算法复杂度太高？如果不做结构化，统计出来的数据毫无意义。
我的方案是半自动结构化。在提交评论的时候，系统会提示选择问题类型（逻辑错误、性能问题、代码风格、安全问题、可读性建议等），同时允许自由文本补充。对于没有选择类型的评论，后台会用一个简单的关键词匹配器做初步分类，准确率大概七成左右，剩下的靠人工补标。
这里有个经验：不要试图用纯自动的方式做分类。我试过用文本分类模型，训练数据不够的情况下准确率还不如关键词匹配。后来改成“人工标注为主、自动补标为辅”，数据质量立刻上来了。而且标注这个动作本身就在提醒评审人：你提的这条意见到底属于哪一类？想清楚了再写，意见质量也会提高。
3. 环境搭建与部署：从裸机到跑通第一条评审
3.1 依赖选择与版本锁定
这个项目后端用 Python 写，Web 框架选了 FastAPI，数据库用 PostgreSQL，缓存和消息队列用 Redis。选 FastAPI 的原因很简单：异步支持好，自动生成 API 文档，类型提示友好。PostgreSQL 是因为需要 JSONB 字段来存事件 payload，同时事务支持完善。Redis 用来做事件流的缓冲和实时通知。
版本锁定这件事我必须单独强调。早期我没锁版本，结果某次部署的时候 FastAPI 从 0.95 升到 0.100，中间有个破坏性变更导致所有路由的依赖注入全部报错。从那以后我学乖了，所有依赖都用pip-compile生成锁定文件，部署时严格按锁定文件安装。
# 生成锁定文件 pip-compile requirements.in --output-file requirements.txt # 部署时安装 pip install -r requirements.txt数据库迁移用 Alembic，每次改表结构都生成一个迁移脚本，绝不手动改数据库。这个习惯在多人协作的时候尤其重要，否则你永远不知道生产环境的表结构到底是什么样。
3.2 最小可运行配置
如果你想快速跑起来看看效果，不需要完整的生产环境配置。一个最小的可运行配置只需要三样东西：一个 PostgreSQL 实例、一个 Redis 实例、一份配置文件。
配置文件我放在config/local.yaml，内容大概长这样：
database: host: "localhost" port: 5432 name: "open_code_review" user: "reviewer" password: "reviewer_pass" redis: host: "localhost" port: 6379 db: 0 server: host: "0.0.0.0" port: 8000 debug: true review: default_required_approvals: 1 auto_assign: true notification_channel: "log"启动步骤就三步：建库、迁移、起服务。
# 建库 createdb open_code_review # 迁移 alembic upgrade head # 起服务 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000跑起来之后访问http://localhost:8000/docs就能看到自动生成的 API 文档。我建议先用文档里的接口手动发几条评审事件，感受一下数据流是怎么走的。这比直接看代码理解得快。
3.3 接入现有代码仓库的方式
这个项目本身不托管代码，它通过 Webhook 和 API 与现有的代码托管平台对接。对接方式有两种：一种是平台主动推送事件到本系统，另一种是本系统定时拉取平台的评审数据。
推送方式实时性好，但需要平台支持 Webhook 配置。拉取方式通用性强，但会有延迟。我的建议是两者结合：Webhook 负责实时事件，定时拉取负责补偿丢失的事件和同步历史数据。
对接的时候有个坑要注意：不同平台的 Webhook payload 结构差异很大，而且同一个平台不同版本的事件格式也可能不同。我的做法是在接入层做一层适配器，把各种平台的 payload 统一转换成内部事件格式。适配器用插件方式加载，新增一个平台只需要写一个适配器类，不用改核心代码。
class BaseAdapter: def parse_event(self, raw_payload: dict) -> ReviewEvent: raise NotImplementedError class PlatformAAdapter(BaseAdapter): def parse_event(self, raw_payload: dict) -> ReviewEvent: # 把平台A的格式转成内部格式 return ReviewEvent( event_type=self._map_type(raw_payload["action"]), actor=raw_payload["sender"]["login"], payload=self._extract_payload(raw_payload), )适配器模式在这里的价值在于，核心逻辑不依赖任何具体平台。哪天要换平台，或者同时对接多个平台，只需要增加适配器，核心的评审流程和统计逻辑完全不用动。
4. 评审流程编排：从提交到合并的完整链路
4.1 评审发起与自动指派
评审发起这个环节，最容易出问题的是指派谁。手动指派的话，发起人可能总是找那几个熟人，导致评审负载不均，而且容易形成小圈子。自动指派的话，如果算法太简单，比如轮询，又可能把前端代码指派给后端工程师，评审质量堪忧。
我的方案是基于专家标签的加权指派。每个评审人有一组专家标签（比如frontend、backend、database、security），每个仓库或目录也有一组标签。指派的时候计算评审人标签与目标标签的匹配度，再结合当前负载（待评审数量）做加权排序，选 top N 作为候选人。
def assign_reviewers(review, candidates, n=2): scored = [] for c in candidates: match_score = compute_tag_match(review.tags, c.expertise_tags) load_penalty = c.pending_reviews * 0.1 score = match_score - load_penalty scored.append((c, score)) scored.sort(key=lambda x: x[1], reverse=True) return [c for c, _ in scored[:n]]这个算法不复杂，但效果比轮询好很多。实测下来，评审意见的专业度明显提升，因为指派给的人确实懂这块。当然，标签体系需要维护，新来的同事要记得打标签，这个靠流程约束。
4.2 评论与讨论的线程管理
评审评论不是孤立的，它们会形成讨论串。一个评论可能引出回复，回复又引出新的回复，最后形成一个树状结构。如果只是简单地把评论按时间排序平铺，阅读体验很差，而且容易漏掉关键讨论。
我的做法是显式维护评论的父子关系。每条评论有一个parent_comment_id字段，根评论的该字段为空。前端展示的时候按树形结构渲染，支持折叠和展开。后端查询的时候用递归 CTE 一次性把整棵树拉出来，避免 N+1 查询。
WITH RECURSIVE comment_tree AS ( SELECT * FROM review_comment WHERE parent_comment_id IS NULL AND review_id = :review_id UNION ALL SELECT c.* FROM review_comment c INNER JOIN comment_tree ct ON c.parent_comment_id = ct.comment_id ) SELECT * FROM comment_tree ORDER BY created_at;这里有个细节：评论的解决状态要能独立追踪。一条根评论可能引出五条回复，其中三条讨论的是同一个问题，另外两条是另一个问题。如果只给根评论标记“已解决”，粒度太粗。我的做法是允许任意评论被标记为“已解决”，并且解决状态会向上冒泡——当一条评论的所有子评论都解决后，父评论自动标记为已解决。这样既保留了细粒度，又不会让根评论一直挂着未解决状态。
4.3 审批门槛与合并拦截
审批门槛的配置前面讲过了，这里重点说合并拦截的实现。当评审状态不满足合并条件时，系统需要阻止合并操作。但这里有个矛盾：如果拦截太严格，会阻塞正常流程；如果太宽松，又失去了把关的意义。
我的策略是分级拦截。把不满足的条件分成“硬性阻断”和“软性警告”两类。硬性阻断的条件比如“必需审批人未审批”“存在未解决的严重问题评论”；软性警告的条件比如“评审人数量少于建议值”“评审时长超过平均值”。硬性条件不满足时直接拒绝合并请求，软性条件不满足时允许合并但记录一条警告日志。
def check_merge_eligibility(review): blockers = [] warnings = [] if review.approvals < review.required_approvals: blockers.append("审批人数不足") if review.has_unresolved_critical_comments(): blockers.append("存在未解决的严重问题") if review.reviewer_count < review.suggested_reviewers: warnings.append("评审人数量偏少") return { "eligible": len(blockers) == 0, "blockers": blockers, "warnings": warnings, }这个设计的好处是，紧急情况下可以绕过软性警告，但硬性阻断必须解决。实际使用中，硬性阻断真正拦住的问题并不多，但它的存在本身就是一种威慑，让大家知道有些底线不能碰。
5. 数据统计与质量度量：让评审效果看得见
5.1 评审效率指标的计算口径
统计这件事，口径比算法重要。同样叫“平均评审时长”，从提交到第一次评论算，和从提交到最终合并算，结果可能差好几倍。我的做法是明确定义每个指标的计算口径，并在界面上标注清楚。
常用的几个指标：
| 指标名称 | 计算口径 | 用途 |
|---|---|---|
| 首次响应时长 | 提交到第一条评论的时间差 | 衡量评审人的响应速度 |
| 评审闭环时长 | 提交到最终合并/关闭的时间差 | 衡量整体流程效率 |
| 评论密度 | 评论数 / 变更行数 | 衡量评审细致程度 |
| 问题发现率 | 标记为问题的评论数 / 总评论数 | 衡量评审有效性 |
| 返工率 | 合并后回滚或修复的提交数 / 总合并数 | 衡量评审质量 |
这些指标单独看意义不大，要结合趋势和对比才有价值。比如首次响应时长突然变长，可能是评审人负载过高；问题发现率突然下降，可能是评审人开始敷衍了。我在系统里做了一个简单的趋势图，按周展示这些指标的变化，异常波动会自动标红。
5.2 评审人画像与负载均衡
评审人画像这个功能，一开始我觉得是锦上添花，后来发现是刚需。画像的核心数据包括：擅长领域、平均响应时长、评论质量评分、当前负载。这些数据汇总起来，就能回答“这个评审该派给谁”和“为什么最近评审变慢了”这两个问题。
评论质量评分是个主观指标，我的做法是让提交者给评论打分。每条评论旁边有一个“有帮助/没帮助”的按钮，提交者可以快速反馈。积累一段时间后，每个评审人的平均得分就出来了。这个分数不公开排名，只用于内部参考和负载调整。
负载均衡方面，我设置了一个软上限：当某个评审人的待评审数量超过阈值时，自动指派会跳过该评审人，除非没有其他候选人。阈值默认是 5，可以根据团队规模调整。这个机制有效防止了“忙的人越来越忙，闲的人越来越闲”的马太效应。
5.3 从数据反推流程改进
数据统计的最终目的是驱动流程改进。我每个月会看一次评审数据，重点关注三个问题：哪些环节耗时最长？哪类问题反复出现？哪些规则从未被触发？
举个例子，有段时间我发现“首次响应时长”的中位数是 4 小时，但 90 分位是 26 小时。这说明大部分评审响应很快，但有一小部分拖了很久。进一步分析发现，拖久的评审集中在周五下午提交的。于是我们调整了自动指派策略，周五下午提交的评审会优先指派给下周一周二有空的人，并且自动发送提醒。调整之后，90 分位降到了 12 小时。
另一个例子是，我发现“代码风格”类评论占比很高，但这类评论对代码质量的提升有限。于是我们在提交前增加了一个自动格式化检查，把风格问题拦截在评审之前。调整之后，评审评论中“逻辑错误”和“安全问题”的占比明显上升，评审的有效性提高了。
6. 踩坑实录：那些让我熬夜排查的问题
6.1 事件流乱序导致的统计偏差
事件流设计有个天然问题：事件到达顺序不等于发生顺序。Webhook 推送可能延迟，定时拉取可能补录旧事件，多个来源的事件混在一起，如果不做排序处理，统计结果就会出错。
我遇到过一次典型的事故：某天的“评审闭环时长”突然变成负数。排查发现，一个补录的历史事件被当成了新事件，它的时间戳比当前时间早，导致计算时长时出现了负值。修复方案是在事件写入时强制按事件发生时间排序，并且对乱序到达的事件做缓冲处理——如果新事件的时间戳早于最近一条事件，就插入到正确位置而不是追加到末尾。
def insert_event(event): last_event = get_last_event(event.review_id) if last_event and event.occurred_at < last_event.occurred_at: # 乱序事件，需要重新排序 reorder_events(event.review_id) else: append_event(event)这个坑的教训是：不要假设事件到达顺序等于发生顺序。任何分布式系统里，这个假设都不成立。
6.2 评论树递归查询的性能问题
评论树用递归 CTE 查询，在评论数量少的时候没问题。但当一条评审有几百条评论、嵌套层级很深的时候，递归查询的性能急剧下降。我遇到过一条评审加载了 8 秒才出来，用户体验极差。
优化方案是限制递归深度 + 懒加载。默认只加载前三层评论，更深的层级在用户点击“展开”时再按需加载。同时给parent_comment_id加索引，给review_id加索引，查询速度提升了一个数量级。
CREATE INDEX idx_comment_parent ON review_comment(parent_comment_id); CREATE INDEX idx_comment_review ON review_comment(review_id);另一个优化是缓存评论树。评论树的变化频率不高，可以缓存起来，有新的评论事件时再失效。我用 Redis 缓存序列化后的评论树，命中率大概 85%，效果很好。
6.3 规则引擎的优先级冲突
规则引擎刚上线的时候，我收到一个反馈：某个目录的修改既匹配了“核心模块双人评审”规则，又匹配了“文档修改快速通道”规则，结果系统不知道该用哪个，随机选了一个执行。这显然不可接受。
修复方案是显式定义规则优先级。每条规则有一个priority字段，数值越小优先级越高。匹配的时候按优先级排序，第一条匹配的规则生效。同时增加了一个规则冲突检测工具，在配置加载时检查是否有规则的作用范围重叠且优先级相同，如果有就报错。
rules: - name: "核心模块双人评审" priority: 10 scope: paths: ["src/core/**"] # ... - name: "文档修改快速通道" priority: 20 scope: paths: ["docs/**", "*.md"] # ...这个坑的教训是：任何配置系统都要考虑冲突处理。用户不会按照你设想的顺序写配置，你必须假设最坏情况。
6.4 通知风暴与静默策略
通知功能上线后，有个同事抱怨说他一天收到了 200 多条通知，根本看不过来。排查发现，每次评论、每次状态变更都会触发通知，而且没有聚合。一个人如果参与了多个评审，通知量就会爆炸。
解决方案是通知聚合 + 静默期。同一个评审在 30 分钟内的多条通知合并成一条摘要发送。非工作时间的通知延迟到下一个工作时间发送。用户还可以自定义通知偏好，比如只接收“被指派”和“被提及”的通知，其他的一律静默。
def should_notify(user, event): if user.preferences.get("mute_all"): return False if event.type in user.preferences.get("muted_types", []): return False if is_quiet_hours(user.timezone): return False return True这个功能看起来简单，但对用户体验的影响巨大。通知太多和通知太少一样糟糕，关键是让用户感觉到“每一条通知都值得看”。
7. 一些让系统更好用的细节打磨
7.1 评审模板与检查清单
评审质量参差不齐，很多时候是因为评审人不知道该看什么。我加了一个评审模板功能，发起评审时可以选择模板，模板里预置了一组检查项。评审人逐项确认，系统自动记录哪些项已检查、哪些项有问题。
模板内容可以自定义，我常用的一个后端评审模板包含这些检查项：
- 边界条件是否处理（空值、越界、并发）
- 错误处理是否完善（异常捕获、日志记录、用户提示）
- 数据库操作是否有索引支持
- 是否有硬编码的配置项
- 是否有安全风险（注入、越权、敏感信息泄露）
这个功能上线后，评审意见的覆盖面明显变广，以前经常被忽略的安全问题现在被频繁提及。而且新同事上手更快，照着清单看就行，不用凭感觉。
7.2 评审意见的闭环追踪
评审意见提了之后，有没有被处理？这个问题如果不追踪，评审就变成了“提了白提”。我的做法是给每条问题评论一个状态机：待处理、处理中、已解决、已忽略。提交者可以更新状态，评审人可以确认解决。
状态变更会触发通知，而且未解决的问题会阻塞合并（前面提到的硬性阻断）。这个机制确保了每条意见都有回音，不会石沉大海。
class CommentStatus(Enum): PENDING = "pending" IN_PROGRESS = "in_progress" RESOLVED = "resolved" IGNORED = "ignored" def can_merge(review): unresolved = [c for c in review.comments if c.status == CommentStatus.PENDING] return len(unresolved) == 0实际使用中，“已忽略”这个状态很有用。有些意见确实不需要处理，比如“这个变量名可以更好”但当前名字也没问题。允许忽略，但要求填写忽略理由，这样既尊重了评审人的意见，又给了提交者灵活度。
7.3 与现有工作流的集成方式
这个系统不是孤立的，它需要和现有的工作流集成。我提供了几种集成方式：命令行工具、API、Webhook 回调。命令行工具适合本地开发时快速查看评审状态；API 适合和其他系统对接；Webhook 回调适合触发外部动作，比如自动部署。
命令行工具我用 Python 的click库写，用起来大概是这样：
# 查看待我评审的列表 ocr list --assignee me # 查看某个评审的详情 ocr show REVIEW-123 # 快速审批 ocr approve REVIEW-123 --comment "LGTM"这个工具虽然简单，但日常使用频率很高。开发者不用打开浏览器就能完成大部分操作，效率提升明显。
8. 关于这个项目的一些个人体会
做这个项目最大的收获，不是技术上的，而是对代码评审这件事本身的理解。以前我觉得评审就是找bug，后来发现找bug只是其中一小部分。评审更重要的是知识传递、规范落地、风险预警。一个健康的评审流程，能让新人在几个月内熟悉代码库，能让团队的技术规范真正被执行，能在问题进入生产环境之前拦住它。
技术层面，我最大的体会是数据模型的设计决定了系统的上限。事件流的设计让后面的统计和回溯变得容易，如果当初用了状态覆盖的方式，很多分析根本做不了。另一个体会是配置化不是万能的，规则引擎虽然灵活，但配置本身也需要维护，规则太多太复杂反而会成为负担。我的建议是先从最简单的规则开始，遇到具体问题再加规则，不要一开始就设计一个大而全的规则体系。
如果你打算自己搭一套类似的系统，我的建议是：先跑通最小闭环，再逐步加功能。最小闭环就是“提交评审 → 添加评论 → 审批通过 → 记录数据”这四步。把这四步做扎实，后面的统计、画像、规则都是锦上添花。反过来，如果最小闭环都没跑通，加再多功能也是空中楼阁。
最后分享一个我常用的调试技巧：在开发阶段，我会写一个事件回放脚本，把生产环境的事件流导出到本地，然后回放一遍，观察系统状态的变化。这个脚本帮我发现了无数边界情况，比单元测试覆盖的场景还全面。如果你也在做类似的数据流系统，强烈建议你写一个这样的工具。
