zap在gin中不可直接替换默认日志，必须全程控制初始化、字段注入与写入安全：需锁定writesyncer、禁用自定义时间格式化、关闭采样、预置通用字段、结构体注入logger、显式sync，否则将丢结构、增开销、漏上下文。
zap 在 Gin 中不是“插上就能用”的日志替换，直接套用 zap.NewProduction() 或硬桥接 log.Printf 会丢结构、吃性能、漏上下文——真正可用的集成必须绕过 Gin 默认中间件的生命周期陷阱，从初始化、字段注入到写入安全全程控制。
为什么 gin.Logger() 中间件不能直接换成 zap.Logger
因为 gin.Logger() 是一个闭包函数，内部直接调用 fmt.Fprintf 写 os.Stdout，它不接受任何外部 logger 实例；强行在中间件里 new 一个 zap.Logger 并调用 Info()，会导致：
• 每次请求都重建 encoder 和 sink，CPU 开销翻倍
• 字段无法继承（比如 service_name、env）
• panic 恢复时丢失 trace_id 等关键字段
• zap.S() 全局 sugar 实例未锁，在高并发下可能 panic
初始化时必须锁定 WriteSyncer 并禁用时间格式化
裸写文件句柄（如 os.OpenFile）在多 goroutine 下会 panic；而默认的 time.Now().Format() 时间编码每条日志触发一次内存分配，压测中 GC 压力陡增。
正确做法是：
- 用
zapcore.Lock(zapcore.AddSync(&lumberjack.Logger{...}))包裹 writer - encoder 必须设
EncodeTime: zapcore.ISO8601TimeEncoder，而非自定义func(t time.Time, enc zapcore.PrimitiveArrayEncoder) - 显式关闭采样：
zap.AddSampler(zapcore.NewSampler(...))或直接不用zap.NewProduction()，改用zap.New(core)手动构造
在 Gin handler 中安全注入请求级字段
别在 middleware 里对每个请求都调用 logger.With(zap.String("req_id", uuid)) —— 字段合并有反射开销，且易导致内存逃逸。
更稳的方式是：
- 提前预置通用字段：
globalLogger = logger.With(zap.String("service", "user-api"), zap.String("env", "prod")) - 把
*zap.Logger注入到 handler struct receiver 中，而非塞进c.Request.Context()
例如：type UserHandler struct { logger *zap.Logger } func (h *UserHandler) Login(c *gin.Context) { h.logger.Info("login start", zap.String("ip", c.ClientIP())) } - 错误处理统一走
echo.HTTPErrorHandler或 Gin 的gin.RecoveryWithWriter替换，内部调用logger.Error("http_error", ...)，避免 recover 后上下文字段丢失
日志切割与 flush 时机必须显式控制
lumberjack 不是“开箱即用”的安全轮转器：它本身不提供 flush 接口，若进程异常退出（如 kill -9），缓冲区日志会丢失；zapcore.NewTee 多输出时若没配好 sync 逻辑，也会丢日志。
关键动作：
- 所有
defer logger.Sync()必须放在main()函数末尾，不能只在 init 里 defer - HTTP 服务 shutdown 时要显式调用
logger.Sync()，并在gin.Engine.Run()后补一层os.Interrupttrap - 不要依赖
zapcore.NewCore的默认 buffer size（默认 32KB），高频场景建议设为zapcore.WrapCore(func(c zapcore.Core) zapcore.Core { return &syncCore{c} })自定义 flush 阈值
zap.AddCallerSkip(1) —— 它让 caller 信息指向业务代码而非中间件封装层，否则你永远查不到真实出错行号。
