必须用私有 struct{} 类型作 context key，否则 ctx.Value() 在 Gin handler 里永远返回 nil；因字符串字面量在不同包中地址不同，key 比较基于类型和值而非内容，需定义未导出空 struct 并全局唯一变量，且须更新 c.Request.Context() 才生效。
必须用私有 struct{} 类型作 context key，否则 ctx.Value() 在 Gin handler 里永远返回 nil —— 这不是 bug，是 Go 类型系统的设计事实。
为什么 ctx.Value("trace_id") 在 Gin 中取不到值
字符串字面量 "trace_id" 在不同包里是不同内存地址的实例，ctx.Value() 比较的是 key 的底层类型和值，不是字符串内容。你在中间件里用 context.WithValue(c.Request.Context(), "trace_id", id) 存，handler 里用 c.Request.Context().Value("trace_id") 取，实际是两个不等价的 key，结果必为 nil。
正确做法只有这一种：
- 定义未导出空 struct：
type traceKey struct{} - 声明全局唯一变量：
var traceKeyKey = traceKey{} - 存值：
ctx := context.WithValue(c.Request.Context(), traceKeyKey, traceID) - 取值：
traceID := ctx.Value(traceKeyKey).(string)（注意类型断言）
Gin 中间件里注入 TraceID 后，为什么 handler 还是拿不到
只改 c.Request.Context() 不够，Gin 的 c.Next() 调用后续 handler 时，用的仍是原始 c.Request 对象 —— 它的 Context() 方法返回的还是旧 context。
立即学习“go语言免费学习笔记（深入）”；
关键一步必须做：c.Request = c.Request.WithContext(newCtx)。漏掉这句，等于白注入。
完整链路：
- 从
c.Request.Header.Get("traceparent")或X-Trace-ID提取 ID - 用
otel.GetTextMapPropagator().Extract()解析 W3C 格式（推荐） newCtx := context.WithValue(c.Request.Context(), traceKeyKey, traceID)c.Request = c.Request.WithContext(newCtx)c.Next()
Handler 里读 TraceID 为什么会 panic
ctx.Value(traceKeyKey) 返回 interface{}，直接转 string 会 panic，尤其当中间件没执行或 key 错配时。
安全读法必须带判断：
if traceID, ok := ctx.Value(traceKeyKey).(string); ok && traceID != "" {
// 使用 traceID
} else {
// fallback：生成新 ID 或打 warning 日志
}
别依赖 c.Get("trace_id") 或 c.MustGet() —— 那只是 Gin 自己的 map 缓存，跟 context.Context 无关，跨中间件或异步调用时不可靠。
goroutine 启动后 TraceID 突然消失
go func() { log.Printf("trace: %s", ctx.Value(traceKeyKey)) }() 这种写法大概率打印 <nil>。因为 go 启动的新 goroutine 默认不继承父 context，闭包捕获的 ctx 可能已被 cancel，或根本没注入过值。
修复只有两种方式，且必须显式做：
- 把
ctx当参数传进去：go doWork(ctx)，函数签名必须接收ctx context.Context - 在 goroutine 内部重新提取：
traceID := ctx.Value(traceKeyKey).(string)，再传给子任务
所有数据库查询、HTTP 调用、消息发送，都得用 db.QueryRowContext(ctx, ...) 或 req.WithContext(ctx)，硬编码 context.Background() 就是主动断链。
最易被忽略的一点：OpenTelemetry 的 tracer.Start() 会自动从 context 提取 span，但如果你手动用 context.WithValue() 存了 traceID，又没删掉，就可能和 OTel 自动管理的 span 冲突——建议统一走 OTel propagator，别自己重复存字段。
