技能｜吞噬异常统一留痕治理法

适用场景

代码里散落"抓了异常却什么都不做"的写法，出问题无从定位时。触发词：except: pass、静默失败、吞异常、加了日志还是查不到原因。适用于任何"跑着没报错但结果不对"的系统。

操作步骤

1. 先建统一出口，再改调用点：一个极小的告警模块，提供 告警(位置, 异常, 说明)，同时写标准错误输出与本机日志文件（可配置路径，超上限自动轮转一份）。
   写日志本身永不抛异常、永不打断主流程——否则治理行为自己制造故障。
2. 全量清点：搜索所有"捕获异常但无处理"的写法（含无变量绑定、直接 pass/continue、直接返回默认值这三类），按文件统计数量，先给总数再动手。
3. 逐处补留痕：改成绑定异常变量 + 调用统一出口，说明里带上"哪个对象失败了"（文档名、批次大小、编号），别只写"失败"两个字。
4. 收敛既有的自制告警函数：如果已有某个模块自己写的告警助手，改为转发到统一出口，保持一个出口，不要各写各的。
5. 信息类留痕也走同一出口（如"同名母本去重：A 被 B 取代"），启动时可见，比事后猜强。
6. 编译 + 回归验证：改完全量编译；跑一遍全页面冒烟，确认没有因为加日志引入异常。
7. 验收口径：日志里出现的条目能解释清楚每一条；真实异常告警应为 0，剩下的都是预期内的说明性留痕。

注意边界

• 只补留痕，不改原有降级逻辑（原来返回 None/False/空列表的，照旧），避免顺手改出行为变化。
• 高频路径（如每批次都调用）留痕要带计数/规模信息，便于判断是偶发还是全崩。
• 日志只写本机，不上传；内容里避免完整证件号、住址等敏感字段（异常信息常带长路径，可截断）。

反例避雷

• 各处自己 print/自己写文件 → 日志散落，等于没有。
• 只改"pass"那几处，漏掉直接返回默认值的（数量更多、更隐蔽）。
• 告警函数自己抛异常 → 把可观测性变成新故障源。
• 说明里不带对象标识 → 日志写着"解析失败"，但不知道是哪份文件。
• 改完不编译/不回归 → 少一个变量绑定就会全站报错。

关联笔记

• [[技能｜全页面回归冒烟法]]

实战战绩

2026-09-28 首跑：清点出 18 处静默捕获（应用 5 / 模型层 3 / 文档解析 3 / 其余 7），全部改为统一留痕；顺带发现并修复"索引批次失败仍标记为已建完"的缺陷——这个缺陷正是靠留痕才暴露出来的。日志最终 14 条全为预期内的去重说明，真实异常 0 条。

版本记录