GolangUberZap错误字段记录技巧

本文深入解析了在 Golang 中使用 Uber Zap 日志库时，如何正确记录自定义错误类型的结构化字段——指出 zap.Error() 仅调用 err.Error() 输出扁平字符串、无法展现 Code、TraceID、嵌套原因等关键信息这一常见痛点，并给出优雅解决方案：为自定义 error 类型实现 MarshalLogObject 方法，结合 zap.Object() 实现字段级、递归式结构化日志输出，同时提醒避免重复记录和中间件冲突等实战陷阱，助你写出清晰、可追溯、易排查的高质量错误日志。

zap.Error() 为什么不能直接传入自定义 error 类型

因为 zap.Error() 内部只认实现了 Error() 方法的接口，且默认用 err.Error() 字符串做日志输出——它不展开结构体字段，也不递归打印嵌套错误。你传一个 *MyError 进去，日志里只看到一行字符串，关键字段（比如 Code、TraceID）全丢了。

• 常见错误现象：zap.Error(err) 后发现日志里只有 "failed to process request"，没看到你加的 StatusCode: 400 或 RetryAfter: 30s
• 根本原因：zap 不解析 error 的字段，只调用 Error() 方法取字符串
• 正确做法是把 error 当成普通结构体，用 zap.Object() 或显式字段打点传入

如何让 zap 记录 error 的结构化字段（含嵌套）

别依赖 zap.Error()，改用 zap.Object() + 自定义 MarshalLogObject() 方法。这是最干净、可复用的方式。

• 给你的 error 类型实现 MarshalLogObject(enc zapcore.ObjectEncoder) 方法
• 在方法里手动调用 enc.AddString()、enc.AddInt() 等写入每个字段
• 如果 error 包含另一个 error（比如用 fmt.Errorf("wrap: %w", orig)），记得递归调用 enc.AddObject() 处理它
• 示例：

  func (e *MyError) MarshalLogObject(enc zapcore.ObjectEncoder) {
      enc.AddString("message", e.Error())
      enc.AddInt("code", e.Code)
      enc.AddString("trace_id", e.TraceID)
      if e.Cause != nil {
          enc.AddObject("cause", zap.Error(e.Cause))
      }
  }

zap.Error() 和 zap.Object() 混用时的坑

别在一个 logger.Error() 调用里既用 zap.Error(err) 又用 zap.Object("err", err)——这会重复记录，而且字段名冲突（前者固定叫 error，后者叫 err），排查时容易误判。

• 错误写法：logger.Error("request failed", zap.Error(err), zap.Object("err", err))
• 更隐蔽的坑：某些中间件（如 gin-zap）自动加了 zap.Error(err)，你在 handler 里又手动加一次，日志里就出现两份 error 字段
• 兼容性注意：老版本 zap（MarshalLogObject 支持不稳定，建议锁死 go.uber.org/zap@v1.24.0+
• 性能影响：MarshalLogObject 是同步调用，如果 error 结构复杂或含 IO（比如读文件取堆栈），会影响日志吞吐，慎在高频路径上做重操作

不用改 error 类型也能临时打结构化字段

如果你没法改第三方 error 类型（比如 github.com/pkg/errors 或 go.opentelemetry.io/otel/codes），就别硬套 MarshalLogObject，用字段平铺更实际。

• 用 errors.As() 或类型断言提取底层结构，再逐个传字段：

  var myErr *MyError
  if errors.As(err, &myErr) {
      logger.Error("request failed",
          zap.String("message", myErr.Error()),
          zap.Int("code", myErr.Code),
          zap.String("trace_id", myErr.TraceID),
      )
  }

• 对标准库 net.OpError、os.PathError 这类，直接访问 err.Err、err.Path 等公开字段
• 别试图用反射自动提取——字段名大小写、导出性、嵌套深度都会导致行为不一致，线上环境容易崩

结构化记录 error 字段这事，核心不是“能不能”，而是“要不要让日志系统知道你的 error 长什么样”。Zap 不会猜，你得明说；字段一多，漏一个就可能卡住线上问题定位。

好了，本文到此结束，带大家了解了《GolangUberZap错误字段记录技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！