必须用 context.Context 透传 TraceID，因为 *gin.Context 和全局变量无法被 http.Client、gRPC、OTel SDK、日志库等标准组件识别；只有 c.Request.Context() 是 Go 生态链路追踪的统一载体，需通过 c.Request = c.Request.WithContext(context.WithValue(...)) 更新才能确保全链路贯通。
必须用 context.Context 透传 TraceID，而不是往 *gin.Context 或全局变量里塞；否则 HTTP 调用、gRPC、日志、OTel SDK 全部拿不到，链路必然断裂。
为什么不能直接用 c.Set("trace_id", ...)
Gin 的 *gin.Context 是框架封装层，不参与 Go 标准库的 context.Context 生命周期管理。所有下游依赖（http.Client、grpc.ClientConn、otel.GetTextMapPropagator()、zap.Logger）只认 http.Request.Context() 或函数入参里的 ctx context.Context。用 c.Set 存的值：
- 不会自动注入到 req.Header
- 不会被 OTel propagator 提取或注入
- 无法被 logrus.WithContext(ctx) 或自定义 zap wrapper 拿到
- 在 goroutine 启动时彻底丢失
如何安全注入 TraceID 到 http.Request.Context()
入口中间件必须用 c.Request = c.Request.WithContext(newCtx) 替换原请求上下文，否则后续 handler 和中间件拿到的仍是旧 ctx：
- 定义私有 key 类型防止冲突：
type traceIDKey struct{}，别用"trace_id"字符串 - 优先解析 W3C
traceparent头（格式如00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01），从中提取第 2 段作为 TraceID - fallback 到
X-Trace-ID，再 fallback 到X-Request-ID（注意后者不保证唯一性，仅保底） - 若全无，则用
uuid.NewString()生成新 ID，并确保后续 HTTP 请求写入X-Trace-ID - 调用
c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), traceIDKey{}, traceID))
HTTP 客户端和 gRPC 客户端如何透传
客户端侧不手动透传，就等于没传 —— Context 里的值不会自动映射到网络协议头或 metadata：
Colly 是一个用于 Go 语言的快速开源爬取和爬虫框架。它适用于从简单的页面提取到异步爬虫处理大量页面集合，支持请求回调和结构化解析。
- HTTP：
req.Header.Set("X-Trace-ID", traceID)或更标准地用otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header)) - gRPC：必须显式构造
metadata.MD，例如md := metadata.Pairs("x-trace-id", traceID)，再通过grpc.InjectMetadata(ctx, md)注入，不能只靠context.WithValue - 异步 goroutine（如
go func() { ... }()）必须显式传入带 TraceID 的 ctx，不能用context.Background()或闭包捕获外层变量
日志库怎么自动带上 TraceID
zap、logrus 等本身不读 context，必须桥接；每次手动 logger.With(zap.String("trace_id", ...)) 极易遗漏：
立即学习“go语言免费学习笔记（深入）”；
- zap 推荐封装
LoggerFromCtx(ctx context.Context) *zap.Logger，内部调用ctx.Value(traceIDKey{})并.With()构造新 logger - logrus 可用
log.WithContext(ctx).WithField("trace_id", GetTraceID(ctx)).Info(...)，但需确保GetTraceID做好类型断言防护 - 切忌在服务启动时初始化一个全局 logger 并一次性写入 trace_id —— 那个值永远是启动时刻的空字符串或 panic
- 性能敏感场景下，
With()是浅拷贝，开销可控；但避免在 hot path 上高频构造新 logger 实例
最常被忽略的一点：gRPC 服务端拦截器提取 metadata 后，必须用 context.WithValue 把 TraceID 再塞回 ctx，否则 handler 里 ctx.Value 拿不到；而 HTTP 客户端发请求到 gRPC 服务时，还要额外做 header → metadata 的映射，否则协议边界直接断链。
