ThreadLocal 的原理是什么？为什么可能内存泄漏？

简化版

ThreadLocal 给每个线程一份变量的独立副本，互不干扰。数据并不存在 ThreadLocal 对象里，而是存在每个线程自己的 ThreadLocalMap 里，key 是 ThreadLocal 实例，value 是你存的值。泄漏原因：Map 的 key 是弱引用、value 是强引用，线程被复用（线程池）时没清理的 value 会一直赖着不被回收。

详细版

存储结构（这是理解一切的基础）：

Thread ──> ThreadLocalMap ──> Entry[]
                                 └─ Entry: key = ThreadLocal(弱引用), value = 你的值(强引用)

每个 Thread 对象内部有一个 threadLocals 字段，类型是 ThreadLocalMap。当你调 threadLocal.set(v)，实际是「拿到当前线程的 map，以这个 threadLocal 为 key 存 v」。所以：

每个线程一张 map，数据天然隔离——这就是「线程本地」的由来；
get() 就是从当前线程的 map 里按 this（ThreadLocal 实例）取值。

内存泄漏链路：Entry 的 key 对 ThreadLocal 是弱引用，value 对你的值是强引用。当外部对 ThreadLocal 的强引用断开后，下次 GC 会回收这个 ThreadLocal，key 变成 null，但 value 仍被线程的 map 强引用着。如果线程池工作线程长期存活，又没有后续 map 操作触发启发式清理，这条「key=null 但 value 还在」的 Entry 就可能长期占用内存。

完整版教学

一、为什么 key 要设计成弱引用

初学者常问：既然弱引用 key 反而搞出了「key=null 的僵尸 Entry」，为什么不用强引用？

反过来想：如果 key 是强引用，那么只要线程和 map 仍然存活，map 就会继续引用 ThreadLocal；即使业务代码早已不用它，也无法单独回收 key，泄漏风险会更严重。

弱引用 key 是一种补救：当 ThreadLocal 没有其他强引用时，至少 key 能被 GC 掉，配合 ThreadLocal 内部在 set/get/remove 时顺手清理 key=null 的 Entry的机制，能减轻泄漏。但它只是「减轻」，不能「根治」——因为清理是被动的，只有你再次操作这个线程的 ThreadLocal 才会触发。

二、泄漏为什么在线程池里才致命

普通线程 run() 结束就销毁，它的整个 ThreadLocalMap 随线程一起被回收，value 自然没了，没有泄漏问题。

但线程池的线程是复用的、长期存活的。一个请求在线程 A 上 set 了用户上下文，处理完没 remove，线程 A 被还回池里、下次处理别的请求——那份旧 value 还在 A 的 map 里：

内存泄漏：value 一直不被回收，累积起来吃内存；
更严重的是数据串了：下个请求如果读到上个请求残留的用户上下文，会发生越权、串号这类安全事故。

在线程池复用场景，应把「在 finally 中执行 remove()」作为工程硬约束，同时防止内存滞留和跨任务数据污染。

三、正确用法：try-finally + remove

private static final ThreadLocal<User> CTX = new ThreadLocal<>();

void handle(Request req) {
    CTX.set(resolveUser(req));
    try {
        doBusiness();        // 业务中随处可 CTX.get()
    } finally {
        CTX.remove();        // 铁律：finally 里清理，防泄漏也防串号
    }
}

remove() 会把当前线程 map 里这个 key 对应的 Entry 整个删掉，value 立即可回收。

四、典型用途

用户上下文/请求链路：TraceId、登录用户，跨方法传递不用层层加参数；
非线程安全对象的每线程副本：经典是 SimpleDateFormat（线程不安全），每线程一个避免加锁；
数据库连接/事务：Spring 的事务管理就用 ThreadLocal 把 Connection 绑定到当前线程。

五、哈希槽和惰性清理为什么重要

每个 Thread 持有自己的 ThreadLocalMap，Entry 的 key 是 ThreadLocal 弱引用，value 是普通强引用。ThreadLocal 使用专门的哈希增量减少相邻实例落在同一槽位的概率；发生冲突时采用开放寻址探测，而不是 HashMap 的链表/红黑树。

