企业官网建设流程全解析

大概从团队人数超过十五个人开始，代码评审这件事就从一种习惯变成了一种负担。各个仓库里的合并请求散落在不同列表里，谁负责审、审到哪一步、有没有卡在某人手里，基本靠大家自觉和口口相传。我最初也想找现成的代码评审平台，但调研一圈后发现，团队真正缺的不是一个"点通过/打回"的按钮，而是整个评审过程的透明度、可追踪性和可自定义能力。所以就有了这个命名为 open-code-review 的开源项目——一个自托管、Webhook 驱动、数据和规则完全开放的代码审查协作工具。这篇东西不打算讲什么宏大架构，只把从设计到落地过程中真正解决了问题的思路、关键代码和踩过的坑写出来，供有类似需求的人参考。

1. 为什么我要从零写一个开放的代码审查工具

1.1 现成方案看起来够用，实际很难落地

市面上的代码审查能力往往和托管平台深度绑定，适合那种"一个仓库、一个团队、平台自带工作流"的简单场景。但是当仓库数量多起来，团队又横跨后端、前端、数据等多个方向时，问题就暴露出来了：合并请求分散在各个仓库里，没有一个统一视图能看到"今天有哪些评审在等我"；仓库主人、技术负责人的指派逻辑完全靠人工记忆；更麻烦的是，评审时长、响应率、积压数量这些数据拿不到，想推动改进都没有依据。

这还只是功能层面。协作工具往往会沉淀大量团队行为数据，如果这些数据封闭在第三方平台里，导出又受限制，那后续做内部复盘、生成月度报告、和自动化脚本联动都会很痛苦。open-code-review 的出发点就是把这些东西全部打开：部署在自己的服务器上，所有评审任务数据存在自己的数据库里，指派规则、提醒策略、统计口径都可以按团队实际情况调整。开源的意义不在于"代码可见"，而在于"整个评审流程对团队可见、可改、可掌控"。

1.2 项目定位与能力边界

在动手之前我先把边界划清楚了，这比写代码更重要。open-code-review 不是一个托管平台，也不试图取代行级评论功能。它的定位是"评审协作层"：监听代码托管平台推送的事件，把合并请求转成可跟踪的评审任务，负责指派评审人、发送提醒、记录评审结果、产出统计报表。

所以能力边界是：

• 做：收集合并请求事件，建立评审任务；按规则自动指派评审人；分时段提醒与超时升级；统计评审时效与团队负载；开放 REST API 和出站回调。
• 不做：不代替 CI 做静态检查和自动化测试；不提供代码托管；不介入代码存储和权限管理，只通过 Webhook 和只读 API 与托管平台交互。

技术选型上我用了 Python + FastAPI + PostgreSQL，前端是一个很轻的管理页面，部署直接用 Docker Compose。团队小的时候用 SQLite 也能跑，但我建议一开始就上 PostgreSQL，因为后面统计查询会用到窗口函数和百分位计算，SQLite 的性能和表达力都撑不住。

项目结构大致是这样：

open-code-review/ ├── app │ ├── main.py # FastAPI 入口 │ ├── models.py # 数据表定义 │ ├── webhook.py # 事件接收与验签 │ ├── normalize.py # 各平台事件归一化 │ ├── dispatcher.py # 评审人分配逻辑 │ ├── scheduler.py # 提醒与升级任务 │ └── stats.py # 统计查询 ├── config/ │ ├── code_owners.yaml │ └── policies.yaml ├── docker-compose.yml └── README.md

2. 核心流程设计：评审任务从一个合并请求到闭环

2.1 数据模型：评审任务不是一行待办记录

很多工具把评审简单当成一个待办事项，加一行记录就完事了。实际跑起来你会发现远远不够：一个合并请求会经历创建、指派、评论、要求修改、重新推送、合入等多个阶段，每个阶段都要留下痕迹，否则后面统计"平均评审时长""积压数"的时候根本不知道时间口径怎么算。

我设计了三个核心表，第一张是评审请求主表：

