Zipkin-Go 集成失败主因是 HTTP Reporter URL 错误（如空字符串或缺 http://）、未调 span.Finish()、服务名为空、B3 头未透传、采样率过高致丢 span；须用正确 URL、配对 Finish、设有效服务名、启用中间件透传 header、合理配置采样与 reporter。
HTTP Reporter 初始化失败：400 Bad Request 或 unsupported protocol scheme ""
这是 Zipkin-Go 集成中最常卡住的第一步——reporter.NewHTTPReporter 传了空字符串或错误 URL，导致 tracer 启动不报错但所有 span 静默丢弃。根本原因不是网络不通，而是 URL 格式非法（比如漏写 http://）或用了已废弃的旧版库（如 v0.1.x 的 zipkin-go）。
-
reporter.NewHTTPReporter("http://zipkin:9411/api/v2/spans")是唯一推荐方式；别自己拼http.Client.Post调用/api/v2/spans - 容器内部署时，
localhost指向容器自身，必须换成 Zipkin 服务的真实 DNS 名（如zipkin.default.svc.cluster.local）或 ClusterIP - v0.4+ 才原生支持 HTTP Reporter；v0.5 更稳定，不要用 v0.1.x 或 fork 分支
- 如果 Zipkin 后端是阿里云链路分析等 SaaS 服务，URL 中含特殊字符（如
@、/），需提前url.PathEscape处理路径部分
tracer.StartSpan 后忘记 defer span.Finish()
span 不上报、UI 显示“incomplete”、耗时为 0 —— 八成是因为没调 span.Finish()。Zipkin-Go 不会自动补全，也不依赖 defer 机制兜底（哪怕你写了 defer，如果 panic 发生在 span 创建前，它也压根没进 defer 队列）。
- 每个
tracer.StartSpan必须配对defer span.Finish()，且放在函数最开头附近，避免被条件分支绕过 - HTTP 中间件（如
zipkinhttp.NewServerMiddleware）只处理入站请求，出站调用（如http.Get调第三方 API）必须手动创建 child span 并 finish - 若 span 创建后立即返回错误，也要显式
span.Finish()，否则上下文泄漏、内存缓慢增长
服务名为空或上下文未透传：Zipkin UI 显示 unknown / 查不到链路
服务名（zipkin.WithName("auth-service")）为空字符串，会导致 Zipkin UI 里所有 trace 都归到 unknown 下，过滤失效；而 HTTP 请求头中缺失 X-B3-TraceId 等字段，则跨服务链路直接断裂。
-
zipkin.WithName("auth-service")中的 name 绝不能是空字符串或纯空格，否则 tracer 初始化成功但数据无归属 - Go 默认不解析 b3 header，必须用
zipkinhttp.NewServerMiddleware(tracer)包裹 handler，它才自动 extract 并注入 context - 客户端发请求时，要用
zipkinhttp.NewClient(tracer)包装http.Client，或手动调tracer.Inject(span.Context(), zipkin.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header)) - 若混用 OpenTracing 接口（如
opentracing.StartSpanFromContext），必须确保全局opentracing.SetGlobalTracer已指向 Zipkin tracer 实例
采样率与 reporter 性能：高并发下 span 大量丢失
默认全量采样（zipkin.NewCountingSampler(1)）在 QPS 上千时，reporter 缓冲区溢出、HTTP 连接超时、甚至拖慢业务响应。这不是 bug，是设计使然——你需要主动限流。
立即学习“go语言免费学习笔记（深入）”；
- 生产环境务必设采样器，例如
zipkin.NewModuloSampler(100)表示每 100 个请求采 1 个 - HTTP Reporter 默认缓冲 100 个 span，超限即丢弃；可通过
reporter.NewHTTPReporter(url, reporter.HTTPBatchSize(50))调小批次降低延迟，但增加请求数 - 对延迟敏感服务（如网关），建议用 UDP reporter（
reporter.NewUDPReporter("localhost:9411", 1024)），但要接受少量不可靠上报 - 若 Zipkin 后端压力大，优先调低采样率，而不是增大 reporter 缓冲——后者只是把问题延后到内存 OOM
真正难的不是写那几行初始化代码，而是每次加新服务、换新中间件、对接老系统时，都要重新检查 reporter URL 是否可连、span 是否 finish、b3 header 是否透传——这些点散落在不同包、不同生命周期里，一漏就断链。
