log包直接打日志不适合微服务接口，因其缺乏请求上下文（如trace ID、路径、耗时、状态码）且不支持结构化输出，导致无法串联链路和被ELK/Loki解析。
为什么 log 包直接打日志不适合微服务接口
微服务中，单个请求常跨多个服务，log.Printf 或 log.Println 打出的日志没有请求上下文（如 trace ID、路径、耗时、状态码），查问题时无法串联请求链路。更严重的是，它默认不支持结构化输出（JSON），难以被 ELK / Loki 等日志系统解析和检索。
用 zap + context 实现带 trace ID 的接口日志
推荐使用 uber-go/zap（高性能、结构化）配合 context.Context 透传 trace ID。关键点不是“加日志”，而是“让每条日志自动携带当前请求的元信息”。
- 启动时初始化全局
*zap.Logger，启用development或production配置（后者默认 JSON 输出） - HTTP 中间件从请求头（如
X-Request-ID或traceparent）提取或生成 trace ID，并写入context.WithValue - Handler 内通过
ctx.Value("trace_id")获取，但更推荐封装一个带字段的Logger：用logger.With(zap.String("trace_id", tid))派生子 logger - 避免在每个 handler 里重复写
With，可封装中间件返回带 trace 字段的 logger 到 context
func loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
tid := r.Header.Get("X-Request-ID")
if tid == "" {
tid = uuid.New().String()
}
ctx := context.WithValue(r.Context(), "trace_id", tid)
// 派生 logger 并存入 context（建议用自定义 key 类型，避免字符串冲突）
logger := zap.L().With(zap.String("trace_id", tid), zap.String("path", r.URL.Path))
ctx = context.WithValue(ctx, loggerKey{}, logger)
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
zap 日志字段怎么选才利于排查接口问题
光有 trace_id 不够。接口日志必须包含可定位、可聚合、可过滤的最小字段集，否则等于没记。
- 必填字段：
level（zap 自带）、trace_id、path（请求路径）、method（GET/POST）、status_code（响应状态）、duration_ms（耗时，单位毫秒） - 按需字段：
user_id（鉴权后注入）、client_ip（r.RemoteAddr或X-Forwarded-For）、error（仅失败时写，不要全量打 error stack） - 避免字段：
body（敏感、体积大）、raw_query（含 token 或密码参数）、full_stack（除非 panic，否则用zap.Error(err)即可） - 注意：zap 的
Duration字段名必须是duration或带_ms后缀，否则 Grafana/Loki 的 duration 聚合可能失效
如何让日志同时输出到文件和 stdout（适配容器环境）
Kubernetes 中，stdout 是标准日志采集入口；但调试或审计时又需要保留文件副本。zap 支持多写入器（zapcore.AddSync），但要注意锁和性能。
立即学习“go语言免费学习笔记（深入）”；
- 不要用
os.OpenFile直接写，应使用lumberjack.Logger做轮转（防止日志撑爆磁盘） - stdout 和 file 写入器需共用同一
EncoderConfig，否则字段对不齐 - 生产环境禁用
consoleEncoder（人类可读格式），统一用jsonEncoder，避免日志系统解析失败 - 若服务部署在 K8s，
stdout写入器必须存在，否则日志采集器（如 fluent-bit）收不到任何内容
func newZapLogger() (*zap.Logger, error) {
encoderCfg := zap.NewProductionEncoderConfig()
encoderCfg.TimeKey = "timestamp"
encoderCfg.EncodeTime = zapcore.ISO8601TimeEncoder
consoleCore := zapcore.NewCore(
zapcore.NewJSONEncoder(encoderCfg),
zapcore.AddSync(os.Stdout),
zap.InfoLevel,
)
fileWriter, _ := lumberjack.NewLogger(&lumberjack.Logger{
Filename: "/var/log/my-service/app.log",
MaxSize: 100, // MB
MaxBackups: 5,
MaxAge: 7, // days
})
fileCore := zapcore.NewCore(
zapcore.NewJSONEncoder(encoderCfg),
zapcore.AddSync(fileWriter),
zap.InfoLevel,
)
core := zapcore.NewTee(consoleCore, fileCore)
return zap.New(core), nil
}
Gin 或 Chi 等框架的中间件里埋日志不难，难的是字段一致、trace 可传递、输出格式能被基础设施消费。很多人卡在“日志写了但搜不到”，其实是字段命名不规范或 encoder 配置不匹配——比如用了 consoleEncoder 却指望 Loki 解析 JSON。 
