traceid 是链路追踪核心标识，需通过 threadlocal 实现线程内透传，并结合显式捕获、复制与绑定机制支持跨线程传递；生产环境应优先使用 sleuth、skywalking 或 opentelemetry 等成熟框架。

在分布式系统中，TraceId 是链路追踪的核心标识，用于串联一次请求经过的所有服务节点。要让 TraceId 在同一线程内透传、跨线程（如线程池、异步调用）也能延续，ThreadLocal 本身只能解决单线程内的存储问题，必须配合显式传递与上下文复制机制才能真正支撑全链路追踪。

ThreadLocal 存储 TraceId 的基本用法

ThreadLocal 提供线程隔离的变量副本，适合保存当前线程专属的 TraceId：

• 初始化时从请求头（如 X-B3-TraceId 或 trace-id）提取并写入 ThreadLocal
• 后续同一线程内任意位置可通过 get() 获取，无需层层手动传参
• 请求结束时务必调用 remove()，避免线程复用（如 Tomcat 线程池）导致 TraceId 被污染

ThreadLocal 无法自动跨线程：常见陷阱

以下场景中，仅靠 ThreadLocal 会丢失 TraceId：

• 使用 CompletableFuture.supplyAsync() 或 new Thread().start() 启动新线程
• 提交任务到自定义线程池（如 ThreadPoolExecutor）
• Spring 中使用 @Async 注解的方法

原因：子线程拥有独立的 ThreadLocal Map，不会继承父线程的值。

跨线程传递 TraceId 的可靠方案

核心思路是「捕获 + 复制 + 绑定」：

• 手动捕获：在提交任务前，从当前 ThreadLocal 读取 TraceId
• 显式传递：将 TraceId 作为参数或封装进 Runnable/Callable
• 子线程绑定：在新线程执行逻辑前，把 TraceId 写入其 ThreadLocal，并在结束后清理

更优做法是封装通用工具类，例如：

• 包装线程池（继承 ThreadPoolExecutor），重写 beforeExecute 和 afterExecute 自动传递/清理
• 为 CompletableFuture 提供带上下文的静态工厂方法（如 withTrace(()->...)）
• Spring 场景下，可结合 AsyncConfigurer 自定义 TaskDecorator 实现透明增强

与主流链路追踪框架的协同

不要重复造轮子。成熟方案已内置上下文传播能力：

• Spring Cloud Sleuth + Zipkin：自动注入 Tracer，通过 currentSpan() 获取 TraceId，并支持 wrap() 包装 Runnable/Callable
• Apache SkyWalking：提供 ContextManager，其 capture() / resume() 方法专为跨线程设计
• OpenTelemetry Java SDK：使用 Context.current().with(Span) 构建可传递的 Context 对象，配合 Context.wrap(Runnable) 安全跨线程

自行基于 ThreadLocal 实现时，应视作学习或轻量定制场景；生产环境优先集成标准 SDK，它们已解决上下文传播、异步适配、MDC 集成等细节问题。