ThreadLocal：值挂在线程上，线程不死，值就不走

• 层层传参：placeOrder(userId, traceId, tenantId, …)，每加一个上下文字段就要改一串方法签名；中间夹着框架代码（AOP、MyBatis 拦截器、日志 Appender）时，参数根本传不进去。
• 自己建 static Map<Thread, Long>：所有线程抢同一张表，要用 ConcurrentHashMap；表强引用着 Thread 对象，线程结束了也不会自动删；请求结束忘了删，照样串号。
• 缺的那一块：每个线程自己的一格存储，只有本线程读写，不用加锁。这就是 ThreadLocal。它省掉了锁和参数，但没有省掉“用完要删”这件事。

不懂这一点时的典型误用：把 ThreadLocal 当成“线程安全的全局变量”，只 set 不 remove，还觉得“请求结束了，值自然就没了”。实测 2 个线程的池子，先来两个登录用户，再来 4 个不带头的请求，4 个全部读到了前一个用户的号（⑤）。

选择规则：能传参就传参；要穿过框架代码时用 ThreadLocal，但 set 和 remove 必须成对；要跨到线程池里，用包装器显式带过去（⑥第三圈）；JDK 25 起新代码可以考虑 ScopedValue。本页学 ThreadLocal 本身，以及它怎么泄漏。

ThreadLocal 还有第二种用法：给每个线程一份线程不安全的对象，比如 ThreadLocal.withInitial(() -> new SimpleDateFormat(…))。机制一样，坑也一样，只是这种通常不用清（值不属于某个请求）。

④-1引用链：key 是弱的，value 是强的

• 1key 弱：ThreadLocal 对象没人用了（比如它是某个请求对象的字段），GC 能回收它，表里那格的 key 变成 null，成了“能认出来的垃圾”。
• 2value 强：value 只有表里这一条引用。它要等这一格被清理（④-3）、被 remove()，或者线程死掉（Thread.exit() 把 threadLocals 置 null）才会被放开。
• 3线程池让第三条几乎不成立：Tomcat 的 exec 线程、业务线程池的线程跟进程同寿。所以在服务端代码里，“线程结束就没了”不能当清理手段。

④-2两种坏事：串号和泄漏

串号比泄漏更常见，也更危险：它不报错，只是把数据写错人。弱引用只跟泄漏 ② 有关；另外三种它都管不着。

④-3清理是“顺手”的：动手看 ThreadLocalMap

key 变成 null 以后，表并不会马上知道。JDK 17 的源码注释原话是：没有用引用队列，所以过期条目只有在表快满的时候才保证会被清掉（“stale entries are guaranteed to be removed only when the table starts running out of space”）。平时只在这几个时候顺手清：

• 1get() 没在第一格命中、往后探测时，遇到 key 为 null 的格子就清（expungeStaleEntry，顺带把后面的条目往前挪）。第一格就命中时什么都不清。
• 2set() 放进新条目后，往后扫 log₂(条目数) 格（cleanSomeSlots）；扫到一个过期的，就把扫描次数重置成 log₂(表长) 继续扫。
• 3条目数到了表长的 2/3：先全表清一遍（expungeStaleEntries），剩下的还多才扩容。
• 4remove()：清掉这一格，再顺着往后清一段。这是唯一确定的清理。

模拟逻辑是 JDK 17 ThreadLocalMap 的 set、getEntry、remove、replaceStaleEntry、expungeStaleEntry、cleanSomeSlots、rehash、resize 逐行翻译，在 node 里跑过。真实 JVM 里 GC 什么时候来由堆决定，这里由你点。

④-4为什么这样设计：弱 key、强 value、不用引用队列

决定胜负的约束：get 要快、表只属于一个线程、key 几乎从不过期。所以 JDK 把弱引用当成兜底，把“及时清”交还给使用者：remove()。（源码注释只写了“不用引用队列”；右边几条是按这个约束推出来的，不是源码原话。）

public final class UserContext {
  private static final ThreadLocal<Long> USER = new ThreadLocal<>();   // static final：全进程一个 key
  public static Long get()        { return USER.get(); }
  public static void set(Long id) { USER.set(id); }
  public static void clear()      { USER.remove(); }
}

