📖 English Documentation | 📖 中文文档

• 🔧 功能
• 🎨 需求场景
• 👥 User Guide
  • 1. 简å?•ä½¿ç”¨
  • 2. ä¿?è¯?线程池中传递值
    • 2.1 修饰Runnableå’ŒCallable
      • 整个过程的完整时åº?图
    • 2.2 修饰线程池
    • 2.3 使用Java Agentæ?¥ä¿®é¥°JDK线程池实现类
      • Java Agentçš„å?¯åŠ¨å?‚æ•°é…?ç½®
• 🔌 Java API Docs
• ðŸ?ª Mavenä¾?èµ–
• 🔨 关于编译构建与IDEå¼€å?‘
• â?“ FAQ
• ✨ 使用TTL的好处与必è¦?性
• 🗿 更多文档
• 📚 相关资料
  • JDK Core Classes
• ðŸ’? Who used
• 👷 Contributors

🔧 功能

👉 TransmittableThreadLocal(TTL)：在使用线程池等会池化å¤?用线程的执行组件情况下，æ??ä¾›ThreadLocal值的传递功能，解决异步执行时上下文传递的问题。一个Java标准库本应为框架/中间件设施开å?‘æ??供的标é…?能力，本库功能è?šç„¦ & 0ä¾?赖，支æŒ?Java 17/16/15/14/13/12/11/10/9/8/7/6。

JDKçš„InheritableThreadLocalç±»å?¯ä»¥å®Œæˆ?父线程到å­?线程的值传递。但对于使用线程池等会池化å¤?用线程的执行组件的情况，线程由线程池创建好，并且线程是池化起æ?¥å??å¤?使用的；这时父å­?线程关系的ThreadLocal值传递已ç»?没有æ„?义，应用需è¦?的实际上是把 任务æ??交给线程池时的ThreadLocal值传递到 任务执行时。

本库æ??供的TransmittableThreadLocal类继承并加强InheritableThreadLocal类，解决上述的问题，使用详è§? User Guide。

整个TransmittableThreadLocal库的核心功能（用户API与框架/中间件的集æˆ?APIã€?线程池ExecutorService/ForkJoinPool/TimerTaskå?Šå…¶çº¿ç¨‹å·¥åŽ‚çš„Wrapper），å?ªæœ‰ ~1000 SLOC代ç ?行，é?žå¸¸ç²¾å°?。

欢迎 �

• 建议和æ??问，æ??交 Issue
• 贡献和改进，Fork å?Žæ??通过 Pull Request 贡献代ç ?

🎨 需求场景

ThreadLocal的需求场景å?³TransmittableThreadLocal的潜在需求场景，如果你的业务需è¦?『在使用线程池等会池化å¤?用线程的执行组件情况下传递ThreadLocal值ã€?则是TransmittableThreadLocal目标场景。

下�是几个典型场景例�。

1. 分布�跟踪系统 或 全链路压测（�链路打标）
2. 日志收集记录系统上下文
3. Session级Cache
4. 应用容器或上层框架跨应用代ç ?给下层SDK传递信æ?¯

�个场景的展开说明���文档 需求场景。

👥 User Guide

使用类TransmittableThreadLocalæ?¥ä¿?存值，并跨线程池传递。

TransmittableThreadLocal继承InheritableThreadLocal，使用方å¼?也类似。相比InheritableThreadLocal，添加了

1. copy方法
   用于定制 任务æ??交给线程池时 çš„ThreadLocal值传递到 任务执行时 çš„æ‹·è´?行为，缺çœ?是简å?•çš„赋值传递。
   • 注æ„?：如果传递的是一个对象（引用类型）且没有å?šæ·±æ‹·è´?，如直接传递引用或是浅拷è´?，那么
     • 跨线程传递而ä¸?å†?有线程å°?闭，传递对象在多个线程之间是有共享的；
     • 与InheritableThreadLocal.childValue一样，使用者/业务逻辑è¦?注æ„?传递对象的线程安全。
2. protectedçš„beforeExecute/afterExecute方法
   执行任务(Runnable/Callable)çš„å‰?/å?Žçš„生命周期回调，缺çœ?是空æ“?作。

关于copy方法 çš„ 展开说明

严谨地说，应该是『传递行为ã€?，而ä¸?是『拷è´?行为ã€?；相应的，这个方法应该命å??æˆ?transmiteeValue，与InheritableThreadLocal.childValue方法有一致的命å??风格。

