Sentinel错误使用场景分析与解决办法

Go 中的哨兵错误（sentinel error）并非通用错误处理工具，而是仅适用于语义清晰、无上下文依赖、跨包契约长期稳定的极少数底层场景（如 io.EOF、syscall.ENOENT），必须通过 var 全局定义并供调用方用 == 精确判断；一旦滥用——例如用于携带动态信息的业务错误或频繁变更的 SDK 错误——便会引发隐性耦合、测试脆弱、升级锁死等严重问题，甚至让本该灵活演进的代码变成难以维护的“枷锁”；真正成熟的错误设计，应优先选用可扩展的错误类型配合 errors.As，或语义化包装配合 errors.Is，把“能删掉而不炸”作为哨兵是否合理的终极检验标准。

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，而是敢不敢在三个月后把它删掉 —— 如果删了会炸一片，那它就已经不是哨兵，而是枷锁了。

好了，本文到此结束，带大家了解了《Sentinel错误使用场景分析与解决办法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！