Appearance
2.4-8 ThreadLocal:原理、内存泄漏、跨线程传递
所属:02 Java 运行时 / 2.4 并发 分级:A 状态:◐ 初稿 关联:2.4-1、2.4-6、2.4-11、2.4-12、2.1-9
题型:原理 / 排查 / 场景
一句话结论:ThreadLocal 是“线程封闭”工具,每个
Thread持有自己的ThreadLocalMap,key 弱引用、value 强引用;它用空间换隔离,但线程池复用线程时必须remove(),否则会上下文串线和 value 泄漏;跨线程传递要靠InheritableThreadLocal、TTL 或显式传参,虚拟线程时代优先评估ScopedValue。分层要点:
- 数据结构:
Thread有两个字段threadLocals和inheritableThreadLocals,类型都是ThreadLocal.ThreadLocalMap。ThreadLocalMap不是java.util.Map,而是自定义的开放寻址哈希表:Entry[] table,初始容量 16,阈值2/3;Entry继承WeakReference<ThreadLocal<?>>,key 是弱引用,value 是强引用。每个ThreadLocal构造时生成threadLocalHashCode,用黄金比例增量0x61c88647递增,保证连续创建的 key 在 2 的幂大小的表里分布均匀。 - get / set / remove 流程:
get()先取当前线程的 map,再getEntry(this),命中直接返回 value,未命中走setInitialValue():调用initialValue()(默认 null),map 不存在就createMap,存在就set。set()从 hash 槽开始线性探测:key 相同就覆盖;遇到 key 为 null 的 stale entry 就replaceStaleEntry;找到空槽插入后cleanSomeSlots,必要时rehash/resize。remove()找到 key 后clear()并expungeStaleEntry,把 value 和 Entry 一起清掉,同时把后续元素重新哈希填洞。 - 内存泄漏的真正原因:
Thread -> ThreadLocalMap -> Entry -> value是强引用链;key 只是弱引用。若ThreadLocal对象不再被外部强引用(例如方法里的局部变量、临时 new),key 会被 GC 成 null,但 value 仍被 Entry 强引用,Entry 又被长生命周期的线程持有。线程池 worker 不死,value 就一直活着;如果 value 是大对象、用户上下文或 ClassLoader,就是内存泄漏/类加载器泄漏。ThreadLocalMap只在该 map 被 get/set/remove 时顺带清理 stale entry,没有后台线程,所以“不再访问”就等于永远不清理。 - 跨线程传递:
InheritableThreadLocal在new Thread()时由父线程复制inheritableThreadLocals,childValue()默认返回同一个 value 引用;它只解决“创建那一刻”的继承。线程池线程只创建一次,之后提交的任务不会重新继承,容易读到陈旧值;正确做法是 TTL(提交时 capture、执行时 replay、结束后 restore)、SpringTaskDecorator、MDC 手动 copy,或者显式把上下文作为参数传下去。CompletableFuture默认异步、ForkJoinPool.commonPool都不会自动传播 ThreadLocal。 - 典型场景与边界:常见用途是请求上下文(用户、租户、traceId/MDC)、事务连接绑定、
SimpleDateFormat等非线程安全对象的每线程副本、每线程缓冲区。ThreadLocal 只提供“每线程一份引用”,不保证 value 本身线程安全;如果多个线程拿到同一个可变对象,仍然要加锁或改用不可变对象。不要把它当缓存(每线程副本无界增长),也不要用它传递跨线程的业务参数。 - 生产实践:声明为
private static final ThreadLocal<...>让 key 稳定、避免每次 new;在finally里remove();Web 请求在 Filter/Interceptor 的 afterCompletion 清理;线程池任务用TaskDecorator/TTL 包装;应用关闭、Tomcat 重新部署时清理,防止 value 持有 ClassLoader。排查时抓 heap dump,用 MAT 看ThreadLocalMap$Entry中 key 为 null 但 value 仍在的对象,再看 GC Root 路径。
- 数据结构:
图/流程:
text
Thread
├─ threadLocals ──────────► ThreadLocalMap
│ table[] ──► Entry
│ ├─ key: WeakReference<ThreadLocal> ──✗ 可被 GC
│ └─ value: strong ──► 业务对象
└─ inheritableThreadLocals ─► 父线程在 new Thread 时复制(childValue)text
线程池 worker(长生命周期)
└─ Thread.threadLocals ──► ThreadLocalMap ──► Entry
├─ key = null(ThreadLocal 已被 GC)
└─ value = 用户上下文 / 大对象 / ClassLoader
↑ 仍被强引用,泄漏java
static class Entry extends WeakReference<ThreadLocal<?>> {
Object value;
Entry(ThreadLocal<?> k, Object v) {
super(k); // key 弱引用
value = v; // value 强引用
}
}版本/源码锚点:
- JDK 1.2:
ThreadLocal、InheritableThreadLocal。 - JDK 5:泛型化;JDK 7:
ThreadLocalRandom(不走 ThreadLocalMap)。 - JDK 8:
ThreadLocal.withInitial(Supplier);当前ThreadLocalMap开放寻址实现。 - JDK 21:虚拟线程正式(JEP 444);
ScopedValue、结构化并发仍是 preview。 - JDK 25:
ScopedValue正式(JEP 506);结构化并发仍是 preview(JEP 505)。 - 源码:
Thread.threadLocals、ThreadLocal.get/set/remove/createMap、ThreadLocalMap.Entry/set/getEntry/expungeStaleEntry/rehash/resize、ThreadLocal.createInheritedMap、InheritableThreadLocal.childValue。 - 第三方:Alibaba TransmittableThreadLocal(TTL)2.x,非 JDK 标准。
- JDK 1.2:
ThreadLocal vs synchronized:
| 维度 | ThreadLocal | synchronized |
|---|---|---|
| 解决问题 | 线程隔离,每线程一份副本 | 互斥,保护共享状态 |
| 方向 | 空间换时间 | 时间换空间 |
| 竞争 | 无共享,通常无锁 | 有竞争,可能阻塞 |
| 适用 | 上下文、非线程安全对象副本 | 计数器、共享资源临界区 |
| 风险 | 泄漏、上下文串线 | 死锁、锁粒度、性能 |
- 跨线程传递方案:
| 方案 | 原理 | 适用 | 局限 |
|---|---|---|---|
InheritableThreadLocal | new Thread 时复制父线程 map | 手动创建子线程 | 线程池只继承一次,值会陈旧 |
| TTL | 提交时 capture,执行时 replay,结束后 restore | 线程池、异步任务 | 需包装或 agent,注意清理与开销 |
| 显式传参/上下文对象 | 方法参数、RequestContext | 可控、可测试 | 侵入业务签名 |
Spring TaskDecorator | 包装 Runnable,复制/清理 MDC 等 | @Async、Spring 线程池 | 只覆盖 Spring 管理的任务 |
ScopedValue | 作用域绑定,子线程/结构化并发继承 | 虚拟线程、请求上下文 | 不可变,普通线程池仍需显式传递 |
追问链:
- ThreadLocal 的原理? → 每个
Thread有一个ThreadLocalMap,以 ThreadLocal 对象为 key、业务对象为 value;get/set/remove只操作当前线程的 map,所以天然隔离。 - 为什么 key 用弱引用、value 用强引用? → key 弱引用是为了 ThreadLocal 对象不再被使用时能被 GC;value 强引用是因为它是线程真正要用的数据,若也弱引用可能被意外回收。代价是 key 死后 value 仍被 Entry 持有,必须
remove()。 - ThreadLocal 内存泄漏是怎么发生的? → 线程池线程长期存活,ThreadLocal 对象被 GC 后 key 变 null,但 Entry 的 value 仍是强引用,且 map 只在被访问时才清理 stale entry,于是 value 和它引用的对象一直活着。
- 为什么线程池里必须 remove? → worker 线程会被复用,不清理会让下一个任务读到上一个请求的用户/trace/事务上下文,既串数据又泄漏;
finally里 remove 是底线。 - 用 static final 声明 ThreadLocal 就不会泄漏了吗? → 不会。static final 只保证 key 不被 GC,避免“key 为 null 的 stale entry”;如果 value 一直不 remove,仍然会随线程存活,属于逻辑泄漏。static final 是推荐写法,不是免死金牌。
set(null)和remove()有什么区别? →set(null)仍然保留 Entry(key 还在,value 为 null);remove()会清掉 Entry、value 并触发expungeStaleEntry。线程池清理上下文应该用remove()。- ThreadLocalMap 为什么用开放寻址而不是链表? → 每个线程的 ThreadLocal 通常很少,开放寻址不需要额外 Node、内存更紧凑、局部性更好;冲突用线性探测,删除时
expungeStaleEntry重新哈希填洞。 0x61c88647是什么? → 黄金比例增量,用来生成threadLocalHashCode,让连续创建的 ThreadLocal 在 2 的幂大小的表里均匀散布,减少碰撞。- InheritableThreadLocal 的原理? →
Thread构造时如果inheritThreadLocals=true,会把父线程的inheritableThreadLocals复制一份,value 默认经childValue()直接传引用;子线程之后set只改自己的 map,不影响父线程。 - 为什么线程池里 InheritableThreadLocal 会失效? → 线程池线程只在创建时继承一次,之后父线程再 set 不会同步;任务复用时读到的可能是创建时的旧值,甚至不同请求的值。要用 TTL 或显式传参。
- TTL 的原理? → 提交任务时捕获当前线程的 TTL 快照,任务执行前把快照回放到 worker 线程,执行完恢复 worker 原来的上下文;
TtlRunnable/TtlCallable/TtlExecutors或 Java Agent 做包装。 - ThreadLocal 能保证 value 线程安全吗? → 不能。它只保证每个线程拿到自己的引用;如果多个线程 set 了同一个可变对象,或者 value 内部引用共享状态,仍然要同步或使用不可变对象。
- ThreadLocal 和 ThreadLocalRandom 的关系? → ThreadLocalRandom 不是用 ThreadLocalMap,而是用
Thread上的threadLocalRandomSeed/probe字段,避免每个线程维护 map 的开销和竞争,适合高并发随机数。 - ThreadLocal 在虚拟线程下有什么问题? → 每个虚拟线程也是
Thread,有自己的 ThreadLocalMap;虚拟线程数量可能很大,每线程一份上下文会放大内存。虚拟线程更适合用ScopedValue表达有界、不可变的上下文。 - ScopedValue 和 ThreadLocal 的区别? → ScopedValue 不可变、绑定在词法作用域内、离开作用域自动恢复、可被结构化并发子任务继承,不需要 remove;ThreadLocal 可变、生命周期跟随线程、需要手动清理。ScopedValue 不是可变线程状态的通用替代。
- Spring 里哪些地方用了 ThreadLocal? →
RequestContextHolder存请求属性、TransactionSynchronizationManager绑定连接/事务、SecurityContextHolder存安全上下文、LocaleContextHolder等;异步/线程池场景要TaskDecorator或 TTL 传递。 - 怎么排查 ThreadLocal 泄漏? →
jcmd/jmap抓 heap dump,MAT 里看ThreadLocalMap$Entry,找 key 为 null 但 value 很大的条目,再沿 GC Root 找到线程池 worker;结合代码检查是否在 finally remove、是否 static final、是否把大对象/ClassLoader 放进 value。 - ThreadLocal 会导致类加载器泄漏吗? → 会。若 value 持有应用类、ClassLoader 或框架对象,而 worker 线程生命周期超过应用,重新部署后旧 ClassLoader 无法回收;Tomcat 的
ThreadLocalLeakPreventionListener只能在容器层兜底,应用仍要主动 remove。
- ThreadLocal 的原理? → 每个
生产案例/取舍(示例,替换成你的项目):
- 用户上下文用 ThreadLocal 缓存,线程池任务结束没有 remove;下一个请求复用到同一 worker,读到了上一个用户的权限,出现越权。修复:Filter 的
finally中UserContext.remove(),并加单测验证线程复用。 @Async方法里 MDC 的 traceId 丢失,日志无法串联;用TaskDecorator在提交时复制MDC.getCopyOfContextMap(),执行后MDC.clear()。SimpleDateFormat写成 static 共享,偶发日期串位;改成DateTimeFormatter(不可变、线程安全),或 ThreadLocal 包装并在 finally remove。- 异步任务里
@Transactional失效,因为事务连接绑定在原线程的 ThreadLocal 上;改为在异步线程里用TransactionTemplate显式开事务,或把事务边界收回到调用线程。 - Tomcat 重新部署后 Metaspace OOM,heap dump 发现 worker 线程的 ThreadLocal value 持有旧应用的 ClassLoader;在
contextDestroyed中清理,并排查所有 ThreadLocal 的 remove。 - 取舍:ThreadLocal 用空间换隔离,避免锁竞争;代价是每线程副本、必须清理、跨线程不自动传播。上下文传递优先显式参数或 TTL;虚拟线程 + 不可变上下文优先 ScopedValue。
- 用户上下文用 ThreadLocal 缓存,线程池任务结束没有 remove;下一个请求复用到同一 worker,读到了上一个用户的权限,出现越权。修复:Filter 的
易错点:
- 认为 key 是弱引用就不会泄漏,忽略 value 的强引用。
- 认为
static final就万事大吉,不 remove。 - 线程池任务结束不清理 ThreadLocal,导致用户/trace/事务上下文串线。
- 用
InheritableThreadLocal解决线程池传递,结果读到创建时的旧值。 - 认为 ThreadLocal 的值天然线程安全,多个线程共享同一个可变对象。
- 把 ThreadLocal 当成本地缓存,value 随线程无界增长。
- 用
set(null)代替remove(),Entry 仍然留在 map 里。 - 在
CompletableFuture/parallelStream/commonPool 里直接get(),以为会自动继承。 - 虚拟线程里大量使用 ThreadLocal,忽略每线程 map 的内存放大。
- value 持有 ClassLoader、连接、大 buffer,重新部署或长时间运行后 OOM。
- 子线程修改
InheritableThreadLocal以为会影响父线程;实际只改自己的 map,但可变 value 仍可能共享。
30 秒口述稿:
ThreadLocal 是线程封闭工具,每个 Thread 有一个 ThreadLocalMap,key 是弱引用的 ThreadLocal,value 是强引用。get/set 只操作当前线程的 map,开放寻址,初始 16、阈值 2/3。内存泄漏的根源是线程池线程长活:ThreadLocal 对象被 GC 后 key 变 null,但 value 还被 Entry 强引用;所以要用 static final、finally remove。跨线程 InheritableThreadLocal 只在 new Thread 时复制,线程池里会陈旧,要用 TTL 或显式传参;虚拟线程时代可以用 ScopedValue。
- 3 分钟展开顺序:结论(线程封闭 + 弱 key/强 value)→ Thread/ThreadLocalMap/Entry 结构 → get/set/remove 与开放寻址 → 内存泄漏链路与 remove → static final 的边界 → InheritableThreadLocal 与线程池失效 → TTL/TaskDecorator/显式传参 → ThreadLocal vs synchronized → 虚拟线程与 ScopedValue → 生产案例与排查。