ThreadLocal 在分布式追踪中失效，因其值绑定单线程，无法跨线程池、异步任务等场景传递 traceId；可靠方案是 MDC + 显式透传封装或使用 TransmittableThreadLocal（TTL）增强。
Java 中 ThreadLocal 本身不能直接支撑分布式追踪的调用链透传，因为它只在单线程内有效，跨线程（尤其是线程池复用）时上下文会丢失。要实现 traceId 在整个异步调用链中稳定传递，必须结合机制增强或替代方案。
为什么 ThreadLocal 在分布式追踪中会失效
ThreadLocal 值绑定在具体线程上，而分布式追踪要求 traceId 从 HTTP 入口开始，贯穿同步调用、线程池任务、定时任务、CompletableFuture 等所有执行阶段。但：
- 线程池中的线程被反复使用，MDC 或自定义 ThreadLocal 的值不会自动清空或更新
- InheritableThreadLocal 只能传递给子线程，无法应对线程池 submit/execute 场景
- HTTP 请求结束时若未清理 MDC，残留 traceId 可能污染后续请求日志
主流可靠方案：MDC + 显式透传封装
这是 Spring 生态中最常用、最可控的方式，不依赖第三方库，适配性广：
- 在 Web Filter 或 Interceptor 中生成 traceId，通过
MDC.put("traceId", id)绑定到当前线程 - 所有线程池提交任务前，必须包装为
TraceableRunnable或TraceableCallable，构造时调用MDC.getCopyOfContextMap()快照上下文，执行时先MDC.setContextMap()再运行业务逻辑 - Spring Boot 推荐用
ThreadPoolTaskExecutor配合setTaskDecorator，统一注入MdcTaskDecorator，避免每个 submit 都手动包装 - CompletableFuture 必须指定自定义线程池（如
supplyAsync(fn, executor)），禁用默认 ForkJoinPool
更轻量高效的方案：TransmittableThreadLocal（TTL）
阿里开源的 TTL 是专为解决该问题设计的增强型 ThreadLocal，原理是“捕获-传递-回放”（CRR）：
- 引入依赖
com.alibaba:transmittable-thread-local - 将普通
ThreadLocal替换为TransmittableThreadLocal，或直接用MDC配合TtlMDCAdapter - 提交任务时用
TtlRunnable.get(runnable)包装，或用TtlExecutors.getTtlExecutorService(executor)修饰整个线程池 - 支持嵌套线程池、定时任务、RxJava、Dubbo 等复杂场景，且对业务代码侵入极小
定时与异步任务的特别处理
这些地方最容易漏掉 traceId，导致链路断裂：
- @Scheduled 方法每次执行都是新线程，需在方法开头重新从 MDC 获取或生成 traceId 并 put 进去
- XXL-JOB、Quartz 等调度框架，可通过 JobDataMap 携带 traceId，或在 JobListener 中统一注入
- 消息队列消费者（如 Kafka Listener）需在 onMessage 前还原上下文，可借助 AOP 或监听器拦截
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
