TransmittableThreadLocal：跨线程池的上下文传递

一句话结论（30s）

TTL 的本质是”通过装饰任务在提交/执行/结束三个时机搬运 ThreadLocal 快照”，因为线程池复用线程导致残留污染、InheritableThreadLocal 只在 Thread 构造时浅拷贝一次。关键设计是 CRR 装饰模式：父线程捕获（深拷贝快照）→ 子线程执行前重放 → 执行后恢复。权衡是每个任务多一次深拷贝开销，换来跨线程池上下文的无损传递和最小侵入。

核心原理（2min）

TtlRunnable.get(task) 在父线程捕获所有已注册 TTL 的深拷贝快照；子线程 run() 前把快照重放到自己 ThreadLocal；执行后恢复成执行前原值，防止双向污染。默认深拷贝避免父子共享引用导致数据错乱，可用 Transmitter 自定义策略；另有 Java Agent 字节码增强实现无侵入。

底层深入（5-10min）

ThreadLocal在线程池场景下有一个著名的大坑：线程复用导致上次任务的残留值污染下一次任务。InheritableThreadLocal试图解决父子线程的上下文传递，但在线程池面前同样失效。阿里巴巴开源的TransmittableThreadLocal（TTL）就是为这个场景设计的。

ThreadLocal的线程池污染问题

ThreadLocal<String> context = new ThreadLocal<>();

// 请求1：设置了context="张三"
context.set("张三");
processRequest();  // 打印"张三"
// 请求1结束，context没有remove

// 请求2：没有set，复用了请求1的线程
processRequest();  // 打印"张三"——这是残留数据，请求2应该是null！

线程池中的线程不销毁，ThreadLocal的值会一直保留。解决方案是在每次使用后用try-finally确保remove。但一旦忘了remove，问题就出现了。

想一想：为什么线程池会让 ThreadLocal 残留？因为池中线程不销毁，上次任务 set 的值如果没 remove，就一直留在 Thread.threadLocals 里；下次复用同一线程的任务直接读到脏值。

InheritableThreadLocal：父子线程传递的局限

InheritableThreadLocal允许子线程”继承”父线程的ThreadLocal值：

InheritableThreadLocal<String> context = new InheritableThreadLocal<>();
context.set("父线程的值");

new Thread(() -> {
    System.out.println(context.get());  // "父线程的值"——继承成功
}).start();

原理：Thread构造时（init()方法中），如果父线程的inheritableThreadLocals不为空，会浅拷贝一份给子线程。

但在线程池场景下彻底失效：线程池的线程是预先创建好并反复使用的，不会重新调用Thread的构造函数——InheritableThreadLocal的”继承”只在构造线程的那一刻发生一次。之后父线程的上下文变化不会再传递给已存在的池中线程。

想一想：为什么 ITL 在线程池下彻底失效？因为 ITL 的继承动作只发生在 Thread 构造时（init() 里浅拷贝一次），池中线程早已构造好、不会再走构造函数，父线程之后的变化自然传不进去。

TTL的核心设计：CRR装饰模式

TTL不修改线程池，而是装饰（包装）提交给线程池的任务。核心是CRR模式：

C（Callable 装饰）：TtlCallable包装一个Callable
R（Runnable 装饰）：TtlRunnable包装一个Runnable
R（Runnable 普通线程转型）：TtlRunnable也支持在普通new Thread场景

工作机制：三个时机

时机一：提交任务时（在调用者线程）—— 捕获（Capture）

// 在父线程中
TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();
context.set("traceId-12345");

// TtlRunnable.get() 在父线程执行，捕获当前所有TTL的值
executorService.submit(TtlRunnable.get(() -> {
    // 这个lambda在子线程执行时会自动拥有context的值
    String traceId = context.get();  // "traceId-12345"
}));
context.remove();  // 父线程可以立即清理

TtlRunnable.get(task)调用时，在父线程中执行捕获（Capture）：遍历所有已注册的TTL，深拷贝它们的值，打包成一个backup快照。

想一想：为什么要”深拷贝”快照而不是直接传引用？因为父子线程共享同一引用时，子线程改字段会污染父线程；深拷贝隔离出两份数据，互不影响，也呼应了后面”防止传递引用被意外修改”的动机。