CREATE TABLE review_requests ( id BIGSERIAL PRIMARY KEY, event_id VARCHAR(128) NOT NULL, repo VARCHAR(128) NOT NULL, mr_id VARCHAR(64) NOT NULL, title TEXT NOT NULL, status VARCHAR(32) NOT NULL DEFAULT 'pending', author VARCHAR(64) NOT NULL, changed_files JSONB NOT NULL DEFAULT '[]', assignee VARCHAR(64), created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), merged_at TIMESTAMPTZ, UNIQUE (repo, mr_id) ); CREATE TABLE review_comments ( id BIGSERIAL PRIMARY KEY, request_id BIGINT NOT NULL REFERENCES review_requests(id), reviewer VARCHAR(64) NOT NULL, action VARCHAR(32) NOT NULL, -- approve / comment / request_changes content TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE event_log ( id BIGSERIAL PRIMARY KEY, event_id VARCHAR(128) NOT NULL UNIQUE, event_type VARCHAR(64) NOT NULL, payload JSONB NOT NULL, received_at TIMESTAMPTZ NOT NULL DEFAULT now() );

这里有几个设计细节要注意。UNIQUE (repo, mr_id)保证了同一个仓库里的同一个合并请求只有一条评审任务，平台重复推送事件时不会造成任务重复。changed_files一定要存下来，后面分配评审人要靠它匹配代码归属。review_comments单独建表而不是在主表上堆字段，因为一个评审任务可能会有很多次评论、审批动作，用字段存根本存不下，而且统计响应率、首次反馈时间都依赖这些明细数据。event_log是幂等和审计的底座，每一条进来的事件都先落库，处理完之后再更新状态，这样任何环节出错都能重放。

2.2 状态机：防止任务在流转中"漂移"

状态字段如果只是随手写个pending或者open，后面提醒和统计都会出乱子。我给任务定义了一套明确的状态机，每种状态迁移都有触发条件：

状态机的好处是让"现在这个任务到底卡在哪一步"变得可以回答。提醒任务只扫in_review和changes_requested状态的记录，不会误伤已经通过的任务；统计"评审时长"用created_at到merged_at的差值，口径统一之后不同团队之间才能比较。

有一次我在实现时图省事，想省掉changes_requested状态，直接复用in_review加一个标记字段。后来发现这样会导致一个非常隐蔽的问题：要求修改后作者重新推送，系统会认为任务还在被同一个评审人占着，无法触发重新派发。加了独立状态之后，changes_requested → in_review的迁移就是一个非常自然的时机，可以在这一步根据变更量决定是继续原评审人还是重新分配。

2.3 一次完整的事件流转

我把一条合并请求从诞生到闭环的过程串起来看，整个链路是这样的：

1. 开发者在仓库创建合并请求，托管平台向 open-code-review 推送mr.opened事件。
2. Webhook 接收模块验签通过后，把原始事件存进event_log，同时归一化成内部事件。
3. 创建或更新review_requests记录，状态置为pending。
4. 分配模块读取changed_files和code_owners.yaml，结合当前每个人的待审数量计算得分，选出评审人写入assignee，状态置为in_review。
5. 通知模块向评审人推送卡片消息，带上合并请求标题和链接。
6. 评审人评论或审批，动作写入review_comments，状态按上面对应关系更新。
7. 定时任务每小时扫描一次超时未完成的评审，按照配置触发提醒或升级。
8. 合并请求合入后，托管平台推送mr.merged事件，任务进入closed，时间数据流入统计表。

这套链路里最容易忽略的是第 4 步和第 7 步之间的衔接：分配不是只发生在刚创建时，当任务被"要求修改"重新打开后，如果原评审人长期无响应，也要能自动重新派发。所以在状态迁移到in_review的每个入口都复用了同一个分配函数，而不是只在事件处理里写一次。

3. 与代码托管平台的对接：Webhook 接入的工程细节

3.1 报文验签：所有推送进来都要先过这关

Webhook 接口是公网可访问的，任何人都可能往这个地址打请求。如果不验签，攻击者可以伪造合并请求事件，把任务池刷爆，甚至诱导评审人点开恶意链接。所以接收事件的第一步永远是校验签名。

不同托管平台的签名算法大同小异。主流做法是：平台用配置好的密钥对请求体做 HMAC-SHA256 签名，放在请求头里，我们这边用同样的密钥和请求体重算一遍，再用恒定时间比较函数核对。Python 实现如下：

import hashlib import hmac def verify_signature(secret: bytes, payload: bytes, signature: str) -> bool: expected = hmac.new(secret, payload, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)

这里有两个坑要提醒。第一，比较签名的时候千万不能用普通的字符串相等，hmac.compare_digest是恒定时间比较，能防止时序侧信道攻击。第二，验签用的原始请求体必须和生成签名时的内容完全一致。我遇到过的情况是，框架默认把请求体读取后又被 JSON 解析了一次，导致验签时拿到的字节和平台端不一致，折腾了半天才发现要先读原始bytes，验签通过后再做 JSON 解析：

payload_bytes = await request.body() if not verify_signature(secret, payload_bytes, request.headers.get("X-Signature")): raise HTTPException(status_code=401, detail="invalid signature") event_data = json.loads(payload_bytes)

3.2 事件归一化：把不同平台的差异挡在外面

代码托管平台虽然都走 Webhook，但事件命名、字段结构千差万别。同一个"合并请求创建"动作，有的平台叫merge_request，有的叫pull_request，字段更是各有各的叫法。如果业务代码里到处写平台分支判断，后期维护绝对是灾难。

我的做法是在normalize.py里做一层统一的"内部事件模型"，无论哪个平台推送过来，最终都转换成下面这种结构：

{ "event": "mr.opened", "repo": "backend/user-service", "mr_id": "3421", "title": "[feat] 用户中心接入新的登录协议", "author": "dev_a", "changed_files": ["src/api/login.py", "src/models/user.py"], "raw": {...} }

事件类型统一用mr.opened、mr.commented、mr.approved、mr.changes_requested、mr.merged这几个枚举。后续业务代码只认这套模型，新接入一个平台只需要写一个新的解析器，业务逻辑完全不用动。这个抽象层对"开放"的意义很大——任何人都可以贡献自己平台的事件解析代码，而不需要理解我们的业务细节。

3.3 重复推、漏推、时间乱：Webhook 远没有文档里那么可靠

对接 Webhook 之后马上会遇到两个现实问题：重复事件和漏掉事件。

平台为了保证投递，往往会对失败请求做重试，导致同一条事件被推好几次。如果处理逻辑没有幂等，任务会被重复创建，提醒也会重复发。我在event_log上加了event_id唯一索引，落库时用INSERT ... ON CONFLICT DO NOTHING，已经处理过的事件直接忽略。这是处理重复事件最省心的方案。

漏事件比重复更麻烦。有时候是平台端配置变更，有时候是服务重启期间事件丢失。单靠 Webhook 这种"推"模式永远有盲区。我给系统加了一条保底策略：每天凌晨跑一次对账任务，通过托管平台的只读 API 拉取所有尚未合入的合并请求，与数据库里的任务对比，缺失的自动补建。这就是典型的"Webhook 走快路径，轮询走保底路径"双轨设计。事实证明，没有这个对账机制，任务池迟早会漏数据。

3.4 安全与权限边界

安全上我坚持两条原则：入站的 Webhook 只暴露必要端口，启用签名校验；出站访问只读 API 用的令牌存数据库时加密落盘，并且权限最小化——只需要读合并请求列表和评论的权限，不需要写权限。因为很多自动化脚本会把 token 打到日志里或者提交进仓库，写权限泄露的代价太高。

4. 关键模块的实现：分配、提醒与统计

4.1 评审人分配：既要负载均衡，也要熟悉代码

自动分配评审人是最容易翻车的模块。如果简单随机分配，资深开发者可能被分到自己不熟悉、也不负责的模块；如果完全按代码归属分配，代码多的人会被活活压垮。我最后用的是"归属优先 + 负载加权"的评分策略。

首先在配置文件里维护一份代码归属表，类似 CODEOWNERS 的简化版：

code_owners: "src/backend/user": - dev_a - dev_b "src/backend/order": - dev_b "src/frontend/console": - dev_c

合并请求进来后，把changed_files逐条和这些前缀匹配，命中的人获得归属加分。同时统计每个人当前打开的评审数量作为负载分，待审越多分越高。最后综合得分最低的人被选为评审人：

score = 当前待审任务数 × 10 + 归属不匹配惩罚(50) 归属匹配则 score -= 20 取 score 最小的候选者

这样既能保证改动集中在某个人负责的模块时优先派给那个人，又不会让他长期被压榨。因为是取最小值，待审数多的老人会自动把机会让给空闲的人。我见过有的团队用纯轮询，结果一个很资深的开发者一周被安排了二十几个评审，另一个新人闲得没事干。有了负载分之后这种情况基本消失了。

4.2 提醒与升级：把"催促"变成可配置的规则

写评审提醒之前我先问了团队一个问题："你希望多久没人管的时候被提醒？"答案五花八门。有人觉得 24 小时就该提醒，有人认为 48 小时是底线。没有一个配置机制，这种分歧没法调和。所以提醒策略全部做成了配置：

reminder: first_hours: 24 # 超过 24 小时无响应的评审 second_hours: 48 # 超过 48 小时，再次提醒并抄送作者 escalate_hours: 72 # 超过 72 小时，升级给技术负责人 skip_repos: - "legacy/monolith" # 某些仓库不参与提醒 working_days_only: true

定时任务用 APScheduler 每小时跑一次，逻辑很简单：查出状态为in_review或changes_requested且updated_at超过阈值的任务，按档位发送不同力度的通知。但有一个细节很容易忽视——如果评审人已经在评论里给了反馈，只是还没点"通过"，这时候不应该按无响应处理。所以查询时要用NOT EXISTS排除掉最近 24 小时内有过评论动作的任务。

working_days_only这个配置是我血的教训。第一次上线时周末也在发提醒，周一一到办公室，一群人涌过来问为什么休息日被疯狂打扰。后来加了工作日判断，并且把提醒窗口限定在每天 10:00 到 18:00 之间，团队满意度立刻上去一大截。

4.3 统计看板：回答"评审到底卡在哪"

代码评审最怕的是"感觉大家都很忙，但流程就是慢"。统计模块的价值就是把感觉变成数字。我做了三个核心指标：中位评审时长、评审响应时长、个人待审负载。

中位评审时长用百分位函数算，比平均值更抗噪——平均值会被少数几个拖了两周的大任务拉高，中位数才能反映典型体验：

SELECT repo, percentile_cont(0.5) WITHIN GROUP ( ORDER BY extract(epoch FROM (merged_at - created_at)) / 3600 ) AS median_review_hours, count(*) AS closed_count FROM review_requests WHERE status = 'closed' AND merged_at IS NOT NULL AND created_at >= now() - interval '30 days' GROUP BY repo ORDER BY median_review_hours DESC;

响应时长的口径是created_at到第一条评审评论或审批动作的时间差，反映的是"评审人多久开始看这个任务"。这两个指标一个看端到端效率，一个看响应积极性，配合起来能定位瓶颈到底在"没人看"还是"看了之后一直拖着"。

看板不需要花哨，团队最需要的是每天早上打开能看到：昨晚新增多少评审任务、目前积压多少、哪些卡了超过三天、分配给谁。数据能回答这些问题，会议讨论立刻就从"我觉得"变成"数据显示"。

5. 真实部署后的故障复盘与技术调优

5.1 Webhook 爆发式涌入，应用直接卡死

上线第一个月遇到的最严重事故：某天下午有人把一批历史合并请求同步进来，托管平台一次性推了几百条事件，FastAPI 接口直接卡死，数据库连接池打满，整个服务几十秒没有响应。当时我在 Webhook 处理器里直接用同步方式调用了数据库和通知模块，每个请求都占着一个工作协程，事件一多就雪崩。

方案是引入异步队列。第一次图省事用了内存队列，进程重启就丢事件，后来换成了 Redis 列表，Webhook 接收后立即入队返回，后台 worker 慢慢消费。这样接口的响应时间不再依赖下游处理速度，峰值吞吐量提升了几十倍。消费端简化之后长这样：

def consume_events(): while True: item = redis.blpop("review_events", timeout=0) if item: event_data = json.loads(item[1]) try: handle_event(event_data) except Exception: # 失败的事件放回队列，重试次数记录下来 logger.exception("handle event failed")

这是一条非常通用的经验：任何外部系统回调的入口，如果可能面临突发流量，绝对不能同步处理到底。Webhook 接口的第一优先级永远是"快速确认收到"，然后异步慢慢算。

5.2 一条事件被处理了十几遍，提醒发到崩溃

另一次事故由"重试 + 客户端重连"叠加造成。托管平台对失败的投递会重试多次，而我当时有个通知模块在连接异常时会主动重拉最近的事件列表，两者叠加导致同一条合并请求事件被处理了十几遍，评审人收到了十几条一样的提醒。

排查后发现根因就是没有幂等。事件入库时没有唯一约束，handle_event每次都新建任务。修好之后我定了一条铁律：所有从外部进入的数据，第一步必须做去重，要么用数据库唯一索引，要么用业务唯一键（比如repo + mr_id）。去重不是防御性编程，而是和外部系统协作的基本前提。而且event_log表要长期保留，这样才能在出问题时回溯到底哪条事件被重复消费了。

5.3 提醒误报惹毛团队：机器人和草稿被当成真人评审

提醒功能刚上线的时候误报率特别高，团队意见很大。查下来有三个原因：第一，有些仓库的自动化机器人账号也会触发合并请求事件，它们没有真人评审需求；第二，草稿状态的合并请求还不应该进入评审流转；第三，有人开了定时自动合并的机器人，任务被合入前会短暂停留在in_review，被当成积压任务提醒。

每个问题都有对应的过滤规则：按作者账号模式排除机器人；跳过标记为草稿的合并请求；对存在自动合入标记的任务直接放宽提醒。我还加了一个非常实用的开关：合并请求标题里出现[skip-review]、[wip]这类关键词时，任务进入pending而不是in_review，不触发指派和提醒，等作者移除关键词后再次推送事件才正式进入评审。这个小功能后来成了团队使用频率最高的特性之一，连我自己都没料到。它说明了一个道理：工具做得再智能，也必须给使用者留一个明确的手动出口，人知道自己什么时候不该被打扰。

5.4 数据量增长后的索引与清理

系统跑了三个月之后，event_log表已经有几十万行，对账任务的查询开始变慢。排查发现主要是没有及时清理和索引缺失。后来给review_requests的status字段和created_at做了复合索引，提醒查询从全表扫描变成走索引；event_log只保留最近 60 天的原始数据，更早的压缩归档到离线文件，审计需要时再解压查询。现在半夜对账任务跑完只要几秒钟，整体不需要过度设计，但基础索引和归档策略在数据量上来之前就定好，能省掉后面不少麻烦。

6. 把工具继续做"开放"：规则模板化与扩展 API

6.1 仓库级策略全部下沉到配置文件

做到这一步，工具已经从"能用"进入"好用"的阶段。但真正让它变得"开放"的，是把所有策略规则都模板化。不同仓库、不同团队对评审的诉求差别很大：核心支付服务的合并请求要求至少两个评审人通过才允许合入；内部工具类仓库只需要一个评审人；文档仓库甚至可以免评审。这些策略不应该硬编码在代码里，而应该让每个使用方自己定义。

我在config/policies.yaml里按仓库维护了一套策略：

repositories: "payment/core-settlement": required_reviewers: 2 auto_assign: true remind_sla_hours: [12, 24, 48] close_inactive_days: 14 "internal/ops-tools": required_reviewers: 1 auto_assign: false remind_sla_hours: [48] "docs/knowledge-base": required_reviewers: 0 auto_assign: false

配置加载做成"启动读取 + 定时热加载"，改配置不需要重启服务，十分钟内自动生效。这样做还有一个额外的好处：新仓库接入时不需要改任何代码，只要往配置里加一段就行。开放不只是代码开源，更是指产品的扩展边界是配置化的，使用方可以根据自己的流程调整行为。

6.2 对外 API 与出站回调：让数据流动起来

最后一步是开放数据访问能力。open-code-review 对外提供了一组只读和操作型的 REST API，让外部工具可以把评审数据接进自己的自动化流程：

GET /api/v1/reviews?status=open&repo=payment/core-settlement GET /api/v1/reviews/{id}/comments POST /api/v1/reviews/{id}/assign {"reviewer": "dev_b"} GET /api/v1/statistics/team?days=30

出站回调设计成可配置的 Webhook，评审任务变成in_review、approved、changes_requested等关键状态时，可以向团队内部的即时通讯机器人、自动化运维系统推送消息。这样整个评审流程能嵌入已有的协作体系，而不是强行把大家拉到另一个新工具里。设计出站回调时我只遵循一条原则：回调内容是事件通知，不携带敏感代码内容，避免消息系统成为信息泄露的渠道。

这些 API 还有一个更长远的意义——任何使用这个工具的人都可以把数据导出做自己的分析、开发自己想要的面板。open-code-review 这个名字里的"open"不只是代码层面的开放，我希望它在数据层面也是开放的，团队对自己的评审行为数据拥有完全的控制权和二次开发权。

我自己在这个工具上跑了大半年之后，最大的体会是：代码评审最大的敌人从来不是缺少工具，而是流程本身不透明。哪怕只是一个很小的开源项目，只要能把每一步都摊开让所有人看见，团队的协作质量就会明显上一个台阶。这个方向还有很大的扩展空间，比如评审行为画像、跨仓库的改进建议、更细粒度的自动指派策略，后续我会继续在这个基础上迭代，也真心希望有类似痛点的人一起参与进来，共同把它打磨成更顺手的样子。