如何在Golang中定义Sentinel Errors哨兵错误 Go语言预定义错误变量设计

sentinel Error 是预先定义的导出错误变量（如 io.EOF），用于精确、高效、类型安全的错误比较；不用 errors.new 动态构造，因其无法用 == 判断，易导致脆弱的字符串匹配。

什么是 sentinel error，为什么不用 errors.New 直接返回？

go 里 sentinel error 指的是预先定义好的、可导出的错误变量（如 io.EOF），用于在多个包间做精确的错误判断。它不是为了“看起来规范”，而是解决 errors.New("EOF") == errors.New("EOF") 为 false 的根本问题——字符串相等不等于错误语义相等。

用 errors.New 动态构造，会导致调用方只能用 Strings.Contains(err.Error(), "xxx") 这种脆弱方式判断，一旦消息微调就崩；而哨兵错误支持直接用 == 比较，稳定、高效、类型安全。

• 必须是包级导出变量：var ErrInvalidID = errors.New("invalid user ID")，不能是函数内局部变量
• 不要给哨兵错误加动态信息（比如拼入 ID 值），那已不属于哨兵范畴，该用 fmt.Errorf 包裹
• 如果错误需携带上下文（如失败的键名、http 状态码），就别硬塞进哨兵，改用自定义错误类型

如何正确定义和导出 ErrXXX 变量？

定义位置决定可见性，导出规则和普通变量完全一致：首字母大写 + 在包顶层声明。常见错误是把它藏在函数里、或用 const 声明（const 无法赋值给 error 接口）。

package user  import "errors"  // ✅ 正确：包级导出变量，类型是 error var ErrNotFound = errors.New("user not found") var ErrInvalidAge = errors.New("age must be between 0 and 150")  // ❌ 错误：在函数里定义，外部无法引用 func load() {     err := errors.New("failed to load") // 外部拿不到这个值，无法比较 }  // ❌ 错误：const 不能直接是 error 类型 // const ErrBadFormat = "bad format" // 类型是 string，不是 error

• 变量名统一用 ErrXXX 前缀，Go 生态已形成共识，ide 和 linter（如 errcheck）都认这个约定
• 错误信息保持简洁、不含标点结尾（如 "user not found" 而非 "user not found."），方便后续组合使用
• 如果包有多个子模块，哨兵错误应定义在主包（如 user），避免分散在 user/internal/xxx 中导致使用者无法导入

在调用方如何正确判断 sentinel error？

必须用 ==，不是 errors.Is 或 errors.As。后者是为嵌套错误设计的，对纯哨兵反而多一层间接、略慢，且可能掩盖误用（比如把未导出的局部 error 当哨兵用）。

立即学习“go语言免费学习笔记（深入）”；

if err == user.ErrNotFound {     log.Println("user missing, proceed with default")     return DefaultUser } // ✅ 干净、快速、意图明确

• errors.Is(err, user.ErrNotFound) 虽然也能工作，但属于“过度通用”——它会遍历整个错误链，而哨兵错误从不嵌套，没必要
• 绝对不要写 if strings.Contains(err.Error(), "not found")，这绕过了类型系统，且易被日志中间件污染（比如加了 traceID 前缀）
• 如果函数返回的是包装后的错误（如 fmt.Errorf("loading user: %w", user.ErrNotFound)），此时必须用 errors.Is，因为原始哨兵已被包裹，== 失效

哪些场景不该用 sentinel error？

哨兵错误只适用于“固定、有限、跨边界需精确识别”的错误条件。一旦出现以下情况，就该停手，换别的方案。

• 错误需要携带数据：比如 “key "session_123" expired at 2024-05-01”，这时定义 type ExpiredError Struct { Key string; Expires time.Time } 更合适
• 错误种类太多、难以枚举：如 HTTP 客户端把所有状态码都做成哨兵（Err400, Err401, … Err503），不如用 StatusCode 字段 + errors.Is 判断范围
• 错误只在包内部流转、无外部消费方：比如 parser 包里某个私有语法错误，用 errors.New 即可，不必导出
• 你发现要给哨兵加方法（比如 ErrNotFound.Reason()），说明它已超出简单标识用途，该升级为自定义错误类型

最常被忽略的一点：哨兵错误一旦导出，就是 API 的一部分，修改其值（比如从 errors.New("not found") 改成 errors.New("user not found")）虽不破坏编译，但可能让依赖 err.Error() 的旧代码逻辑异常——所以定义时就想清楚语义，之后尽量不动。