CompletableFuture默认不传递线程上下文，需通过ThreadLocal快照+自定义Executor手动透传；Spring项目可结合AsyncConfigurer与TaskDecorator统一治理，跨服务需配合OpenTelemetry等标准方案注入请求头。
在企业级分布式链路中，CompletableFuture 默认不继承或传递线程上下文（如 TraceId、用户身份、租户信息等），直接使用会导致链路追踪断裂、日志脱节、权限上下文丢失。解决核心在于：**手动注入与透传上下文，并确保异步执行时上下文可被正确捕获和还原**。
用 ThreadLocal + 自定义 Executor 封装上下文
这是最常用且可控的方式。原理是将当前线程的 ThreadLocal 快照保存，在异步任务执行前还原。
- 定义一个上下文快照工具类（如
TraceContextSnapshot），把关键字段（traceId、spanId、tenantId等）序列化为不可变对象 - 包装原始
Executor，在execute()/submit()前捕获快照，执行时先还原再调用业务逻辑 - 对
CompletableFuture的所有异步方法（supplyAsync、thenApplyAsync等）统一指定该包装后的Executor
示例：
public class ContextAwareExecutor implements Executor {
private final Executor delegate;
public ContextAwareExecutor(Executor delegate) {
this.delegate = delegate;
}
@Override
public void execute(Runnable command) {
TraceContextSnapshot snapshot = TraceContext.currentSnapshot();
delegate.execute(() -> {
try (TraceContext.Scope scope = snapshot.restore()) {
command.run();
}
});
}
}
用 CompletableFuture 的 defaultExecutor 替换为上下文感知型
全局替换默认异步执行器，避免每个 async 调用都显式传参。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
立即学习“Java免费学习笔记（深入）”；
- 通过
ForkJoinPool.commonPool()不支持上下文透传，必须自定义线程池 - 启动时用
CompletableFuture.defaultExecutor(new ContextAwareExecutor(customThreadPool))（注意：JDK 19+ 才支持此 API；JDK 8–18 需靠反射或框架层拦截） - 更稳妥做法是封装工具方法：
AsyncUtil.supplyAsync(() -> ...)内部固定使用上下文感知的Executor
结合 Spring 的 TaskDecorator 或 AsyncConfigurer
若项目基于 Spring，优先利用其异步抽象能力统一治理。
- 实现
AsyncConfigurer，重写getAsyncExecutor()返回带上下文装饰的ThreadPoolTaskExecutor - 设置
setTaskDecorator(new ContextCopyingDecorator())，在每个任务执行前后复制ThreadLocal数据 - Spring 的
@Async方法、CompletableFuture工具类均可复用同一套上下文机制
注意跨服务调用时的上下文传播
单机内上下文透传只是第一步；分布式链路还需将上下文透出到 HTTP/GRPC/RPC 请求头中。
- 在发起远程调用前，从当前
TraceContext提取traceId、spanId等，注入到HttpHeaders或 RPC 的Attachments - 下游服务需有对应 Filter/Interceptor 解析并重建
ThreadLocal上下文 - 推荐集成标准方案如
OpenTelemetry或Spring Cloud Sleuth（已内置CompletableFuture上下文支持）
不复杂但容易忽略：所有 thenAccept、thenCompose 等无 Async 后缀的方法都在当前线程同步执行，不会触发上下文切换；只有带 Async 后缀的方法才真正跨线程，才是上下文透传的关键战场。