时机二：任务执行前（在工作线程）—— 重放（Replay）

子线程拿到任务后，执行run()之前，先把backup中捕获的上下文值**重放（Replay）**到子线程的ThreadLocal中。此时子线程中的TTL值等于父线程提交任务那一刻的值。

时机三：任务执行后（在工作线程）—— 恢复（Restore）

任务执行完毕后，把子线程的TTL值恢复成执行前该线程原有的值（如果有的话），防止先前残留的值影响本次任务，也防止本次任务设置的值残留给后续复用的线程。

想一想：为什么执行完还要”恢复”一步？因为要防双向污染：既防止本次任务设置的值残留给下一个复用线程，也要恢复执行前该线程原有的值——否则上下文在两次方向上都可能串。

深拷贝：防止传递引用被意外修改

InheritableThreadLocal的浅拷贝有一个隐蔽问题：如果父子线程共享了同一个引用对象，子线程修改这个对象的字段，父线程也会看到修改——可能造成数据错乱。

TTL默认使用深拷贝（通过transmit()方法获取副本）。你可以自定义拷贝策略——比如通过实现TransmittableThreadLocal.Transmitter接口来指定序列化/反序列化方式，或者干脆不深拷贝（适合不可变对象，如String、Long）。

TTL Agent：无侵入使用

如果你不想修改业务代码（把所有Runnable都包一层TtlRunnable.get()），TTL提供了Java Agent方式：

java -javaagent:transmittable-thread-local.jar -jar your-app.jar

Agent在类加载时对线程池的execute、submit等方法做了字节码增强，自动包装提交的Runnable/Callable。这对升级遗留系统非常友好。

实战建议

ThreadLocal使用后必须remove：不管用不用TTL，都要在finally块中清理。
线程池场景传递上下文用TTL：不要自己手写”提交前get、执行时set、执行后remove”的模板代码。
选择拷贝策略：小对象用默认深拷贝，大对象或不可变对象可以自定义轻量级拷贝。
监控TTL的捕获/重放开销：高并发下，每个任务都要深拷贝一批TTL值，如果TTL里放了大型对象（如整个Session对象），开销会非常大。只传必要的键值。
JDK 21的ScopedValue是ThreadLocal的取代方向：对于不可变上下文的线程传递，JDK 21的ScopedValue（预览特性）提供了更优雅的结构化并发支持，可以作为TTL的替代方案。

TTL解决了Java生态中一个非常实际的痛点——在一个没有官方支持的”线程上下文传递”领域，用最小的侵入和清晰的语义提供了健壮的解决方案。它是阿里中间件团队最广为流传的开源贡献之一。

章末提问

追问 1：ThreadLocal 在线程池下为什么会”串”？InheritableThreadLocal 为什么也救不了？

回答思路：结论先行——线程池复用线程导致上次任务残留值污染下次任务；InheritableThreadLocal 只在 Thread 构造时浅拷贝一次，池中线程早已构造好、父线程后续变化传不进去。因为池中线程不销毁、ThreadLocal 值不 remove 就一直留着；ITL 的继承动作发生在构造函数里，线程复用不会重走构造。

追问 2：TTL 的 CRR 模式是怎么工作的？

回答思路：结论先行——在提交/执行/结束三个时机搬运快照：父线程捕获（深拷贝）→ 子线程执行前重放 → 执行后恢复。因为 TtlRunnable.get(task) 在父线程遍历所有已注册 TTL 深拷贝成 backup；子线程 run() 前把 backup 重放到自己 ThreadLocal；执行完恢复成执行前原值，防止双向污染。

追问 3：TTL 为什么要深拷贝？有什么代价？

回答思路：结论先行——深拷贝防止父子线程共享引用导致数据错乱，代价是每个任务多一次深拷贝开销。因为浅拷贝下子线程改字段会污染父线程；深拷贝隔离两份数据。高并发时若 TTL 里放了大对象（整个 Session），每个任务都深拷贝一批值，开销会很大，所以只传必要键值、或对不可变对象自定义轻量拷贝策略。