但多数情况下，传递的是一个å¤?æ?‚的对象，习惯上会先想到的是如何å?šæ‹·è´?，如深拷è´?ã€?æµ…æ‹·è´?；命å??æˆ?copyå??而更容易ç?†è§£è¿™ä¸ªè¿‡ç¨‹ä¸Žè¡Œä¸ºäº†ã€‚ 😂

关于构è¯?å?Žç¼€er与ee的说明：

• transmit是动è¯?传递，transmitter动作的执行者/主动方，而transmitee动作的接收者/被动方。
• er与eeå?Žç¼€çš„常è§?è¯?是employer（雇主）/employee（雇员）ã€?caller（调用者）/callee（被调用者）。

具体使用方��下�的说明。

1. 简�使用

父线程给�线程传递值。

示例代�：

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

// =====================================================

// 在父线程中设置
context.set("value-set-in-parent");

// =====================================================

// 在�线程中�以读�，值是"value-set-in-parent"
String value = context.get();

# 完整å?¯è¿?行的Demo代ç ?å?‚è§?SimpleDemo.kt。

这其实是InheritableThreadLocal的功能，应该使用InheritableThreadLocalæ?¥å®Œæˆ?。

但对于使用线程池等会池化å¤?用线程的执行组件的情况，线程由线程池创建好，并且线程是池化起æ?¥å??å¤?使用的；这时父å­?线程关系的ThreadLocal值传递已ç»?没有æ„?义，应用需è¦?的实际上是把 任务æ??交给线程池时的ThreadLocal值传递到 任务执行时。

解决方法��下�的这几�用法。

2. ��线程池中传递值

2.1 修饰Runnableå’ŒCallable

使用TtlRunnableå’ŒTtlCallableæ?¥ä¿®é¥°ä¼ å…¥çº¿ç¨‹æ± çš„Runnableå’ŒCallable。

示例代�：

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

// =====================================================

// 在父线程中设置
context.set("value-set-in-parent");

Runnable task = new RunnableTask();
// �外的处�，生�修饰了的对象ttlRunnable
Runnable ttlRunnable = TtlRunnable.get(task);
executorService.submit(ttlRunnable);

// =====================================================

// Task中�以读�，值是"value-set-in-parent"
String value = context.get();

注�：
å?³ä½¿æ˜¯å?Œä¸€ä¸ªRunnable任务多次æ??交到线程池时，æ¯?次æ??交时都需è¦?通过修饰æ“?作（å?³TtlRunnable.get(task)）以抓å?–这次æ??交时的TransmittableThreadLocal上下文的值；å?³å¦‚æžœå?Œä¸€ä¸ªä»»åŠ¡ä¸‹ä¸€æ¬¡æ??交时ä¸?执行修饰而ä»?然使用上一次的TtlRunnable，则æ??交的任务è¿?行时会是之å‰?修饰æ“?作所抓å?–的上下文。示例代ç ?如下：

// 第一次æ??交
Runnable task = new RunnableTask();
executorService.submit(TtlRunnable.get(task));

// ...业务逻辑代�，
// 并且修改了 TransmittableThreadLocal上下文 ...
// context.set("value-modified-in-parent");

// å†?次æ??交
// �新执行修饰，以传递修改了的 TransmittableThreadLocal上下文
executorService.submit(TtlRunnable.get(task));

上é?¢æ¼”示了Runnable，Callable的处ç?†ç±»ä¼¼

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

// =====================================================

// 在父线程中设置
context.set("value-set-in-parent");

Callable call = new CallableTask();
// �外的处�，生�修饰了的对象ttlCallable
Callable ttlCallable = TtlCallable.get(call);
executorService.submit(ttlCallable);

// =====================================================

// Call中�以读�，值是"value-set-in-parent"
String value = context.get();

# 完整å?¯è¿?行的Demo代ç ?å?‚è§?TtlWrapperDemo.kt。

整个过程的完整时�图

2.2 修饰线程池

çœ?去æ¯?次Runnableå’ŒCallable传入线程池时的修饰，这个逻辑å?¯ä»¥åœ¨çº¿ç¨‹æ± ä¸­å®Œæˆ?。

通过工具类com.alibaba.ttl.threadpool.TtlExecutors完æˆ?，有下é?¢çš„方法：

• getTtlExecutor：修饰接å?£Executor
• getTtlExecutorService：修饰接å?£ExecutorService
• getTtlScheduledExecutorService：修饰接å?£ScheduledExecutorService

示例代�：

ExecutorService executorService = ...
// �外的处�，生�修饰了的对象executorService
executorService = TtlExecutors.getTtlExecutorService(executorService);

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

