Golang错误包装技巧：Errorf与上下文管理

Go 1.13 引入的错误包装机制让开发者能构建可追溯、可判定的错误链，但真正发挥其威力的关键仅在于两个细节：使用 `%w` 动词正确包装错误，以及为自定义错误类型实现 `Unwrap()` 方法；一旦误用 `%v` 拼接字符串或遗漏 `Unwrap`，再丰富的上下文也会退化为不可检测的“装饰性文本”，导致 `errors.Is` 和 `errors.As` 失效、调试成本陡增——掌握这看似微小却决定成败的包装规范，是写出健壮、可维护 Go 错误处理代码的核心前提。

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 行为不可预测

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang错误包装技巧：Errorf与上下文管理》文章吧，也可关注golang学习网公众号了解相关技术文章。