大家好，我是晚安code。
这篇把事讲透：普通 ThreadLocal 为什么传不进线程池、InheritableThreadLocal 为什么也救不了，以及阿里开源 TransmittableThreadLocal 靠「捕获-重放-恢复」解决线程池上下文传递的原理与接入。点个收藏，往下看。
一、先看事故：一个串号的 userId
串号的根因不是异步，是「复用」。
先说最常见的场景。用户登录后，你把 userId 塞进 ThreadLocal，想着后续业务随时能取。但在微服务里，很多处理是丢给线程池异步做的，比如发短信、记日志、调下游 RPC。
// 示例：普通 ThreadLocal，父线程的值传不进线程池
ThreadLocal<String> userId = new ThreadLocal<>();
userId.set("1001");
ExecutorService pool = Executors.newFixedThreadPool(1);
pool.submit(() -> {
System.out.println("异步线程读到 userId: " + userId.get());
});
这段代码我在本地跑过，输出只有一行：
异步线程读到 userId: null
ThreadLocal（线程本地变量）：Java 自带的线程私有存储，每个线程读写自己的那一份，别的线程碰不到。你可以理解为「每个人桌上贴着自己的便利贴」。子线程是另一张桌子，父线程写的内容它自然看不见。
问题就出在这：父线程（Tomcat 工作线程）把任务提交给线程池后，池子里的任务线程是另一个线程，ThreadLocal 根本不跨线程传值，所以读到的就是 null。值「丢」了还算轻的，更隐蔽的是下面这种——值「串」了。
二、InheritableThreadLocal 也救不了线程池
InheritableThreadLocal 救不了线程池，问题恰恰出在「继承」只发生在线程创建的那一刻。
InheritableThreadLocal（可继承的线程本地变量）：ThreadLocal 的扩展，子线程创建时把父线程的值复制一份带过去。你可以理解为「新桌子开张时，按老桌子的便利贴抄了一份」。
看起来能用，但线程池有个致命特点：线程是复用的，不是每个任务都新建线程。继承只在「创建线程」时抄一次，任务 B 复用同一个线程时，它拿到的是任务 A 留下的值——这就串号了。
// 示例：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
});
运行结果：
任务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 同理，版本以官方为准）：
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>transmittable-thread-local</artifactId>
<version>2.14.5</version>
</dependency>
TTL 提供两种接入姿势，任选其一：
// 示例：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 重跑了一遍，输出是这样的：
① 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，持续分享编程干货。觉得有用的话记得点赞收藏和关注~也欢迎在评论区聊聊：你在线程池传递上下文时踩过串号的坑吗？最后是怎么解决的？
