不能直接用 context.WithValue 传 TraceID，因 string 等基础类型作 key 易跨包冲突导致值覆盖或取不到，且需私有未导出类型（如 type traceKey struct{}）作 key、显式透传至 goroutine/HTTP/gRPC 等所有下游调用，漏一处即断链。
为什么不能直接用 context.WithValue 传 TraceID
go 的 context.withvalue 确实能存 traceid，但很多人忽略它本质是「无类型键」——你传 string 做 key，取的时候还得强转，一不小心就 panic。更麻烦的是，不同包里如果各自定义自己的 key（比如 "trace_id" 和 keytraceid），值根本串不起来，下游服务拿到空值就断链。
正确做法是定义一个私有类型作为 key，确保类型唯一性：
type traceKey struct{}
然后统一用这个类型做 key：
ctx = context.WithValue(ctx, traceKey{}, "abc123")
取的时候也必须用同一类型断言：
if tid, ok := ctx.Value(traceKey{}).(string); ok { /* ... */ }
如何在 HTTP 入口自动注入 TraceID 并透传
HTTP 请求进来时，TraceID 通常来自请求头（如 X-Trace-ID），没带就生成一个新的。关键点在于：必须在中间件里完成注入，并把新 context 传给 handler，否则后续调用链拿不到。
- 不要只解析 header 后存在局部变量里——那只是字符串，不是可传递的上下文
- 务必用
http.Request.WithContext()替换原 request 的 context，否则chi.ServeMux、gin.Context.Request等都读不到 - 下游 HTTP 调用时，记得把 TraceID 写回
req.Header.Set("X-Trace-ID", tid)，否则链路在出向就断了
示例中间件片段：
func TraceIDMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
tid := r.Header.Get("X-Trace-ID")
if tid == "" {
tid = uuid.New().String()
}
ctx := context.WithValue(r.Context(), traceKey{}, tid)
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
gRPC 场景下怎么让 TraceID 跨进程传递
gRPC 默认通过 metadata 透传上下文数据，但和 HTTP 不同：它不自动把 context.Value 映射过去，得手动塞进 metadata，再在服务端手动取出来塞回 context。
- 客户端调用前，从当前 context 取 TraceID，写入
metadata.Pairs("trace-id", tid) - 服务端拦截器里，用
grpc_ctxtags.Extract(ctx).Set("trace_id", tid)这类方式暂存不如直接context.WithValue稳定——推荐自己写拦截器提取 metadata 并 set 到 context - 注意 gRPC metadata key 是小写 + 连字符风格（
"trace-id"），但 Go context key 仍是上面定义的traceKey{}类型，两者不冲突
服务端拦截器关键逻辑：
func serverTraceIDInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
md, ok := metadata.FromIncomingContext(ctx)
var tid string
if ok {
if vals := md["trace-id"]; len(vals) > 0 {
tid = vals[0]
}
}
if tid == "" {
tid = uuid.New().String()
}
ctx = context.WithValue(ctx, traceKey{}, tid)
return handler(ctx, req)
}
日志打印时怎么自动带上 TraceID
日志库本身不认 context，所以不能指望 log.Printf 自动捞出 TraceID。常见错误是每次打日志都手动 ctx.Value(traceKey{}).(string)，既啰嗦又易 panic。
- 用支持 context 的日志库（如
zerolog或zap）+ctxlog这类适配器，或自己封装一个带 TraceID 的 logger 实例 - 更轻量的做法：在中间件/拦截器里把 TraceID 注入到 logger 的
With()字段，后续所有子 logger 都继承该字段 - 切记别在 goroutine 里直接用外层函数的 ctx —— 如果那个 ctx 已 cancel，
Value可能返回 nil，导致日志 panic 或漏打
例如用 zerolog 封装：
func WithTraceID(ctx context.Context, logger *zerolog.Logger) *zerolog.Logger {
if tid, ok := ctx.Value(traceKey{}).(string); ok {
return logger.With().Str("trace_id", tid).Logger()
}
return *logger
}
跨 goroutine 时最容易丢 TraceID，尤其在 go func() {}() 里直接用外部 ctx —— 那个 ctx 可能已经超时或被 cancel，Value 返回 nil。真正安全的做法是：在启动 goroutine 前，先取出 TraceID 字符串，再作为参数传进去。
