外观
B - ThreadLocal 内存泄漏与上下文污染
适用 JDK:ThreadLocal 部分适用 JDK 8+。Scoped Values 在 JDK 21–24 经历预览,在 JDK 25 定稿;使用时仍应核对项目的编译与运行 JDK。
前置阅读:02 - Java 线程生命周期与正确中断方式、09 - ThreadPoolExecutor 参数与容量设计。
摘要
请求 B 读到了请求 A 的用户 ID,往往是因为两个请求先后使用了同一个工作线程,而请求 A 没有清理留下的值。ThreadLocal 按线程保存状态,不会自动按请求清理状态。
上下文是处理请求时需要随调用传递的信息,例如用户 ID、租户标识和追踪标识。同一个 ThreadLocal 对象可以被多个线程使用,但 set()、get() 和 remove() 操作的是当前线程中的值:设置、读取或移除这个线程的绑定。切换到另一个线程,不会自动带上原线程的值。
本文区分两个问题:上下文污染是后续任务读到了不属于自己的值;内存滞留是任务已经不再需要对象,但线程仍通过引用保留着它。先理解请求边界上的清理,再看引用结构和异步传播。下面的 Java 代码均为局部示意片段,Request、process、executor 和 task 由外围业务提供,并非完整可运行程序。
1. 上下文污染
下面的请求入口设置了用户 ID,却没有在处理结束后清理:
java
private static final ThreadLocal<String> USER_ID = new ThreadLocal<>();
public void handle(Request request) {
USER_ID.set(request.userId());
process(request);
// 忘记 remove()
}假设请求 A 在工作线程上留下了用户 ID,随后请求 B 复用该线程。如果 B 在设置自己的上下文前就读取 USER_ID,读到的仍是 A 的值;提前返回或异常若绕过初始化、清理,也可能让旧值继续留存。若 B 成功执行了 set(),后续读取会得到 B 的值,因此不能把线程复用本身等同于必然串数据。
对于负责建立上下文、且没有外层绑定需要恢复的请求入口,应在 finally 中移除值。这样,process() 正常返回或抛出异常时都会执行清理:
java
public void handle(Request request) {
USER_ID.set(request.userId());
try {
process(request);
} finally {
USER_ID.remove();
}
}嵌套调用还有另一层要求。例如外层已经设置用户 ID,内层暂时换成另一个 ID;内层结束后,外层应继续读到自己的值。通用库若无条件 remove(),会把外层绑定一起删掉,所以应先保存原值,再在退出时恢复:
java
String previous = USER_ID.get();
USER_ID.set(request.userId());
try {
process(request);
} finally {
if (previous == null) {
USER_ID.remove();
} else {
USER_ID.set(previous);
}
}这里沿用前面默认初始化的 ThreadLocal<String>,把读到 null 视为没有需要恢复的业务值;它不区分“未绑定”和“显式绑定了 null”。若组件需要区分这两种状态,或使用自定义初始值,就要单独设计状态记录,不能直接套用这个判断。
清理和恢复的选择取决于调用边界:请求入口负责结束自己的绑定,嵌套组件负责恢复进入前的状态。后文的上下文传播也需要遵守这个规则。
2. ThreadLocalMap 引用结构
ThreadLocalMap 是线程内部保存这些绑定的结构,每条记录称为 Entry。其中 Key 是 ThreadLocal 对象,Value 是业务保存的值。Entry 对 Key 使用弱引用,对 Value 使用强引用。
强引用会让可达对象继续被保留;弱引用本身不会阻止 GC(垃圾回收)回收对象。这里要分别看两条引用关系,不能因为 Key 是弱引用,就认为 Value 也会自动释放。
图表将在阅读到此处时加载…
当 Key 不再被其他强引用保留、并被 GC 回收后,Entry 的 Key 变成 null,但线程到 Value 的强引用链仍可能存在。这样的记录称为失效 Entry。ThreadLocalMap 的后续 get/set/remove 操作在某些路径上会顺带清理部分失效 Entry;这属于惰性清理,即在后续操作中处理,而非在 Key 回收时立即处理。不能假定下一次操作会清理所有失效记录。
前例的 static final USER_ID 在所属类仍可达时,通常仍被强引用保留,Key 并不会仅因一次请求结束而消失。此时忘记清理,同样会留下 Value,也可能造成上下文污染。Key 已回收、Value 仍被保留则是另一种滞留路径,不能把两者混为一谈。
如果 Value 间接引用 Web 应用的 ClassLoader(加载应用类的类加载器),而工作线程由生命周期更长的容器创建,这条引用链还可能阻止旧应用版本的 ClassLoader 被回收。弱 Key 不会切断线程到 Value 再到其他对象的强引用链。
3. 为什么线程池放大问题
关键差别在于:任务结束不等于执行它的线程结束。线程池为了复用工作线程,会让线程继续等待并执行后续任务;保存在该线程中的值,不会仅因当前任务返回而自动清理。
短生命周期线程结束后,其线程局部状态可以释放;线程池工作线程却可能存活数小时甚至与进程同寿。因此,遗漏清理可能同时带来两种后果:Value 被长期保留,以及后续任务在覆盖它之前读到旧值。是否构成内存泄漏,要结合对象是否仍有业务用途、保留时长和引用链判断,不能只看到 ThreadLocal 就认定泄漏。
4. 异步跨线程不会自动传播
把任务交给执行器,不会把普通 ThreadLocal 的值一起交过去。以下片段假设任务由另一个工作线程执行:
java
USER_ID.set("u-1");
executor.execute(() -> {
System.out.println(USER_ID.get()); // 通常是 null 或该工作线程的旧值
});这里读取的是工作线程自己的 USER_ID,并非提交线程的值。注释描述的是这种条件下的预期行为,不是实测输出;若执行器直接在提交线程执行任务,就没有发生这个跨线程边界。
业务输入优先显式传参:先在提交线程读取用户 ID,再让任务使用捕获的局部变量,避免执行时依赖工作线程的旧状态。
java
String userId = USER_ID.get();
executor.execute(() -> process(userId));日志、追踪等信息常被多个业务层共同使用,称为横切上下文。MDC(Mapped Diagnostic Context,映射诊断上下文)用于让日志携带请求标签;TraceId 是关联同一请求链路的追踪标识。框架若需要传播这些信息,可以按“提交时捕获 → 执行前安装 → 退出时恢复”的顺序包装任务。
下面使用 MDC API 示意这一流程,需要相应日志库及 Map 类型。captured 是提交线程的上下文快照,即提交时复制的状态;previous 是执行线程进入任务前的状态:
java
Map<String, String> captured = MDC.getCopyOfContextMap();
executor.execute(() -> {
Map<String, String> previous = MDC.getCopyOfContextMap();
try {
if (captured == null) MDC.clear();
else MDC.setContextMap(captured);
task.run();
} finally {
if (previous == null) MDC.clear();
else MDC.setContextMap(previous);
}
});finally 恢复执行线程原来的 MDC,避免本任务的标签留给后续任务,也避免嵌套执行时删掉外层标签。这是传播模式的示意代码,生产实现还应处理任务提交被拒绝,以及组合多个上下文系统时的清理顺序。推广到其他上下文时,还要检查快照中的可变值:复制容器不等于复制了其中所有对象,共享可变对象仍可能带来竞争。
10 - CompletableFuture 异步编排中的异步阶段也遵守同样边界,不能根据提交线程的值推断执行线程中的值。
5. InheritableThreadLocal 的边界
InheritableThreadLocal 在创建子线程时传递父线程的值,传递时点是线程创建,而非每次任务提交。线程池的线程通常在后续任务提交前已经创建,即使某些工作线程是在提交时才创建,也只发生一次创建时的继承。因此它不能直接解决线程池中每个任务的上下文传播,还可能把创建线程时的旧值长期保留。
继承也不代表父线程后续的 set() 会同步到子线程。默认 childValue() 并不会深拷贝业务对象;如果 Value 可变,父子线程还可能持有同一对象。两边无同步地读写它,就可能发生数据竞争,即并发访问同一状态且至少一方写入、又缺少必要同步。线程局部存储隔离的是绑定,不会自动隔离被引用对象。
6. 虚拟线程与 Scoped Values
虚拟线程是由 JDK 调度的轻量线程,同样支持 ThreadLocal。通常按任务创建虚拟线程时,不再让多个请求先后复用同一个线程,因此传统线程池中的旧值污染风险会降低。但大量线程各自保留大对象,仍有内存代价;长生命周期虚拟线程和未受控传播也仍需管理。
Scoped Values 将上下文绑定限制在一次受控调用及其下游调用期间,退出后本次绑定失效,避免在任意位置 set() 后忘记 remove()。这里的“只读”指绑定不能像 ThreadLocal 那样被任意改写,不代表绑定对象的内部状态自动不可变,也不代表任意异步任务都会继承它。
Scoped Values 在 JDK 25 定稿;如果应用仍要求 JDK 21 或其他旧版本,需要单独设计兼容策略,不能在通用库中直接假定 API 可用。虚拟线程的版本边界见 13 - JDK 21 虚拟线程实战。
7. Spring 事务为什么不能随意跨线程
Spring 声明式事务的常见线程绑定管理器,会将当前数据库连接和事务同步回调绑定到执行线程。同步回调是框架在事务完成等阶段调用的处理逻辑。DAO(数据访问对象)封装数据库操作;在事务方法内把 DAO 操作投递到普通线程池,新线程通常不会自动参与原事务,因为原事务资源绑定在调用线程上。
手工复制 Spring 内部 ThreadLocal 不会自动建立正确的事务关系,还可能让多个线程使用同一个连接。应重新设计事务边界、在子任务中开启独立事务,或使用明确的消息/补偿模型;补偿是通过后续业务操作处理先前操作的影响,并非让分开的事务自动变成同一个事务。这里讨论常见的线程绑定事务,具体行为仍需核对所用事务管理器。执行链见 Spring 11 - Spring 声明式事务执行链。
8. 排查方法
先按现象选择证据,避免把污染和内存增长当成同一个问题:
- 读到旧上下文:检查请求入口和所有相关
set()的退出路径,确认正常返回、异常、提前返回时都清理或恢复。跨线程时,检查捕获、安装和恢复分别发生在哪个线程。 - 怀疑内存滞留:从堆 Dump(堆中对象及引用关系的快照)沿
Thread -> threadLocals/inheritableThreadLocals -> Entry -> value跟踪,确认哪个长生命周期线程还在保留对象。 - 检查保留原因和规模:区分 Key 仍可达但值未清理,与 Key 已回收、Entry Key 为 null 的情况;再看 Value 是否持有大集合、ClassLoader、请求对象或连接。对象自身很小,也可能间接保留大量对象;保留集描述因该对象的引用关系而被留下的对象集合。
- 增加回归测试:让不同用户或租户的任务先后复用同一工作线程,在新任务安装上下文前检查是否有旧值;再覆盖异常退出和嵌套调用,确认内层退出后外层值被恢复。测试用于验证修复,不是仅凭一次堆快照就认定原因。
内存证据的通用工具见 JVM 07 - 故障排查与监控工具。
9. 容易踩的坑
- 把请求结束当成线程结束,遗漏
finally中的清理。 - 只看弱 Key,忽略线程到 Value 的强引用链和清理时机。
- 把创建线程时的继承,当成每次任务提交时的传播。
- 在 ThreadLocal 中缓存连接或大对象,却没有明确的释放边界。
- 对嵌套调用一律清空,破坏外层仍需使用的上下文。
10. 总结
ThreadLocal 按线程保存状态;要让状态只在一次请求或调用中有效,必须显式管理绑定的边界。
- 请求入口在
finally中清理,嵌套组件在finally中恢复原状态。 - 弱 Key 不保证 Value 及时释放;长生命周期线程会放大遗漏清理的影响。
- 业务输入优先显式传递,框架传播按捕获、安装、恢复组织;事务资源不能当作普通标签复制。
后续阅读:21 - 并发上下文传播与 ScopedValue进一步区分可传播上下文与不可跨线程复制的资源。