// 过滤器（全景第 3 站和第 11 站）：set 和 remove 在同一层，用 finally 配对
UserContext.set(parseHeader(req));          // 没头也 set（null），不留上一个请求的值
try {
  chain.doFilter(req, resp);
} finally {
  UserContext.clear();
}

ThreadLocal<DateTimeFormatter> f = ThreadLocal.withInitial(() -> …);   // 第一次 get 时建

跨线程怎么带（InheritableThreadLocal、TTL、TaskDecorator）、Tomcat 的类加载器泄漏、虚拟线程和 ScopedValue，放到第⑥步。

实验 1：2 个 exec 线程，先来两个登录用户，再来 4 个不带头的请求

$ java -cp … Mixup
请求 1  头 X-User=1024  线程 exec-1  下单用户=1024
请求 2  头 X-User=2048  线程 exec-2  下单用户=2048
请求 3  头 X-User=null  线程 exec-1  下单用户=1024  <-- 串号！
请求 4  头 X-User=null  线程 exec-2  下单用户=2048  <-- 串号！
请求 5  头 X-User=null  线程 exec-1  下单用户=1024  <-- 串号！
请求 6  头 X-User=null  线程 exec-2  下单用户=2048  <-- 串号！

$ java -cp … Mixup remove        # finally 里 USER.remove()
请求 3  头 X-User=null  线程 exec-1  下单用户=null
请求 4 … 请求 6                      下单用户=null

• 1串号跟着线程走：exec-1 上的请求都读到 1024，exec-2 上的都读到 2048。真实的 Tomcat 有几十个线程，哪个请求落到哪个线程上是随机的，所以这个 bug 时有时无，很难复现。
• 2加一行 finally { USER.remove(); } 就全对了。也可以在入口无条件 set（没头就 set null），两样都做最稳。

实验 2：池里 1 个线程，跑 200 个请求，每个请求往 ThreadLocal 里放 1 MB

$ java -Xmx512m --add-opens java.base/java.lang=ALL-UNNAMED -cp … Leak perobj 200
模式 perobj，200 个请求跑完                 # 每个请求 new 一个 ThreadLocal，不 remove
  [请求刚结束]       表长 128，活条目 22（22 MB），key=null 的条目 0
  [Full GC 之后]     表长 128，活条目 2（0 MB），key=null 的条目 22（还挂着 22 MB）
  [再来一次 set 之后] 表长 128，活条目 2（0 MB），key=null 的条目 20（还挂着 20 MB）

$ java … Leak static 200               # static ThreadLocal，不 remove
  [Full GC 之后]     表长 16，活条目 3（1 MB），key=null 的条目 0

$ java … Leak remove 200               # 每个请求 new 一个，finally remove
  [Full GC 之后]     表长 16，活条目 1（0 MB），key=null 的条目 0

• 1弱引用只救了 key：Full GC 后 22 个 key 全变成 null，22 MB 一个字节都没少。再来一次 set，cleanSomeSlots 只扫几格，清掉 2 个。
• 2泄漏有上限，但上限没人说得准：取决于 GC 什么时候来、新的 set 碰巧扫到哪几格。三次分别是 22、29、41 MB。线程池里有 200 个线程，就要乘 200。
• 3堆比开始时多占了约 2 倍（44～82 MB），因为 G1 这里的 region 是 1 MB，1 MB 的数组加上对象头放不进一个 region，按“大对象”占了两个。

• TransmittableThreadLocal 源码：capture / replay / restore 怎么做到不串号，Java Agent 怎么包住 JDK 线程池
• 用 MAT 打开堆转储，从 Thread → threadLocals 找到泄漏的 value（J14 线上排障）
• Netty 的 FastThreadLocal：用数组下标代替哈希探测，为什么更快、什么时候反而更费内存
• ScopedValue 加 StructuredTaskScope：虚拟线程时代的上下文传递（第 9 个知识点）
• 在 Tomcat 里复现一次重新部署的类加载器泄漏，看 Metaspace 和那条 SEVERE 日志

自测