直接用 log 包在微服务中不够用，因其缺乏服务名、实例id、trace id 区分能力，不支持结构化输出、多级异步写入与滚动切片；zap 通过无锁设计、buffer池和预分配内存实现高性能，比 logrus 快 4–10 倍。
为什么直接用 log 包在微服务里不够用
微服务场景下，日志要能区分服务名、实例ID、请求追踪ID（trace ID），还要支持结构化输出、多级别异步写入、滚动切片——log 包连 JSON 格式都要自己拼，更别说字段动态注入和采样控制。Zap 的 Logger 实例本身是无锁的，底层用 buffer 池和预分配内存避免 GC 压力，实测比 logrus 快 4–10 倍，尤其在高并发打日志时延迟更稳。
初始化 Zap Logger 要绕开两个常见坑
新手常直接用 zap.NewDevelopment() 或 zap.NewProduction()，但这两种方式无法注入服务元信息，且 NewProduction() 默认禁用 caller（看不到哪行代码打的日志），调试时抓瞎。正确做法是用 zap.Config 自定义：
-
Level设为zap.AtomicLevel，方便运行时热更新（比如 DEBUG 级别只开某几个服务） -
EncoderConfig.EncodeLevel必须设为zapcore.CapitalLevelEncoder，否则 Kubernetes 日志采集器（如 fluent-bit）可能无法识别 level 字段 -
OutputPaths推荐同时写stdout和文件（如./logs/app.log），但文件路径必须提前os.MkdirAll，Zap 不会自动建目录
如何把 trace ID、service name 注入每条日志
Zap 本身不提供上下文透传，得靠 logger.With() + context.Context 配合中间件完成。不要在每个 handler 里反复调用 logger.With(zap.String("trace_id", tid))，容易漏或写错键名。
推荐在 HTTP 中间件中统一提取并注入：
func LoggingMiddleware(logger *zap.Logger) gin.HandlerFunc {
return func(c *gin.Context) {
traceID := c.GetHeader("X-Trace-ID")
if traceID == "" {
traceID = xid.New().String() // fallback
}
ctx := context.WithValue(c.Request.Context(), "logger", logger.With(
zap.String("trace_id", traceID),
zap.String("service", "user-service"),
zap.String("method", c.Request.Method),
zap.String("path", c.Request.URL.Path),
))
c.Request = c.Request.WithContext(ctx)
c.Next()
}
}
后续 handler 里用 c.Request.Context().Value("logger").(*zap.Logger) 取即可，避免全局变量或依赖注入容器过度设计。
替换 fmt.Printf 类裸打印时要注意字段类型
Zap 是强类型的：传 int64 就必须用 zap.Int64()，不能用 zap.Int()（后者只接受 int）。Go 的 time.Duration 是 int64 别名，但 Zap 提供了专用的 zap.Duration()，它会自动转成带单位的字符串（如 "123ms"），比手动 zap.String("dur", d.String()) 更可靠。
常见踩坑点：
- HTTP 状态码用
zap.Int("status", c.Writer.Status())，不是zap.String - 错误对象优先用
zap.Error(err)，它会展开err.Error()+%+v堆栈（如果实现了StackTrace()） - 结构体不要直接
zap.Any("req", req)，JSON 序列化可能 panic；先json.Marshal再zap.ByteString，或用zap.Reflect（性能差但安全）
字段命名统一用小写下划线（user_id），别混用驼峰，否则 ELK 或 Loki 查询时字段名不一致。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
