从 ThreadLocal 到 TTL,再到 WebFlux Context:一次讲透 Java 线程上下文传递

2026-07-23后端18 分钟161 次阅读
AI 摘要鱼粮不足,AI 今天先歇着 · 正文在下面

前言

在 Java 后端开发里,ThreadLocal 是一个非常常见的工具。

你可能在这些场景里见过它:

  • 保存当前登录用户
  • 保存 traceId / requestId
  • 保存租户 ID
  • 保存数据源路由 key
  • 保存链路追踪上下文
  • 保存本地事务上下文
  • 保存灰度、语言、时区等请求级信息

看起来它很好用:

java 复制代码
RequestContextHolder.set(context);
RequestContext context = RequestContextHolder.get();

业务代码不用层层传参,就能拿到当前请求上下文。

但是很多线上问题也和它有关:

  • 接口 A 的用户信息串到了接口 B
  • 线程池里异步任务拿不到 traceId
  • ThreadLocal 没有 remove() 导致内存泄漏
  • InheritableThreadLocal 在线程池里表现不符合预期
  • 使用 CompletableFuture 后日志 traceId 丢了
  • WebFlux 里明明入口设置了 ThreadLocal,后面却读不到

这类问题的根源不是某个工具不好,而是我们经常把三个概念混在一起:

  1. 线程内存储
  2. 跨线程传递
  3. 响应式订阅链路传递

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

三、上下文传递全景图

先看整体关系。

flowchart TD A["HTTP 请求进入"] --> B{"应用模型"} B --> C["Spring MVC / Servlet"] B --> D["线程池异步任务"] B --> E["WebFlux / Reactor"] C --> C1["HandlerInterceptor"] C1 --> C2["ThreadLocal.set"] C2 --> C3["Controller / Service 当前线程读取"] C3 --> C4["finally / afterCompletion remove"] D --> D1["普通 ThreadLocal 丢失"] D --> D2["手工捕获 + 深拷贝 + set + remove"] D --> D3["TTL 包装 Runnable / Callable / Executor"] E --> E1["传统 ThreadLocal 失效"] E --> E2["WebFilter 写入 Reactor Context"] E2 --> E3["Mono.deferContextual 读取"] E3 --> E4["显式传参给业务方法"]

核心结论:

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 对象里保存了每个线程的值

其实不是。

真实关系更接近这样:

flowchart LR T["Thread 当前线程"] --> M["ThreadLocalMap"] M --> E1["Entry"] E1 --> K1["key: ThreadLocal 弱引用"] E1 --> V1["value: RequestContext 强引用"] TL["static ThreadLocal 变量"] -. "作为 key" .-> K1

也就是说:

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();
            }
        });
    }
}

流程图:

sequenceDiagram participant Client as 客户端 participant Interceptor as MVC 拦截器 participant Controller as Controller participant Holder as RequestContextHolder Client->>Interceptor: HTTP 请求 X-Trace-Id / X-User-Id Interceptor->>Holder: set(RequestContext) Interceptor->>Controller: 放行 Controller->>Holder: get() Controller-->>Client: 返回响应 Interceptor->>Holder: 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);
}

流程:

sequenceDiagram participant T1 as Tomcat 请求线程 participant TL1 as T1 的 ThreadLocalMap participant Pool as 业务线程池 participant T2 as pool-thread-1 participant TL2 as T2 的 ThreadLocalMap T1->>TL1: set(RequestContext) T1->>Pool: submit task Pool->>T2: 执行 task T2->>TL2: get() TL2-->>T2: null

原因很简单:

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

流程图:

flowchart LR A["父线程 RequestContextHolder.get"] --> B["deepCopy 快照"] B --> C["提交异步任务"] C --> D["子线程 RequestContextHolder.set"] D --> E["执行业务"] E --> F["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 只能在创建子线程时传递。

示意图:

flowchart TD A["父线程 set"] --> B["new Thread"] B --> C["子线程创建时复制父线程变量"]

但线程池是这样:

flowchart TD A["应用启动"] --> B["线程池创建核心线程"] B --> C["线程长期存活"] D["请求进来 set 上下文"] --> E["submit task"] E --> C C --> F["复用旧线程执行任务"]

线程早就创建好了。

后续提交任务时不会重新触发 InheritableThreadLocal 的复制逻辑。

所以它不能解决线程池传递问题。

2. TTL 的核心思想

TTL 的关键不是“变量类型换了”。

关键是“任务提交时包装”。

大概流程:

sequenceDiagram participant Parent as 父线程 participant TTL as TTL participant Executor as 线程池 participant Worker as 工作线程 Parent->>TTL: set(RequestContext) Parent->>TTL: 包装 Runnable/Callable 时捕获上下文 Parent->>Executor: submit(wrappedTask) Executor->>Worker: 执行 wrappedTask Worker->>TTL: replay 捕获的上下文 Worker->>Worker: 执行业务逻辑 Worker->>TTL: restore 原线程上下文

总结成三句话:

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. 避免污染线程池线程

结构图:

flowchart TD A["父线程 TTL 上下文"] --> B["TtlRunnable / TtlCallable"] B --> C["capture 快照"] C --> D["提交到线程池"] D --> E["工作线程执行"] E --> F["replay 快照"] F --> G["执行业务逻辑"] G --> H["restore 原上下文"]

面试回答可以这么说:

text 复制代码
TTL 并不是让 ThreadLocal 魔法般跨线程可见,而是在任务包装层做 capture/replay/restore。
它本质上把上下文从“线程绑定”转换成了“任务提交时携带的快照”。

十四、WebFlux 为什么不适合 ThreadLocal

前面讲的 MVC 是同步阻塞模型。

但 WebFlux 是响应式非阻塞模型。

响应式链路中,一个请求可能经历多个线程:

sequenceDiagram participant Client as 客户端 participant T1 as event-loop-1 participant T2 as boundedElastic-1 participant T3 as parallel-1 participant Chain as Reactor Chain Client->>T1: 请求进入 T1->>Chain: 执行 operator A Chain->>T2: publishOn 切线程 T2->>Chain: 执行 operator B Chain->>T3: 再次调度 T3->>Chain: 执行 operator C

如果你在 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 链路

结构图:

flowchart LR A["Subscriber"] --> B["Reactor Context"] B --> C["traceId"] B --> D["userId"] B --> E["tenantId"] A --> F["operator A"] F --> G["operator B"] G --> H["operator C"]

它跟着响应式链路走,而不是跟着线程走。

所以即使发生线程切换,只要还在同一条订阅链路里,就可以读到上下文。


十七、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()));
        };
    }
}

流程图:

sequenceDiagram participant Client as 客户端 participant Filter as WebFilter participant Context as Reactor Context participant Handler as Controller Client->>Filter: HTTP 请求 Filter->>Filter: 构造 RequestContext Filter->>Context: contextWrite 写入上下文 Filter->>Handler: 进入响应式链路 Handler->>Context: deferContextual 读取上下文

注意:

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 可以在订阅时读取当前上下文,而不是在链路组装时提前读取。


二十四、一次请求的完整演进

从同步到异步再到响应式,可以这样理解:

flowchart TD A["阶段 1:同步 MVC"] --> B["ThreadLocal 足够"] B --> C["阶段 2:MVC 中加入线程池"] C --> D["ThreadLocal 丢失"] D --> E["手工传递或 TTL"] E --> F["阶段 3:响应式 WebFlux"] F --> G["线程不再是上下文边界"] G --> H["Reactor Context"]

工程里的接口正好对应这个演进过程:

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 条
登录 之后才能评论
Salmon2026-07-29

觉得有帮助的,留个言吧~😁