用装饰器加链路追踪而非直接改 handler，是因为旧业务缺乏 context 透传、无 span 注入点、混用注册方式，硬插 start() 会破坏调用链且遗漏异步逻辑与 panic 恢复路径；装饰器在不侵入原逻辑前提下将 span 生命周期套入请求流，仅依赖 http.handlerfunc 底层契约，兼容 legacy 代码。
为什么用装饰器函数加链路追踪，而不是直接改 handler？
因为旧业务模块往往没有 context 透传、没预留 span 注入点、甚至混着 http.Handle 和 http.HandleFunc 两种注册方式。硬插 otel.Tracer().Start() 会破坏原有调用链，还容易漏掉中间件里的异步逻辑或 panic 恢复路径。
装饰器函数本质是“在不碰原逻辑的前提下，把 span 生命周期套进请求流”。它不依赖框架抽象层（比如 Gin 的 gin.HandlerFunc），只认 http.HandlerFunc 这个底层契约，所以能无缝兼容 legacy 代码。
如何写一个带 span 的 WithTracing 装饰器？
关键不是“开启 span”，而是确保 span 在正确上下文里创建、结束，并把 trace context 透传给下游服务。下面这个版本避开了三个常见坑：
-
context.WithValue()不要用来存 span —— 它只是临时容器，otel.GetTextMapPropagator().Inject()才是跨服务传递的正道 - 别在 defer 里调用
span.End()后再写日志 —— span 结束后无法再打 tag 或 event - 如果 handler 里有 goroutine，必须用
trace.ContextWithSpanContext()显式传入，否则子协程无 trace 上下文
示例：
func WithTracing(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
tracer := otel.Tracer("http-server")
// 从 header 提取上游 trace context
spanCtx := otel.GetTextMapPropagator().Extract(ctx, propagation.HeaderCarrier(r.Header))
ctx, span := tracer.Start(
trace.ContextWithRemoteSpanContext(ctx, spanCtx),
r.Method+" "+r.URL.Path,
trace.WithAttributes(
attribute.String("http.method", r.Method),
attribute.String("http.url", r.URL.String()),
),
)
defer span.End()
// 把新 ctx 注入 request，供下游逻辑（如 client.Do）使用
r = r.WithContext(ctx)
next(w, r)
}
}
和 OpenTelemetry SDK 自动插桩冲突吗？
会。如果你同时启用了 otelhttp.NewHandler 包装整个 mux，再手动用装饰器包单个 handler，就会出现 span 嵌套错乱、trace ID 不一致、采样率叠加等问题。
二者选其一：
- 全量自动插桩：用
otelhttp.NewHandler+otelhttp.NewClient，适合新项目或可统一改造的模块 - 局部手动增强：用装饰器函数，只对关键路径（如支付回调、第三方 webhook 入口）加追踪，其余保持原样
混用时务必关掉自动插桩的对应路径，例如：otelhttp.NewHandler(mux, "", otelhttp.WithFilter(func(r *http.Request) bool { return !strings.HasPrefix(r.URL.Path, "/legacy/") }))
装饰器链里 span 的父子关系怎么保证？
顺序决定继承关系。假设你写成 WithTracing(WithRecovery(handler))，那 WithRecovery 内部的 span 就是 WithTracing 创建的 span 的 child；但如果你写成 WithRecovery(WithTracing(handler))，panic 捕获逻辑就跑在 span 外面，一旦 panic 发生，span 已提前结束，导致 trace 断裂。
正确做法：
- 所有带 span 的装饰器必须最外层
- recover、logging、auth 等不依赖 trace context 的逻辑放内层
- 如果某个装饰器内部要发起 HTTP 请求，必须确保它拿到的是带 span 的
r.Context()，而不是原始r.Context()
最容易被忽略的一点：Gin 中的 c.Next() 或 echo 的 next() 如果没把 context 透传下去，中间件链里的 span 就是孤立的——它们有 trace ID，但没 parent span ID，最终在 Jaeger 里显示为“根 span”，而非子 span。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
