做过全链路追踪的同学肯定都遇到过这个问题：主线程设置了 TraceID，异步任务或线程池中新线程里却拿不到这个值，导致日志里 TraceID 断掉了，排查问题时要在一堆没有上下文关联的日志里大海捞针。

我之前就遇到过这样一个案例：一个接口处理耗时 5 秒，排查后发现代码里用了 @Async 注解异步执行数据库操作，但子线程的日志里 TraceID 是空的，问了半天才发现是线程池上下文丢失的问题。

今天我们就来聊聊为什么异步场景下上下文会丢失，以及如何用 InheritableThreadLocal 或 TransmittableThreadLocal 来完美解决这个问题。

线程上下文丢失的真相

1. 为什么异步会丢上下文

问题场景：

主线程：
┌─────────────────────────────────────────────┐
│  Thread-1                                  │
│  TraceID: abc123                           │
│  UserID: 100                               │
│  RequestID: req-001                        │
└─────────────────────────────────────────────┘
        │
        │ 提交到线程池
        ▼
┌─────────────────────────────────────────────┐
│  ThreadPool-Worker-3                       │
│  TraceID: ??? (空的!)                      │
│  UserID: ??? (空的!)                       │
│  RequestID: ??? (空的!)                   │
└─────────────────────────────────────────────┘

原因：线程池中的新线程是预创建的，跟主线程没有任何关系

2. 普通 ThreadLocal 的局限

ThreadLocal 工作原理：

┌─────────────────────────────────────────────┐
│  ThreadLocalMap                            │
│  ┌─────────────────────────────────────┐  │
│  │ key: TraceID, value: abc123         │  │
│  │ key: UserID, value: 100             │  │
│  └─────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
           │
           │ Thread-1 独享
           ▼
每个线程都有自己的独立存储空间，互不干扰

问题：子线程使用的是完全不同的 Thread 对象
     普通 ThreadLocal 无法跨线程传递数据

3. 异步场景的三个典型坑

坑1: @Async 注解
@Async
public void asyncProcess() {
    log.info("TraceID: {}", TraceID.get()); // null!
}

坑2: 线程池提交任务
CompletableFuture.supplyAsync(() -> {
    log.info("TraceID: {}", TraceID.get()); // null!
});

坑3: 批量处理
List<Thread> threads = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    threads.add(new Thread(() -> {
        log.info("TraceID: {}", TraceID.get()); // null!
    }));
}

解决方案一：InheritableThreadLocal

1. 核心原理

InheritableThreadLocal 工作原理：

主线程设置值：
Thread-1.set("TraceID", "abc123")

创建子线程时（只有 new Thread() 才有效）：
┌─────────────────────────────────────────────┐
│  父 Thread-1 的 InheritableThreadLocal     │
│  TraceID: abc123                           │
└─────────────────────────────────────────────┘
                    │
                    │ 传递给子线程
                    ▼
┌─────────────────────────────────────────────┐
│  子 Thread-2 的 InheritableThreadLocal      │
│  TraceID: abc123 (自动继承!)               │
└─────────────────────────────────────────────┘

特点：
- 子线程自动继承父线程的值
- 但只限于 new Thread() 的场景
- 线程池复用线程时，值不会更新

2. 为什么线程池场景下也失效

线程池的问题：

1. 线程预先创建好
   ThreadPool-Worker-1 已经在等了

2. 第一次使用（主线程 A）
   ┌─────────────────────────────────────────┐
   │ ThreadPool-Worker-1                    │
   │ TraceID: A's TraceID (继承自 A)         │
   └─────────────────────────────────────────┘

3. 第二次使用（主线程 B）
   ┌─────────────────────────────────────────┐
   │ ThreadPool-Worker-1 (复用了!)           │
   │ TraceID: A's TraceID (还是旧的!)        │
   └─────────────────────────────────────────┘
                      │
                      │ 问题：B 的 TraceID 没有传进去
                      ▼
                   日志串了！

3. InheritableThreadLocal 的局限

局限性总结：

1. ❌ 只在 new Thread() 时传递一次
2. ❌ 线程池复用时不会重新传递
3. ❌ 不支持线程池场景
4. ❌ 不支持夸服务的上下文传递
5. ❌ 线程复用导致上下文污染

结论：InheritableThreadLocal 只适合简单的父子线程场景
      不适合线程池场景！

解决方案二：TransmittableThreadLocal

1. 核心原理

TransmittableThreadLocal 工作原理：

1. 捕获：在线程池提交任务前，捕获当前上下文
   ┌─────────────────────────────────────────┐
   │ 主线程上下文                            │
   │ TraceID: abc123                         │
   │ UserID: 100                            │
   │ RequestID: req-001                     │
   └─────────────────────────────────────────┘

2. 传输：任务提交到线程池时携带上下文
   ┌─────────────────────────────────────────┐
   │ TtlRunnable / TtlCallable              │
   │ 携带: abc123, 100, req-001             │
   └─────────────────────────────────────────┘

3. 注入：在线程池工作线程执行前，注入上下文
   ┌─────────────────────────────────────────┐
   │ ThreadPool-Worker-1                    │
   │ TraceID: abc123 (重新注入!)            │
   └─────────────────────────────────────────┘

4. 还原：执行完毕后，还原线程原有上下文

2. 阿里 TTL 的优势

TransmittableThreadLocal 优势：

1. ✅ 线程池场景完美支持
2. ✅ 每次任务执行前都重新捕获
3. ✅ 任务执行后自动还原
4. ✅ 支持跨线程池传递
5. ✅ 支持夸服务传递（配合框架）
6. ✅ 兼容 ThreadLocal 用法

