trace_id为空主因是context未透传到位；HTTP入口须用私有struct{}作key注入，zap需封装WithContext自动提取，goroutine和DB调用必须显式传ctx，HTTP/gRPC出站需双写header/metadata。
日志里 trace_id 为空，不是日志库没配好，而是 context 没传到位——90% 的链路断点发生在 HTTP 中间件或 goroutine 分叉处。
HTTP 入口必须用私有 struct{} 类型 key 注入 traceID
用 string 字面量当 context key（比如 "trace_id"）会导致跨包冲突，下游取值时 ctx.Value("trace_id") 返回 nil。Go 官方明确建议用未导出的空 struct 做 key，确保类型唯一：
- 定义：
type traceIDKey struct{}，不要导出 - 注入：
ctx := context.WithValue(r.Context(), traceIDKey{}, id) - 取值：
if tid, ok := ctx.Value(traceIDKey{}).(string); ok { ... } - 别 fallback 到
context.Background()—— 会丢掉超时、取消等关键信号
zap.Logger 必须封装一层才能自动读 context
zap.Logger 和 zap.SugaredLogger 都不感知 context，直接调用 logger.Info("msg") 不可能带 trace_id。手动在每条日志里加 zap.String("trace_id", id) 易漏、难维护。
- 正确做法：封装
func (l *Logger) WithContext(ctx context.Context) *zap.Logger - 内部提取：
if tid, ok := ctx.Value(traceIDKey{}).(string); ok { l = l.With(zap.String("trace_id", tid)) } - 注意：
zap.AddCallerSkip(1)要加，否则日志里显示的是封装函数名，不是业务代码行号 - 别用全局 logger 实例打日志，每次都要从当前 ctx 派生新 logger
goroutine 启动时必须显式传入带 traceID 的 ctx
写 go fn() 是最常见断链场景：父 goroutine 的 context 不会自动继承，新 goroutine 里 ctx.Value(traceIDKey{}) 一定是 nil。
立即学习“go语言免费学习笔记（深入）”；
- 错误：
go doWork()——doWork内部取不到 traceID - 正确：
go doWork(ctx)，并在doWork开头就提取 traceID - DB 查询也一样：
db.WithContext(ctx).Find(&u)，gorm v2+ 支持WithContext方法 - 第三方库（如 redis-go、sqlx）若不支持 ctx，需自己 wrap 或改用支持 context 的客户端
gRPC 和 HTTP 出站请求必须双写 header / metadata
HTTP 请求只设 req.Header.Set("X-Trace-ID", tid) 不够；gRPC 只往 context 塞 traceID 也不行——两者传播机制完全隔离。
- HTTP 客户端：
req.Header.Set("X-Trace-ID", tid)+req.Header.Set("traceparent", w3cHeader)（优先兼容 W3C） - gRPC 客户端：用
metadata.Pairs("x-trace-id", tid)构造metadata.MD，再通过grpc.InjectMetadata(ctx, md)注入 - 服务端 gRPC 拦截器中，必须用
metadata.FromIncomingContext(ctx)取值，再context.WithValue写回 - 别依赖网关自动生成的
X-Request-ID——它不保证全局唯一，也不含 span 信息
真正难的不是写几行注入代码，而是所有中间件、所有异步路径、所有出站调用都严格遵循同一套透传规则。一个地方漏掉 .WithContext(ctx)，整条链路上的日志就再也串不起来。
