从 ThreadLocal 到 TTL,再到 WebFlux Context:一次讲透 Java 线程上下文传递
前言
在 Java 后端开发里,ThreadLocal 是一个非常常见的工具。
你可能在这些场景里见过它:
- 保存当前登录用户
- 保存 traceId / requestId
- 保存租户 ID
- 保存数据源路由 key
- 保存链路追踪上下文
- 保存本地事务上下文
- 保存灰度、语言、时区等请求级信息
看起来它很好用:
java
RequestContextHolder.set(context);
RequestContext context = RequestContextHolder.get();
业务代码不用层层传参,就能拿到当前请求上下文。
但是很多线上问题也和它有关:
- 接口 A 的用户信息串到了接口 B
- 线程池里异步任务拿不到 traceId
ThreadLocal没有remove()导致内存泄漏InheritableThreadLocal在线程池里表现不符合预期- 使用
CompletableFuture后日志 traceId 丢了 - WebFlux 里明明入口设置了
ThreadLocal,后面却读不到
这类问题的根源不是某个工具不好,而是我们经常把三个概念混在一起:
- 线程内存储
- 跨线程传递
- 响应式订阅链路传递
ThreadLocal 只解决第一件事。
如果要跨线程,需要手动传递或用 TTL。
如果进入 WebFlux / Reactor,则应该用 Reactor Context。
这篇文章就按这个顺序讲清楚。
一、先用一句话回答面试题
1. ThreadLocal 是什么
ThreadLocal 是 Java 提供的一种线程本地变量机制。
每个线程内部都有自己的 ThreadLocalMap,同一个 ThreadLocal 变量在不同线程中可以保存不同的值。
它适合保存“线程生命周期内独享”的数据。
2. ThreadLocal 为什么会内存泄漏
因为 ThreadLocalMap 的 key 是弱引用,value 是强引用。
当 ThreadLocal 对象没有强引用后,key 可能被 GC 回收,但 value 仍然被线程持有。
如果线程是线程池线程,线程长期存活,value 就可能长期残留,造成内存泄漏。
所以生产代码里必须:
java
try {
threadLocal.set(value);
// do business
} finally {
threadLocal.remove();
}
3. ThreadLocal 能不能在线程池里传递上下文
不能自动传递。
普通 ThreadLocal 绑定的是当前线程。
线程池执行异步任务时,任务跑在另一个线程里,自然拿不到父线程中的值。
4. InheritableThreadLocal 能不能解决线程池问题
不能稳定解决。
InheritableThreadLocal 只在创建子线程时复制父线程变量。
线程池里的线程通常早就创建好了,后续只是复用线程,不会每次提交任务都重新复制上下文。
5. TTL 解决了什么问题
TTL 全称是 TransmittableThreadLocal。
它解决的是线程池场景下“提交任务时捕获父线程上下文,任务执行时恢复上下文,执行后清理和还原上下文”的问题。
6. WebFlux 为什么不能依赖 ThreadLocal
WebFlux 是响应式模型,不保证一次请求从头到尾都在同一个物理线程上执行。
请求可能经历多个线程切换。
所以 ThreadLocal 这种线程绑定模型天然不可靠。
WebFlux 应该使用 Reactor Context。
二、Demo 工程结构
本文配套工程是:
text
ThreadLocalContextDemo
├── pom.xml
├── README.md
├── docs
│ ├── ThreadLocal-TTL-WebFlux-Context-Propagation.md
│ └── 公众号发布稿-从ThreadLocal到TTL再到WebFlux上下文传递.md
└── src
├── main
│ ├── java/com/salmon/demo
│ │ ├── ThreadLocalDemoApplication.java
│ │ ├── config
│ │ │ ├── ThreadPoolConfig.java
│ │ │ ├── WebMvcContextConfig.java
│ │ │ └── WebFluxContextConfig.java
│ │ ├── context
│ │ │ ├── RequestContext.java
│ │ │ ├── RequestContextHolder.java
│ │ │ ├── TtlRequestContextHolder.java
│ │ │ ├── ReactorContextKeys.java
│ │ │ └── ContextView.java
│ │ └── controller
│ │ ├── ThreadLocalLeakController.java
│ │ ├── HttpContextController.java
│ │ ├── TtlContextController.java
│ │ └── ReactiveContextController.java
│ └── resources
│ ├── application.properties
│ └── application-webflux.properties
└── test
启动方式:
bash
mvn -f ThreadLocalContextDemo/pom.xml spring-boot:run
WebFlux 模式:
bash
mvn -f ThreadLocalContextDemo/pom.xml spring-boot:run -Dspring-boot.run.profiles=webflux
三、上下文传递全景图
先看整体关系。
核心结论:
text
Servlet 同步链路:ThreadLocal
线程池异步链路:TTL 或手工传递
WebFlux 响应式链路:Reactor Context
四、ThreadLocal 基础原理
1. ThreadLocal 的表面用法
先看最简单的上下文 Holder。
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/context/RequestContextHolder.java
核心代码:
java
package com.salmon.demo.context;
public final class RequestContextHolder {
private static final ThreadLocal<RequestContext> LOCAL = new ThreadLocal<RequestContext>();
private RequestContextHolder() {
}
public static void set(RequestContext context) {
LOCAL.set(context);
}
public static RequestContext get() {
return LOCAL.get();
}
public static void remove() {
LOCAL.remove();
}
}
这个类非常典型:
set()写入上下文get()读取上下文remove()清理上下文
面试里如果只问使用方式,这样回答基本够了。
但如果问“为什么会泄漏”,就不能只停留在 API 层。
2. ThreadLocal 的真实存储位置
很多人会误以为:
text
ThreadLocal 对象里保存了每个线程的值
其实不是。
真实关系更接近这样:
也就是说:
text
值是挂在线程 Thread 上的,不是挂在 ThreadLocal 对象上的。
这个细节非常重要。
因为线程池里的线程会长期存活。
只要线程还活着,线程里的 ThreadLocalMap 就可能还活着。
只要 value 还被 map 引用,它就不会被回收。
3. 为什么 key 是弱引用,value 还是会泄漏
ThreadLocalMap.Entry 的 key 是弱引用。
弱引用的意思是:只要外部没有强引用指向这个 ThreadLocal 对象,GC 时 key 就可能被回收。
但是 value 不是弱引用。
value 是强引用。
于是会出现这种情况:
text
key = null
value = 一个很大的 RequestContext / User / List / Map
如果这个线程一直活着,value 就一直被间接持有。
这就是内存泄漏风险。
4. 线程池下更危险
普通临时线程执行完会销毁。
线程销毁后,它自己的 ThreadLocalMap 也没了。
但线程池线程不同:
text
线程池线程长期存活
任务 1 执行完,线程不会销毁
任务 2 继续复用这个线程
任务 1 的 ThreadLocal 值可能还在
这不仅是内存泄漏,还可能是数据串味。
五、ThreadLocal 泄漏 Demo
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/controller/ThreadLocalLeakController.java
1. 线程池配置
为了稳定复现,demo 里准备了一个只有 1 个线程的线程池:
java
@Bean(destroyMethod = "shutdown")
public ExecutorService leakExecutor() {
ThreadPoolExecutor executor = (ThreadPoolExecutor) Executors.newFixedThreadPool(1);
executor.prestartAllCoreThreads();
return executor;
}
只有一个线程的好处是:
text
第一次请求写入 ThreadLocal
第二次请求大概率还是同一个线程执行
所以可以稳定读到上一次残留的数据
2. 故意不 remove
接口:
text
GET /api/threadlocal/leak/write?userId=user-a
核心代码:
java
@GetMapping("/api/threadlocal/leak/write")
public ContextView leakWrite(@RequestParam(defaultValue = "user-a") String userId) throws Exception {
Future<ContextView> future = leakExecutor.submit(() -> {
RequestContext context = new RequestContext(UUID.randomUUID().toString(), userId);
context.getAttributes().put("demo", "no-remove");
RequestContextHolder.set(context);
return ContextView.current("写入 ThreadLocal,但故意不 remove,模拟线程池复用导致脏数据残留");
});
return future.get();
}
这里故意没有调用:
java
RequestContextHolder.remove();
3. 不设置上下文却读到了旧值
接口:
text
GET /api/threadlocal/leak/read
核心代码:
java
@GetMapping("/api/threadlocal/leak/read")
public ContextView leakRead() throws Exception {
Future<ContextView> future = leakExecutor.submit(() ->
ContextView.current("没有设置上下文,却读到了上一次任务留在线程里的值,就是线程池场景下的上下文泄漏"));
return future.get();
}
执行顺序:
bash
curl "http://localhost:8080/api/threadlocal/leak/write?userId=user-a"
curl "http://localhost:8080/api/threadlocal/leak/read"
第二个接口明明没有设置上下文,却可能读到第一个接口留下来的 user-a。
这就是线程池复用下的上下文泄漏。
4. 正确修复方式
接口:
text
GET /api/threadlocal/leak/fix?userId=user-b
核心代码:
java
@GetMapping("/api/threadlocal/leak/fix")
public ContextView leakFix(@RequestParam(defaultValue = "user-b") String userId) throws Exception {
Future<ContextView> future = leakExecutor.submit(() -> {
try {
RequestContext context = new RequestContext(UUID.randomUUID().toString(), userId);
context.getAttributes().put("demo", "try-finally-remove");
RequestContextHolder.set(context);
return ContextView.current("生产代码必须在 finally 中 remove");
} finally {
RequestContextHolder.remove();
}
});
return future.get();
}
注意重点:
java
finally {
RequestContextHolder.remove();
}
这是生产底线。
六、传统 Spring MVC 请求上下文
在 Spring MVC 里,一次请求通常由一个 Servlet 容器线程处理。
这种模型下,用 ThreadLocal 保存请求上下文是合理的。
1. 请求上下文对象
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/context/RequestContext.java
核心字段:
java
public class RequestContext {
private String traceId;
private String userId;
private Map<String, String> attributes;
private LocalDateTime createTime;
public RequestContext(String traceId, String userId) {
this();
this.traceId = traceId;
this.userId = userId;
}
}
这个对象模拟真实项目中的请求上下文。
真实项目里可能还会有:
- tenantId
- token
- requestUri
- clientIp
- language
- timezone
- grayTag
- dataPermission
2. MVC 拦截器写入上下文
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/config/WebMvcContextConfig.java
核心代码:
java
@Configuration
@Profile("!webflux")
public class WebMvcContextConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new HandlerInterceptor() {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
String traceId = headerOrDefault(request, "X-Trace-Id", UUID.randomUUID().toString());
String userId = headerOrDefault(request, "X-User-Id", "anonymous");
RequestContext context = new RequestContext(traceId, userId);
context.getAttributes().put("source", "spring-mvc-interceptor");
RequestContextHolder.set(context);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
RequestContextHolder.remove();
}
});
}
}
流程图:
3. 当前线程读取上下文
接口:
text
GET /api/http/context/current
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/controller/HttpContextController.java
核心代码:
java
@GetMapping("/api/http/context/current")
public ContextView current() {
return ContextView.current("传统 MVC 请求线程内,可以直接从 ThreadLocal 读取拦截器写入的上下文");
}
测试:
bash
curl -H "X-Trace-Id: trace-001" -H "X-User-Id: user-001" \
"http://localhost:8080/api/http/context/current"
在 MVC 同步链路里,这样做是正常的。
七、线程池让 ThreadLocal 失效
问题来了。
如果 Controller 里提交了异步任务呢?
1. 普通线程池读取不到
接口:
text
GET /api/http/context/async-lost
核心代码:
java
@GetMapping("/api/http/context/async-lost")
public CompletableFuture<ContextView> asyncLost() {
return CompletableFuture.supplyAsync(() ->
ContextView.current("切换到业务线程池后,普通 ThreadLocal 不会自动传递"), bizExecutor);
}
流程:
原因很简单:
text
ThreadLocal 绑定的是线程,不绑定任务。
父线程设置的值在父线程的 ThreadLocalMap 里。
线程池线程读取的是它自己的 ThreadLocalMap。
所以读不到。
2. 手工传递上下文
接口:
text
GET /api/http/context/async-manual
核心代码:
java
@GetMapping("/api/http/context/async-manual")
public CompletableFuture<ContextView> asyncManual() {
RequestContext captured = RequestContextHolder.get() == null ? null : RequestContextHolder.get().deepCopy();
return CompletableFuture.supplyAsync(() -> {
try {
RequestContextHolder.set(captured);
return ContextView.current("手工捕获、深拷贝、设置、finally remove,可以解决普通线程池传递");
} finally {
RequestContextHolder.remove();
}
}, bizExecutor);
}
标准动作有四步:
text
1. 提交任务前捕获父线程上下文
2. 做一次深拷贝
3. 子线程执行时 set
4. finally 中 remove
流程图:
这就是最朴素、最容易理解、也最可靠的方式。
缺点是每个异步任务都要写一遍,很容易漏。
所以才有 TTL。
八、浅拷贝为什么不安全
上下文跨线程传递时,经常有人这么写:
java
RequestContext child = parent;
或者:
java
RequestContext child = parent.shallowCopy();
这都可能出问题。
1. Demo 里的浅拷贝
源码:
java
public RequestContext shallowCopy() {
RequestContext copy = new RequestContext();
copy.traceId = this.traceId;
copy.userId = this.userId;
copy.attributes = this.attributes;
copy.createTime = this.createTime;
return copy;
}
这里的问题是:
java
copy.attributes = this.attributes;
两个对象共享同一个 Map。
2. 深拷贝
源码:
java
public RequestContext deepCopy() {
RequestContext copy = new RequestContext();
copy.traceId = this.traceId;
copy.userId = this.userId;
copy.attributes = new HashMap<String, String>(this.attributes);
copy.createTime = this.createTime;
return copy;
}
这里重新 new 了一个 HashMap。
3. 浅拷贝风险接口
接口:
text
GET /api/threadlocal/shallow-copy-risk
核心代码:
java
@GetMapping("/api/threadlocal/shallow-copy-risk")
public Map<String, Object> shallowCopyRisk() throws Exception {
RequestContext parent = new RequestContext("trace-shallow", "user-parent");
parent.getAttributes().put("role", "buyer");
RequestContext shallow = parent.shallowCopy();
RequestContext deep = parent.deepCopy();
parent.getAttributes().put("role", "admin");
Map<String, Object> result = new HashMap<String, Object>();
result.put("parentRole", parent.getAttributes().get("role"));
result.put("shallowCopyRole", shallow.getAttributes().get("role"));
result.put("deepCopyRole", deep.getAttributes().get("role"));
return result;
}
预期结果:
json
{
"parentRole": "admin",
"shallowCopyRole": "admin",
"deepCopyRole": "buyer"
}
解释:
text
shallowCopyRole 变成 admin,是因为浅拷贝共享了同一个 Map。
deepCopyRole 仍然是 buyer,是因为深拷贝拿到的是独立快照。
生产建议:
text
跨线程上下文尽量不可变。
如果对象里有 Map/List/自定义对象,要么深拷贝,要么只传不可变快照。
九、阿里巴巴 TTL 是什么
TTL 全称:
text
TransmittableThreadLocal
中文可以理解为:
text
可传递的 ThreadLocal
它主要解决线程池里的上下文传递问题。
1. 为什么不是直接用 InheritableThreadLocal
InheritableThreadLocal 只能在创建子线程时传递。
示意图:
但线程池是这样:
线程早就创建好了。
后续提交任务时不会重新触发 InheritableThreadLocal 的复制逻辑。
所以它不能解决线程池传递问题。
2. TTL 的核心思想
TTL 的关键不是“变量类型换了”。
关键是“任务提交时包装”。
大概流程:
总结成三句话:
text
提交任务时 capture
执行任务前 replay
执行任务后 restore
这就是 TTL 的核心原理。
十、TTL Holder 示例
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/context/TtlRequestContextHolder.java
核心代码:
java
package com.salmon.demo.context;
import com.alibaba.ttl.TransmittableThreadLocal;
public final class TtlRequestContextHolder {
private static final TransmittableThreadLocal<RequestContext> LOCAL =
new TransmittableThreadLocal<RequestContext>() {
@Override
public RequestContext copy(RequestContext parentValue) {
return parentValue == null ? null : parentValue.deepCopy();
}
};
private TtlRequestContextHolder() {
}
public static void set(RequestContext context) {
LOCAL.set(context);
}
public static RequestContext get() {
return LOCAL.get();
}
public static void remove() {
LOCAL.remove();
}
}
这里有个重点:
java
public RequestContext copy(RequestContext parentValue) {
return parentValue == null ? null : parentValue.deepCopy();
}
我们重写了 TTL 的复制逻辑。
这样任务传递上下文时,不是共享同一个 RequestContext,而是传递深拷贝。
这能减少跨线程共享可变对象带来的风险。
十一、TTL 线程池配置
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/config/ThreadPoolConfig.java
核心代码:
java
@Bean(destroyMethod = "shutdown")
public ExecutorService ttlExecutor() {
ThreadPoolExecutor executor = (ThreadPoolExecutor) Executors.newFixedThreadPool(2);
executor.prestartAllCoreThreads();
return TtlExecutors.getTtlExecutorService(executor);
}
重点是:
java
TtlExecutors.getTtlExecutorService(executor)
它会返回一个被 TTL 包装过的线程池。
以后提交到这个线程池的任务,会自动完成 TTL 上下文的捕获、恢复和还原。
生产建议:
text
不要让业务代码到处手写 TtlRunnable.get。
更推荐统一包装业务线程池。
十二、TTL 三个接口对比
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/controller/TtlContextController.java
1. 不包装线程池
接口:
text
GET /api/ttl/without-wrapper
核心代码:
java
@GetMapping("/api/ttl/without-wrapper")
public CompletableFuture<ContextView> withoutWrapper(@RequestParam(defaultValue = "ttl-user") String userId) {
TtlRequestContextHolder.set(newContext(userId, "without-wrapper"));
try {
return CompletableFuture.supplyAsync(() ->
ContextView.of(TtlRequestContextHolder.get(), "普通线程池没有 TTL 包装时,提交后的任务不会稳定拿到父线程上下文"), bizExecutor);
} finally {
TtlRequestContextHolder.remove();
}
}
重点:
text
只用 TransmittableThreadLocal,不代表线程池自动传递。
因为普通线程池并不知道要帮 TTL 捕获上下文。
2. 使用 TtlRunnable 包装任务
接口:
text
GET /api/ttl/runnable
核心代码:
java
@GetMapping("/api/ttl/runnable")
public ContextView ttlRunnable(@RequestParam(defaultValue = "ttl-user") String userId) throws Exception {
TtlRequestContextHolder.set(newContext(userId, "ttl-runnable"));
try {
Callable<ContextView> callable = () ->
ContextView.of(TtlRequestContextHolder.get(), "TtlRunnable/TtlCallable 会在提交任务时捕获上下文,并在执行后恢复现场");
FutureTask<ContextView> task = new FutureTask<ContextView>(callable);
bizExecutor.execute(TtlRunnable.get(task));
return task.get();
} finally {
TtlRequestContextHolder.remove();
}
}
这里的关键是:
java
TtlRunnable.get(task)
这一步会捕获当前父线程里的 TTL 上下文。
3. 使用 TTL 线程池
接口:
text
GET /api/ttl/executor
核心代码:
java
@GetMapping("/api/ttl/executor")
public CompletableFuture<ContextView> ttlExecutor(@RequestParam(defaultValue = "ttl-user") String userId) {
TtlRequestContextHolder.set(newContext(userId, "ttl-executor"));
try {
return CompletableFuture.supplyAsync(() ->
ContextView.of(TtlRequestContextHolder.get(), "TtlExecutors 包装线程池后,提交 Runnable/Callable 时自动完成捕获和恢复"), ttlExecutor);
} finally {
TtlRequestContextHolder.remove();
}
}
这就是生产里更推荐的方式。
业务代码只需要用被包装后的线程池。
十三、TTL 帮我们做了什么
如果不用 TTL,我们手工写上下文传递通常要这样:
java
RequestContext captured = RequestContextHolder.get().deepCopy();
executor.submit(() -> {
try {
RequestContextHolder.set(captured);
doBusiness();
} finally {
RequestContextHolder.remove();
}
});
TTL 帮我们把这套模板封装起来:
text
1. 任务提交时捕获上下文
2. 任务执行前把上下文放到工作线程
3. 任务执行后恢复工作线程原来的上下文
4. 避免污染线程池线程
结构图:
面试回答可以这么说:
text
TTL 并不是让 ThreadLocal 魔法般跨线程可见,而是在任务包装层做 capture/replay/restore。
它本质上把上下文从“线程绑定”转换成了“任务提交时携带的快照”。
十四、WebFlux 为什么不适合 ThreadLocal
前面讲的 MVC 是同步阻塞模型。
但 WebFlux 是响应式非阻塞模型。
响应式链路中,一个请求可能经历多个线程:
如果你在 T1 上做:
java
RequestContextHolder.set(context);
后面到 T2、T3 时:
java
RequestContextHolder.get();
不一定能拿到。
这就是 WebFlux 下传统 ThreadLocal 失效的根本原因。
十五、WebFlux 反例:ThreadLocal 失效
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/controller/ReactiveContextController.java
接口:
text
GET /api/reactive/threadlocal-fail
核心代码:
java
@GetMapping("/api/reactive/threadlocal-fail")
public Mono<ContextView> threadLocalFail() {
RequestContextHolder.set(new RequestContext(UUID.randomUUID().toString(), "reactive-user"));
return Mono.delay(Duration.ofMillis(30))
.publishOn(Schedulers.boundedElastic())
.map(ignore -> ContextView.current("响应式链路发生线程切换后,传统 ThreadLocal 很容易读不到或读到脏值"))
.doFinally(signalType -> RequestContextHolder.remove());
}
这里故意做了线程切换:
java
.publishOn(Schedulers.boundedElastic())
一旦线程切换,传统 ThreadLocal 就可能读不到入口线程设置的值。
十六、Reactor Context 是什么
Reactor Context 可以理解为响应式链路里的上下文容器。
它不绑定物理线程,而是绑定订阅链路。
对比一下:
text
ThreadLocal:绑定 Thread
Reactor Context:绑定 Subscriber / Subscription 链路
结构图:
它跟着响应式链路走,而不是跟着线程走。
所以即使发生线程切换,只要还在同一条订阅链路里,就可以读到上下文。
十七、subscriberContext、contextWrite、deferContextual 的关系
很多老文章会写:
java
.subscriberContext(...)
这是 Reactor 旧版本里的 API。
在新版本中,推荐使用:
java
.contextWrite(...)
读取上下文则推荐:
java
Mono.deferContextual(ctx -> {
RequestContext context = ctx.get("requestContext");
return Mono.just(context);
});
所以可以这样理解:
text
subscriberContext:旧 API,老项目或老文章中常见
contextWrite:新 API,用于写入 Reactor Context
deferContextual:新 API,用于在订阅时读取 Reactor Context
为什么要用 deferContextual?
因为 Reactor Context 是订阅时才确定的。
如果你在组装链路时就读取,很可能读不到最终上下文。
十八、WebFlux 入口写入 Context
源码文件:
text
ThreadLocalContextDemo/src/main/java/com/salmon/demo/config/WebFluxContextConfig.java
核心代码:
java
@Configuration
@Profile("webflux")
public class WebFluxContextConfig {
@Bean
public WebFilter reactorContextWebFilter() {
return (exchange, chain) -> {
String traceId = exchange.getRequest().getHeaders().getFirst("X-Trace-Id");
String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id");
RequestContext context = new RequestContext(
traceId == null || traceId.trim().length() == 0 ? UUID.randomUUID().toString() : traceId,
userId == null || userId.trim().length() == 0 ? "anonymous" : userId
);
context.getAttributes().put("source", "webflux-reactor-context");
return chain.filter(exchange)
.contextWrite(ctx -> ctx.put(ReactorContextKeys.REQUEST_CONTEXT, context.deepCopy()));
};
}
}
流程图:
注意:
java
.contextWrite(ctx -> ctx.put(ReactorContextKeys.REQUEST_CONTEXT, context.deepCopy()))
这里同样做了深拷贝。
十九、WebFlux 业务代码读取 Context
接口:
text
GET /api/reactive/defer-contextual
核心代码:
java
@GetMapping("/api/reactive/defer-contextual")
public Mono<ContextView> deferContextual() {
return Mono.deferContextual(ctx -> {
RequestContext context = ctx.getOrDefault(
ReactorContextKeys.REQUEST_CONTEXT,
new RequestContext("no-webflux-filter", "anonymous"));
return Mono.just(ContextView.of(context, "Mono.deferContextual 在订阅时读取上下文,是响应式代码里最常用的安全读取方式"));
})
.publishOn(Schedulers.parallel());
}
重点:
java
Mono.deferContextual(ctx -> ...)
它不是从线程里拿数据,而是从当前响应式订阅上下文中拿数据。
即使后面有:
java
.publishOn(Schedulers.parallel())
也不会像普通 ThreadLocal 那样天然丢失。
二十、WebFlux 生产写法
接口:
text
GET /api/reactive/production
核心代码:
java
@GetMapping("/api/reactive/production")
public Mono<ContextView> production() {
return Mono.deferContextual(ctx -> {
RequestContext context = ctx.get(ReactorContextKeys.REQUEST_CONTEXT);
return fakeRemoteCall(context)
.map(value -> ContextView.of(context, "生产写法:WebFilter 写入 Reactor Context,业务方法用 deferContextual 读取并显式传参"));
})
.publishOn(Schedulers.boundedElastic());
}
private Mono<String> fakeRemoteCall(RequestContext context) {
return Mono.delay(Duration.ofMillis(20))
.map(ignore -> "traceId=" + context.getTraceId());
}
这段代码里有一个很重要的设计:
java
fakeRemoteCall(context)
也就是说:
text
从 Reactor Context 取出请求上下文后,继续显式传给业务方法。
这是我更推荐的生产写法。
不要让所有业务方法都到处读取全局上下文。
更好的方式是:
text
入口统一解析
链路统一承载
边界处读取
业务方法显式传参
二十一、MVC、线程池、WebFlux 三种模型对比
| 场景 | 执行模型 | 推荐上下文方案 | 是否依赖线程 | 注意事项 |
|---|---|---|---|---|
| Spring MVC 同步请求 | 一个请求主要在一个 Servlet 线程中执行 | ThreadLocal |
是 | 必须 remove() |
| MVC + 业务线程池 | 请求线程提交异步任务 | TTL 或手工传递 | 部分依赖 | 提交任务时捕获上下文 |
CompletableFuture |
默认或自定义线程池 | TTL 线程池或显式传参 | 否 | 不要用裸线程池 |
| WebFlux | 响应式流、多线程切换 | Reactor Context |
否 | 用 contextWrite + deferContextual |
| 日志链路追踪 | MVC / 异步 / 响应式都有 | 按模型适配 MDC | 视情况 | MDC 本身也是 ThreadLocal |
二十二、生产项目标准落地方案
1. MVC 项目
推荐结构:
text
web
├── filter / interceptor
│ └── 解析 traceId、userId、tenantId
├── context
│ ├── RequestContext
│ └── RequestContextHolder
└── service
└── 当前请求线程内读取
模板代码:
java
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
RequestContext context = buildContext(request);
RequestContextHolder.set(context);
return true;
}
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
RequestContextHolder.remove();
}
2. 线程池异步项目
推荐结构:
text
executor
├── 普通线程池禁止直接注入业务
├── 统一暴露包装后的 TTL 线程池
└── 统一处理上下文传递
模板代码:
java
@Bean(destroyMethod = "shutdown")
public ExecutorService ttlExecutor() {
ExecutorService executor = Executors.newFixedThreadPool(16);
return TtlExecutors.getTtlExecutorService(executor);
}
业务代码:
java
CompletableFuture.supplyAsync(() -> {
RequestContext context = TtlRequestContextHolder.get();
return doBusiness(context);
}, ttlExecutor);
3. WebFlux 项目
推荐结构:
text
webflux
├── WebFilter
│ └── 写入 Reactor Context
├── controller
│ └── deferContextual 读取
└── service
└── 显式传 RequestContext
模板代码:
java
return chain.filter(exchange)
.contextWrite(ctx -> ctx.put("requestContext", context));
读取:
java
return Mono.deferContextual(ctx -> {
RequestContext context = ctx.get("requestContext");
return service.handle(context);
});
二十三、面试高频问题整理
1. ThreadLocal 的 key 为什么设计成弱引用
为了减少 ThreadLocal 对象本身无法回收的风险。
如果 key 是强引用,即使外部已经不再使用这个 ThreadLocal,线程里的 ThreadLocalMap 仍然强引用它,它就无法被 GC。
但 key 是弱引用不代表完全不会泄漏。
因为 value 仍然是强引用。
所以仍然需要 remove()。
2. 为什么 remove 很重要
因为线程池线程会复用。
不 remove 会导致:
- 旧用户信息残留
- 旧 traceId 残留
- 大对象无法释放
- 下一个任务读到脏数据
3. 线程池里 ThreadLocal 为什么丢失
因为父线程和线程池工作线程不是同一个线程。
ThreadLocal 的数据保存在各自线程内部。
4. InheritableThreadLocal 为什么不推荐在线程池里用
它只在线程创建时继承。
线程池线程创建一次后会一直复用。
后续任务提交时不会重新继承父线程变量。
5. TTL 原理是什么
TTL 通过包装任务或线程池,在提交任务时捕获上下文,在执行任务前恢复上下文,任务结束后还原线程原上下文。
关键词:
text
capture
replay
restore
6. TTL 能不能解决 WebFlux 上下文传递
不推荐这么用。
WebFlux 的问题不是普通线程池任务传递问题,而是响应式订阅链路问题。
WebFlux 应该用 Reactor Context。
7. Reactor Context 和 ThreadLocal 的区别
ThreadLocal 绑定线程。
Reactor Context 绑定响应式订阅链路。
8. Mono.deferContextual 为什么重要
因为 Reactor Context 是订阅期上下文。
deferContextual 可以在订阅时读取当前上下文,而不是在链路组装时提前读取。
二十四、一次请求的完整演进
从同步到异步再到响应式,可以这样理解:
工程里的接口正好对应这个演进过程:
text
1. /api/http/context/current
2. /api/http/context/async-lost
3. /api/http/context/async-manual
4. /api/ttl/without-wrapper
5. /api/ttl/runnable
6. /api/ttl/executor
7. /api/reactive/threadlocal-fail
8. /api/reactive/defer-contextual
9. /api/reactive/production
二十五、运行接口清单
1. 启动 Servlet 模式
bash
mvn -f ThreadLocalContextDemo/pom.xml spring-boot:run
2. 测试 MVC 当前线程上下文
bash
curl -H "X-Trace-Id: trace-001" -H "X-User-Id: user-001" \
"http://localhost:8080/api/http/context/current"
3. 测试普通线程池丢上下文
bash
curl -H "X-Trace-Id: trace-002" -H "X-User-Id: user-002" \
"http://localhost:8080/api/http/context/async-lost"
4. 测试手工传递上下文
bash
curl -H "X-Trace-Id: trace-003" -H "X-User-Id: user-003" \
"http://localhost:8080/api/http/context/async-manual"
5. 测试 ThreadLocal 泄漏
bash
curl "http://localhost:8080/api/threadlocal/leak/write?userId=user-a"
curl "http://localhost:8080/api/threadlocal/leak/read"
curl "http://localhost:8080/api/threadlocal/leak/fix?userId=user-b"
curl "http://localhost:8080/api/threadlocal/leak/after-fix-read"
6. 测试浅拷贝风险
bash
curl "http://localhost:8080/api/threadlocal/shallow-copy-risk"
7. 测试 TTL
bash
curl "http://localhost:8080/api/ttl/without-wrapper?userId=ttl-user"
curl "http://localhost:8080/api/ttl/runnable?userId=ttl-user"
curl "http://localhost:8080/api/ttl/executor?userId=ttl-user"
8. 启动 WebFlux 模式
bash
mvn -f ThreadLocalContextDemo/pom.xml spring-boot:run -Dspring-boot.run.profiles=webflux
9. 测试 WebFlux 上下文
bash
curl -H "X-Trace-Id: reactive-001" -H "X-User-Id: reactive-user" \
"http://localhost:8081/api/reactive/threadlocal-fail"
curl -H "X-Trace-Id: reactive-002" -H "X-User-Id: reactive-user" \
"http://localhost:8081/api/reactive/context-write"
curl -H "X-Trace-Id: reactive-003" -H "X-User-Id: reactive-user" \
"http://localhost:8081/api/reactive/defer-contextual"
curl -H "X-Trace-Id: reactive-004" -H "X-User-Id: reactive-user" \
"http://localhost:8081/api/reactive/production"
二十六、这类问题怎么排查
线上如果怀疑上下文串了,可以按这个顺序排查:
text
1. 找所有 ThreadLocal.set 的地方
2. 检查是否一定有 remove
3. 检查 remove 是否在 finally 或 afterCompletion
4. 检查是否进入线程池
5. 检查线程池是否 TTL 包装
6. 检查上下文对象是否共享可变引用
7. 如果是 WebFlux,检查是否错误使用 ThreadLocal
8. 检查日志 MDC 是否同样需要适配
特别注意:
text
MDC 本质上也常基于 ThreadLocal。
所以日志 traceId 丢失和业务上下文丢失,经常是同一类问题。
二十七、最佳实践总结
1. ThreadLocal 使用原则
text
能不用就不用。
用了就必须 remove。
只放小对象。
不要放大集合、大对象、连接、流等资源。
2. 请求上下文原则
text
入口统一构建。
业务尽量只读。
跨线程传快照。
不要共享可变对象。
3. 线程池原则
text
不要裸用普通线程池传上下文。
统一包装线程池。
统一治理 CompletableFuture executor。
4. WebFlux 原则
text
不要依赖 ThreadLocal。
入口用 WebFilter 写 Reactor Context。
业务用 deferContextual 读。
读出来后显式传参。
二十八、最后总结
ThreadLocal 本身不复杂。
真正复杂的是现代 Java 后端的执行模型变复杂了。
以前一个请求一个线程,ThreadLocal 很自然。
后来加入线程池,任务和线程分离,ThreadLocal 开始丢上下文。
再后来进入响应式编程,请求链路和物理线程彻底解耦,ThreadLocal 就更不适合作为上下文载体。
所以我们要按模型选方案:
text
Spring MVC 同步链路:ThreadLocal + finally remove
线程池异步链路:TTL / 手工传递上下文
WebFlux 响应式链路:Reactor Context
如果你在面试里能把这条线讲清楚:
text
ThreadLocal 原理
内存泄漏原因
线程池上下文丢失
InheritableThreadLocal 局限
TTL capture/replay/restore
WebFlux 为什么不能用 ThreadLocal
Reactor Context 怎么解决
基本就不是背八股了,而是真的理解了 Java 后端上下文传递这件事。
评论
1 条觉得有帮助的,留个言吧~😁