17370845950

哨兵错误仅适用于语义明确、无上下文、跨包契约稳定的场景；需用var全局定义，供调用方做确定性分支判断，且不可携带动态信息；滥用会导致耦合与演进锁死。

Go 中的 sentinel error 不是“能用就行”的兜底方案，而是**仅在语义明确、无上下文需求、跨包契约稳定**时才适用的特殊约定。滥用它会导致错误处理僵化、测试脆弱、升级困难。

什么时候该用 errors.New 定义哨兵错误？

核心判断标准：调用方是否需要根据这个错误做**确定性分支逻辑**，且该错误不携带任何动态信息（比如路径、ID、时间戳）。

• 典型场景：文件不存在（io.EOF）、系统调用失败（syscall.ENOENT）、数据库记录未找到（gorm.ErrRecordNotFound）
• 必须满足：错误值在包级别导出、全局唯一、生命周期与包一致（不能在函数内反复 errors.New）
• 反例：用户输入校验失败（应带字段名）、HTTP 请求超时（应含 timeout 值）、JSON 解析失败（应含偏移量）——这些都该用 fmt.Errorf("...: %w", err) 包装

为什么 err == ErrNotFound 能工作？

因为 errors.New 返回的是 *errors.errorString 指针，而 Go 接口比较底层实际比的是底层值的指针地址 —— 所以只有用同一个变量赋值的错误实例才会相等。

• ✅ 正确写法：

  var ErrNotFound = errors.New("not found")

  其他包直接比较 if err == mypkg.ErrNotFound
• ❌ 错误写法：

  if err == errors.New("not found")

  每次都新建对象，永远不相等
• ⚠️ 注意：一旦错误被 fmt.Errorf(... %w) 包装，原始哨兵值就被“藏”在链里，此时必须用 errors.Is(err, ErrNotFound) 判断

哨兵错误最大的隐性成本：包耦合与演进锁死

一旦对外暴露了 ErrInvalidInput，所有调用方代码就和你的包版本强绑定 —— 你不能重命名、不能合并、甚至不能加文档注释（因为会影响 err.Error() 输出），否则可能破坏下游的 == 判断。

• 真实踩坑：某 SDK 升级时把 ErrTimeout 改成 ErrRequestTimeout，导致所有用 == 判断的业务逻辑静默跳过重试
• 替代思路：优先定义错误类型（type ValidationError struct{ Field string }），用 errors.As 提取行为；或彻底放弃哨兵，统一用 errors.Is + 包装后的语义标签
• 折中建议：只对 OS 层、协议层、存储层等极少变动的底层错误使用哨兵；业务域错误一律避免

真正难的不是怎么定义一个 ErrNotFound，而是敢不敢在三个月后把它删掉 —— 如果删了会炸一片，那它就已经不是哨兵，而是枷锁了。