// =====================================================

// 在父线程中设置
context.set("value-set-in-parent");

Runnable task = new RunnableTask();
Callable call = new CallableTask();
executorService.submit(task);
executorService.submit(call);

// =====================================================

// Task或是Call中�以读�，值是"value-set-in-parent"
String value = context.get();

# 完整å?¯è¿?行的Demo代ç ?å?‚è§?TtlExecutorWrapperDemo.kt。

2.3 使用Java Agentæ?¥ä¿®é¥°JDK线程池实现类

è¿™ç§?æ–¹å¼?，实现线程池的传递是é€?明的，业务代ç ?中没有修饰Runnable或是线程池的代ç ?。å?³å?¯ä»¥å?šåˆ°åº”用代ç ? 无侵入。
# 关于 无侵入 的更多说明å?‚è§?文档Java Agentæ–¹å¼?对应用代ç ?无侵入。

示例代�：

// ## 1. 框架上层逻辑，�续�程框架调用业务 ##
TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();
context.set("value-set-in-parent");

// ## 2. 应用逻辑，�续�程业务调用框架下层逻辑 ##
ExecutorService executorService = Executors.newFixedThreadPool(3);

Runnable task = new RunnableTask();
Callable call = new CallableTask();
executorService.submit(task);
executorService.submit(call);

// ## 3. 框架下层逻辑 ##
// Task或是Call中�以读�，值是"value-set-in-parent"
String value = context.get();

Demoå?‚è§?AgentDemo.kt。执行工程下的脚本scripts/run-agent-demo.shå?³å?¯è¿?è¡ŒDemo。

ç›®å‰?TTL Agent中，修饰了的JDK执行器组件（å?³å¦‚线程池）如下：

1. java.util.concurrent.ThreadPoolExecutor å’Œ java.util.concurrent.ScheduledThreadPoolExecutor
   • 修饰实现代ç ?在JdkExecutorTtlTransformlet.java。
2. java.util.concurrent.ForkJoinTask（对应的执行器组件是java.util.concurrent.ForkJoinPool）
   • 修饰实现代ç ?在ForkJoinTtlTransformlet.java。从版本 2.5.1 开始支æŒ?。
   • 注æ„?：Java 8引入的CompletableFuture与（并行执行的）Stream底层是通过ForkJoinPoolæ?¥æ‰§è¡Œï¼Œæ‰€ä»¥æ”¯æŒ?ForkJoinPoolå?Žï¼ŒTTL也就é€?明支æŒ?了CompletableFuture与Stream。🎉
3. java.util.TimerTaskçš„å­?类（对应的执行器组件是java.util.Timer）
   • 修饰实现代ç ?在TimerTaskTtlTransformlet.java。从版本 2.7.0 开始支æŒ?。
   • 注æ„?：从2.11.2版本开始缺çœ?å¼€å?¯TimerTask的修饰（因为ä¿?è¯?正确性是第一ä½?，而ä¸?是最佳实践『ä¸?推è??使用TimerTaskã€?:）；2.11.1版本å?Šå…¶ä¹‹å‰?的版本没有缺çœ?å¼€å?¯TimerTask的修饰。
   • 使用Agentå?‚æ•°ttl.agent.enable.timer.taskå¼€å?¯/关闭TimerTask的修饰：
     • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true
     • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false
   • 更多关于TTL Agentå?‚æ•°çš„é…?置说明详è§?TtlAgent.javaçš„JavaDoc。

关于java.util.TimerTask/java.util.Timer çš„ 展开说明

Timer是JDK 1.3çš„è€?类，ä¸?推è??使用Timer类。

推è??用ScheduledExecutorService。
ScheduledThreadPoolExecutor实现更强壮，并且功能更丰富。 如支æŒ?é…?置线程池的大å°?（Timerå?ªæœ‰ä¸€ä¸ªçº¿ç¨‹ï¼‰ï¼›Timer在Runnable中抛出异常会中止定时执行。更多说明å?‚è§? 10. Mandatory Run multiple TimeTask by using ScheduledExecutorService rather than Timer because Timer will kill all running threads in case of failing to catch exceptions. - Alibaba Java Coding Guidelines。

Java Agentçš„å?¯åŠ¨å?‚æ•°é…?ç½®

在Javaçš„å?¯åŠ¨å?‚数加上：-javaagent:path/to/transmittable-thread-local-2.x.y.jar。

注�：

