TransmittableThreadLocal 线程池上下文传递：捕获重放恢复

大家好，我是晚安code。

这篇把事讲透：普通 ThreadLocal 为什么传不进线程池、InheritableThreadLocal 为什么也救不了，以及阿里开源 TransmittableThreadLocal 靠「捕获-重放-恢复」解决线程池上下文传递的原理与接入。点个收藏，往下看。

一、先看事故：一个串号的 userId

串号的根因不是异步，是「复用」。

先说最常见的场景。用户登录后，你把 userId 塞进 ThreadLocal，想着后续业务随时能取。但在微服务里，很多处理是丢给线程池异步做的，比如发短信、记日志、调下游 RPC。

java 复制代码

// 示例：普通 ThreadLocal，父线程的值传不进线程池
ThreadLocal<String> userId = new ThreadLocal<>();
userId.set("1001");

ExecutorService pool = Executors.newFixedThreadPool(1);
pool.submit(() -> {
    System.out.println("异步线程读到 userId: " + userId.get());
});

这段代码我在本地跑过，输出只有一行：

yaml 复制代码

异步线程读到 userId: null

ThreadLocal（线程本地变量）：Java 自带的线程私有存储，每个线程读写自己的那一份，别的线程碰不到。你可以理解为「每个人桌上贴着自己的便利贴」。子线程是另一张桌子，父线程写的内容它自然看不见。

问题就出在这：父线程（Tomcat 工作线程）把任务提交给线程池后，池子里的任务线程是另一个线程，ThreadLocal 根本不跨线程传值，所以读到的就是 null。值「丢」了还算轻的，更隐蔽的是下面这种------值「串」了。

二、InheritableThreadLocal 也救不了线程池

InheritableThreadLocal 救不了线程池，问题恰恰出在「继承」只发生在线程创建的那一刻。

InheritableThreadLocal（可继承的线程本地变量）：ThreadLocal 的扩展，子线程创建时把父线程的值复制一份带过去。你可以理解为「新桌子开张时，按老桌子的便利贴抄了一份」。

看起来能用，但线程池有个致命特点：线程是复用的，不是每个任务都新建线程。继承只在「创建线程」时抄一次，任务 B 复用同一个线程时，它拿到的是任务 A 留下的值------这就串号了。

java 复制代码

// 示例：InheritableThreadLocal + 线程池复用，任务B 读到任务A 的值
InheritableThreadLocal<String> userId = new InheritableThreadLocal<>();
userId.set("1001");

ExecutorService pool = Executors.newFixedThreadPool(1);

pool.submit(() -> {
    userId.set("1001-A");        // 任务A 改了自己的值
    System.out.println("任务A 读到: " + userId.get());
});
pool.submit(() -> {
    System.out.println("任务B 读到: " + userId.get());  // 任务B 没 set
});

运行结果：

less 复制代码

任务A 读到: 1001-A
任务B 读到: 1001-A     ← 串号：任务B 读到的是 A 的值

任务 B 从头到尾没写过值，却读到了 1001-A。想想看，如果这个值是 userId，用户 A 的操作被记到用户 B 名下，排查起来真要命。

三、TTL 是什么：阿里开源的线程池上下文传递库

TTL 是目前解决线程池上下文传递最省心的方案，没有之一。

TransmittableThreadLocal（可传递的线程本地变量，简称 TTL）：阿里巴巴开源的增强版 InheritableThreadLocal，专门解决线程池等复用场景下的上下文传递，零依赖，引 jar 就能用。你可以理解为「每次提交任务时都会重新抄一遍便利贴的 ThreadLocal」。

项目在 GitHub 上叫 alibaba/transmittable-thread-local，我核对的版本是 v2.14.5（2026 年 8 月），要求 Java 8+。接入它不改变你原来的写法------get() / set() 和 ThreadLocal 一模一样，只是多了线程池传递的能力。

看图 2：左边是旧方案的两条断头路（传不进 / 复用串号），右边是 TTL 的正确链路，三步走完值到位：

三种方案放一起对比，差异一眼就清楚：