Thread (GC Root)
  └─ ThreadLocalMap
       ├─ Entry[slot 3]: weak key → value A
       └─ Entry[slot 7]: key=null  → value B（stale entry）

Map 会在 get/set/remove 等操作中顺带扫描和清理 stale entry，但它不是持续运行的后台清洁器。线程长期不再操作相关区域时，null key 对应 value 仍可能一直被线程强引用。

六、用线程池复用算一遍风险

假设固定池有 50 个工作线程，每个请求向 ThreadLocal 放入平均 2 MB 的上下文，又遗漏 remove。最坏情况下每个线程保留最近一次 value，仅这一项就可能约占 50 × 2 MB = 100 MB；如果 Map 中还有多个 stale 槽位，占用会更高。

更危险的是数据串用：请求 A 在线程 worker-7 写入 userId=1001 后未清理，请求 B 恰好复用 worker-7 且错误地先读取，就可能把 A 的身份带入 B。ThreadLocal 问题因此既是内存风险，也是安全与隔离风险。

try {
    USER_CONTEXT.set(context);
    handle();
} finally {
    USER_CONTEXT.remove();
}

记忆钩子：弱引用只让 key 有机会消失，真正决定 value 何时断链的是 Map 清理、显式 remove 或线程结束；在线程池里最可靠的是 finally remove。

七、InheritableThreadLocal、虚拟线程与 ScopedValue 边界

InheritableThreadLocal 在线程创建时复制父线程可继承值，不适合把动态请求上下文传播到预先创建并复用的线程池。线程池工作线程通常早已存在，提交任务时不会重新发生“子线程创建”。

虚拟线程常采用一任务一线程，能减少池复用导致的串数据，但大量 ThreadLocal 值仍会增加内存占用。现代 JDK 的 ScopedValue 适合在线程调用范围内传递只读上下文，并让绑定拥有由代码块界定的有界动态作用域；是否采用要绑定目标 JDK 与框架支持，不能仅为追新而替换所有 ThreadLocal。

机制	传播/作用域	主要风险或边界
ThreadLocal	当前线程，显式 set/remove	池化线程残留、可变状态
InheritableThreadLocal	创建子线程时复制	不匹配线程池任务提交时机
ScopedValue	代码块界定的有界动态作用域绑定	JDK 25 正式，旧版兼容性需评估

八、常见误区与追问

误区：ThreadLocal 把数据存放在 ThreadLocal 对象内部。 数据实际位于当前 Thread 的 ThreadLocalMap，ThreadLocal 主要充当 key 和访问入口。
误区：key 是弱引用就彻底不会内存泄漏。 key 清除后 value 仍被 Entry 强引用，要等惰性清理、remove 或线程结束。
误区：把 ThreadLocal 声明成 static 就不必清理。 static 只让 key 更稳定，value 仍会在线程间复用并可能串数据。
追问：为什么必须在 finally 调用 remove？ 业务异常也要清理；否则当前工作线程回池后仍保留上个任务的值。
追问：ThreadLocalMap 为什么不用普通 HashMap？ 它针对弱 key、开放寻址和 stale entry 清理做了专门设计，并且只由所属线程访问。
追问：InheritableThreadLocal 为什么在线程池中不可靠？ 继承发生在线程创建时，不是每次提交任务时。
追问：ThreadLocal 一定线程安全吗？ 它隔离了每线程槽位，但 value 若指向同一个共享可变对象，那个对象仍需同步。

九、加强记忆

ThreadLocal 的引用链要从线程画起：Thread 强引用 ThreadLocalMap，Entry 弱引用 key、强引用 value，因此 key 消失并不等于 value 立即释放。get/set/remove 的惰性清理只能降低风险，长寿命线程池里必须用 try-finally remove，同时防止身份、事务等上下文串到下一请求。InheritableThreadLocal 只在线程创建时复制，不能自动解决池化任务传播；虚拟线程减少复用但不消除上下文内存成本。记住“数据在线程里、key 弱 value 强、用完 finally 清”，就抓住了实现和故障根因。

简化版

详细版