• 如果修改了下载的TTLçš„Jar的文件å??（transmittable-thread-local-2.x.y.jar），则需è¦?自己手动通过-Xbootclasspath JVMå?‚æ•°æ?¥æ˜¾å¼?é…?置。
  比如修改文件å??æˆ?ttl-foo-name-changed.jar，则还需è¦?加上Javaçš„å?¯åŠ¨å?‚数：-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar。
• 或使用v2.6.0之å‰?的版本（如v2.5.1），则也需è¦?自己手动通过-Xbootclasspath JVMå?‚æ•°æ?¥æ˜¾å¼?é…?置（就åƒ?TTL之å‰?的版本的å?šæ³•ä¸€æ ·ï¼‰ã€‚
  加上Javaçš„å?¯åŠ¨å?‚数：-Xbootclasspath/a:path/to/transmittable-thread-local-2.5.1.jar。

Java命令行示例如下：

java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \
    -cp classes \
    com.alibaba.demo.ttl.agent.AgentDemo

# 如果修改了TTL jar文件å?? 或 TTL版本是 2.6.0 之å‰?
# 则还需�显�设置 -Xbootclasspath �数
java -javaagent:path/to/ttl-foo-name-changed.jar \
    -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar \
    -cp classes \
    com.alibaba.demo.ttl.agent.AgentDemo

java -javaagent:path/to/transmittable-thread-local-2.5.1.jar \
    -Xbootclasspath/a:path/to/transmittable-thread-local-2.5.1.jar \
    -cp classes \
    com.alibaba.demo.ttl.agent.AgentDemo

关于boot class path çš„ 展开说明

因为修饰了JDK标准库的类，标准库由bootstrap class loader加载；修饰å?Žçš„JDK类引用了TTL的代ç ?，所以Java Agent使用方å¼?下TTL Jar文件需è¦?é…?置到boot class path上。

TTL从v2.6.0开始，加载TTL Agent时会自动设置TTL Jar到boot class path上。
注æ„?：ä¸?能修改从Maven库下载的TTL Jar文件å??（形如transmittable-thread-local-2.x.y.jar）。 如果修改了，则需è¦?自己手动通过-Xbootclasspath JVMå?‚æ•°æ?¥æ˜¾å¼?é…?置（就åƒ?TTL之å‰?的版本的å?šæ³•ä¸€æ ·ï¼‰ã€‚

自动设置TTL Jar到boot class path的实现是通过指定TTL Java Agent Jar文件里manifest文件（META-INF/MANIFEST.MF）的Boot-Class-Path属性：

Boot-Class-Path

A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed.

更多详�

• Java Agent规范 - JavaDoc
• JAR File Specification - JAR Manifest
• Working with Manifest Files - The Javaâ„¢ Tutorials

🔌 Java API Docs

当�版本的Java API文档地�： https://alibaba.github.io/transmittable-thread-local/apidocs/

� Maven�赖

示例：

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

�以在 search.maven.org 查看�用的版本。

🔨 关于编译构建与IDEå¼€å?‘

编译构建的环境è¦?求： JDK 8~11；用Maven常规的方å¼?执行编译构建å?³å?¯ï¼š
# 在工程中已ç»?包å?«äº†ç¬¦å?ˆç‰ˆæœ¬è¦?求的Maven，直接è¿?è¡Œ 工程根目录下的mvnw；并ä¸?需è¦?先手动自己安装好Maven。

# �行测试Case
./mvnw test
# 编译打包
./mvnw package
# �行测试Case�编译打包�安装TTL库到Maven本地
./mvnw install

#####################################################
# 如果使用你自己安装的 maven，版本�求：maven 3.3.9+
mvn install

如何用IDEæ?¥å¼€å?‘时注æ„?点，更多说明å?‚è§? 文档 如何用IDEå¼€å?‘ - Developer Guide。

â?“ FAQ

Q1. TTL Agent与其它Agent（如Skywalkingã€?Promethues）é…?å?ˆä½¿ç”¨æ—¶ä¸?生效？

é…?ç½®TTL Agent在最å‰?çš„ä½?置，å?¯ä»¥é?¿å…?与其它其它Agenté…?å?ˆä½¿ç”¨æ—¶ï¼ŒTTL Agentå?¯èƒ½çš„ä¸?生效问题。é…?置示例：

java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \
     -javaagent:path/to/skywalking-agent.jar \
     -jar your-app.jar

原因是：

