用途:在编写或改动任何错误路径、catch 块、回退、默认值、重试或降级模式时使用,适用于任何语言、任何仓库。需要以 principal-engineering 技能为前置背景。
核心契约:每个 catch 与失败路径必须做且只做三件事之一,并且三种都是响亮的:记录 WARN 或 ERROR 后重抛;记录并返回调用方必须处理的类型化失败(结果类型、密封错误、编译器或契约强制下游确认的状态);记录并进入明确文档化的降级模式(在代码与文档中命名,并有可观测信号表明系统已降级)。
禁止(无例外):裸 catch 后继续执行;catch 后返回默认值(空列表、null、零、缓存副本)掩盖失败;用 ?? 回退及其同类隐藏主路径已失败,除非缺失同时在其他地方响亮暴露。
推论:必需的条目缺失应响亮失败,注册表、配置或目录中缺失属于构建或启动失败,不是静默默认;错误状态必须可见,工作流不能在失败时显得健康;面向运维的修复提示要具体,如“连接失败,检查 REDIS_URL 及 redis 是否响应 PING”;重试有界且可观测;有副作用的操作重放要幂等;降级模式要有边界,跳过并继续需要明确的阈值常量,且可由运维调整,无界降级即慢性吞错;失败路径的可观测性属于最低要求,日志、计数器与告警须随修复一起交付。
处理已有吞错:正在编辑的代码若已吞错,应在本次工作中修复,或明确标记为待还并说明其隐藏内容;评审中新增的静默吞错是自动阻断项,触碰却未标记的既有吞错是对该变更的警告。
常见错误:以“这不该发生”为由吞错;只在 DEBUG 记录;用宽泛 catch 处理窄问题;无人知晓的降级模式;用默认为失败让测试通过。