SentinelError模式：错误变量定义技巧

小伙伴们有没有觉得学习Golang很有意思？有意思就对了！今天就给大家带来《Sentinel Error模式：定义预定义错误变量的最佳实践》，以下内容将会涉及到，若是在学习中对其中部分知识点有疑问，或许看了本文就能帮到你！

应该，但需封装：用 var 声明顶层哨兵错误，优先 errors.New；需上下文或扩展时升级为自定义类型并实现 Unwrap() 返回自身；包装必须用 %w，导出错误名以 Err 开头且慎用。

Go 里该不该用 var ErrXXX = errors.New("xxx") 定义 Sentinel 错误？

应该，但得加一层封装。直接裸用 errors.New 创建的错误变量，无法携带上下文、不支持比较语义（比如 errors.Is）、也不利于后期扩展为带字段的错误类型。

常见错误现象：写了个 var ErrNotFound = errors.New("not found")，后来想在日志里加请求 ID，发现没法动态注入；或者调用方用 == 比较失败——因为 errors.New 每次都新建实例，地址不同。

• 始终用 var 声明顶层错误变量，别在函数里重复 errors.New
• 优先用 errors.New 而不是 fmt.Errorf 初始化 Sentinel 错误（后者隐含格式化开销，且易误加参数）
• 如果未来可能需要携带字段（如码、追踪 ID），现在就定义为自定义类型，哪怕暂时只实现 Error() 方法

为什么 errors.Is 找不到你定义的 ErrXXX？

因为 errors.Is 依赖错误链中的“底层哨兵值”匹配，而你可能无意中把它包掉了。比如用了 fmt.Errorf("wrap: %w", ErrNotFound) 是 OK 的，但 fmt.Errorf("wrap: %v", ErrNotFound) 就断链了——%v 触发 Error() 输出字符串，丢掉原始错误引用。

使用场景：HTTP handler 中判断是否返回 404，或重试逻辑里跳过特定错误。

• 所有包装必须用 %w 动词，不能用 %s、%v 或字符串拼接
• 自定义错误类型若要支持 errors.Is，需在 Unwrap() 方法中返回哨兵变量（或 nil）
• 测试时用 errors.Is(err, pkg.ErrNotFound)，别用 err == pkg.ErrNotFound（后者只对未包装的顶层错误有效）

Sentinel 错误该放在 package 还是 internal/？

公开暴露的错误（调用方需要显式判断并处理的）必须放在 package 顶层；仅内部使用的哨兵错误应移入 internal/ 或私有变量（首字母小写），否则会污染导出 API。

性能影响：无。但兼容性影响大——一旦导出，就不能删、不能改类型、甚至不能改错误文本（有些下游用 strings.Contains(err.Error(), "timeout") 这种反模式硬匹配）。

• 导出错误变量名必须以 Err 开头，如 ErrTimeout，符合 Go 社区惯例
• 如果错误只在本包内判断（比如某个 retry loop），定义为小写变量 errInvalidState 即可
• 不要为每个 HTTP 状态码都导出一个 ErrStatus400——状态码映射应由 handler 层统一处理，错误类型聚焦业务语义

要不要给 Sentinel 错误加错误码字段？

要，但别一开始就加结构体。先用纯 var + errors.New，等真出现多语言提示、监控分类、或需要和外部系统对齐码值时，再升级为带字段的类型。过早抽象反而增加调用方负担。

容易踩的坑：有人一上来就定义 type NotFoundError struct{ Code int; Msg string }，结果发现 errors.Is(err, pkg.ErrNotFound) 失败——因为新类型没实现 Unwrap() 返回哨兵值。

• 升级路径：从 var ErrNotFound = errors.New("not found") → 改为 var ErrNotFound = ¬FoundError{}，其中 notFoundError 是未导出类型
• Unwrap() 方法必须返回 ErrNotFound 自身（或 nil），才能维持 errors.Is 链路
• 错误码字段建议用常量定义（如 const CodeNotFound = 404），别硬编码在结构体里

事情说清了就结束。最常被忽略的是：Sentinel 错误的生命期比你想的长得多——它一旦导出，就变成 API 的一部分，改名、删掉、甚至改错信息，都可能让下游 panic。

本篇关于《SentinelError模式：错误变量定义技巧》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！