Go 1.13+ errors库需用%w封装才支持自动展开，errors.New()和无%w的fmt.Errorf()返回扁平错误；errors.Is/As依赖Unwrap()逐层匹配，自定义错误只需实现Unwrap()方法即可兼容。

Go 1.13+ 的 errors 标准库不支持嵌套错误的自动展开，必须显式调用 errors.Unwrap() 或用 errors.Is()/errors.As() 判断；直接用 == 或 strings.Contains(err.Error(), ...) 会漏掉封装后的底层错误。

为什么 errors.New() 和 fmt.Errorf() 行为不同

errors.New() 返回一个不可展开的原始错误；fmt.Errorf() 加了 %w 动词才支持封装（即返回实现了 Unwrap() error 方法的类型）。没加 %w 就和 errors.New() 一样是“扁平”错误。

• ✅ 正确封装：fmt.Errorf("failed to open file: %w", os.ErrNotExist)
• ❌ 未封装：fmt.Errorf("failed to open file: %v", os.ErrNotExist) —— 后续无法用 errors.Is(err, os.ErrNotExist) 匹配
• ⚠️ 注意：%w 只接受单个 error 类型参数，不能写成 %w: %w 或拼接多个

errors.Is() 和 errors.As() 的实际使用边界

这两个函数内部会循环调用 Unwrap()，逐层检查是否匹配目标错误或能转成目标类型。但它们只对用 %w 封装的错误链有效，对 fmt.Errorf("%s: %v", msg, err) 这类字符串拼接完全无效。

• errors.Is(err, os.ErrNotExist)：检查错误链中是否存在某个具体错误值（支持指针比较）
• errors.As(err, &target)：尝试将错误链中任一环节转成指定类型（比如自定义错误结构体），成功则返回 true
• ⚠️ 常见坑：errors.As(err, &myErr) 中 myErr 必须是指针类型变量，且该类型需实现 error 接口；若传值或类型不匹配，返回 false 且不报错

自定义错误类型如何兼容标准库错误链

只要在自定义错误结构体中实现 Unwrap() error 方法，就能被 errors.Is()、errors.As() 和 errors.Unwrap() 正确识别。不需要额外接口继承或注册。

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

type MyError struct {
    Msg  string
    Code int
    Err  error // 底层封装的错误
}

func (e *MyError) Error() string { return e
.Msg }
func (e *MyError) Unwrap() error { return e.Err } // ? 关键：暴露下一层

• 如果 Err 字段为 nil，Unwrap() 应返回 nil，否则会导致无限循环
• 避免在 Unwrap() 中做耗时操作或 panic，它可能被日志、中间件等频繁调用
• 不建议在 Unwrap() 中返回新构造的错误（如 fmt.Errorf(...)），会破坏错误链的原始上下文

真正难的不是怎么封装，而是团队里有人忘了加 %w，或者在日志里只打印 err.Error() 而丢掉了整个错误链——这时候再好的封装也白搭。