哨兵错误仅适用于语义明确、无上下文、跨包契约稳定的场景；需用var全局定义，供调用方做确定性分支判断，且不可携带动态信息；滥用会导致耦合与演进锁死。
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() 输出），否则可能破坏下游的 == 判断。
立即学习“go语言免费学习笔记（深入）”；
- 真实踩坑：某 SDK 升级时把
ErrTimeout改成ErrRequestTimeout，导致所有用==判断的业务逻辑静默跳过重试 - 替代思路：优先定义错误类型（
type ValidationError Struct{ Field string }），用errors.As提取行为；或彻底放弃哨兵，统一用errors.Is+ 包装后的语义标签 - 折中建议：只对 OS 层、协议层、存储层等极少变动的底层错误使用哨兵；业务域错误一律避免
真正难的不是怎么定义一个 ErrNotFound，而是敢不敢在三个月后把它删掉 —— 如果删了会炸一片，那它就已经不是哨兵，而是枷锁了。