直接在 handler 里用 log.Printf 打 trace_id 日志是错的，因会导致并发错乱、中间件未执行就打日志、字段名不统一（trace_id vs traceId）、漏传 context、字符串拼接拖慢性能，且链路易断裂；应封装 zap.Logger，从 context 安全提取 trace_id，统一字段名为 trace_id，Gin 中间件需显式调用 r.WithContext(newCtx)，审计日志须收口为函数并白名单过滤敏感字段。
为什么直接在 handler 里写 log.Printf("trace_id=%s", traceID) 是错的
这会导致 traceID 在并发请求中错乱、中间件未执行前就打日志、字段名不统一（trace_id vs traceId）、漏传 context、甚至因字符串拼接触发 fmt 包反射而拖慢性能。更糟的是，一旦某处漏写或写错，整条链路就断了——你查 Jaeger 时看到一堆无 trace_id 的孤点。
用 zap.Logger 封装 traceID 提取逻辑，别碰全局变量
zap 不自带 context 感知能力，但你可以封装一层：声明一个带 ctx 参数的日志方法，从 context 中安全提取 trace_id 字段（推荐用 ctx.Value("trace_id") 或自定义 key 类型），再透传给 zap.Logger。关键点：
- 禁止用
log.Printf或fmt.Printf打链路日志——它们不结构化、无法被 ELK / Loki 正确解析 - 别把
trace_id存全局变量或 map —— goroutine 不安全，中间件链一长就覆盖错 - 统一字段名必须是
trace_id（下划线），Jaeger 和 OpenTelemetry SDK 默认认这个 - 初始化 logger 时不要绑定固定
trace_id，否则所有日志都带同一个值
Gin 中间件必须显式传递新 context，否则 traceID 会丢失
常见错误是中间件 A 解析了 X-Trace-ID 并调用 context.WithValue(ctx, key, val)，但中间件 B 调用 next.ServeHTTP(w, r) 时没把新 ctx 注入 request：r = r.WithContext(newCtx)。结果 handler 里拿到的还是空 context。
正确写法：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
func TraceIDMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
traceID := c.GetHeader("X-Trace-ID")
if traceID == "" {
traceID = "unknown-" + uuid.New().String()
}
ctx := context.WithValue(c.Request.Context(), traceIDKey, traceID)
c.Request = c.Request.WithContext(ctx) // ← 这行不能少
c.Next()
}
}
后续所有中间件和 handler 都能通过 c.Request.Context().Value(traceIDKey) 安全取值。
audit.Log() 必须收口为函数，且只接受 context.Context
散落在各 handler 里的 log.Printf("user %s updated email %s", userID, newEmail) 是审计日志失效的根源：字段缺失、敏感字段未脱敏、没带 IP 和时间戳、无法对接 SIEM 系统。
真正可落地的做法是定义一个函数：
func LogAudit(ctx context.Context, event AuditEvent) {
traceID := getTraceIDFromCtx(ctx)
userID := getUserIDFromCtx(ctx)
ip := getIPFromCtx(ctx)
logger.Info("audit_event",
zap.String("trace_id", traceID),
zap.String("user_id", userID),
zap.String("ip", ip),
zap.String("action", event.Action),
zap.String("resource_id", event.ResourceID),
zap.Any("before", event.Before), // 白名单后才填
zap.Any("after", event.After),
)
}
业务代码只需调用 LogAudit(c.Request.Context(), AuditEvent{Action: "update_profile"})，其余字段自动补全。复杂点在于 Before/After 必须走白名单过滤——比如只允许记录 email 和 phone，其他字段一律丢弃，否则审计日志会泄露密码哈希或 token。
