zap.Error() 不能直接传入自定义 error 类型，因其仅调用 err.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，用字段平铺更实际。
立即学习“go语言免费学习笔记（深入）”；
- 用
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等公开字段 - 别试图用反射自动提取——字段名大小写、导出性、嵌套深度都会导致行为不一致，线上环境容易崩
