采集代码的 Code Review 清单：五类 20 项，逐条打勾

采集代码的 review 最容易被「跑得通就行」糊弄过去——反正能出数，细节不重要。直到有一次 review 放过的重试逻辑在生产把请求打爆，我才意识到：采集代码是生产代码，而且是一类有自己专属雷区的生产代码。这篇把多年踩坑沉淀成一份 review 清单，五类 20 项，review 时逐条打勾。

A. 安全与密钥（先看这三条，出事最贵）

1. Key 从环境变量读取，没写死在代码/配置文件里？
2. 日志和报错信息里没有 Key（或打了掩码）？
3. 请求头没被完整打印进日志？

B. 请求与网络（排第二，故障面最广）

4. 超时设置了，且同时覆盖连接和读取两个阶段（timeout=(5, 30)）？
5. 重试有次数上限 + 指数退避 + 抖动，不是无限重试？
6. 只对可重试的错误重试（超时/5xx），参数错误（4xx）直接抛？
7. 并发受控：有界队列或信号量，没有「一把全发」？

C. 数据处理（解析层，日常事故的高发区）

8. 可选字段一律 .get() 兜底，没有硬索引？（snippet、featured_snippet 这类）
9. 类型有防御：rank 被当成数字前确认过它真的是数字？
10. 编码统一 UTF-8（读词表、写文件、发请求三处）？
11. 字段映射集中在一层（归一化），没有散落在各处？

D. 写入与幂等（数据层，跑错一次脏一片）

12. 写入幂等：唯一键 + INSERT OR IGNORE / ON CONFLICT DO NOTHING，重跑安全？
13. 批量提交：按批 commit，没有一条一事务？
14. 数据库连接正确关闭（closing/上下文），没有悬着的写锁？

E. 观测与成本（运维层，没这三条等于盲跑）

15. 日志带 request_id 和 credits_charged（排查和成本归因的地基）？
16. 失败有去处：失败清单、告警或至少日志里能被查出来？
17. 重复查询有缓存（同参数不重复真调）？
18. 测试覆盖：fixture 测试 + 冒烟脚本都在？

清单怎么用（三条纪律）

1. 逐项打勾，不适用也要写明理由——「不适用」本身是有信息量的
2. 一次 review 预算 10-15 分钟，清单太长会变成摆设
3. 清单是活的：每次事故复盘，把「这次该查出来的」加进去；每季度裁剪失效项

踩坑记录

坑 1：清单越来越长。 只加不删，最后 50 项没人看。控制 20 项内，季度裁剪。

坑 2：「不适用」当豁免。 有些项明明适用，勾了个「不适用」跳过。不适用必须写理由，reviewer 可追问。

坑 3：只看代码，不跑一遍。 静态看完就过，冒烟脚本该跑没跑。代码 review 之后补一次端到端冒烟。

坑 4：规则没有「坏例子」。 「可选字段要兜底」不如「如果写 data["snippet"]，提示用 .get()」。每条规则配一个反面示例。

坑 5：只有清单没有记录。 评审结论不存档，回头说不清谁放的。review 记录留档，哪怕一句。

工程清单

1. 五类 20 项：安全 / 请求 / 数据 / 写入 / 观测
2. 逐项打勾，不适用写理由
3. 10-15 分钟预算，清单季度裁剪
4. 每条规则配反面示例
5. review 后补冒烟，结论留档

清单的价值不在「全」，在「每次 review 都会想到这些」——采集代码的雷区是高度可枚举的，把它们固化成打勾动作，比依赖 reviewer 的记性和经验可靠得多。一份 20 项的清单，就是把这些年的学费固化成流程。

清单里的字段语义（request_id、credits_charged、可选字段）见 SerpBase 官方文档。你们的 review 有清单吗？评论区聊聊你加进清单的那条规则。