直接在 context.WithValue 中打日志无效，因其仅创建新 context 而不触发日志；日志须加在使用 context 发起可观测动作前（如 http.Do、db.QueryContext），并携带 trace ID 和层级信息。
为什么直接在 context.WithValue 里打日志没用
因为 context.WithValue 只是把键值对塞进新 context，它本身不触发任何日志行为。你调用它时没日志，下游取值时也没日志——日志得你主动加，而且得加在「经过 context 的关键路径上」，比如 HTTP handler 入口、RPC 方法开头、数据库查询前。
常见错误是：只在创建 context 时 log 一句，结果调用链深了之后完全不知道这个 context 被传到了哪一层。
- 不要在
context.WithValue调用点打日志（信息太早、太孤立） - 要在每次「使用该 context 发起可观测动作」前打，比如
http.Do、db.QueryContext、grpc.Invoke - 日志必须包含能串联的 trace ID（从 context 里取），否则就是一堆散点
怎么从 context 提取并打印 trace ID 和调用层级
Go 的 context.Context 本身不带 trace ID，得你自己往里塞（比如用 context.WithValue(ctx, key, "req-abc123")）。但更稳妥的是用标准 key，比如 OpenTelemetry 的 oteltrace.SpanFromContext，或自己定义一个 type ctxKey string 常量。
打印时别只打 ID，要体现「当前函数在链路中的位置」，靠调用栈深度或显式传入层级标识。例如：
func handleUser(ctx context.Context, userID string) {
span := oteltrace.SpanFromContext(ctx)
logger.Info("handleUser start", "trace_id", span.SpanContext().TraceID(), "level", 2)
// ...
}
- 用
runtime.Caller(0)获取函数名可辅助定位，但别依赖它做逻辑判断（性能差、不可靠） - 层级数字建议由上层显式传入（如
handleUser(ctx, userID, 2)），避免递归时误算 - 如果用了 OpenTelemetry，优先用
span.SpanContext()，别自己解析 context 里的字符串
HTTP handler 中如何自动注入和打印链路日志
最实用的方式是在中间件里统一处理：从请求提取 trace ID（Header 或 query），塞进 context，再在每层 handler 开头打日志。这样不用每个 handler 都重复写。
示例中间件：
func TraceLogMiddleware(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 = "trace-" + uuid.New().String()
}
ctx := context.WithValue(r.Context(), traceKey, traceID)
logger.Info("http request start", "trace_id", traceID, "path", r.URL.Path, "method", r.Method)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
- 注意：不要用
context.Background()替换掉原r.Context()，会丢掉 cancel 和 timeout - Header 名统一用
X-Trace-ID，避免大小写混用导致取不到（HTTP header 是 case-insensitive，但 Go 的Header.Get实际按字面匹配） - 日志字段保持精简，
trace_id、path、method足够串联；加太多字段反而影响日志检索效率
容易被忽略的坑：goroutine 分裂后 context 日志丢失
当你用 go fn(ctx) 启动 goroutine，但没把 context 传进去，或者传了却没在 goroutine 里打日志，那这部分执行就彻底脱离链路——查问题时会发现日志断层。
更隐蔽的是：用了 context.WithTimeout，但 goroutine 没监听 ctx.Done()，超时后日志还在打，trace ID 却已失效。
- 所有
go启动的函数，只要涉及业务逻辑，必须接收context.Context参数 - 在 goroutine 开头立刻打日志，且必须用传入的 ctx 取 trace ID，不能闭包引用外层变量
- 如果 goroutine 里调用了
time.Sleep或阻塞 I/O，务必配合select { case ，否则日志时间戳会严重失真
链路日志不是加几行 log.Printf 就完事，关键在「谁在什么时候、用哪个 context、打了什么字段」——漏掉任意一环，排查时就会卡在某个看不见的 goroutine 里。
