fmt.Errorf 默认不支持错误嵌套，需用 %w 动词才能正确包装错误；自定义错误类型须实现 Unwrap() 方法以支持错误链穿透，否则丢失可判定性。

fmt.Errorf 本身不支持错误嵌套，直接用会丢失原始错误链

Go 1.13 引入了错误包装（wrapping）机制，但 fmt.Errorf 默认不包装错误——除非显式使用 %w 动词。如果写成 fmt.Errorf("failed to open file: %v", err)，原始 err 就被转成字符串丢进新错误里，再也无法用 errors.Is 或 errors.As 检查或提取。

• ✅ 正确包装：fmt.Errorf("failed to open file: %w", err)
• ❌ 错误降级：fmt.Errorf("failed to open file: %v", err)（原始错误被 toString 化）
• ⚠️ 注意：%w 只接受单个 error 类型参数，不能跟其他动词混用在同一个占位符里（如 %w: %s 是非法的）

用 errors.Wrap（来自 github.com/pkg/errors）还是原生 %w？

老项目可能还在用 github.com/pkg/errors 的 Wrap，它能自动附加调用栈和上下文；但 Go 原生 %w 不带栈信息，也不提供额外字段。二者不兼容：用 %w 包装的错误，pkg/errors.Cause 拿不到原始错误；反过来也一样。

• 新项目优先用原生 %w：标准库支持、无额外依赖、errors.Is/As 直接可用
• 需要调试时快速定位 panic 点？原生方案得靠 debug.PrintStack() 或日志打点，pkg/errors 的 Wrap 自带栈但已停止维护
• 混合使用风险高：两个包装系统共存时，errors.Unwrap 只能解开一层原生包装，对 pkg/errors 返回的错误返回 nil

如何安全添加上下文而不破坏错误类型判断？

加上下文的本质是“包装”，不是“拼接字符串”。只要坚持用 %w，就能保持错误可判定性。但要注意两件事：一是别在中间层把错误转成 string 再造新 error；二是避免多层无意义包装，比如连续三次 fmt.Errorf("step A: %w", fmt.Errorf("step B: %w", err))，会让 errors.Is 查找变慢（需逐层 Unwrap）。

• 推荐模式：

  if err != nil {
      return fmt.Errorf("process user %d: %w", userID, err)
  }

• 避免模式：

  if err != nil {
      return errors.New("process user " + strconv.Itoa(userID) + ": " + err.Error())
  }

  （彻底丢失包装能力）
• 性能提示：超过 5 层嵌套时，errors.Is 平均要多做几次指针解引用，但一般业务场景影响可忽略

自定义错误类型想支持包装，必须实现 Unwrap() 方法

如果你写了带字段的结构体错误（比如含 Code、TraceID），又希望它能被 %w 包装并保留原始行为，就必须手动实现 Unwrap() error 方法。否则，即使你用 %w 包了它，外层 errors.Is 也无法穿透到它内部的 cause。

• 示例：

  type MyError struct {
      Msg   string
      Code  int
      Cause error
  }
  
  func (e *MyError) Error() string { return e.Msg }
  func (e *MyError) Unwrap() error { return e.Cause }

• 没实现 Unwrap？那它就是“终端错误”，再怎么 %w 包也只是一层死胡同
• 注意：不要在 Unwrap 里返回 nil 以外的非 error 类型，否则 errors.Is 行为不可预测