completablefuture 默认不继承主线程 mdc 上下文，需显式捕获、主动恢复并清理；应使用装饰线程池或 ttl 透传，链式调用各阶段均需独立处理，定时与远程调用场景亦须补全。

CompletableFuture 默认不继承主线程的 MDC 上下文，因为其底层依赖 ThreadLocal，而子线程无法自动获取父线程的上下文快照。直接使用 supplyAsync() 或 thenApplyAsync() 会丢失 traceId、userId 等关键日志标记，导致链路追踪断裂。解决核心是：**显式捕获 + 主动恢复 + 清理兜底**。

用包装线程池替代默认 ForkJoinPool

CompletableFuture 的无参方法（如 supplyAsync(() -> ...)）默认使用 ForkJoinPool.commonPool()，该线程池无法透传 MDC。必须指定自定义线程池，并确保它能携带上下文：

• 推荐使用 Spring 的 TaskDecorator 对 ThreadPoolTaskExecutor 做装饰，在任务执行前复制 MDC、执行后清理
• 或手动封装：调用 MDC.getCopyOfContextMap() 获取快照，传入 Runnable/Callable 构造器，在 run() 开头调用 MDC.setContextMap(map)，结尾调用 MDC.clear()
• 避免复用未清理的线程：线程池中线程被复用时，若上一次任务未 clear，MDC 会残留脏数据

适配 CompletableFuture 链式调用

每个异步阶段（thenApplyAsync、thenComposeAsync 等）都需独立处理上下文，不能只在首层设置：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• 所有带 Async 后缀的方法，必须显式传入已装饰的线程池，例如：thenApplyAsync(fn, decoratedExecutor)
• 不要依赖“自动继承”——即使上游已设好 MDC，下游新线程仍为空
• 若使用 CompletableFuture.allOf() 或 anyOf() 聚合多个任务，每个子任务都需单独做上下文透传

用 TransmittableThreadLocal（TTL）简化透传

相比手动快照/恢复，TTL 提供更透明的解决方案，尤其适合复杂异步链路：

• 引入 com.alibaba:transmittable-thread-local 依赖
• 将 traceId 存入 TransmittableThreadLocal<string></string>，而非普通 ThreadLocal
• 用 TtlExecutors.getTtlExecutorService(originalExecutor) 包装线程池，后续所有 submit/run/submitCallable 自动透传
• 对 CompletableFuture，优先使用 supplyAsync(supplier, ttlExecutor)，禁用无参形式

注意定时与远程调用场景

@Scheduled 方法和 Feign/Dubbo 调用容易被忽略，但同样会断链：

• @Scheduled 方法启动时，MDC 为空，需在方法入口主动检查并补全 traceId（如通过 UUID 生成临时 ID）
• Feign 拦截器中读取 MDC.get("traceId")，写入请求头；下游服务在 Filter 中解析并重新绑定到 MDC
• Dubbo 的 Filter 机制同理，需在 provider 端反向注入

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南