Gin默认不携带SkyWalking追踪上下文，因其作为轻量HTTP框架不内置分布式追踪传播逻辑；需手动通过sw8协议提取/注入header，并在中间件中桥接gin.Context与skywalking-go的context.Context，否则Trace ID断裂、span无法聚合。
为什么 Gin 默认不携带 SkyWalking 追踪上下文
因为 Gin 是轻量 HTTP 框架，本身不处理分布式追踪的传播逻辑；skywalking-go SDK 虽支持 HTTP 场景，但需要手动注入/提取 sw8 或 sw6 头，Gin 中间件不自动做这件事。
常见现象：服务 A 调用 Gin 服务 B，B 的 SkyWalking 页面显示“独立入口”，Trace ID 断开，trace_id 为空或生成新值。
- 根本原因是未在 Gin 的
gin.Context和 SkyWalking 的context.Context之间桥接 -
skywalking-go的propagation.Extract和propagation.Inject必须显式调用 - Gin 的
c.Request.Header需手动读取sw8头，不能依赖框架自动解析
如何写一个兼容 sw8 协议的 Gin 中间件
核心是：从请求头提取上下文 → 创建 SkyWalking span → 绑定到 Gin context → 响应时注入 trace header。
注意：sw8 是 SkyWalking v8+ 默认协议，比旧版 sw6 更紧凑，Gin 中间件必须匹配服务端配置的采样协议。
立即学习“go语言免费学习笔记（深入）”；
- 使用
skywalking-go/toolkit/http/propagation提供的Extract解析sw8头 - 用
sw.ContextWithSpan将 span 注入 Gin 的c（推荐存入c.Set("sw_span", span)） - 响应前调用
propagation.Inject写回sw8头，否则下游收不到上下文 - 务必在
c.Next()前创建 entry span，否则 span 生命周期错乱
func SkyWalkingMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
carrier := propagation.HTTPCreateCarrier(c.Request.Header)
ctx, span := sw.CreateEntrySpan(c.Request.Context(), c.Request.URL.Path, carrier.Extract)
if span != nil {
defer span.End()
c.Set("sw_span", span)
c.Request = c.Request.WithContext(ctx)
}
c.Next()
if span != nil {
propagation.HTTPCreateCarrier(c.Writer.Header()).Inject(span.Context())
}
}
}
Gin 发起下游调用时如何透传 trace 上下文
单纯中间件只解决「进」，不解决「出」；Gin handler 内部调用其他服务（如 HTTP client）时，必须手动注入 sw8 头，否则链路在第一跳就断。
关键点：不能直接用原生 http.Client，必须用 sw.NewHTTPClient() 封装，或手动注入 carrier。
- 推荐方式：用
sw.NewHTTPClient()替代默认 client，它会自动读取当前 span 并注入sw8 - 若必须用原生 client，需先获取 span：
span, _ := c.Get("sw_span")，再调用propagation.HTTPCreateCarrier(req.Header).Inject(span.(sw.Span).Context()) - 注意：如果 handler 中启动 goroutine 异步调用，必须用
sw.ContextWithSpan传递 context，否则 span 丢失
常见坑：跨服务 trace_id 不一致或 span 名称混乱
不是代码没跑，而是 SkyWalking 的 span 命名和层级理解偏差导致 UI 显示异常。
-
sw.CreateEntrySpan的第一个参数是 operation name，默认展示为 “/api/user” —— 它不是 service name，service name 由SW_AGENT_NAME环境变量决定 - 如果用了
sw.CreateLocalSpan但没设SetOperationName，UI 里会显示 “unknown” - Gin 中间件中 span
End()必须 defer，否则 panic 时 span 未结束，SkyWalking 后端丢数据 - 本地开发时忘记启动 SkyWalking OAP 或 agent 配置错误，会导致 span 发送失败但无报错，日志里只有
failed to report segment一类 warning
最常被忽略的是：Gin 中间件注册顺序。必须放在所有业务 handler 之前，且不能被其他中间件（比如 CORS、JWT）拦截或覆盖 header。