• åƒ?Skywalking这样的Agentçš„å…¥å?£é€»è¾‘（premain）包å?«äº†çº¿ç¨‹æ± çš„å?¯åŠ¨ã€‚
• 如果é…?置在这样的Agenté…?置在å‰?é?¢ï¼Œåˆ°äº†TTL Agent（的premain）时，TTL需è¦?加强的线程池类已ç»?加载（load）了。
• TTL Agentçš„TtlTransformer是在类加载时触å?‘类的增强；如果类已ç»?加载了会跳过TTL Agent的增强逻辑。

更多讨论å?‚è§? Issue：TTL agent与其他Agent的兼容性问题 #226。

Q2. MacOS下，使用Java Agent，å?¯èƒ½ä¼šæŠ¥JavaLaunchHelper的出错信æ?¯

JDK Bug: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8021205
å?¯ä»¥æ?¢ä¸€ä¸ªç‰ˆæœ¬çš„JDK。我的开å?‘机上1.7.0_40有这个问题，1.6.0_51ã€?1.7.0_45å?¯ä»¥è¿?行。
# 1.7.0_45还是有JavaLaunchHelper的出错信æ?¯ï¼Œä½†ä¸?å½±å“?è¿?行。

✨ 使用TTL的好处与必è¦?性

注：ä¸?读这一节，并ä¸?会影å“?你使用TTLæ?¥è§£å†³ä½ ç¢°åˆ°çš„问题，å?¯ä»¥æ”¾å¿ƒè·³è¿‡ï¼›è¯»äº† User Guide å°±å?¯ä»¥å¿«é€Ÿç”¨èµ·æ?¥äº†ï½ž 😄 这一节信æ?¯å¯†åº¦è¾ƒé«˜ä¸?易读。

好处：�明且自动完�所有异步执行上下文的�定制�规范化的��与传递。
这个好处也是TransmittableThreadLocal的目标。

必�性：��应用的分布�微�务化并使用��中间件，越�越多的功能与组件会涉���的上下文，逻辑�程也越�越长；上下文问题实际上是个大的易错的架构问题，需�统一的对业务�明的解决方案。

使用ThreadLocal作为业务上下文传递的ç»?典技术手段在中间件ã€?技术与业务框架中广泛大é‡?使用。而对于生产应用，几乎一定会使用线程池等异步执行组件，以高效支撑线上大æµ?é‡?。但使用ThreadLocalå?Šå…¶set/remove的上下文传递模å¼?，在使用线程池等异步执行组件时，存在多方é?¢çš„问题：

1. 从业务使用者角度�看

1. ç¹?ç??
   • 业务逻辑è¦?知é?“：有哪些上下文；å?„个上下文是如何获å?–的。
   • 并需è¦?业务逻辑去一个一个地æ?•æ?‰ä¸Žä¼ é€’。
2. ä¾?èµ–
   • 需è¦?直接ä¾?èµ–ä¸?å?ŒThreadLocal上下文å?„自的获å?–的逻辑或类。
   • åƒ?RPC的上下文（如Dubboçš„RpcContext）ã€?全链路跟踪的上下文（如SkyWalkingçš„ContextManager）ã€?ä¸?å?Œä¸šåŠ¡æ¨¡å?—中的业务æµ?程上下文，等等。
3. ��（易�）
   • 因为è¦? 事先 知é?“有哪些上下文，如果系统出现了一个新的上下文，业务逻辑就è¦?修改添加上新上下文传递的几行代ç ?。也就是说因 系统的 上下文新增，业务的 逻辑就跟进è¦?修改。
   • 而对于业务æ?¥è¯´ï¼Œä¸?关心系统的上下文，å?³å¾€å¾€å°±å?¯èƒ½é?—æ¼?，会是线上故障了。
   • éš?ç?€åº”用的分布å¼?å¾®æœ?务化并使用å?„ç§?中间件，越æ?¥è¶Šå¤šçš„功能与组件会涉å?Šä¸?å?Œçš„上下文，逻辑æµ?程也越æ?¥è¶Šé•¿ï¼›ä¸Šä¸‹æ–‡é—®é¢˜å®žé™…上是个大的易错的架构问题，需è¦?统一的对业务é€?明的解决方案。