方案	父线程传子线程	线程池复用	改动成本	推荐度
ThreadLocal	不传，读 null	值丢失/串号	无	★★
InheritableThreadLocal	创建时传一次	值错乱	无	★★
TransmittableThreadLocal	每次提交都传	正确传递	包任务或包线程池	★★★★★

四、捕获-重放-恢复：三阶段是怎么救场的

TTL 的所有魔法，都能拆成提交时捕获、执行时重放、执行后恢复这三步。

拿出差类比：你出门前拍一张房间照片（捕获快照 ），到酒店按照片把行李摆回原样（重放），退房时再把房间恢复成刚入住的样子（恢复）。TTL 干的就是这件事------提交任务那一刻拍下父线程的快照，任务线程执行前把快照重放进来，执行完立刻恢复现场。

我第一次看 TTL 源码时也没转过弯：重放不就好了，为什么还要「恢复」？原因就在「复用」二字------线程是公用的，这轮任务重放的值如果不恢复，下个任务就会读到，串号再次发生。所以恢复这一步，恰恰是防串号的保险栓。

看下面这张时序图，重点盯「提交时 capture」和「执行后 restore」这两个动作：

五、上手示例：TtlRunnable 与 TtlExecutors 两种接法

接入 TTL 只需要改「提交」这一步，业务逻辑一行不用动。

Maven 加一行依赖（Gradle 同理，版本以官方为准）：

xml 复制代码

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>transmittable-thread-local</artifactId>
    <version>2.14.5</version>
</dependency>

TTL 提供两种接入姿势，任选其一：

java 复制代码

// 示例：TTL 的两种接法
TransmittableThreadLocal<String> userId = new TransmittableThreadLocal<>();
userId.set("1001");

// 方式一：包装任务，提交时自动捕获快照
pool.submit(TtlRunnable.get(() ->
    System.out.println("异步线程读到: " + userId.get())));

// 方式二：包装线程池，提交处完全不用改
ExecutorService ttlPool = TtlExecutors.getTtlExecutorService(pool);
ttlPool.submit(() -> System.out.println("异步线程读到: " + userId.get()));

我把上一节的「串号现场」整体换成 TTL 重跑了一遍，输出是这样的：

yaml 复制代码

① ThreadLocal  异步线程读到: null
② ITL 任务A 读到: 1001-A
② ITL 任务B 读到: 1001-A（任务B 从未 set，却读到了别人的值）
③ TTL  异步线程读到: 1001
④ 包装池 异步线程读到: 1002

注意 ④：我把值改成 1002 再提交，包装池照样拿到新值------说明它捕获的是「这一次提交时」的快照，不是缓存的旧值。这正是 TTL 和 ITL 最本质的区别。

可能有人会问：同一个任务提交多次，每次都要重新 TtlRunnable.get() 吗？

要。快照是在调用 get() 那一刻捕获的，复用旧的包装对象会把上一次提交的快照带过来。所以规范是「提交一次，包装一次」。

六、什么时候该上 Java Agent

能用 TtlExecutors 就不要上 Agent，除非线程池藏在你看不见的框架里。

Java Agent ：通过 -javaagent 启动参数对 JDK 线程池做字节码增强，让所有提交自动带上下文，连包装这一步都不用写。你可以理解为「给线程池整体装了个自动感应装置」。

什么时候用得上？你自己代码里的线程池都能摸到，TtlExecutors 就够了。但像某些中间件、框架内部自己 new 的线程池，你改不到，才需要 Agent 全透明接管。

可能有人会问：那普通 ThreadLocal 是不是该全部换成 TTL？

不必。单线程内用的局部变量，ThreadLocal 完全够用。只有当「这个值需要跨线程传递，且经过线程池复用」时，才值得上 TTL。

结语

我的结论很直接：以后写跨线程传上下文，直接上 TransmittableThreadLocal，别在 ThreadLocal 和 InheritableThreadLocal 之间做选择题了。核心就一句话------提交时捕获快照，执行时重放，执行后恢复，串号这个坑就堵死了。

我是晚安code，持续分享编程干货。觉得有用的话记得点赞收藏和关注~也欢迎在评论区聊聊：你在线程池传递上下文时踩过串号的坑吗？最后是怎么解决的？