Golang自定义sentinel错误详解

本文深入解析了Go语言中哨兵错误（sentinel error）的正确使用方式与常见误区，强调其本质是通过包级导出的、地址唯一的error变量实现语义化、可比较的错误标识；重点指出不能用errors.New在运行时动态创建错误值作全局比较，必须统一定义在errors.go中并以大写Err前缀导出，同时厘清==与errors.Is的适用场景——前者用于未包装的原始哨兵判断，后者用于穿透%w包装链；最后明确哨兵错误的边界：仅适用于无状态、纯语义的错误分类，一旦涉及上下文信息、结构化字段或类型断言需求，就必须升级为自定义错误类型，二者应协同而非互斥。

为什么不能用 errors.New 直接当全局错误变量用

因为每次调用 errors.New 都会新建一个 error 实例，内存地址不同，== 比较必然失败。下游代码写 if err == ErrNotFound 就永远进不去分支——哪怕错误消息一模一样。

• 哨兵错误的本质是「单例标识」，必须靠同一地址实现值比较
• 导出的变量名必须大写（如 ErrNotFound），否则包外不可见
• 不能在函数里重复声明，比如 func handle() { var ErrNotFound = errors.New("not found") } —— 这不是哨兵，只是个局部变量
• 别用 fmt.Errorf("not found: %w", err) 初始化哨兵，它返回的是 *fmt.wrapError，底层结构不兼容 ==

怎么正确定义一个包级 ErrXXX 变量

在包根目录下建 errors.go，用 var 声明一次、导出、带 Err 前缀：

package user

import "errors"

var (
    ErrNotFound   = errors.New("user not found")
    ErrInvalidID  = errors.New("invalid user ID")
    ErrPermission = errors.New("permission denied")
)

• 所有哨兵集中放一个文件，避免散落在 internal/ 或子模块里——使用者得能 import "yourpkg" 就拿到
• 不要加 const：Go 没有「错误常量」语法，const 无法满足 error 接口要求
• 消息字符串保持简洁，不带动态内容（如 ID、时间戳），否则就该换成自定义错误类型
• 如果包有多个子功能（如 user/auth, user/profile），哨兵仍定义在 user 主包，不拆分

== 和 errors.Is 到底该用哪个

优先用 ==，仅当错误可能被 %w 包装时才切到 errors.Is。

• if err == user.ErrNotFound 最快、最直接，适用于未包装的原始错误
• if errors.Is(err, user.ErrNotFound) 能穿透 fmt.Errorf("loading failed: %w", err) 多层包装
• 别混用：errors.Is(err, errors.New("user not found")) 永远 false —— 你 new 的不是那个哨兵变量
• 测试里别伪造哨兵，比如 return errors.New("user not found")；应直接返回 user.ErrNotFound 或用 errors.Is 断言

什么情况不该用哨兵错误

哨兵只适合「无状态、纯语义标识」的错误。一旦需要携带上下文（比如失败的字段名、HTTP 状态码、重试次数），就必须换路子。

• 错误消息含变量："failed to parse field 'name': invalid format" → 改用自定义结构体 + Unwrap()/Is()
• 需要日志中提取结构化字段（如 StatusCode）→ 自定义类型比字符串拼接可靠得多
• 想支持 errors.As(err, &e) 提取原始错误值 → 哨兵做不到，必须实现接口
• 第三方库返回的错误（如 redis.Nil）已自带哨兵，别自己再造一个同名变量去比

容易被忽略的一点：哨兵错误和自定义错误类型不是二选一，而是协作关系——前者做顶层分类，后者承载细节。错把上下文塞进 ErrInvalidID 的字符串里，后面谁都救不了你。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于Golang的相关知识，也可关注golang学习网公众号。