4. 定制性
   • 因为需è¦?业务逻辑æ?¥å®Œæˆ?æ?•æ?‰ä¸Žä¼ é€’，业务è¦?关注『上下文的传递方å¼?ã€?：直接传引用？还是拷è´?传值？拷è´?是深拷è´?还是浅拷è´?？在ä¸?å?Œçš„上下文会需è¦?ä¸?å?Œçš„å?šæ³•ã€‚
   • 『上下文的传递方å¼?ã€?往往是 上下文的æ??供者（或说是业务逻辑的框架部分）æ‰?能决策处ç?†å¥½çš„；而 上下文的使用者（或说是业务逻辑的应用部分）往往ä¸?（期望）知é?“上下文的传递方å¼?。这也å?¯ä»¥ç?†è§£æˆ?是 ä¾?赖，å?³ä¸šåŠ¡é€»è¾‘ ä¾?èµ–/关注/实现了 系统/架构的『上下文的传递方å¼?ã€?。

2. 从整体�程实现角度�看

关注的是 上下文传递�程的规范化。上下文传递到了�线程��好 清�（或更准确地说是� �� �之�的上下文），需�业务逻辑去处�好。如果业务逻辑对清�的处��正确，比如：

• 如果清ç?†æ“?作æ¼?了：
  • 下一次执行å?¯èƒ½æ˜¯ä¸Šæ¬¡çš„，å?³ã€Žä¸Šä¸‹æ–‡çš„ 污染/串å?·ã€?，会导致业务逻辑错误。
  • 『上下文的 泄æ¼?ã€?，会导致内存泄æ¼?问题。
• 如果清ç?†æ“?作å?šå¤šäº†ï¼Œä¼šå‡ºçŽ°ä¸Šä¸‹æ–‡ 丢失。

上é?¢çš„问题，在业务开å?‘中引å?‘çš„Bug真是屡è§?ä¸?鲜 ï¼?本质原因是：ThreadLocalçš„set/remove的上下文传递模å¼? 在使用线程池等异步执行组件的情况下ä¸?å†?是有效的。常è§?的典型例å­?：

• 当线程池满了且线程池的RejectedExecutionHandler使用的是CallerRunsPolicy时，æ??交到线程池的任务会在æ??交线程中直接执行，ThreadLocal.removeæ“?作清ç?†æ??交线程的上下文导致上下文丢失。
• 类似的，使用ForkJoinPool（包å?«å¹¶è¡Œæ‰§è¡ŒStream与CompletableFuture，底层使用ForkJoinPool）的场景，展开的ForkJoinTask会在任务æ??交线程中直接执行。å?Œæ ·å¯¼è‡´ä¸Šä¸‹æ–‡ä¸¢å¤±ã€‚

怎么设计一个『上下文传递�程�方案（�上下文的生命周期），以��没有上�的问题？

期望：上下文生命周期的æ“?作从业务逻辑中分离出æ?¥ã€‚业务逻辑ä¸?涉å?Šç”Ÿå‘½å‘¨æœŸï¼Œå°±ä¸?会有业务代ç ?如ç–?忽清ç?†è€Œå¼•å?‘的问题了。整个上下文的传递æµ?程或说生命周期å?¯ä»¥è§„范化æˆ?：æ?•æ?‰ã€?回放和æ?¢å¤?è¿™3个æ“?作，å?³CRR(capture/replay/restore)模å¼?。更多讨论å?‚è§? Issue：能在详细讲解一下replayã€?restore的设计ç?†å¿µå?—？#201。

总结上é?¢çš„说明：在生产应用（几乎一定会使用线程池等异步执行组件）中，使用ThreadLocalå?Šå…¶set/remove的上下文传递模å¼?几乎一定是有问题的，å?ªæ˜¯åœ¨ç­‰ä¸€ä¸ªå‡ºBug的机会。

更多TTL好处与必è¦?性的展开讨论å?‚è§? Issue：这个库带æ?¥æ€Žæ ·çš„好处和优势？ #128，欢迎继续讨论 ♥ï¸?

🗿 更多文档

• 🎨 需求场景说明
• â?¤ï¸? å°?伙伴å?Œå­¦ä»¬å†™çš„TTL使用场景 与 设计实现解æž?的文章（写得都很好ï¼?） - Issue #123
• 🎓 Developer Guide
• ☔ 性能测试

📚 相关资料

JDK Core Classes

• WeakHashMap
• InheritableThreadLocal

� Who used

使用了TTL的一部分开æº?项目：

