不能直接用全局变量存 traceid，因并发下 goroutine 调度不可预测，会导致多个请求共用同一变量而串号；必须通过 context.withvalue 注入并透传，且 goroutine 启动时需显式传递 context。
为什么不能直接用全局变量存 TraceID
全局变量或包级变量在并发场景下会互相污染，Go 的 goroutine 调度不可预测，http.Handler、中间件、异步任务、数据库调用都可能跨 goroutine。一旦多个请求共用同一个变量，TraceID 就会串号——你看到的 trace_id=abc123 实际混了 A 请求的日志和 B 请求的 DB 查询。
context 是 Go 官方为这类跨 goroutine、跨函数、跨组件的「请求作用域数据」设计的机制，天然支持 cancel/timeout/deadline，且自带不可变性（WithValue 返回新 context）。
如何从 HTTP 请求头注入并透传 TraceID
入口处（比如 HTTP middleware）必须从 req.Header.Get("X-Trace-ID") 读取，而不是生成新 ID——否则上游已埋点的链路就断了。若头不存在，才 fallback 生成（如 uuid.NewString()）。
关键点：
- 必须用
context.WithValue(ctx, traceKey{}, traceID)注入，traceKey{}不能是字符串（避免 key 冲突），推荐定义私有空 struct 类型 - HTTP handler 中拿到的
req.Context()是基础 context，需显式替换为带 TraceID 的新 context - 下游调用（如
http.NewRequestWithContext、db.QueryContext）必须传这个新 context
示例片段：
type traceKey struct{}
func TraceIDFromContext(ctx context.Context) string {
if v := ctx.Value(traceKey{}); v != nil {
return v.(string)
}
return ""
}
func TraceMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
traceID := r.Header.Get("X-Trace-ID")
if traceID == "" {
traceID = uuid.NewString()
}
ctx := context.WithValue(r.Context(), traceKey{}, traceID)
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
goroutine 启动时如何确保 TraceID 不丢失
直接写 go doSomething() 会丢失父 context 中的 TraceID，因为新 goroutine 拿到的是 background context。
正确做法只有两种：
- 用
go doSomething(ctx)显式传入 context，并在函数内调用TraceIDFromContext(ctx) - 用
ctx = context.WithValue(parentCtx, traceKey{}, traceID)构造新 context 后再启动 goroutine，且函数内部必须基于该 ctx 取值
常见错误：在 goroutine 里直接调用 context.Background() 或忽略传参，导致日志里 TraceID 为空或显示 background。
第三方库（如 sqlx、redis-go）是否自动透传 context
不是所有库都尊重 context。比如老版本 sqlx 的 Get/Select 方法不接受 context，必须改用 GetContext/SelectContext；github.com/go-redis/redis/v9 全面支持 context，但 v8 及更早版本只在部分方法中支持。
检查方式很简单：看函数签名是否含 ctx context.Context 参数。没有？那它不参与链路透传，你的 DB 查询就脱离 TraceID 了。
务必确认：
- DB 连接初始化时是否启用
WithContext模式（如sql.OpenDB(connector)配合context.WithTimeout） - 日志库（如
zerolog、zap）是否在With或InfoCtx中注入了 TraceID 字段 - gRPC client 是否用
ctx构造metadata.MD并附加到请求头（X-Trace-ID）
漏掉任意一环，TraceID 就会在某层戛然而止。
最易被忽略的是：中间件注入 context 后，handler 函数里没把新 context 传给后续调用链，而是继续用原始 r.Context()——看起来逻辑对，实则 TraceID 始终没真正流动起来。
