应统一使用 gin.Context 的 c.Set()/c.Get() 而非 context.WithValue 传 traceID，因 Gin 自维护独立键值存储且生命周期与请求强绑定；混用会导致中间件写入、handler 读取失败。
为什么不能直接用 context.Context 传 traceID？
很多人一上来就往 context.WithValue 里塞 traceID，以为 Gin 的 *gin.Context 底层是 Go 原生 context.Context 就能通用——但这是错的。Gin 的 *gin.Context 是封装体，它内部确实持有一个 context.Context（叫 c.Request.Context()），但 *gin.Context 自己还维护了一套独立的键值存储（c.Set()/c.Get()），且生命周期和请求绑定更紧密。直接改 c.Request.Context() 不影响 c.Get()，反过来也一样。混用会导致中间件写入、handler 读不到，或者日志打出来 traceID 是空。
推荐做法：统一走 c.Set() + 中间件注入
在入口中间件里从请求头（比如 X-Trace-ID）提取 traceID，用 c.Set("trace_id", id) 存进去；后续所有 handler 和中间件都用 c.GetString("trace_id") 或 c.Get("trace_id") 读取。这样简单、线程安全、和 Gin 生命周期一致。
常见操作：
- 优先从
X-Trace-ID头读，不存在时生成一个（如uuid.New().String()） - 务必在
c.Next()前 set，否则下游拿不到 - 如果要透传给下游 HTTP 服务，记得在调用前把 traceID 写进 outbound 请求头
- 避免用数字或布尔作 key（如
c.Set(123, "abc")），Gin 内部用interface{}做 map key，类型不一致会导致 get 失败
// 示例中间件
func TraceIDMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
traceID := c.GetHeader("X-Trace-ID")
if traceID == "" {
traceID = uuid.New().String()
}
c.Set("trace_id", traceID)
c.Next()
}
}
日志和下游调用怎么带出 traceID？
日志库（如 zap、logrus）需要手动把 traceID 注入字段；HTTP 客户端调用下游时，也要显式加 header。这两步漏掉，链路就断了。
关键点：
- zap 日志：用
logger.With(zap.String("trace_id", c.GetString("trace_id")))包一层，别在每条 log 里重复写 - logrus：类似，
log.WithField("trace_id", c.GetString("trace_id")) - 调下游 HTTP：用
c.Request.Context()构造新 request，并设 header：req.Header.Set("X-Trace-ID", c.GetString("trace_id")) - 不要依赖
http.DefaultClient，它不带 context；要用http.Client并传入c.Request.Context()
为什么不用 c.Request.Context().WithValue()？
可以，但没必要，而且容易出问题。Gin 的 c.Request.Context() 是随请求创建的，理论上也能存 traceID，但你得确保所有地方都从这里取——包括日志、DB 调用、异步 goroutine。而 c.Set() 更轻量、语义明确、只在当前请求生命周期内有效，不会意外泄漏到其他请求。更大的坑是：如果你在中间件里用 WithValue，然后 handler 里又用 c.Get()，两边根本对不上。
真要跨 goroutine 传递（比如启动后台任务），才考虑用 c.Request.Context() + WithValue，并且必须用指针或不可变结构体传参，不能只传 *gin.Context 本身——它不是线程安全的。
复杂点在于 traceID 要贯穿 DB 查询、Redis、消息队列、HTTP 调用多个环节，每个环节的 client 是否支持 context、是否自动透传 header、日志是否被正确装饰，都得单独确认。一个环节没接上，整条链路就残了。