• 中间件
  • sofastack/sofa-rpc
    SOFARPC is a high-performance, high-extensibility, production-level Java RPC framework
  • dromara/hmily
    Distributed transaction solutions
  • acmenlt/dynamic-threadpool
    强大的动�线程池，附带监控报警功能（没有�赖中间件），完全�循阿里巴巴编�规范
  • lyh200/dynamic-tp
    轻�级动�线程池，内置监控告警功能，支�线程池上下文传递，基于主��置中心（已支�Nacos�Apollo，Zookeeper，�通过SPI自定义实现）
  • siaorg/sia-gateway
    微�务路由网关（zuul-plus）
  • ZTO-Express/zms
    ZTO Message Service
  • tuya/connector
    The connector framework maps cloud APIs to local APIs based on simple configurations and flexible extension mechanisms.
• 中间件/æ•°æ?®
  • ppdaicorp/das
    数�库访问框架(data access service)，包括数�库控制�das console，数�库客户端das client和数�库�务端das server三部分
  • SimonAlong/Neo
    Orm框架：基于ActiveRecord�想开�的至简化且功能很全的Orm框架
  • didi/ALITA
    a layer-based data analysis tool
  • didi/daedalus
    实现快速创建数�构造�程，数�构造�程的�视化�线上化��久化�标准化
  • aiwenmo/DataLink
    a new open source solution to bring Flink development to data center
• 中间件/æµ?程引擎
  • dromara/liteflow
    a lightweight and practical micro-process framework
  • alibaba/bulbasaur
    A pluggable, scalable process engine
• 中间件/日志
  • dromara/TLog
    Lightweight distributed log label tracking framework
  • fayechenlong/plumelog
    一个java分布�日志组件，支�百亿级别
  • minbox-projects/minbox-logging
    分布å¼?零侵入å¼?ã€?链路å¼?请求日志分æž?框架。æ??ä¾›Admin端点进行采集日志ã€?分æž?日志ã€?日志告警通知ã€?æœ?务性能分æž?等。通过Admin Uiå?¯æŸ¥çœ‹å®žæ—¶é“¾è·¯æ—¥å¿—ä¿¡æ?¯ã€?在线业务æœ?务列表
    • minbox-projects/api-boot
      为接��务而生的，基于“ SpringBoot�完�扩展和自动�置，内部�装了一系列的开箱�用Starters
  • ofpay/logback-mdc-ttl
    logback扩展，集�transmittable-thread-local支�跨线程池的mdc跟踪
  • oldratlee/log4j2-ttl-thread-context-map
    Log4j2 TTL ThreadContextMap, Log4j2 extension integrated TransmittableThreadLocal to MDC
• 中间件/字节ç ?
  • ymm-tech/easy-byte-coder
    Easy-byte-coder is a non-invasive bytecode injection framework based on JVM
• 业务æœ?务或平å?°åº”用
  • OpenBankProject/OBP-API
    An open source RESTful API platform for banks that supports Open Banking, XS2A and PSD2 through access to accounts, transactions, counterparties, payments, entitlements and metadata - plus a host of internal banking and management APIs
  • Joolun/JooLun-wx
    JooLun微信商城
  • yangzongzhuan/RuoYi-Cloud
    基于Spring Boot�Spring Cloud & Alibaba的分布�微�务架构��管�系统
  • somowhere/albedo
    基于 Spring Boot �Spring Security�Mybatis 的RBAC��管�系统
  • tengshe789/SpringCloud-miaosha
    一个基于spring cloud Greenwich的简�秒�电�商城项目
• 工具产å“?
  • ssssssss-team/spider-flow
    新一代爬虫平�，以图形化方�定义爬虫�程，�写代���完�爬虫
  • nekolr/slime
    � 一个�视化的爬虫平�
  • zjcscut/octopus
    长链接压缩为短链接的�务
  • xggz/mqr
    茉莉QQ机器人（简称MQR），采用miraiçš„Androidå??议实现的QQ机器人æœ?务，通过web控制机器人的å?¯å?œå’Œé…?ç½®
• 测试解决方案或工具
  • alibaba/jvm-sandbox-repeater
    A Java server-side recording and playback solution based on JVM-Sandbox, 录制/回放通用解决方案
  • alibaba/testable-mock
    ���路写Mock，让�元测试更简�
  • shulieTech/Takin
    全链路压测平�，measure online environmental performance test for full-links, Especially for microservices
    • shulieTech/LinkAgent
      a Java-based open-source agent designed to collect data and control Functions for Java applications through JVM bytecode, without modifying applications codes
  • alibaba/virtual-environment
    Route isolation with service sharing, 阿里测试环境æœ?务隔离和è?”调机制的Kubernetes版实现
