Java Spring @Async多线程场景下如何跨线程共享请求上下文数据

核心问题出在之前存储请求ID用的是普通ThreadLocal，这类容器本身是线程隔离的，父线程写入的值子线程天然无法读取，不需要把请求ID作为参数硬编码到所有@Async方法里，Spring生态本身提供了无侵入的扩展点，按以下步骤实现即可：

1. 替换上下文存储载体 #

不要自行实现基于普通ThreadLocal的上下文容器，优先选择适配线程池复用场景的存储方案：

• 最简方案是直接用SLF4J提供的MDC（Mapped Diagnostic Context）存储请求ID，这也是全链路追踪场景下的通用方案，不需要额外维护上下文类，后续日志打印也可以直接读取MDC中的值自动拼接请求ID。
• 如果需要存储自定义业务上下文，不要直接用InheritableThreadLocal——这类实现仅在线程创建时拷贝父线程值，在线程池复用工作线程的场景下会出现上下文串号问题，要选择支持任务级上下文传递的ThreadLocal实现。

2. 为@Async线程池配置任务装饰器，自动拷贝上下文 #

Spring的ThreadPoolTaskExecutor本身提供了TaskDecorator扩展点，可以在任务提交到线程池、实际执行的两个节点做切面逻辑，完全无侵入实现上下文传递，不需要修改任何@Async方法的定义：
首先自定义任务装饰器，在任务提交时捕获父线程的请求ID，子线程执行前写入上下文，执行完成后清空上下文避免串号：

public class RequestIdTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable task) {
        // 提交任务时，从当前父线程捕获请求ID
        String currentRequestId = MDC.get("X-Request-Id");
        return () -> {
            try {
                // 子线程执行任务前，写入请求ID到上下文
                MDC.put("X-Request-Id", currentRequestId);
                task.run();
            } finally {
                // 任务执行完成后清空上下文，避免线程池复用导致串号
                MDC.remove("X-Request-Id");
            }
        };
    }
}

之后将装饰器注入到@Async使用的线程池中，通过@EnableAsync开启异步能力时，实现AsyncConfigurer接口自定义异步执行器即可：

@Configuration
@EnableAsync
public class AsyncPoolConfig implements AsyncConfigurer {
    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(8);
        executor.setMaxPoolSize(32);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("biz-async-");
        // 注入自定义的上下文透传装饰器
        executor.setTaskDecorator(new RequestIdTaskDecorator());
        executor.initialize();
        return executor;
    }
}

注意：项目中所有自定义的业务线程池，只要会执行业务逻辑，都需要注入这个装饰器，否则依然会出现上下文断层。

3. 适配原有入口、出口拦截逻辑 #

之前实现的同步场景下的请求ID逻辑只需要调整存储载体，不需要改动核心流程：

• 入口拦截（Servlet Filter/Spring Interceptor）：请求进入时先从约定的请求头（比如X-Request-Id）读取ID，读不到就用UUID生成新值，写入MDC/自定义上下文；请求处理完成后在finally块中清空当前线程的上下文，避免Tomcat/NIO线程复用导致串号。
• 出站拦截（RestTemplate/OpenFeign/WebClient拦截器）：发起下游调用时，直接从MDC/上下文中读取请求ID，追加到请求头中传递即可。这部分逻辑在异步线程中执行时，因为TaskDecorator已经提前完成了上下文拷贝，可以直接读到正确的ID值，不需要额外编码。

常见踩坑点 #

• 不要直接依赖InheritableThreadLocal做上下文传递：如前文所说，线程池复用场景下它不会重新拷贝父线程的上下文，会出现A请求的ID出现在B请求异步日志里的串号问题，必须配合任务级的拷贝、清理逻辑使用。
• 日志格式可以直接配置MDC字段，比如在logback/log4j2的pattern中加入%X{X-Request-Id}，异步线程打印的日志会自动带上对应的请求ID，不需要手动在每一行日志里传参。
• 如果项目中用了@Scheduled定时任务，这类任务没有上游请求，需要在任务执行前生成默认的请求ID写入上下文，避免出现ID空值的问题。

内容的提问来源于stack exchange，提问作者Shaul Zuarets