3. 使用方式

方式1：使用 TtlExecutors 包装线程池

ExecutorService ttlExecutor = TtlExecutors.getTtlExecutor(executor);

方式2：使用 TtlRunnable / TtlCallable 包装任务

Runnable task = TtlRunnable.get(() -> {
    log.info("TraceID: {}", TraceID.get());
});

方式3：使用 @TransmittableThreadLocal 注解（推荐）

@TransmittableThreadLocal
static String TraceID = new String();

方式4：配合 Alibaba Cloud SchedulerX（生产级方案）

支持：
- 任务框架原生支持
- 跨机器传递
- 故障恢复
- 监控告警

实战方案

方案一：自定义 TtlRunnable

实现要点：

1. 定义上下文持有类
public class ContextHolder {
    private static final TransmittableThreadLocal<String> TRACE_ID =
        new TransmittableThreadLocal<>();

    public static void set(String traceId) {
        TRACE_ID.set(traceId);
    }

    public static String get() {
        return TRACE_ID.get();
    }
}

2. 提交任务时包装
Runnable ttlTask = TtlRunnable.get(() -> {
    // 这里可以获取到主线程的 TraceID
    log.info("TraceID: {}", ContextHolder.get());
});

3. 使用 TtlExecutors
ExecutorService executor = TtlExecutors.getTtlExecutor(
    new ThreadPoolExecutor(10, 10, 0L, TimeUnit.MILLISECONDS,
        new LinkedBlockingQueue<>())
);

方案二：配合 Spring @Async

实现要点：

1. 配置 TaskDecorator
@Configuration
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(20);
        executor.setQueueCapacity(100);
        executor.setTaskDecorator(new ContextTaskDecorator());
        executor.initialize();
        return executor;
    }
}

2. 定义 TaskDecorator
public class ContextTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        String traceId = ContextHolder.get();
        return TtlRunnable.get(() -> {
            ContextHolder.set(traceId);
            runnable.run();
        });
    }
}

方案三：配合 hutool-all

hutool-all 封装了 TTL，开箱即用：

引入依赖：
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.0</version>
</dependency>

使用方式：
// 包装线程池
ExecutorService executor =cn.hutool.core.thread.ThreadUtil.newExecutor(10, 20);

// 直接使用，ThreadUtil 会自动处理上下文
CompletableFuture.runAsync(() -> {
    log.info("TraceID: {}", ContextHolder.get());
}, executor);

最佳实践

1. 统一封装上下文工具

统一封装示例：

public class TraceContext {
    private static final TransmittableThreadLocal<Map<String, String>> CONTEXT =
        new TransmittableThreadLocal<>();

    public static void set(String key, String value) {
        Map<String, String> context = getOrCreateContext();
        context.put(key, value);
    }

    public static String get(String key) {
        Map<String, String> context = CONTEXT.get();
        return context != null ? context.get(key) : null;
    }

    public static void setTraceId(String traceId) {
        set("traceId", traceId);
    }

    public static String getTraceId() {
        return get("traceId");
    }

    public static void clear() {
        CONTEXT.remove();
    }

    private static Map<String, String> getOrCreateContext() {
        Map<String, String> context = CONTEXT.get();
        if (context == null) {
            context = new HashMap<>();
            CONTEXT.set(context);
        }
        return context;
    }
}

2. 统一线程池创建工具

线程池工具类：

public class ThreadPoolBuilder {
    public static ExecutorService createTtlExecutor(int corePoolSize, int maxPoolSize) {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(corePoolSize);
        executor.setMaxPoolSize(maxPoolSize);
        executor.setQueueCapacity(100);
        executor.setTaskDecorator(new ContextTaskDecorator());
        executor.setThreadNamePrefix("ttl-");
        executor.initialize();
        return TtlExecutors.getTtlExecutor(executor);
    }
}

// 使用
@Resource(name = "ttlExecutor")
private ExecutorService ttlExecutor;

3. 统一入口处设置上下文

Filter 中统一设置：

@Component
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                   HttpServletResponse response,
                                   FilterChain chain) {
        String traceId = request.getHeader("X-Trace-ID");
        if (traceId == null) {
            traceId = UUID.randomUUID().toString();
        }
        TraceContext.setTraceId(traceId);

        try {
            chain.doFilter(request, response);
        } finally {
            TraceContext.clear();
        }
    }
}

4. 日志自动打印 TraceID

MDC 设置：

@Component
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                   HttpServletResponse response,
                                   FilterChain chain) {
        String traceId = request.getHeader("X-Trace-ID");
        if (traceId == null) {
            traceId = UUID.randomUUID().toString();
        }

        MDC.put("traceId", traceId);
        TraceContext.setTraceId(traceId);

        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove("traceId");
            TraceContext.clear();
        }
    }
}

效果对比

总结

异步线程池上下文传递的核心原则：

1. 不要用普通 ThreadLocal：异步场景下会丢失
2. 不要用 InheritableThreadLocal：线程池复用时也会丢失
3. 使用 TransmittableThreadLocal：线程池场景完美支持
4. 配合 TaskDecorator：Spring @Async 必须配置装饰器
5. 统一线程池封装：避免遗漏，强制使用 TTL 线程池

记住：异步不等于无上下文。只要做好上下文传递，异步日志也能完整关联。

源码获取

文章已同步至小程序博客栏目，需要源码的请关注小程序博客。

公众号：服务端技术精选

小程序码：