• Spring Cloud/Spring Boot的框架方案/脚手架
  • zlt2000/microservices-platform
    基于SpringBoot2.x�SpringCloud和SpringCloudAlibaba并采用��端分离的�业级微�务多租户系统架构
  • zuihou/lamp-cloud
    基于Jdk11 + SpringCloud + SpringBoot 的微�务快速开�平�，其中的��置的SaaS功能尤其闪耀， 具备RBAC功能�网关统一鉴��Xss防跨站攻击�自动代�生��多�存储系统�分布�事务�分布�定时任务等多个模�，支�多业务系统并行开�， 支�多�务并行开�，�以作为�端�务的开�脚手架
    • zuihou/lamp-util
      打造一套兼顾 SpringBoot 和 SpringCloud 项目的公共工具类
  • YunaiV/ruoyi-vue-pro
    一套全部开�的�业级的快速开�平�。基于 Spring Boot + MyBatis Plus + Vue & Element 实现的��管�系统 + 微信�程�，支� RBAC 动����数����SaaS 多租户�Activiti + Flowable 工作��三方登录�支付�短信�商城等功能。
  • matevip/matecloud
    一款基于Spring Cloud Alibaba的微�务架构
  • gavenwangcn/vole
    SpringCloud 微�务业务脚手架
  • liuweijw/fw-cloud-framework
    基于springcloud全家桶开�分布�框架（支�oauth2认�授��SSO登录�统一下��微信公众��务�Shardingdbc分库分表�常��务监控�链路监控�异步日志�redis缓存等功能），实现基于Vue全家桶等��端分离项目工程
  • liuht777/Taroco
    æ•´å?ˆNacosã€?Spring Cloud Alibaba，æ??供了一系列starter组件， å?Œæ—¶æ??ä¾›æœ?务治ç?†ã€?æœ?务监控ã€?OAuth2æ?ƒé™?认è¯?，支æŒ?æœ?务é™?级/熔断ã€?æœ?务æ?ƒé‡?
  • mingyang66/spring-parent
    数�库多数���Redis多数���日志组件�全链路日志追踪�埋点扩展点�Netty�微�务�开�基础框架支��异常统一处��返回值�跨域�API路由�监控等
  • yzcheng90/ms
    一个��分离的分布� spring cloud 框架(全家桶)，这里有统一认�，统一网关等等功能，是一个�常简�的微�务脚手架
  • fafeidou/fast-cloud-nacos
    致力于打造一个基于nacos为注册中心，结��业开�习惯，总结的一些基本的实现方�
  • HongZhaoHua/jstarcraft-core
    目标是æ??供一个通用的Java核心编程框架,作为æ?­å»ºå…¶å®ƒæ¡†æž¶æˆ–者项目的基础. 让相关领域的研å?‘人员能够专注高层设计而ä¸?用关注底层实现. 涵盖了缓存,编解ç ?,通讯,事件,输入/输出,监控,存储,é…?ç½®,脚本和事务10个方é?¢
  • budwk/budwk
BudWk 原å?? NutzWk ，基于国产框架 nutz å?Š nutzboot å¼€å?‘çš„å¼€æº?Web基础项目，集æ?ƒé™?体系ã€?系统å?‚æ•°ã€?æ•°æ?®å­—å…¸ã€?站内消æ?¯ã€?定时任务ã€?CMSã€?微信等最常用功能，ä¸?庞æ?‚ã€?ä¸?é?¢é?¢ä¿±åˆ°ï¼Œä½¿å…¶å…·æœ‰ä¸Šæ‰‹å®¹æ˜“ã€?å¼€å?‘便æ?·ã€?扩展ç?µæ´»ç­‰ç‰¹æ€§ï¼Œç‰¹åˆ«é€‚å?ˆå?„类大中å°?型定制化项目需求
  • yinjihuan/spring-cloud
    《Spring Cloud微�务-全栈技术与案例解�》和《Spring Cloud微�务 入门 实战与进阶》�套��
  • louyanfeng25/ddd-demo
    《深入浅出DDD》讲解的演示项目，为了能够更好的�解Demo中的分层与逻辑处�，我强烈建议你���册�深入了解DDD。

更多使用TTLçš„å¼€æº?项目 å?‚è§?

👷 Contributors

• Jerry Lee <oldratlee at gmail dot com> @oldratlee
• Yang Fang <snoop.fy at gmail dot com> @driventokill
• Zava Xu <zava.kid at gmail dot com> @zavakid
• wuwen <wuwen.55 at aliyun dot com> @wuwen5
• Xiaowei Shi <179969622 at qq dot com> @xwshiustc
• David Dai <351450944 at qq dot com> @LNAmp
• Your name here :-)