Go HTTP服务中需在入口中间件从X-Trace-ID头提取或生成TraceID，用私有struct{}类型key通过context.WithValue注入；HTTP/gRPC调用、goroutine启动、DB查询等所有下游操作必须显式传递该context，否则链路中断。
Go HTTP 服务中如何从请求提取并透传 TraceID
HTTP 入口是 TraceID 的源头，必须在首层解析并注入到 context.Context 中。常见错误是直接用 r.Header.Get("X-Trace-ID") 但没做空值校验或生成逻辑，导致下游链路断掉。
- 若 Header 中无
X-Trace-ID，应生成一个新TraceID（推荐用uuid.New().String()或短 ID 如fastuuid.MustNew().String()） - 务必用
context.WithValue(ctx, key, traceID)注入，key必须是自定义类型（如type traceIDKey struct{}），避免字符串 key 冲突 - 不要把
TraceID存进http.Request.Context()后就不管了——后续所有 handler、中间件、业务函数都得显式接收ctx参数并向下传递
跨 goroutine 时 Context 丢失 TraceID 的典型场景
Go 里新开 goroutine 时若直接传入原始 req.Context()，看似没问题，但一旦原请求结束，Context 可能被 cancel，且子 goroutine 拿不到父级的 Value（尤其是非继承自 WithValue 的派生 context）。
- 正确做法：用
ctx = context.WithValue(parentCtx, traceIDKey{}, traceID)显式构造带值的子 context，再传给 goroutine - 禁止写
go fn(req.Context())—— 应写成go fn(ctx)，其中ctx是已注入TraceID的上下文 - 数据库查询、RPC 调用、消息发异步任务等，只要脱离当前 request 生命周期，就必须确保
ctx已携带TraceID并未被 cancel
gRPC 客户端和服务端如何透传 TraceID 到下游服务
gRPC 默认不自动传播 Context.Value，必须手动通过 metadata.MD 封装并注入。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 客户端调用前：构建
md := metadata.Pairs("x-trace-id", traceID)，再用grpc.CallOption注入：grpc.Metadata(md) - 服务端拦截器中：用
grpc_ctxtags.Extract(ctx)或手动取md, _ := metadata.FromIncomingContext(ctx)，再md.Get("x-trace-id")提取 - 注意大小写：gRPC metadata key 默认转为小写，
X-Trace-ID会变成x-trace-id，前后端命名要统一 - 别漏掉超时和取消传递——
ctx本身也要传给conn.Invoke()或client.Method(ctx, req)，否则下游无法感知上游 cancel
为什么 log.Printf 打不出 TraceID？
因为 log 包默认不读取 Context，也不会自动注入 TraceID。你看到的日志没 ID，不是 Context 没传，而是日志没“接住”。
立即学习“go语言免费学习笔记（深入）”；
- 方案一：改用支持 context 的日志库（如
zerolog+zerolog.Ctx(ctx)，或zap+zap.AddCallerSkip(1)配合ctx提取） - 方案二：自己封装 log 函数，每次先从
ctx.Value(traceIDKey{})取值，再拼进 message（但注意并发安全与性能） - 最容易忽略的点：中间件里打印日志用的是
req.Context()，但 handler 里用了另一个子 context，如果没显式 copyTraceID，就会打空
TraceID 不是写一次就完事的事——它得在每个函数签名里出现，在每次 goroutine 启动时检查，在每条 RPC 和 DB 调用前确认是否还在。漏掉任意一环，链路就断了。
