Golang全局错误常量与SentinelErrors使用指南

本文深入剖析了Go语言中全局错误处理的核心实践——Sentinel Errors（哨兵错误），指出直接使用errors.New("xxx")定义全局错误会导致每次调用生成新对象，使==比较失效，从而破坏错误类型的可靠识别；正确做法是通过包级var变量（如var ErrNotFound = errors.New("user not found")）一次性声明导出的哨兵错误，并全程配合errors.Is进行语义化判断，以穿透多层错误包装、保障跨层级和跨包的错误识别一致性，同时提醒开发者规避nil误判、init循环、测试mock失配及过度依赖字符串匹配等工程常见陷阱——真正考验团队协作的，不是定义一个错误变量，而是让整个调用链从数据库到HTTP处理器都坚守这一简单却关键的约定。

为什么不能直接用 errors.New("xxx") 定义全局错误

因为每次调用 errors.New 都会创建新对象，== 比较必然失败，导致下游无法可靠判断错误类型。Sentinel errors 的核心是「复用同一个错误值」，而不是复用错误消息。

• 常见错误现象：if err == ErrNotFound 返回 false，即使 err 是 errors.New("not found")
• 正确做法：用变量声明一次，全局只初始化一次
• 不要在函数里重复 var ErrNotFound = errors.New("not found") —— 位置不对就等于没做

如何正确定义和导出 Sentinel 错误常量

Go 中没有真正的「错误常量」（const），必须用 var 声明包级变量，并确保初始化只发生一次。导出名要大写，且命名带 Err 前缀便于识别。

• 推荐写法：

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

• 避免用 fmt.Errorf 初始化 —— 它返回 *fmt.wrapError，底层结构不同，== 仍可能失效
• 如果需带上下文但又想保持可比较性，用 errors.Join 或包装器（如 fmt.Errorf("wrap: %w", ErrNotFound)）后，必须用 errors.Is 判断，而非 ==
• 多个相关错误建议集中定义在 errors.go 文件中，不散落在各处

errors.Is 和 errors.As 在 Sentinel 场景下的真实用途

当错误被多层包装（比如中间件、重试逻辑、日志装饰）后，== 就完全不可靠了。errors.Is 才是 Sentinel errors 的实际落地接口。

• errors.Is(err, ErrNotFound) 能穿透 fmt.Errorf("failed: %w", ErrNotFound) 层级
• errors.As(err, &target) 主要用于自定义错误类型（如实现了 Unwrap() error 的 struct），对纯 errors.New 常量无效
• 性能影响极小：遍历包装链一般只有 1–3 层，开销可忽略
• 兼容性注意：Go 1.13+ 才支持，低于此版本需用第三方库或手动递归 Unwrap()

容易被忽略的边界情况：nil 错误、跨包引用、测试 Mock

看似简单的事，在工程中常因细节翻车。尤其当错误变量被其他包 import，或单元测试需要伪造时。

• 永远检查 err != nil 再调用 errors.Is —— 对 nil 调用会 panic
• 跨包引用时，确保目标包已初始化：如果 pkgA 的 ErrNotFound 依赖 pkgB.init()，而 pkgB 又依赖 pkgA，可能触发 init 循环
• 测试中不要用 errors.New("user not found") 去 mock ErrNotFound —— 即使消息一样，== 也不成立；应直接返回原变量或用 errors.Is 断言
• 如果错误需要携带字段（如错误码、traceID），Sentinel 就不够用了，得切到自定义 error struct + Is() 方法

真正难的不是定义一个 var ErrXXX，而是让整个调用链从 DB 层到 HTTP handler 都统一用 errors.Is 做判断，且没人偷偷用字符串匹配或 == 硬比较。

到这里，我们也就讲完了《Golang全局错误常量与SentinelErrors使用指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！