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 集成等细节问题。
