Skip to content

ThreadLocal ​

[TOC]

概述 ​

Servlet 单例多线程痛点 ​

Tomcat 等 Servlet 容器默认以单例多线程模式运行:每个 Servlet 类在容器内通常只创建一个实例,当多个客户端并发发起 HTTP 请求时,容器从线程池分配不同的工作线程并行执行同一个 Servlet 实例的 service、doGet 或 doPost 方法。

在这一模型下,跨方法共享单次请求的状态数据会面临两类典型问题:

  1. 成员变量线程不安全:若将当前登录用户、请求追踪 ID(TraceId)或数据库连接等请求级状态保存在 Servlet 的实例成员变量中,多个工作线程会并发读写同一份内存,直接引发数据覆盖与脏读。

  2. 显式参数透传污染签名:若为了避免共享可变状态,将 HttpServletRequest、用户上下文或数据库连接作为方法参数,从 Servlet 逐层传递到 Service 再传递到 DAO,会导致所有中间层方法签名充斥与核心业务无关的基础设施参数,显著增加层间耦合度。

ThreadLocal ​

ThreadLocal 是 java.lang 包提供的线程局部变量工具类,核心设计思想是线程封闭(Thread Confinement):为每个访问该变量的线程提供一份独立的数据副本,使各线程只能读写属于自己的那一份数据,从而在不引入锁竞争的前提下实现线程安全。

在同步阻塞的 Servlet 请求处理模型中,一个 HTTP 请求从进入容器、经过 Filter 拦截、Servlet 分发、调用 Service 与 DAO,直到返回响应,整条调用链默认由同一个 Tomcat 工作线程串行执行。借助 ThreadLocal,只需在请求入口将上下文数据绑定到当前线程,下游任意深度的调用栈都可以直接读取该数据,既消除了多线程竞态,又避免了冗长的参数透传。

image-20261120105814469

需要区分的是,ThreadLocal 本身并不直接存储业务对象,而是作为访问当前线程内部存储容器(ThreadLocalMap)的凭证键,其底层数据结构与散列读写细节将在后续章节展开。

ThreadLocal 与 synchronized 对比 ​

ThreadLocal 与 synchronized 都能解决多线程并发访问下的状态安全问题,但二者的设计思路与适用边界截然不同:

对比维度ThreadLocalsynchronized
核心思路线程封闭,每个线程持有独立副本,消除共享互斥同步,多线程串行访问同一份共享资源
资源权衡以空间换时间,每个线程维护独立数据副本以时间换空间,线程竞争锁时发生阻塞与切换
并发性能无锁操作,高并发读场景下开销极低锁竞争激烈时会引发线程阻塞与上下文切换
数据可见性数据仅对当前线程可见,天然隔离释放锁后对其他线程可见,用于线程间通信与协作
典型用途请求上下文传递、事务连接绑定、非线程安全工具隔离共享计数器、库存扣减、单例延迟初始化等临界区保护

在 Servlet 作用域体系中,ThreadLocal 同样不同于 HttpServletRequest 属性与 HttpSession:

  • HttpServletRequest 属性:绑定于单次请求对象,脱离 Web 层后(如 Service、DAO)如果不显式传递 req 引用便无法直接访问。
  • HttpSession:绑定于浏览器会话,跨多个 HTTP 请求持久存在,服务于会话级状态而非单次请求调用栈。
  • ThreadLocal:绑定于当前执行线程,天然穿透 Filter -> Servlet -> Service -> DAO 完整调用链,但必须随请求结束及时清理,否则会在容器线程池复用时引发跨请求数据污染。

典型应用场景 ​

跨层请求上下文传递 ​

在认证鉴权、操作审计与全链路日志追踪场景中,通常在请求进入 Filter 或 Servlet 时解析当前登录用户信息、客户端 IP 或 TraceId 并写入 ThreadLocal。后续的业务校验、数据权限过滤和日志打印组件均可随时获取当前请求上下文,无需修改中间方法签名。

JDBC 事务连接绑定 ​

当一次业务请求涉及多个 DAO 方法协同操作数据库并需要纳入同一个事务时,这些 DAO 必须共享同一个 java.sql.Connection 实例。将从连接池获取的 Connection 绑定到当前线程的 ThreadLocal 后,业务层开启、提交或回滚事务,底层各 DAO 统一从 ThreadLocal 取出同一条连接执行 SQL,从而在不向业务接口暴露 JDBC 连接对象的前提下保证事务一致性。

非线程安全对象隔离 ​

部分 JDK 或第三方工具类(如 SimpleDateFormat)内部维护了可变的日历状态字段,多线程并发复用同一实例会抛出异常或产生错误解析结果,而每次请求都 new 一个新实例又会带来额外的 GC 压力。通过 ThreadLocal.withInitial 为每个工作线程延迟初始化一个专属实例,既能保证线程安全,又能在线程池生命周期内复用对象。

示例: 请求上下文基础读写 ​

在实际开发中,通常将 ThreadLocal 封装在独立的上下文工具类中,并声明为 private static final,统一收敛读写与清理入口:

java
// 1. 声明静态常量 ThreadLocal 容器,供同一线程在任意调用层存取当前用户标识
public class UserContext {

  private static final ThreadLocal<String> USER_HOLDER = new ThreadLocal<>();

  // 2. 将当前请求的用户标识绑定到当前工作线程
  public static void setUser(String userId) {
    USER_HOLDER.set(userId);
  }

  // 3. 获取当前工作线程绑定的用户标识
  public static String getUser() {
    return USER_HOLDER.get();
  }

  // 4. 主动清除当前线程绑定的数据,防止容器线程复用时发生数据残留
  public static void clear() {
    USER_HOLDER.remove();
  }
}

在 Servlet 中写入上下文后,下游 OrderService 即可直接读取当前请求对应的用户标识;无论业务逻辑是否抛出异常,都必须在 finally 代码块中调用清理方法释放当前线程绑定的数据:

java
@WebServlet("/order")
public class OrderServlet extends HttpServlet {

  private final OrderService orderService = new OrderService();

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 1. 从请求中解析当前登录用户并写入 ThreadLocal
    String userId = req.getHeader("X-User-Id");
    UserContext.setUser(userId);

    try {
      // 2. 调用业务层,无需在方法参数中显式传递 userId
      String result = orderService.createOrder();
      resp.getWriter().write(result);
    } finally {
      // 3. 请求结束前必须在 finally 块中清理上下文,避免污染复用线程
      UserContext.clear();
    }
  }
}

public class OrderService {

  // 4. 在同一处理线程的下游调用栈中直接读取上下文数据
  public String createOrder() {
    String currentUser = UserContext.getUser();
    return "Order created for user: " + currentUser;
  }
}

上述写法展示了单 Servlet 内的基础用法。在包含多个 Servlet 的完整 Web 项目中,通常将写入与清理逻辑进一步下沉至统一的 Filter 或 ServletRequestListener 中管理,具体工程实践将在「6. Servlet 请求上下文管理」与「7. Servlet 线程池复用污染」章节中展开。

API: ThreadLocal ​

构造方法 ​

  • ThreadLocal ThreadLocal():(),无参构造。创建一个新的线程局部变量实例,默认初始值为 null;底层 ThreadLocalMap 采用懒加载机制,仅在当前线程首次调用 get() 或 set() 时才真正分配存储数组。

注意事项:

  1. 业务代码中应优先将 ThreadLocal 实例声明为 private static final 常量,避免在高频方法内重复创建实例导致槽位扩张与陈旧条目堆积。
java
public class ThreadLocalConstructorDemo {

  // 1. 通过无参构造方法创建线程局部变量实例,通常声明为 static final
  private static final ThreadLocal<String> REQUEST_ID = new ThreadLocal<>();

  public static void main(String[] args) {
    // 2. 新建实例在未赋值前默认返回 null
    System.out.println("默认初始值: " + REQUEST_ID.get());

    // 3. 绑定当前线程专属数据并在结束后清理
    REQUEST_ID.set("REQ-1001");
    System.out.println("绑定后的值: " + REQUEST_ID.get());
    REQUEST_ID.remove();
  }
}

初始值定制 ​

  • <S> ThreadLocal<S> ThreadLocal.withInitial():(Supplier<? extends S> supplier),函数式工厂创建。JDK 8 新增的静态工厂方法,通过 Supplier 为每个访问线程按需生成独立初始值,替代匿名子类写法;若传入的 supplier 为 null,将立即抛出 NullPointerException。

  • protected T initialValue():(),默认初始值钩子。返回当前线程首次访问该变量时的初始副本,默认实现返回 null;仅在当前线程未调用过 set() 而直接调用 get(),或调用 remove() 后再次调用 get() 时触发。

注意事项:

  1. 若当前线程先执行了 set() 写入值,再调用 get(),则不会触发 initialValue() 或 withInitial() 提供的 Supplier。
  2. 在 Tomcat 等线程池复用场景下,通过 withInitial() 创建的可变集合(如 ArrayList、HashMap)不会随每次请求自动重建;若请求结束后未调用 remove(),后续复用线程的请求会持续向同一集合追加脏数据。
java
import java.text.SimpleDateFormat;
import java.util.Date;

public class ThreadLocalInitDemo {

  // 1. 通过静态工厂方法 withInitial 为每个线程提供独立的 SimpleDateFormat 实例
  private static final ThreadLocal<SimpleDateFormat> DATE_FORMAT =
      ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

  // 2. 通过匿名子类重写 initialValue 定制默认初始值
  private static final ThreadLocal<String> DEFAULT_ROLE =
      new ThreadLocal<String>() {
        @Override
        protected String initialValue() {
          return "GUEST";
        }
      };

  public static void main(String[] args) {
    // 3. 首次调用 get 时分别触发 withInitial 与 initialValue 生成线程专属副本
    System.out.println("格式化日期: " + DATE_FORMAT.get().format(new Date()));
    System.out.println("默认角色: " + DEFAULT_ROLE.get());

    DATE_FORMAT.remove();
    DEFAULT_ROLE.remove();
  }
}

副本操作 ​

  • T get():(),读取当前线程副本。返回当前线程在自身 ThreadLocalMap 中保存的变量副本;若当前线程尚未建立映射条目,则自动触发 initialValue() 计算并写入初始值后再返回。

  • void set():(T value),写入当前线程副本。将指定值绑定到当前线程的 ThreadLocalMap 中;若对应槽位已存在当前键则原地覆盖旧值,同时顺带执行陈旧条目清理。

  • void remove():(),移除当前线程副本。清除当前线程 ThreadLocalMap 中该键对应的 Entry 槽位与值引用,并重排后续连续探测段;在线程池复用环境中必须在任务结束的 finally 块内显式调用,防止内存泄漏与跨请求数据污染。

注意事项:

  1. set(null) 与 remove() 语义完全不同:set(null) 仍会在 ThreadLocalMap 中保留 Entry 槽位(且后续 get() 直接返回 null 而不再触发 initialValue()),清理现场必须显式调用 remove()。
  2. 调用 remove() 清空条目后,若同一线程再次调用 get(),将会重新执行一次 initialValue() 生成新副本。
java
public class ThreadLocalAccessDemo {

  private static final ThreadLocal<String> USER_HOLDER =
      ThreadLocal.withInitial(() -> "ANONYMOUS");

  public static void main(String[] args) throws InterruptedException {
    // 1. 主线程写入用户标识,演示单线程内的读取与覆盖行为
    USER_HOLDER.set("admin");
    System.out.println("主线程读取: " + USER_HOLDER.get());

    // 2. 启动独立子线程验证线程隔离性,未写入时读取到自身初始值
    Thread worker = new Thread(() -> {
      try {
        System.out.println("工作线程初始读取: " + USER_HOLDER.get());
        USER_HOLDER.set("alice");
        System.out.println("工作线程写入后读取: " + USER_HOLDER.get());
      } finally {
        // 3. 线程任务结束前在 finally 中执行 remove,释放底层 Entry
        USER_HOLDER.remove();
      }
    });
    worker.start();
    worker.join();

    // 4. 主线程调用 remove 后再次 get,会重新触发初始值计算
    USER_HOLDER.remove();
    System.out.println("主线程清理后重读: " + USER_HOLDER.get());
    USER_HOLDER.remove();
  }
}

API: InheritableThreadLocal【待补充】 ​

API: WeakReference【待补充】 ​

API: Filter【待补充】 ​

API: ServletRequestListener【待补充】 ​

API: AsyncContext【待补充】 ​

ThreadLocalMap 存储结构 ​

数据归属设计 ​

初次接触 ThreadLocal 时,容易产生一种直觉误区:认为每个 ThreadLocal 实例内部维护了一张以 Thread 为键的 Map<Thread, T>。JDK 早期版本(JDK 1.3)确实曾采用过这一方案,但从 JDK 1.5 起改为由 Thread 自身持有 ThreadLocalMap,以 ThreadLocal 实例作为键。

java
// 1. Thread 类内部维护当前线程专属的 ThreadLocalMap 实例
public class Thread implements Runnable {
  ThreadLocal.ThreadLocalMap threadLocals = null;

  // 2. 用于父子线程数据传递的继承表,在后续章节展开
  ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;
}

public class ThreadLocal<T> {
  // 3. 读写操作先获取当前线程,再读取该线程持有的 threadLocals
  ThreadLocalMap getMap(Thread t) {
    return t.threadLocals;
  }

  // 4. 首次写入时懒加载创建 ThreadLocalMap 并挂载到当前线程
  void createMap(Thread t, T firstValue) {
    t.threadLocals = new ThreadLocalMap(this, firstValue);
  }
}

在这种反转归属的结构下,ThreadLocal 本身不存储任何业务数据,仅充当访问当前线程 threadLocals 容器的定位键。这一设计带来了三项核心收益:

  1. 彻底消除锁竞争:每个线程只访问自己的 threadLocals 字段,不存在多线程并发修改同一张散列表的情况,读写全程无锁。

  2. 大幅缩减单表规模:服务端并发线程数通常远大于 ThreadLocal 变量的数量。将映射表下沉到线程对象后,每张表的元素数量由“活跃线程数”降为“当前线程使用的 ThreadLocal 变量数”,显著降低哈希冲突概率与扩容频率。

  3. 随线程销毁自动回收:非线程池场景下,当线程执行完毕被垃圾回收时,其持有的 threadLocals 与表内所有数据会一并失去可达性而被回收,无需再从全局 Map 中逐个摘除已消亡线程的条目。

image-20261120105837729

ThreadLocalMap ​

ThreadLocalMap 是 ThreadLocal 的包级私有静态内部类(static class ThreadLocalMap),是一个专为线程局部变量定制的轻量级哈希表,并未实现 java.util.Map 接口。

java
static class ThreadLocalMap {

  // 1. 初始数组容量固定为 16,且扩容后始终保持为 2 的幂次方
  private static final int INITIAL_CAPACITY = 16;

  // 2. 底层连续数组,直接存储 Entry 节点而不挂载链表或红黑树
  private Entry[] table;

  // 3. 当前数组中实际存储的 Entry 数量
  private int size = 0;

  // 4. 扩容阈值,固定为数组长度的 2/3
  private int threshold;

  private void setThreshold(int len) {
    threshold = len * 2 / 3;
  }

  // 5. 懒加载构造:首次调用 set 时才初始化容量为 16 的数组
  ThreadLocalMap(ThreadLocal<?> firstKey, Object firstValue) {
    table = new Entry[INITIAL_CAPACITY];
    int i = firstKey.threadLocalHashCode & (INITIAL_CAPACITY - 1);
    table[i] = new Entry(firstKey, firstValue);
    size = 1;
    setThreshold(INITIAL_CAPACITY);
  }
}

ThreadLocalMap 的存储布局与扩容策略有三个关键特征:

  • 懒加载初始化:创建 Thread 对象时,threadLocals 默认为 null;只有该线程首次向 ThreadLocal 写入数据(或触发初始化默认值)时,才会分配容量为 16 的 Entry[] 数组,避免未使用的线程浪费堆内存。
  • 开放寻址法(线性探测):与 HashMap 的“数组 + 链表/红黑树”拉链法不同,ThreadLocalMap 底层仅有一个连续数组 Entry[] table。当目标槽位发生哈希冲突时,直接向后顺延探测下一个空闲槽位,既省去了链表指针的额外内存开销,又提升了 CPU 缓存行局部性。
  • 更保守的负载因子(2/3):开放寻址法在数组接近满载时容易出现元素扎堆(聚集效应),导致探测步长急剧增加。因此 ThreadLocalMap 将阈值设为数组长度的 23\frac{2}{3}(约 0.667),比 HashMap 的 0.75 更早触发清理与扩容,以保持充足的空闲槽位。

Entry ​

ThreadLocalMap 数组中的每个元素都是一个 Entry 实例。Entry 是 ThreadLocalMap 的静态内部类,继承自 WeakReference<ThreadLocal<?>>:

java
// 1. Entry 继承 WeakReference,使 Key 成为指向 ThreadLocal 的弱引用
static class Entry extends WeakReference<ThreadLocal<?>> {

  // 2. Value 仍由 Entry 以强引用方式直接持有
  Object value;

  Entry(ThreadLocal<?> k, Object v) {
    // 3. 将 ThreadLocal 实例交由父类 WeakReference 的 referent 字段管理
    super(k);
    value = v;
  }
}

从对象引用拓扑来看,Entry 对 Key 与 Value 采取了不对称的引用策略:

  • Key(弱引用):通过 super(k) 将 ThreadLocal 实例绑定到 Reference 基类的 referent 字段。当外部业务代码不再持有该 ThreadLocal 的强引用时,下一次 GC 会直接回收该 ThreadLocal 对象,此时 Entry 内部调用 get() 返回 null,该槽位即变为陈旧条目(Stale Entry)。
  • Value(强引用):Entry 通过普通字段 Object value 强引用业务数据对象。在外部对象仍存活或线程池线程长期复用的场景下,即使 Key 已被回收,Value 依然可能通过 Thread -> threadLocals -> table -> Entry -> value 这条强引用链滞留在堆内存中。关于该不对称引用引发的内存泄漏成因与回收策略,将在「4. 弱引用内存泄漏问题」中完整剖析。

斐波那契散列 ​

由于 ThreadLocalMap 采用开放寻址法,哈希函数的分布均匀性直接决定了冲突率与探测开销。ThreadLocal 并未复用 Object.hashCode(),而是采用基于黄金分割比的斐波那契散列(Fibonacci Hashing)为每个 ThreadLocal 实例分配专属散列码:

java
public class ThreadLocal<T> {

  // 1. 每个 ThreadLocal 实例在创建时分配不可变的专属散列码
  private final int threadLocalHashCode = nextHashCode();

  // 2. 全局原子计数器,保证多线程并发创建 ThreadLocal 时散列码不重复
  private static AtomicInteger nextHashCode = new AtomicInteger();

  // 3. 斐波那契散列增量,使连续实例在 2 的幂次容量数组中近似均匀分布
  private static final int HASH_INCREMENT = 0x61c88647;

  // 4. 每次实例化时以固定步长递增生成下一个散列码
  private static int nextHashCode() {
    return nextHashCode.getAndAdd(HASH_INCREMENT);
  }
}

魔数 0x61c88647(十进制 1640531527)来源于黄金分割比例:

HASH_INCREMENT=⌊232×(1−5−12)⌋≈1640531527=0x61c88647\text{HASH\_INCREMENT} = \left\lfloor 2^{32} \times \left(1 - \frac{\sqrt{5} - 1}{2}\right) \right\rfloor \approx 1640531527 = \text{0x61c88647}

在计算槽位下标时,ThreadLocalMap 利用数组长度恒为 2n2^n 的特性,通过位运算 key.threadLocalHashCode & (len - 1) 替代取模运算 % len。由于 0x61c88647 是奇数,与任意 2n2^n 互质,且其步长符合黄金分割分布,连续创建的 ThreadLocal 实例在映射到数组槽位时会呈现出极佳的均匀散列效果。

以初始容量 16 为例,连续创建 16 个 ThreadLocal 实例(散列码依次为 0、1 * 0x61c88647、…、15 * 0x61c88647),执行 & 15 后的槽位分布依次为:

0 -> 7 -> 14 -> 5 -> 12 -> 3 -> 10 -> 1 -> 8 -> 15 -> 6 -> 13 -> 4 -> 11 -> 2 -> 9

在填满整个容量为 16 的数组之前,16 个连续创建的实例恰好无冲突地落入全部 16 个不同槽位,最大限度地减少了线性探测的步长。

image-20261120105904766

ThreadLocalMap 与 HashMap 对比 ​

从底层结构来看,ThreadLocalMap 针对“单线程独占、元素量小、需配合 GC 回收失效 Key”的场景做了高度定制,与通用集合 HashMap 在多处设计上存在显著差异:

对比维度ThreadLocalMapHashMap
接口实现独立定制内部类,不实现 Map 接口实现 java.util.Map 接口
冲突解决策略开放寻址法(线性探测),纯数组存储拉链法,数组 + 链表 + 红黑树
散列算法斐波那契散列增量 0x61c88647 累加扰动函数 (h = key.hashCode()) ^ (h >>> 16)
槽位定位threadLocalHashCode & (len - 1)(n - 1) & hash
扩容阈值数组长度的 2/3(清理陈旧条目后再判定)数组长度的 3/4(默认负载因子 0.75)
键引用类型WeakReference<ThreadLocal<?>> 弱引用强引用
Key 为 null表示 Key 已被 GC 回收的陈旧条目,待清理允许存在一个 null 键,固定落于下标 0

理解了 ThreadLocalMap 的数组布局、Entry 弱引用包装以及斐波那契散列后,下一章将进入源码层,追踪 set、getEntry、remove 与 rehash 如何在开放寻址数组上完成线性探测读写与陈旧条目清理。

线性探测读写源码 ​

环形索引步进 ​

由于 ThreadLocalMap 采用基于连续数组 Entry[] table 的开放寻址法,发生哈希冲突时不再外挂链表,而是将底层数组逻辑上视作一个首尾相接的环形数组。当探测指针越过数组边界时,自动回绕到另一端继续搜索:

java
// 1. 向后步进一格,越过数组末尾时回绕到下标 0
private static int nextIndex(int i, int len) {
  return ((i + 1 < len) ? i + 1 : 0);
}

// 2. 向前步进一格,越过下标 0 时回绕到数组末尾
private static int prevIndex(int i, int len) {
  return ((i - 1 >= 0) ? i - 1 : len - 1);
}

开放寻址数组中,任意两个相邻 null 空槽之间紧密排列的非空 Entry 构成一个连续探测段(Run)。ThreadLocalMap 的全部读、写、删操作都依赖一个核心不变式:只要目标 key 存在于表中,从它的理想散列槽位 i = key.threadLocalHashCode & (len - 1) 出发向后线性探测,必定能在遇到第一个 null 槽位之前命中它。理解这一不变式,就能看懂后续陈旧槽位替换与重哈希清理的全部设计动机。

写入探测流程 ​

外部调用 ThreadLocal.set(T value) 时,先获取当前线程对应的 ThreadLocalMap;若该线程尚未初始化映射表,则调用 createMap 懒加载创建容量为 16 的 Entry[],否则直接委派给 ThreadLocalMap.set 执行线性探测写入。

线性探测写入 ​

java
private void set(ThreadLocal<?> key, Object value) {
  Entry[] tab = table;
  int len = tab.length;
  // 1. 通过位运算定位当前 key 的理想散列槽位
  int i = key.threadLocalHashCode & (len - 1);

  // 2. 从槽位 i 开始向后线性探测,直到遇到首个空槽位结束
  for (Entry e = tab[i]; e != null; e = tab[i = nextIndex(i, len)]) {
    ThreadLocal<?> k = e.get();

    // 3. 命中相同 key,直接覆盖旧值并返回
    if (k == key) {
      e.value = value;
      return;
    }

    // 4. 探测途中遇到 key 已被 GC 回收的陈旧条目,进入替换与清理流程
    if (k == null) {
      replaceStaleEntry(key, value, i);
      return;
    }
  }

  // 5. 未命中且遇到空槽,直接插入新 Entry 并递增元素计数
  tab[i] = new Entry(key, value);
  int sz = ++size;

  // 6. 先尝试启发式清理;若未清理出任何陈旧槽位且已达 2/3 阈值,触发全量清理与扩容判定
  if (!cleanSomeSlots(i, sz) && sz >= threshold) {
    rehash();
  }
}

向后探测过程中可能出现三种分支:

  1. **命中已有 key**:原地覆盖 e.value,不改变 size,也不触发扩容。

  2. 命中陈旧槽位(k == null):不能直接覆写后返回,因为当前要写入的 key 可能早因哈希冲突被顺延保存在 i 之后的槽位中;若直接覆写会导致同一个 key 在表中出现两份重复条目,因此必须转入 replaceStaleEntry 排查。

  3. 探测至空槽(e == null):确认 key 不存在,直接在当前空槽新建 Entry 并累加 size;随后先调用 cleanSomeSlots 做一次低成本抽样清理,只有在未回收任何槽位且 size >= threshold 时才进入 rehash。

陈旧槽位替换 ​

replaceStaleEntry 的核心职责是避免重复键、复用陈旧槽位并顺带清理同一连续段内的失效条目:

java
private void replaceStaleEntry(ThreadLocal<?> key, Object value, int staleSlot) {
  Entry[] tab = table;
  int len = tab.length;
  Entry e;

  // 1. 从 staleSlot 向前扫描至空槽,记录当前连续段中最靠前的陈旧槽位下标
  int slotToExpunge = staleSlot;
  for (int i = prevIndex(staleSlot, len); (e = tab[i]) != null; i = prevIndex(i, len)) {
    if (e.get() == null) {
      slotToExpunge = i;
    }
  }

  // 2. 从 staleSlot 向后继续探测,排查目标 key 是否存在于连续段后半部分
  for (int i = nextIndex(staleSlot, len); (e = tab[i]) != null; i = nextIndex(i, len)) {
    ThreadLocal<?> k = e.get();

    // 3. 若在后方命中相同 key,更新其值并与 staleSlot 交换,使有效条目更贴近理想槽位
    if (k == key) {
      e.value = value;
      tab[i] = tab[staleSlot];
      tab[staleSlot] = e;

      // 4. 若前向扫描未发现更早的陈旧槽位,则从交换后的陈旧位置 i 开始清理
      if (slotToExpunge == staleSlot) {
        slotToExpunge = i;
      }
      cleanSomeSlots(expungeStaleEntry(slotToExpunge), len);
      return;
    }

    // 5. 前向未发现更早陈旧槽位时,记录后向探测遇到的首个陈旧槽位作为清理起点
    if (k == null && slotToExpunge == staleSlot) {
      slotToExpunge = i;
    }
  }

  // 6. 整个连续段均未命中 key,直接在 staleSlot 处断开旧值并写入新 Entry
  tab[staleSlot].value = null;
  tab[staleSlot] = new Entry(key, value);

  // 7. 若连续段中还存在其他陈旧槽位,执行连续段清理与启发式扫描
  if (slotToExpunge != staleSlot) {
    cleanSomeSlots(expungeStaleEntry(slotToExpunge), len);
  }
}

这里有两处值得留意的设计细节:

  • 前向扫描定位清理起点:slotToExpunge 初始为 staleSlot,先沿 prevIndex 扫描到当前连续段头部,以捕获藏在 staleSlot 前方的陈旧条目,确保稍后清理时能一并回收。
  • 后方命中后交换位置:若在 staleSlot 后方找到相同 key,将其更新后与 staleSlot 互换位置。这一交换既保持了开放寻址的探测顺序、缩短了后续读取的探测步长,又把陈旧条目推到了后方位置 i,随后交由 expungeStaleEntry 彻底清理。若整个连续段未找到 key,则直接用新 Entry 覆盖 staleSlot(无需递增 size);只有当段内还发现过其他陈旧槽位(slotToExpunge != staleSlot)时,才触发清理。

image-20261120105932661

读取探测流程 ​

外部调用 ThreadLocal.get() 时,若当前线程的 threadLocals 为 null,或未在表中找到对应条目,则回退到 setInitialValue() 写入初始值(默认 null,或由 withInitial 提供的默认值);若映射表已存在,则由 getEntry 执行快速路径与未命中探测:

java
private Entry getEntry(ThreadLocal<?> key) {
  // 1. 直接计算理想槽位,绝大多数无冲突读取一次数组访问即可命中
  int i = key.threadLocalHashCode & (table.length - 1);
  Entry e = table[i];

  if (e != null && e.get() == key) {
    return e;
  } else {
    // 2. 理想槽位为空或发生哈希冲突时,转入后向线性探测
    return getEntryAfterMiss(key, i, e);
  }
}

private Entry getEntryAfterMiss(ThreadLocal<?> key, int i, Entry e) {
  Entry[] tab = table;
  int len = tab.length;

  // 3. 沿连续段向后扫描,直至命中目标 key 或遇到空槽返回 null
  while (e != null) {
    ThreadLocal<?> k = e.get();
    if (k == key) {
      return e;
    }

    if (k == null) {
      // 4. 顺路清理陈旧条目并重排后方元素,下标 i 不递增以便重新检查移入当前槽的新元素
      expungeStaleEntry(i);
    } else {
      i = nextIndex(i, len);
    }
    e = tab[i];
  }
  return null;
}

读取路径体现了典型的快慢分离优化:

  1. 快路径内联:getEntry 代码极短,便于 JIT 编译器内联;配合斐波那契散列的低冲突特性,绝大多数读操作只需一次位运算与一次数组下标访问即可返回。

  2. 慢路径顺带清理:进入 getEntryAfterMiss 后,若沿途碰到 k == null 的陈旧条目,会调用 expungeStaleEntry(i) 清理并重排后续槽位。注意此时 i **不会执行 nextIndex**,因为后续原本冲突顺延的条目可能被重哈希前移回槽位 i,下一轮循环必须先检查新的 tab[i],避免漏查目标 key。

连续段清理重哈希 ​

在开放寻址哈希表中,删除或清理一个槽位时,**绝对不能仅仅执行 tab[i] = null**。假设 keyA与keyB 哈希冲突,keyA占据槽位7,keyB线性探测后落入槽位8。若直接将槽位 7置为null,下次查找 keyB时从槽位7开始探测,一见到null就会误判keyB 不存在,导致有效数据“逻辑失联”。

ThreadLocalMap 通过 expungeStaleEntry 解决这一问题,这也是 set、get、remove 三大操作共用的底层核心清理方法:

java
private int expungeStaleEntry(int staleSlot) {
  Entry[] tab = table;
  int len = tab.length;

  // 1. 清理目标陈旧槽位:主动断开 value 强引用并释放数组槽位
  tab[staleSlot].value = null;
  tab[staleSlot] = null;
  size--;

  // 2. 向后遍历直至遇到空槽,边清理沿途陈旧条目边重哈希后续有效条目
  Entry e;
  int i;
  for (i = nextIndex(staleSlot, len); (e = tab[i]) != null; i = nextIndex(i, len)) {
    ThreadLocal<?> k = e.get();
    if (k == null) {
      // 3. 顺带清除连续段内其他已失效的陈旧条目
      e.value = null;
      tab[i] = null;
      size--;
    } else {
      // 4. 重新计算有效条目的理想槽位,若不在理想位置则前移至最近的空闲槽位
      int h = k.threadLocalHashCode & (len - 1);
      if (h != i) {
        tab[i] = null;
        while (tab[h] != null) {
          h = nextIndex(h, len);
        }
        tab[h] = e;
      }
    }
  }
  return i;
}

private void remove(ThreadLocal<?> key) {
  Entry[] tab = table;
  int len = tab.length;
  int i = key.threadLocalHashCode & (len - 1);

  // 5. 定位目标 key 后先清除弱引用,再复用 expungeStaleEntry 完成回收与重排
  for (Entry e = tab[i]; e != null; e = tab[i = nextIndex(i, len)]) {
    if (e.get() == key) {
      e.clear();
      expungeStaleEntry(i);
      return;
    }
  }
}

整个连续段清理重哈希(探测式清理)的执行过程可以概括为三步:

  1. 清空起点槽位:将 tab[staleSlot].value 置 null 以解除业务对象的强引用,将 tab[staleSlot] 置 null 释放 Entry 自身,并将 size 减 1。

  2. 修复后方连续段:从 nextIndex(staleSlot, len) 开始向后遍历直到遇见空槽。沿途若再遇陈旧条目一并置空回收;若遇有效条目且其当前下标 i 不等于理想槽位 h,则先清空旧位置 tab[i],再从 h 开始向后寻找首个空槽重新安放该条目,既填补了空洞维持探测链不断裂,又缩短了后续查找距离。

  3. 统一驱动显式删除:调用 ThreadLocal.remove() 时,底层先调用 e.clear() 将 WeakReference 的 referent 置为 null(主动将其转化为陈旧条目),紧接着复用 expungeStaleEntry(i) 一次性完成 value 断开、槽位清空与连续段重排,并返回扫描结束时的空槽下标。

image-20261120105954147

扩容流程 ​

向数组插入新元素后,如果直接扫描全表清理陈旧条目,单次 set 的时间复杂度会退化为 O(n)O(n);但如果完全不清理,陈旧条目又会不断推高 size 导致无意义的数组扩容。ThreadLocalMap 采用对数级启发式清理 + 全表清理后二次判定的分级策略来平衡性能与空间:

java
private boolean cleanSomeSlots(int i, int n) {
  boolean removed = false;
  Entry[] tab = table;
  int len = tab.length;

  // 1. 以对数步长 log2(n) 抽样向后检查,兼顾清理收益与写入性能
  do {
    i = nextIndex(i, len);
    Entry e = tab[i];
    if (e != null && e.get() == null) {
      // 2. 一旦发现陈旧条目,将探测配额重置为全表长度并扩大清理范围
      n = len;
      removed = true;
      i = expungeStaleEntry(i);
    }
  } while ((n >>>= 1) != 0);
  return removed;
}

private void rehash() {
  // 3. 扩容前先执行一次全表陈旧条目清理,尽量通过回收空间避免扩容
  expungeStaleEntries();

  // 4. 清理后若仍大于等于 3/4 阈值(即数组长度的 1/2),执行 2 倍扩容
  if (size >= threshold - threshold / 4) {
    resize();
  }
}

private void resize() {
  Entry[] oldTab = table;
  int oldLen = oldTab.length;
  int newLen = oldLen * 2;
  Entry[] newTab = new Entry[newLen];
  int count = 0;

  // 5. 遍历旧表并按新容量重新散列迁移,途中顺便断开陈旧条目的 value 引用
  for (int j = 0; j < oldLen; ++j) {
    Entry e = oldTab[j];
    if (e != null) {
      ThreadLocal<?> k = e.get();
      if (k == null) {
        e.value = null;
      } else {
        int h = k.threadLocalHashCode & (newLen - 1);
        while (newTab[h] != null) {
          h = nextIndex(h, newLen);
        }
        newTab[h] = e;
        count++;
      }
    }
  }

  // 6. 更新阈值、实际计数与底层数组引用
  setThreshold(newLen);
  size = count;
  table = newTab;
}

这套分级清理与扩容机制包含三个精巧的阈值与复杂度设计:

  1. 启发式对数扫描(cleanSomeSlots):通过无符号右移 n >>>= 1 控制默认扫描次数为 ⌊log⁡2n⌋\lfloor \log_2 n \rfloor。若没有发现陈旧条目,仅以 O(log⁡n)O(\log n) 代价快速返回;一旦命中陈旧条目,说明表中可能存在成批失效数据,立刻将 n 重置为 len 扩大搜索窗口,并调用 expungeStaleEntry 清理连续段。

  2. 先清后扩的二次阈值判定(rehash):只有当启发式清理未回收任何槽位且 size >= threshold(即 len * 2 / 3)时,才会触发 rehash。它先调用 expungeStaleEntries() 扫描整张数组清空全部陈旧条目,随后以更保守的阈值判定是否真正需要扩容:

threshold−threshold4=34×(23×len)=12len\text{threshold} - \frac{\text{threshold}}{4} = \frac{3}{4} \times \left(\frac{2}{3} \times \text{len}\right) = \frac{1}{2}\text{len}

也就是说,全表清理之后只要剩余有效元素仍达到数组容量的 50%,就立刻触发扩容,防止数组在接近阈值处频繁反复触发全表扫描。

  1. 2 倍扩容与重新散列(resize):新数组容量翻倍(始终维持 2 的幂次),遍历旧表跳过空槽、顺手置空陈旧条目的 value,仅将有效条目按新掩码 newLen - 1 重新线性探测放入 newTab,最后重新计算 threshold = newLen * 2 / 3。

可以看到,ThreadLocalMap 在读、写、删、扩容的每一处源码路径中都穿插了对陈旧条目的被动清理,但这类被动清理只有在后续继续触发 ThreadLocal 操作时才有机会执行。在长生命周期的线程池线程中,若业务代码遗漏了显式清理,仍会埋下内存泄漏隐患——下一章将从引用链与 GC 行为出发,深入剖析弱引用设计与内存泄漏的完整因果链。

弱引用内存泄漏问题 ​

引用链拓扑 ​

分析 ThreadLocal 内存泄漏前,必须先厘清 JVM 堆内存与线程栈之间的对象可达性拓扑。当一个运行中的线程向 ThreadLocal 写入业务对象后,内存中同时存在两条从 GC Roots 出发的引用路径:

  1. 外部访问强引用链:栈帧局部变量 / 静态常量字段 -> ThreadLocal 实例。业务代码依靠这条引用链持有 ThreadLocal 凭证,从而能够调用 get()、set() 或 remove()。

  2. 线程内部强引用链:活跃 Thread 对象 -> ThreadLocalMap -> Entry[] table -> Entry 实例 -> Value 业务对象。只要当前线程仍处于存活状态,这条强引用链就始终可达。

连接这两条路径的桥梁是 Entry 指向 ThreadLocal 实例的键引用——正如「2. ThreadLocalMap 存储结构」所述,Entry 继承自 WeakReference<ThreadLocal<?>>,因此 Entry -> Key 是一条弱引用,而 Entry -> Value 依然是强引用。

image-20261120110015323

弱引用设计权衡 ​

围绕 Entry 的不对称引用结构,最常见的两个疑问是:为什么 Key 要设计为弱引用,而 Value 却不能同步设计为弱引用?

Key 采用弱引用的原因 ​

如果 Entry 对 Key 持有的是强引用,当业务代码将局部 ThreadLocal 置为 null 或其作用域结束时,尽管外部已经完全失去访问该 ThreadLocal 的入口,但只要当前线程尚未销毁,Thread -> ThreadLocalMap -> Entry -> Key 仍会死死拉住 ThreadLocal 实例,导致 Key 与 Value 同时无法被垃圾回收,且 ThreadLocalMap 根本无从判断这个 Key 是否已经被业务废弃。

将 Key 改为 WeakReference 后,一旦外部强引用断开,下一次 GC 会直接回收 ThreadLocal 对象,并将 Entry 继承自 Reference 的 referent 字段自动置为 null。这就为 ThreadLocalMap 留下了一个可识别的失效标记(e.get() == null),使其能在后续探测读写过程中主动识别并清理这些陈旧条目(Stale Entry)。换言之,弱引用不是引发内存泄漏的元凶,而是 JDK 为降低泄漏风险提供的兜底防线。

Value 必须保持强引用的原因 ​

Value 存放的是当前线程正在使用的业务上下文对象(例如刚构建的登录用户信息、SimpleDateFormat 实例或数据库连接包装对象)。在跨层传递场景中,入口层把对象放进 ThreadLocal 后往往就会释放局部变量引用,Entry.value 很可能是整个堆内存中指向该业务对象的唯一引用。

如果将 Value 也改为弱引用,那么在一次 HTTP 请求尚未处理完毕的中途,只要发生一次普通的 Minor GC,正在使用中的业务数据就会被瞬间回收,下游调用 get() 时会毫无征兆地读到 null,彻底破坏程序正确性。因此 Entry 只能对 Value 维持强引用。

内存泄漏成因 ​

ThreadLocal 发生实质性内存泄漏,必须同时满足两个前提条件:

  1. 线程生命周期远长于单次任务:普通短生命周期线程在执行结束后,整个 Thread 实例会脱离 GC Roots,其名下的 ThreadLocalMap、Entry 和 Value 会被整体回收,不会形成持续泄漏。但在 Tomcat 工作线程池、ExecutorService 固定线程池等场景下,核心线程会被长期复用而不销毁,线程内部的强引用链将一直存在。

  2. 业务代码未主动调用 remove() 清理:任务结束后,残留的 Entry 依然挂在复用线程的 table 数组中。

按照 ThreadLocal 变量的声明方式不同,实际工程中会出现两种截然不同的滞留形态:

局部或非静态 ThreadLocal ​

当 ThreadLocal 作为方法局部变量或短生命周期对象的成员变量创建,且任务结束前未调用 remove() 时:

java
// 1. 在方法内部动态创建局部 ThreadLocal 并写入业务对象
public void handleTemporaryContext() {
  ThreadLocal<byte[]> localHolder = new ThreadLocal<>();
  localHolder.set(new byte[1024 * 1024]);

  // 2. 方法返回后,栈帧销毁,localHolder 强引用断开
  // 下次 GC 会回收 ThreadLocal 实例,但当前线程的 Entry 仍强引用 byte[]
}

方法返回并触发 GC 后,Entry 内部的 Key 变为 null,槽位退化为 <null, byte[]> 形式的陈旧条目。由于外部已经丢失 localHolder 引用,业务代码再也无法通过常规方式读出或删除这个 byte[],只能等待该线程后续执行其他 ThreadLocal 操作时顺带将其清理。

静态常量 ThreadLocal ​

在实际 Web 开发中,ThreadLocal 绝大多数时候都会被声明为 private static final。此时类元数据区(静态字段)始终持有指向 ThreadLocal 实例的强引用,Key 永远不会被 GC 回收,弱引用机制根本不会触发。

在这种最常见的形态下,若工作线程处理完本次请求后忘记调用 remove(),线程归还线程池进入空闲状态期间,上一次请求写入的 Value(如报表导出缓冲、用户权限树、大对象上下文)会通过 Thread -> ThreadLocalMap -> Entry -> Value 持续占用堆空间,直到该线程碰巧被下一次同类请求复用并调用 set() 覆盖为止。如果线程池核心线程数较大且存在低峰期大量空闲线程,这些残留的大对象会长期占据老年代空间,甚至诱发 OOM;更严重的是,下一请求若先读后写,还会直接读到上一用户的脏数据。

被动清理局限 ​

在「3. 线性探测读写源码」中可以看到,ThreadLocalMap 在 set()(replaceStaleEntry、cleanSomeSlots、rehash)、getEntryAfterMiss() 与 remove() 中都嵌入了对陈旧条目的清理逻辑。但这种被动清理存在三项天然局限,绝不能替代显式回收:

  • 触发时机不可控:如果线程处理完大对象请求后长期处于空闲阻塞状态,或者后续执行的任务不再访问任何 ThreadLocal,清理代码永远没有机会执行。
  • 读取快路径直接跳过清理:调用 get() 读取另一个有效的 ThreadLocal 时,只要在理想槽位直接命中(e.get() == key),就会走快路径直接返回,不会进入 getEntryAfterMiss(),相邻槽位的陈旧条目不会被触及。
  • 对静态常量键完全无效:当 ThreadLocal 为 static final 时,Key 始终存活且不为 null,不会变为陈旧条目,所有基于 k == null 判定的被动清理机制都不会回收其关联的 Value。

示例: 线程池泄漏与回收 ​

下面的代码模拟了固定大小线程池(类似 Tomcat 工作线程池)中,遗漏清理与使用 try-finally 显式回收的差异:

java
// 1. 声明静态常量 ThreadLocal,模拟单次请求在线程内暂存大体积缓存数据
public class ThreadPoolLeakDemo {

  private static final ThreadLocal<byte[]> BUFFER_HOLDER = new ThreadLocal<>();

  // 2. 复用核心线程的固定线程池,模拟 Tomcat 工作线程常驻存活
  private static final ExecutorService POOL = Executors.newFixedThreadPool(4);

  // 3. 反例:任务结束后未调用 remove,核心线程持续持有大数组强引用导致内存滞留
  public static void submitWithLeak() {
    POOL.execute(() -> {
      BUFFER_HOLDER.set(new byte[1024 * 1024]);
      byte[] data = BUFFER_HOLDER.get();
      process(data);
    });
  }

  // 4. 正例:通过 try-finally 强制执行 remove,任务结束立即断开 Entry 与 value 引用
  public static void submitSafely() {
    POOL.execute(() -> {
      try {
        BUFFER_HOLDER.set(new byte[1024 * 1024]);
        byte[] data = BUFFER_HOLDER.get();
        process(data);
      } finally {
        BUFFER_HOLDER.remove();
      }
    });
  }

  private static void process(byte[] data) {
    // 模拟业务处理逻辑
  }
}

调用 BUFFER_HOLDER.remove() 后,底层不仅会清空当前键的弱引用,还会立即执行 expungeStaleEntry 将 Entry.value 与数组槽位双双置为 null 并重排连续探测段,使业务大对象在下一次 GC 时即可被确定性回收。

显式回收规范 ​

为了在并发容器环境中彻底杜绝 ThreadLocal 引发的堆内存滞留与元空间泄漏,工程实践中需遵循四项核心规范:

  1. 坚持 try-finally 成对回收:任何写入 ThreadLocal 的入口都必须配对 finally 中的 remove() 调用,确保业务代码正常返回或中途抛出未捕获异常时都能可靠释放条目。在 Servlet 应用中,应将该逻辑统一收口至全局 Filter 或 ServletRequestListener。

  2. **优先声明为 private static final**:将 ThreadLocal声明为静态常量可以避免高频重复创建实例,减少ThreadLocalMap槽位扩张与陈旧条目堆积;同时需谨记静态字段会延长 Key 的存活时间,因此必须严格依赖显式remove()释放Value。

  3. 仅存放轻量级请求元数据:避免将大体积字节数组、完整查询结果集等重型对象绑定到 ThreadLocal,只保存用户 ID、TraceId、事务连接等轻量化状态,即使发生短暂滞留也能控制内存峰值。

  4. 警惕容器热部署时的类加载器泄漏:在 Tomcat 等 Servlet 容器中,工作线程池隶属于容器级类加载器,生命周期长于单个 Web 应用。如果某个 Web 应用向工作线程的 ThreadLocal 写入了应用自定义类对象且未执行 remove(),当该应用热卸载(Undeploy)时,常驻工作线程仍通过 Entry.value -> 自定义实例 -> Class 对象 -> WebAppClassLoader 形成可达强引用链,导致整个旧版 WebAppClassLoader 及其加载的所有类元信息无法卸载,多次热部署后便会引发 Metaspace OOM。

解决了单线程内 ThreadLocal 的存储、探测与内存回收问题后,下一章将探讨多线程协作下的第一个扩展诉求:当父线程派生子线程时,如何通过 InheritableThreadLocal 实现线程局部数据的自动传递。

InheritableThreadLocal 父子线程传递 ​

跨线程上下文丢失 ​

普通 ThreadLocal 将数据严格隔离在当前线程的 threadLocals 字段中。在纯同步的 Servlet 请求链路里,整个调用栈由同一个 Tomcat 工作线程串行执行,数据可以顺畅穿透各层;但一旦业务逻辑在请求处理中途派生出新的子线程(例如异步写入操作审计日志、并行调用下游查询接口),子线程拥有全新的空白 threadLocals 字段,在子线程内部调用 get() 只能读到 null,请求上下文(如当前登录用户、TraceId)会立刻丢失。

JDK 在 java.lang 包中提供了 ThreadLocal 的子类 InheritableThreadLocal,专门用于解决父线程创建子线程时的局部变量自动继承问题。

InheritableThreadLocal ​

Thread 类内部除了维护普通线程局部变量表 threadLocals 外,还预留了一张独立的 inheritableThreadLocals 表。InheritableThreadLocal 并没有重写整套散列读写算法,而是直接复用父类 ThreadLocal 的 get、set、remove 模板流程,仅重写了三个钩子方法将底层存储目标切换至 inheritableThreadLocals:

java
// 1. 继承 ThreadLocal,仅重写三个钩子方法切换底层存储容器
public class InheritableThreadLocal<T> extends ThreadLocal<T> {

  // 2. 子线程继承父线程值时的转换钩子,默认直接返回原引用(浅拷贝)
  protected T childValue(T parentValue) {
    return parentValue;
  }

  // 3. 将读取目标从 threadLocals 切换为 inheritableThreadLocals
  ThreadLocalMap getMap(Thread t) {
    return t.inheritableThreadLocals;
  }

  // 4. 首次写入时懒加载创建并挂载到 inheritableThreadLocals 字段
  void createMap(Thread t, T firstValue) {
    t.inheritableThreadLocals = new ThreadLocalMap(this, firstValue);
  }
}

这一双表分离设计带来了一个直接结果:同一个线程可以同时使用普通 ThreadLocal 与 InheritableThreadLocal,二者分别存储在 t.threadLocals 和 t.inheritableThreadLocals 两张互不干扰的 ThreadLocalMap 中。只有写入 InheritableThreadLocal 的数据才会参与父子线程继承,避免无关的线程私有对象(如事务 Connection)被意外泄漏给子线程。

子线程创建拷贝源码 ​

父子线程的数据传递并非发生在 childThread.start() 执行任务时,而是发生在父线程调用 new Thread(...) 构造子线程对象的瞬间。在 Thread 内部初始化方法(JDK 8 中为 init,JDK 11+ 中直接位于构造逻辑)中,会主动检查当前创建者(即父线程)是否存在 inheritableThreadLocals,若存在则将其拷贝给新创建的子线程:

java
// Thread 构造方法内部(简化核心逻辑)
Thread parent = currentThread();

// 1. 创建子线程时,若允许继承且父线程存在可继承表,则立即拷贝一份副本
if (inheritThreadLocals && parent.inheritableThreadLocals != null) {
  this.inheritableThreadLocals =
      ThreadLocal.createInheritedMap(parent.inheritableThreadLocals);
}

// ThreadLocal 内部静态工厂方法
static ThreadLocalMap createInheritedMap(ThreadLocalMap parentMap) {
  return new ThreadLocalMap(parentMap);
}

// 2. ThreadLocalMap 拷贝构造方法:遍历父表并重建子线程独立数组
private ThreadLocalMap(ThreadLocalMap parentMap) {
  Entry[] parentTable = parentMap.table;
  int len = parentTable.length;
  setThreshold(len);
  table = new Entry[len];

  // 3. 逐槽位拷贝有效条目,跳过空槽与已失效的陈旧条目
  for (int j = 0; j < len; j++) {
    Entry e = parentTable[j];
    if (e != null) {
      @SuppressWarnings("unchecked")
      ThreadLocal<Object> key = (ThreadLocal<Object>) e.get();
      if (key != null) {
        // 4. 回调子类的 childValue 计算子线程初始值并封装新 Entry
        Object value = key.childValue(e.value);
        Entry c = new Entry(key, value);
        int h = key.threadLocalHashCode & (len - 1);

        // 5. 沿用线性探测解决新数组中的槽位冲突
        while (table[h] != null) {
          h = nextIndex(h, len);
        }
        table[h] = c;
        size++;
      }
    }
  }
}

整条传递链路的执行时序可以归纳为以下四个步骤:

  1. 写入父表:父线程调用 InheritableThreadLocal.set(value),通过重写后的 createMap / getMap 将数据写入 parent.inheritableThreadLocals。

  2. 构造触发拷贝:父线程执行 new Thread(runnable) 时,构造函数通过 Thread.currentThread() 拿到父线程引用,判断 parent.inheritableThreadLocals != null 后调用 ThreadLocal.createInheritedMap。

  3. 重建独立数组:拷贝构造方法为子线程分配同等长度的新 Entry[] table,遍历父表跳过 null 与 key == null 的陈旧条目,对每个有效条目调用 key.childValue(e.value) 生成新 Entry 并通过线性探测填入子表。

  4. 独立读写运行:子线程启动后,从自身的 this.inheritableThreadLocals 中直接读取继承到的值;由于父子线程各自拥有独立的 ThreadLocalMap 与 Entry 数组,子线程创建之后父线程再调用 set 或 remove,都不会同步更新已经创建好的子线程映射表。

image-20261120220750207

浅拷贝隔离边界 ​

虽然父子线程各自持有一份独立的 ThreadLocalMap,但 InheritableThreadLocal 默认的 childValue 实现直接返回了 parentValue 本身,属于对象引用的浅拷贝。这导致不同类型的业务数据在父子线程间表现出不同的隔离边界:

  • 不可变对象(如 String、Long 或只读 DTO):父子线程初始共享同一对象引用;任意一方调用 set(newValue) 时,只会替换各自 Entry 中的 value 指针,不会相互干扰,天然线程安全。
  • 可变容器或实体对象(如 HashMap、自定义可变上下文对象):父子线程的 Entry.value 指向堆内存中的同一个对象实例。如果父线程或子线程直接调用 map.put(...) 修改对象内部属性,修改结果会立刻暴露给另一方,在并发场景下还会引发 ConcurrentModificationException 或数据竞态。

若业务必须在父子线程间传递可变对象,应当继承 InheritableThreadLocal 并重写 childValue 方法执行深拷贝:

java
// 1. 重写 childValue 返回独立拷贝,避免父子线程并发修改同一个可变 Map
private static final InheritableThreadLocal> CONTEXT_MAP =
  new InheritableThreadLocal>() {
    @Override
    protected Map<String, String> childValue(Map<String, String> parentValue) {
    // 2. 构造新的 HashMap 副本实现读写隔离
    return parentValue == null ? null : new HashMap<>(parentValue);
    }
  };

线程池复用失效 ​

InheritableThreadLocal 最大的工程局限在于它只在 new Thread() 构造新线程时执行一次拷贝,因此在广泛使用线程池的服务端架构中会彻底失效,并衍生出隐蔽的脏数据缺陷:

  1. 核心线程复用跳过拷贝:Tomcat 业务代码中通常将异步任务提交给共享的 ExecutorService 线程池。当线程池首次创建核心工作线程处理请求 A 时,新线程会拷贝请求 A 的上下文快照;当请求 B 到达并向同一个线程池提交任务时,线程池直接复用已存活的旧工作线程,根本不会触发 new Thread(),请求 B 的最新上下文完全无法传递给异步任务。

  2. 残留旧请求脏快照:更危险的是,复用的工作线程内部仍残留着当初创建它时从请求 A 拷贝来的 inheritableThreadLocals。请求 B 的异步任务调用 get() 不仅拿不到 B 的数据,反而会静默读到早已结束的请求 A 的用户信息或 TraceId,引发严重的跨请求串号事故。

  3. 工程应对思路:在线程池场景下,不能依赖线程创建时的静态拷贝,而必须将上下文传递时机推迟到任务提交与执行时刻——即在提交 Runnable / Callable 前主动捕获当前线程的上下文快照,在工作线程执行目标任务前写入快照,并在 finally 块中恢复或清理工作线程现场。实际工程中既可以自行编写任务包装器,也可以引入阿里巴巴开源的 TransmittableThreadLocal(TTL)通过装饰 ExecutorService 实现无侵入的跨线程池透传。

示例: 异步任务上下文传递 ​

下面的示例直观对比了“直建子线程正常继承”与“固定线程池复用导致读到旧快照”的行为差异:

java
// 1. 声明可继承的请求追踪 ID 容器
public class InheritableDemo {

  private static final InheritableThreadLocal<String> TRACE_ID =
      new InheritableThreadLocal<>();

  private static final ExecutorService AUDIT_POOL = Executors.newFixedThreadPool(1);

  public static void main(String[] args) throws InterruptedException {
    // 2. 第一次请求:写入 TRACE-A 并提交任务,线程池首次创建唯一核心线程并拷贝 TRACE-A
    TRACE_ID.set("TRACE-A");
    AUDIT_POOL.execute(() -> System.out.println("任务1读取: " + TRACE_ID.get()));

    Thread.sleep(100);

    // 3. 第二次请求:父线程更新为 TRACE-B,但线程池复用既有线程,未触发 new Thread()
    TRACE_ID.set("TRACE-B");
    AUDIT_POOL.execute(() -> System.out.println("任务2读取: " + TRACE_ID.get()));

    // 4. 新建独立子线程会执行 Thread 构造方法,能够正常继承最新的 TRACE-B
    Thread directChild = new Thread(() -> System.out.println("直建子线程: " + TRACE_ID.get()));
    directChild.start();
    directChild.join();

    // 5. 父线程清理自身上下文并关闭演示线程池
    TRACE_ID.remove();
    AUDIT_POOL.shutdown();
  }
}

运行上述代码后,控制台将输出:

text
任务1读取: TRACE-A
任务2读取: TRACE-A
直建子线程: TRACE-B

可以看到,第二次提交给线程池的任务错误地读到了首次创建工作线程时残留的 TRACE-A。为了在线程池场景下安全传递上下文,可以对提交的 Runnable 做一层快照捕获与现场恢复包装:

java
// 1. 包装异步任务:在提交时刻捕获父线程快照,在执行前后注入并恢复子线程上下文
public static Runnable wrapWithTrace(Runnable task) {
  String snapshot = TRACE_ID.get();

  return () -> {
    // 2. 保存工作线程原有值,防止嵌套调用破坏现场
    String previous = TRACE_ID.get();
    try {
      TRACE_ID.set(snapshot);
      task.run();
    } finally {
      // 3. 任务结束后恢复现场或彻底清除,避免污染复用线程
      if (previous == null) {
        TRACE_ID.remove();
      } else {
        TRACE_ID.set(previous);
      }
    }
  };
}

借助这类“提交时捕获快照、执行前重放、结束后恢复清理”的模式,不仅能解决普通业务线程池的上下文传递问题,也是理解 Servlet 异步请求(AsyncContext)跨线程透传的核心基础。从下一章开始,我们将正式切入 Servlet 容器实战场景,探讨如何在 Web 应用中统一构建与管理请求级上下文。

Servlet 请求上下文管理 ​

上下文收敛封装 ​

在实际 Web 项目中,单次 HTTP 请求往往需要跨层透传多项上下文信息,例如当前登录用户 ID、请求追踪 ID(TraceId)、客户端 IP、租户标识以及区域语言等。如果为每一项元数据都在各自的工具类中零散声明独立的 ThreadLocal 实例,会带来三项工程隐患:

  1. 清理入口碎片化:每新增一个 ThreadLocal,就必须在请求结束处多补一行 remove(),极易在迭代过程中出现遗漏,导致部分状态残留于工作线程中。

  2. 增加槽位与冲突开销:多个分散的 ThreadLocal 会占用更多 ThreadLocalMap 数组槽位,推高哈希冲突与扩容概率。

  3. 状态一致性难以保证:分散写入时若中途抛出异常,可能出现前半部分变量已写入而后续清理未覆盖的半初始化状态。

工程上的标准做法是收敛封装:将单次请求涉及的轻量级元数据聚合为一个不可变的 RequestContext 值对象,再通过单一的 RequestContextHolder 持有唯一的 private static final ThreadLocal<RequestContext>,对外只暴露统一的绑定、读取与清空入口。

生命周期绑定入口 ​

在包含多个 Servlet 的应用中,不应把 set 与 try-finally { clear() } 重复散落在每个 Servlet 的 doGet 或 doPost 方法内。Servlet 规范提供了两类全局请求生命周期扩展点——Filter 与 ServletRequestListener,专门用于将上下文的初始化与销毁收敛至统一入口。

image-20261120220812332

Filter ​

Filter 通过围绕 chain.doFilter(request, response) 的 try-finally 块管理请求上下文:请求进入过滤链时解析 HTTP 请求头、Cookie 或 HttpSession 并写入 ThreadLocal,放行至下游过滤链与目标 Servlet,无论下游正常返回还是抛出异常,控制权回退到 finally 块时立即执行 clear()。

采用 Filter 管理上下文时需注意两项约束:

  • 必须置于过滤链最外层:日志审计、权限校验、事务管理等下游 Filter 往往依赖请求上下文,因此上下文初始化 Filter 应拥有最高执行优先级(在 web.xml 中最先配置 <filter-mapping>,或按容器加载顺序显式编排)。
  • 异常边界限于放行之后:如果排在它之前的其他 Filter 提前拦截或抛出了异常,当前 Filter 尚未介入,不会产生写入也不需要清理;但若在当前 Filter 内部先调用了 set(),后续解析或写响应头代码必须在 try 块之内,防止绑定后未进入 try 就抛出异常而跳过 finally。

ServletRequestListener ​

ServletRequestListener 是由 Servlet 容器在请求生命周期绝对最外层触发的监听器:当 HTTP 请求刚刚进入容器准备分发时,容器回调 requestInitialized(ServletRequestEvent);当所有 Filter、Servlet 执行完毕且请求即将离开容器作用域前,容器必定回调 requestDestroyed(ServletRequestEvent)。

借助 ServletRequestListener 管理上下文具备两项天然优势:

  • 覆盖全链路无排序盲区:requestInitialized 早于任意一个 Filter 执行,requestDestroyed 晚于所有 Filter 结束,能够确保整个请求处理栈(包括最外层日志与监控过滤器)均可访问上下文,也常被用作防止 Filter 遗漏清理的最终兜底防线。
  • 不受内部转发重入干扰:Servlet 规范规定,通过 RequestDispatcher.forward 或 include 发起的容器内部派发不会重新触发 requestInitialized 与 requestDestroyed,每个外部客户端请求只严格配对执行一次初始化与销毁。

不过,ServletRequestEvent 仅暴露了 ServletRequest 与 ServletContext,无法获取 HttpServletResponse,因此无法在监听器中直接回写 X-Trace-Id 等响应头,也无法像 Filter 那样在鉴权失败时直接中断请求并返回 401 或 403 响应。

入口选型对比 ​

对比维度FilterServletRequestListener
触发时机进入与离开过滤链时(受过滤链顺序影响)容器创建与销毁请求上下文的最外层边界
可访问对象HttpServletRequest、HttpServletResponse、FilterChainServletRequest、ServletContext(无响应对象)
能否中断请求支持,可跳过 chain.doFilter 直接写回错误响应不支持,仅被动响应生命周期事件
响应头回写支持(如写入 X-Trace-Id)不支持
内部转发触发默认仅 REQUEST 触发;显式配置 FORWARD 时会重入不重复触发,单次外部请求严格成对执行一次
典型职责完整上下文组装、鉴权拦截、响应头透传、事务边界管控最外层基础元数据绑定(如 HttpServletRequest)、全局清理兜底

实际项目中,既可以单独使用排在最外层的 Filter 完成读写与清理,也可以采用组合模式:由 ServletRequestListener 绑定最基础的请求对象并在 requestDestroyed 中做最终兜底清理,由业务 Filter 负责解析用户身份、补充响应头与执行权限拦截。

内部转发重入边界 ​

在 Servlet 应用中,使用 RequestDispatcher.forward() 或 include() 进行页面跳转、统一错误处理(error-page)时,容器是在同一个工作线程上同步调度目标资源的。这会引发一个容易被忽略的上下文重入陷阱:

  1. 默认安全行为:通过 @WebFilter("/*") 注册的过滤器,其 dispatcherTypes 默认仅包含 DispatcherType.REQUEST。外部请求进入时触发一次 Filter,后续目标 Servlet 调用 forward() 跳转到 JSP 或另一个 Servlet 时,不会再次进入该 Filter,上下文在整个请求结束前保持完整。

  2. 显式扩展 DispatcherType 引发的提前清空:若为了拦截转发请求或错误页,在 @WebFilter 中同时配置了 DispatcherType.FORWARD、DispatcherType.INCLUDE 或 DispatcherType.ERROR,同线程内的二次进入会覆盖原有上下文,且在内层 forward() 返回的瞬间执行内层 finally { RequestContextHolder.clear(); },直接清空当前线程的 ThreadLocal——当控制权回到外层 Servlet 或外层 Filter(如日志记录过滤器)时,读取到的上下文就会意外变为 null。

规避这一问题的原则非常明确:**负责创建与销毁 ThreadLocal 的入口 Filter 必须严格限定为 DispatcherType.REQUEST**;若业务确需在重入场景下临时替换上下文,必须采用“保存旧值快照 -> 写入新值 -> finally中恢复旧值”的栈式托管模式,而非无条件执行remove()。

示例: 请求上下文统一管理 ​

先定义聚合元数据的 RequestContext 与统一读写清理门面 RequestContextHolder:

java
// 1. 聚合单次请求的轻量级元数据,避免为每个字段分散声明多个 ThreadLocal
public final class RequestContext {

  private final String traceId;
  private final String userId;
  private final String clientIp;

  public RequestContext(String traceId, String userId, String clientIp) {
    this.traceId = traceId;
    this.userId = userId;
    this.clientIp = clientIp;
  }

  public String getTraceId() {
    return traceId;
  }

  public String getUserId() {
    return userId;
  }

  public String getClientIp() {
    return clientIp;
  }
}

// 2. 统一收口 ThreadLocal 的读写与清理入口,对外屏蔽底层存储细节
public final class RequestContextHolder {

  private static final ThreadLocal<RequestContext> CONTEXT_HOLDER = new ThreadLocal<>();

  // 3. 绑定当前请求上下文到工作线程
  public static void set(RequestContext context) {
    CONTEXT_HOLDER.set(context);
  }

  // 4. 在调用链任意层级读取当前请求上下文
  public static RequestContext get() {
    return CONTEXT_HOLDER.get();
  }

  // 5. 彻底移除当前线程绑定的上下文,防止复用线程残留数据
  public static void clear() {
    CONTEXT_HOLDER.remove();
  }
}

通过 Filter 在外部请求入口组装上下文、回写追踪响应头,并在 finally 中强制清理:

java
// 1. 仅拦截外部客户端请求,避免内部 forward 或 include 重入导致上下文被提前清空
@WebFilter(urlPatterns = "/*", dispatcherTypes = DispatcherType.REQUEST)
public class RequestContextFilter implements Filter {

  @Override
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
      throws IOException, ServletException {
    HttpServletRequest req = (HttpServletRequest) request;
    HttpServletResponse resp = (HttpServletResponse) response;

    // 2. 解析请求头与会话信息,组装当前请求上下文并写入响应头
    String traceId = req.getHeader("X-Trace-Id");
    if (traceId == null || traceId.isEmpty()) {
      traceId = UUID.randomUUID().toString();
    }
    HttpSession session = req.getSession(false);
    String userId = (session != null) ? (String) session.getAttribute("loginUserId") : "ANONYMOUS";

    RequestContext context = new RequestContext(traceId, userId, req.getRemoteAddr());
    resp.setHeader("X-Trace-Id", traceId);

    // 3. 在放行前绑定上下文,并在 finally 中确保请求结束时必然清理
    try {
      RequestContextHolder.set(context);
      chain.doFilter(request, response);
    } finally {
      RequestContextHolder.clear();
    }
  }
}

若需要让上下文覆盖所有 Filter 并由容器提供最外层清理保障,可采用 ServletRequestListener 方案:

java
// 1. 在容器级请求生命周期最外层绑定与销毁上下文,不受 Filter 排序影响
@WebListener
public class RequestContextListener implements ServletRequestListener {

  @Override
  public void requestInitialized(ServletRequestEvent sre) {
    ServletRequest request = sre.getServletRequest();
    if (!(request instanceof HttpServletRequest)) {
      return;
    }

    // 2. 请求进入容器瞬间绑定基础元数据,保证所有 Filter 均可读取
    HttpServletRequest req = (HttpServletRequest) request;
    String traceId = req.getHeader("X-Trace-Id");
    if (traceId == null || traceId.isEmpty()) {
      traceId = UUID.randomUUID().toString();
    }

    RequestContext context = new RequestContext(traceId, null, req.getRemoteAddr());
    RequestContextHolder.set(context);
  }

  @Override
  public void requestDestroyed(ServletRequestEvent sre) {
    // 3. 容器回收请求对象前统一兜底清理,彻底切断当前线程引用
    RequestContextHolder.clear();
  }
}

实战: JDBC 事务连接绑定 ​

在原生 Servlet + JDBC 架构(如订单创建同时扣减库存与写入订单明细)中,ThreadLocal 与 Filter 的另一项经典协作场景是无侵入声明式事务管理。其核心流程如下:

  1. 懒加载绑定连接:封装 TransactionContext,通过 ThreadLocal<Connection> 缓存当前线程的数据库连接。只有当下游 DAO 真正执行 SQL 时才从数据源取出一条 Connection,调用 setAutoCommit(false) 开启事务并绑定到当前线程;同一请求内后续其他 DAO 调用直接复用该连接。

  2. 统一提交与回滚:在 TransactionFilter 中包裹 chain.doFilter(request, response)。若整条 Servlet -> Service -> DAO 链路执行无异常,统一提交事务;若任意层级抛出异常,统一执行回滚并继续向上抛出异常。

  3. 归还连接与解绑成对执行:无论提交还是回滚,都在 finally 中先恢复连接的自动提交状态并调用 close() 将连接归还给连接池,紧接着调用 CONN_HOLDER.remove() 清除当前线程对已归还连接的引用。

image-20261120220843112

事务上下文封装实现如下:

java
// 1. 将当前请求的 JDBC Connection 绑定至工作线程,保证多个 DAO 共享同一事务连接
public final class TransactionContext {

  private static final ThreadLocal<Connection> CONN_HOLDER = new ThreadLocal<>();

  // 2. 懒加载获取连接并关闭自动提交,后续同线程 DAO 调用直接复用该连接
  public static Connection getConnection() throws SQLException {
    Connection conn = CONN_HOLDER.get();
    if (conn == null) {
      conn = DataSourceHolder.getConnection();
      conn.setAutoCommit(false);
      CONN_HOLDER.set(conn);
    }
    return conn;
  }

  // 3. 提交当前线程绑定的事务连接,并在 finally 中归还连接且清理 ThreadLocal
  public static void commitAndClose() {
    Connection conn = CONN_HOLDER.get();
    if (conn == null) {
      return;
    }

    try {
      conn.commit();
    } catch (SQLException e) {
      throw new RuntimeException("事务提交失败", e);
    } finally {
      closeQuietly(conn);
      CONN_HOLDER.remove();
    }
  }

  // 4. 发生业务异常时回滚事务,同样必须归还连接并执行 remove 防止连接对象残留
  public static void rollbackAndClose() {
    Connection conn = CONN_HOLDER.get();
    if (conn == null) {
      return;
    }

    try {
      conn.rollback();
    } catch (SQLException e) {
      throw new RuntimeException("事务回滚失败", e);
    } finally {
      closeQuietly(conn);
      CONN_HOLDER.remove();
    }
  }

  // 5. 恢复自动提交状态后关闭连接(归还连接池)
  private static void closeQuietly(Connection conn) {
    try {
      conn.setAutoCommit(true);
      conn.close();
    } catch (SQLException ignored) {
    }
  }
}

配合 TransactionFilter 在请求边界自动完成事务提交、回滚与线程解绑:

java
// 1. 在 Filter 层统一管控请求级事务边界,业务层与 DAO 层无需显式处理提交或回滚
@WebFilter(urlPatterns = "/api/*", dispatcherTypes = DispatcherType.REQUEST)
public class TransactionFilter implements Filter {

  @Override
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
      throws IOException, ServletException {
    try {
      // 2. 放行至目标 Servlet,期间各 DAO 通过 TransactionContext 共享同一条连接
      chain.doFilter(request, response);
      TransactionContext.commitAndClose();
    } catch (Throwable ex) {
      // 3. 捕获任意下游异常并触发回滚,随后继续向上抛出交由容器错误页处理
      TransactionContext.rollbackAndClose();
      throw ex;
    }
  }
}

这里有一个极其关键的边界细节:如果 TransactionContext 在归还连接后漏掉了 CONN_HOLDER.remove(),那么下一次复用该 Tomcat 工作线程的请求调用 getConnection() 时,就会直接拿到一个已被关闭或已被其他请求借走的 Connection 代理对象,引发 Connection is closed 异常甚至跨请求的事务错乱。下一章将聚焦 Tomcat 线程池复用场景,系统拆解各类隐蔽的跨请求污染成因与工程防线。

Servlet 线程池复用污染 ​

容器线程池复用模型 ​

在「4. 弱引用内存泄漏问题」中,我们分析了复用线程导致堆内存滞留的成因;但在 Servlet 生产环境中,比内存缓慢增长更具破坏力且更早爆发的事故,是线程池复用引发的跨请求数据污染(脏读与串号)。

Tomcat 等 Servlet 容器为了避免为每个 HTTP 请求频繁创建与销毁操作系统线程,底层通过 Connector 维护了一组长期存活的工作线程池(默认线程名形如 http-nio-8080-exec-1)。当请求到达时,容器执行以下调度循环:

  1. 分配工作线程:从空闲线程队列中取出一个既有工作线程(如 exec-1),交由它执行请求 A 的 Filter 链与目标 Servlet。

  2. 写入线程局部状态:请求 A 在执行过程中将当前用户、租户、数据源路由键或分页参数写入 ThreadLocal,实际落地在 exec-1 对象的 threadLocals 数组中。

  3. 归还线程池:请求 A 写回 HTTP 响应后,exec-1 不会销毁,而是直接回到线程池等待下一个任务。如果请求 A 未能执行 remove(),上述 Entry 会原封不动地保留在 exec-1.threadLocals 中。

  4. 复用并读取脏数据:随后到达的请求 B(可能来自完全不同的客户端用户)恰好被调度到 exec-1。只要请求 B 的执行路径存在“先读后写”或“跳过写入直接读取”,就会直接读到请求 A 遗留的旧状态。

image-20261120220910827

典型污染场景 ​

线程池复用污染在低并发本地联调时极难察觉,一旦上线承受真实并发流量,往往会表现为偶发、难以稳定复现的越权或数据错乱。

用户身份与权限串号 ​

认证过滤链通常会放行白名单接口(如公开商品详情、未登录态首页、健康检查),或允许匿名游客访问某些支持“登录态展示更多字段”的混合接口。若已登录用户 A 的请求在 exec-1 上写入了管理员身份却遗漏清理,随后匿名用户 B 的请求复用 exec-1 且跳过了认证写入步骤,业务层调用 UserContext.getUser() 时便会直接拿到用户 A 的身份凭证,造成严重的信息泄露甚至水平/垂直越权。

分页与数据源路由错乱 ​

在多租户、读写分离架构或使用 MyBatis PageHelper 等基于 ThreadLocal 的中间件时,污染后果同样直接作用于数据库层:

  • 分页参数串扰:PageHelper.startPage(1, 10) 会将分页参数写入当前线程的 ThreadLocal,并依赖随后执行的第一条 MyBatis 查询拦截器将其消费并清除。如果在调用 startPage 之后、执行 SQL 之前,代码因参数校验失败直接 return 或抛出异常,该分页参数就会滞留在工作线程中。下一请求复用该线程执行任意全量查询(例如加载字典表或权限列表)时,会被莫名拼接上 LIMIT 10,导致业务数据凭空截断。
  • 数据源路由漂移:动态数据源通常通过 ThreadLocal<String> 指定本次操作走主库、从库或特定租户库。若前序请求切换至“租户 A”数据源后未在 finally 中清除路由键,后续使用默认路由的请求在复用线程时就会把 SQL 路由到错误的物理库。

日志追踪链路串号 ​

SLF4J 与 Logback / Log4j2 提供的诊断上下文 MDC(Mapped Diagnostic Context)底层同样依赖 ThreadLocal> 存储 traceId、spanId 与 userId。若入口过滤器仅执行 MDC.put("traceId", ...) 而遗漏 MDC.clear(),当后续请求未覆盖某些可选字段(如错误码、业务订单号)时,日志文件中会出现“请求 B 的日志行里混入请求 A 订单号”的串号现象,严重干扰线上故障排查。

隐蔽触发路径 ​

即使开发团队已经具备“使用 ThreadLocal 必须调用 remove()”的意识,以下四类隐蔽编码缺陷仍会导致污染绕过防线:

  1. 异常与提前返回跳过末尾清理:将 remove() 写在方法最后一行而非 finally 块中,一旦中间逻辑抛出 RuntimeException 或因条件分支提前 return,清理语句将彻底失去执行机会。

  2. 写入操作位于 try 块之外:先调用 UserContext.set(user),紧接着在进入 try 块前执行参数解析、JSON 反序列化或数据库查询;若这些前置语句抛出异常,控制流尚未进入 try 块,对应的 finally 块不会被触发。

  3. 过滤链局部覆盖与多入口分散写入:统一清理 Filter 仅映射到 /api/*,但某些后台接口或静态回调 Servlet 挂在 /callback/* 下并自行向同一个 ThreadLocal 写入数据,导致这些路径完全脱离全局清理管控。

  4. ThreadLocal.withInitial 的可变对象复用误区:部分开发者误以为 ThreadLocal.withInitial(ArrayList::new) 会在每次 HTTP 请求到来时重新初始化集合。实际上,initialValue() 在每个工作线程的整个生命周期内仅于首次 get()(或 remove() 后的下一次 get())时调用一次。若不主动清理,复用线程就会把历次请求的数据不断追加到同一个集合中:

java
// 1. 反例:使用 withInitial 初始化可变集合,但请求结束后未调用 remove
private static final ThreadLocal<List<String>> AUDIT_LOGS =
    ThreadLocal.withInitial(ArrayList::new);

public void recordAction(String action) {
  // 2. 工作线程仅首次调用 initialValue,后续复用该线程的请求会持续向同一列表追加
  List<String> logs = AUDIT_LOGS.get();
  logs.add(action);
}

// 3. 正确做法:请求结束必须调用 remove,促使下次请求重新创建干净的列表实例
public void finishRequest() {
  AUDIT_LOGS.remove();
}

示例: 线程池复用脏读复现 ​

下面的 Servlet 演示了一个典型的跨请求身份污染场景:当请求携带 X-User 请求头时写入 ThreadLocal,未携带时跳过写入直接读取,且遗漏了 remove() 清理。

java
// 1. 演示跨请求污染的 Servlet:请求携带 X-User 头时写入上下文,未携带时直接读取
@WebServlet("/profile")
public class PollutedProfileServlet extends HttpServlet {

  private static final ThreadLocal<String> CURRENT_USER = new ThreadLocal<>();

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 2. 模拟仅在已登录请求中写入上下文,匿名请求跳过写入步骤
    String user = req.getHeader("X-User");
    if (user != null && !user.isEmpty()) {
      CURRENT_USER.set(user);
    }

    // 3. 读取当前线程绑定的用户标识并返回,故意遗漏 finally 中的 remove 清理
    String threadName = Thread.currentThread().getName();
    String resolvedUser = CURRENT_USER.get();
    resp.getWriter().write("thread=" + threadName + ", user=" + resolvedUser);
  }
}

如果在本地将 Tomcat Connector 的最大工作线程数临时调小为 1(例如 server.xml 中配置 maxThreads="1"),依次发起两次独立的 HTTP 请求:

  1. 第一次请求(用户 A 携带请求头 X-User: alice):响应输出 thread=http-nio-8080-exec-1, user=alice。

  2. 第二次请求(匿名用户 B 不携带 X-User 请求头):由于复用同一工作线程 http-nio-8080-exec-1,响应错误地输出 thread=http-nio-8080-exec-1, user=alice,而非预期的 user=null。

在真实生产集群中,当工作线程数为 200 时,匿名用户 B 只有 1200\frac{1}{200} 的概率命中刚被污染的线程,从而表现出“绝大多数时候正常、偶发串号”的极高排查难度;而在测试环境将工作线程数压缩至 1 或 2 后,所有遗漏清理的跨请求污染都会在两次请求内稳定暴露。

容器检测与工程防线 ​

Tomcat 泄漏检测与线程重建 ​

不少开发者会疑惑:既然 Tomcat 掌握着工作线程池的调度权,为什么不在每次 HTTP 请求结束后自动清空当前线程的全部 ThreadLocal?原因在于容器无法安全区分业务上下文与 JDK/框架内部依赖的线程级缓存(例如 CharsetEncoder、ByteBuffer 缓存或 SimpleDateFormat 实例);粗暴反射清空不仅会带来显著的性能开销,还会破坏标准库与底层协议栈的正常运行。

Tomcat 提供的 ThreadLocalLeakPreventionListener 与 WebappClassLoaderBase.checkThreadLocalsForLeaks() 解决的是应用停止或热重新加载(Reload / Undeploy)时的类加载器泄漏问题,而非单次 HTTP 请求之间的脏数据隔离:

  1. 应用卸载扫描告警:当 Web 应用停止时,WebappClassLoaderBase 会反射遍历 JVM 内所有存活线程的 threadLocals 与 inheritableThreadLocals,一旦发现某个 Entry 的 Key 或 Value 是由当前 WebAppClassLoader 加载的类,就会输出 SEVERE 级别日志警告存在潜在内存泄漏。

  2. 标记时间戳并延迟重建工作线程:ThreadLocalLeakPreventionListener 会在应用停止时通知 Tomcat 线程池更新 lastContextStoppedTime 时间戳。线程池中早于该时间点创建的 TaskThread 在归还或空闲时会被主动销毁并重新创建干净的新线程,从而切断对旧类加载器的强引用。

由此可见,请求粒度的上下文隔离与防污染责任完全由应用代码自身承担,不能指望 Servlet 容器代劳。

工程防污染实践 ​

为在工程层面系统性消除跨请求污染,建议落地四项防护实践:

  1. 建立集中式注册清理中心:避免每个业务模块各自维护散落的 ThreadLocal 与零散 remove() 调用。通过 ThreadLocalRegistry 统一登记所有请求级上下文,在请求边界执行一次集中清理即可覆盖全应用:
java
// 1. 统一注册应用内所有请求级 ThreadLocal,避免新增上下文时遗漏清理入口
public final class ThreadLocalRegistry {

  private static final List<ThreadLocal<?>> HOLDERS = new CopyOnWriteArrayList<>();

  // 2. 注册受托管的 ThreadLocal 实例并返回自身,便于静态常量声明时链式初始化
  public static <T> ThreadLocal<T> register(ThreadLocal<T> holder) {
    HOLDERS.add(holder);
    return holder;
  }

  // 3. 一键清理当前工作线程名下所有已注册的请求级上下文
  public static void clearAll() {
    for (ThreadLocal<?> holder : HOLDERS) {
      holder.remove();
    }
  }
}
  1. 入口前置清理与出口 finally 双保险:在最外层 Filter(限定 DispatcherType.REQUEST)中,不仅在 finally 块里执行清理,还可以在放行前的入口处先执行一次防御性 clearAll(),彻底阻断上游未知路径残留的脏状态向下游扩散:
java
// 1. 入口前置清空叠加出口 finally 清理,构成防线程复用污染双保险
@WebFilter(urlPatterns = "/*", dispatcherTypes = DispatcherType.REQUEST)
public class DoubleGuardCleanupFilter implements Filter {

  @Override
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
      throws IOException, ServletException {
    // 2. 防御性前置清理:抹除前序未知入口可能遗留的脏数据
    ThreadLocalRegistry.clearAll();

    try {
      chain.doFilter(request, response);
    } finally {
      // 3. 出口强制清理:确保线程归还 Tomcat 线程池时处于干净状态
      ThreadLocalRegistry.clearAll();
    }
  }
}
  1. 规范 try-finally 包裹边界:任何向 ThreadLocal 写入的操作都必须放在 try 块首行(或紧邻 try 之前且中间不含任何可抛异常逻辑),杜绝“先写入、后抛异常、未进 try”的边界漏洞;对于 PageHelper 等第三方组件,应紧贴目标查询方法调用,或在全局 Filter 的 finally 中追加 PageHelper.clearPage() 与 MDC.clear() 兜底。

  2. 单线程回归测试暴露隐患:在集成测试或预发压测阶段,将容器工作线程数临时限制为 1,按“高权限账号 -> 普通账号 -> 匿名请求 -> 异常中断请求”的顺序交替回放接口,能够以极低成本提前暴露所有隐蔽的线程池复用污染问题。

到目前为止,我们讨论的所有 Servlet 请求都运行在传统的同步阻塞模型下——一次请求始终绑定在同一条工作线程上。然而从 Servlet 3.0 起,规范引入了基于 AsyncContext 的异步非阻塞处理模型,允许工作线程提前释放回池、交由另一条异步业务线程完成响应输出。当单次 HTTP 请求跨越多个不同线程执行时,传统的 ThreadLocal 边界会被彻底打破,下一章将专门探讨 AsyncContext 场景下的跨线程上下文传递方案。

AsyncContext 跨线程传递 ​

异步线程切换断链 ​

在传统的同步 Servlet 模型中,一个 HTTP 请求从进入容器到写回响应始终独占同一条 Tomcat 工作线程,因此绑定在该线程上的 ThreadLocal 可以顺畅穿透整条调用栈。但从 Servlet 3.0 起,规范引入了基于 AsyncContext 的异步非阻塞处理能力,用于应对慢速下游 RPC、长轮询或耗时报表生成等 I/O 密集型场景。

一旦目标 Servlet 开启异步模式(@WebServlet(asyncSupported = true))并调用 req.startAsync(),原本完整的单线程执行模型会被拆分为两个或多个独立线程阶段,直接打破 ThreadLocal 的线程封闭前提:

  1. 容器入口线程提前释放:初始工作线程(如 http-nio-8080-exec-1)在提交完异步任务后会立刻从 doGet / doPost 返回,并沿着过滤链逆向退出,迅速归还给 Tomcat 线程池去接待下一个 HTTP 请求。

  2. 异步业务线程脱离原上下文:真正执行业务逻辑与写回响应的任务,由 asyncContext.start(Runnable) 派发给容器异步线程池,或提交给应用自定义的 ExecutorService 业务线程(如 async-biz-3)执行。该线程拥有独立的空白 ThreadLocalMap,直接调用 RequestContextHolder.get() 只会返回 null。

  3. InheritableThreadLocal 同样失效:如「5. InheritableThreadLocal 父子线程传递」所述,无论是容器内部线程池还是业务线程池,底层均复用既有的核心工作线程而不会为每次请求执行 new Thread(),因此将容器替换为 InheritableThreadLocal 既无法传递最新请求上下文,还会残留早期创建线程时的旧快照引发串号。

异步生命周期边界 ​

在异步 Servlet 请求中,除了业务线程读取不到上下文外,Filter 与 ServletRequestListener 的触发时机也会发生显著变化。若沿用同步请求的惯性思维,极易同时触发线程复用污染与二次派发上下文丢失。

Filter ​

在异步请求中,入口 Filter 的执行边界呈现两项必须明确的规则:

  • 禁止因 isAsyncStarted() 跳过清理:部分开发者认为请求开启异步后尚未真正结束,便在 Filter 的 finally 块中写下 if (!request.isAsyncStarted()) { RequestContextHolder.clear(); }。这是极其危险的反模式——初始工作线程在 doFilter 返回的瞬间就会归还 Tomcat 线程池,跳过清理既不能把数据传给异步线程,反而会把本次请求的上下文滞留在初始工作线程中,立刻污染下一个 HTTP 请求。因此,入口 Filter 的 finally 块必须无条件清理当前线程。
  • **全链路必须声明 asyncSupported = true**:Servlet 规范要求,请求经过的所有 Filter以及目标Servlet都必须显式声明asyncSupported = true,只要链路上存在任意一个未开启异步支持的 Filter,调用 req.startAsync()时容器就会直接抛出IllegalStateException。
  • 适配 asyncContext.dispatch() 的 ASYNC 派发:异步业务处理完毕后,除了直接写响应并调用 asyncContext.complete() 外,还可以调用 asyncContext.dispatch("/result.jsp") 将请求再次派发回容器渲染视图。此时容器会分配另一条工作线程(线程 C),以 DispatcherType.ASYNC 类型重新进入过滤链。如果入口 Filter 仅拦截 DispatcherType.REQUEST,线程 C 进入视图渲染阶段时将缺失上下文;由于此时初始线程 A 早已退出 Filter,在入口 Filter 中同时启用 DispatcherType.REQUEST 与 DispatcherType.ASYNC(仍排除 FORWARD 与 INCLUDE)既不会引发同线程重入清空,又能从 HttpServletRequest 属性中无缝恢复同一份上下文。

ServletRequestListener ​

与 Filter 在初始线程退出时即离开作用域不同,ServletRequestListener 遵循整个异步请求的逻辑生命周期:

  • 延迟销毁与跨线程回调:当初始工作线程调用 req.startAsync() 并返回后,容器不会立即触发 requestDestroyed();直到异步任务最终调用 asyncContext.complete()(或触发超时、错误结束异步周期)时,容器才会回调 requestDestroyed()。
  • 无法替代入口 Filter 清理初始线程:执行 requestDestroyed() 的线程往往是调用 complete() 的异步线程或容器的异步超时调度线程,而非最初处理请求的 Tomcat 工作线程 A。因此,如果应用仅依赖 ServletRequestListener.requestDestroyed() 清理 ThreadLocal,初始线程 A 在提前归还线程池后就会带着残留数据裸奔,引发严重的跨请求污染。

快照捕获与重放 ​

要在 AsyncContext 跨越多个复用线程池的链路中可靠传递上下文,核心思路是将上下文的绑定粒度从线程生命周期切换为异步任务执行生命周期,通过三步闭环完成跨线程透传:

  1. 提交前捕获(Capture):在初始工作线程退出 Servlet 之前,主动从当前 ThreadLocal 取出不可变的 RequestContext 快照(若上下文包含可变集合,须先执行深拷贝,防止多线程并发修改)。同时可将快照存入 HttpServletRequest 属性中,便于后续 AsyncListener 回调或 DispatcherType.ASYNC 派发阶段按需恢复。

  2. 执行前重放(Replay):将业务 Runnable 包装为上下文传播任务。当异步工作线程开始执行该任务前,先暂存异步线程自身可能已有的 previous 上下文,再将捕获的 snapshot 写入异步线程的 ThreadLocal。

  3. 结束后还原(Restore / Clear):在异步任务的 finally 块中,先将异步线程恢复为 previous(若原为空则执行 remove())确保异步线程池不被污染,再在业务收尾处可靠调用 asyncContext.complete() 或 dispatch() 结束本次异步周期。

image-20261120220936385

需要特别注意的是,如果异步任务长时间未响应触发了容器超时(AsyncListener.onTimeout)或底层 I/O 异常(AsyncListener.onError),容器会由专门的后台监控线程触发回调,该线程同样不包含初始线程的 ThreadLocal。若需要在超时告警日志中输出正确的 traceId 与 userId,应在 AsyncListener 回调内部从 event.getSuppliedRequest().getAttribute(...) 取出预先缓存的快照,在回调中临时绑定并在 finally 中清除。

跨线程传播方案对比 ​

在 Servlet 异步架构中,常见的跨线程上下文传播方案各有适用边界:

对比维度显式任务包装器(Capture / Replay)HttpServletRequest 属性 + ASYNC 派发TransmittableThreadLocal(TTL)
实现机制包装 Runnable / Callable,提交时捕获、执行前后重放与清理初始请求写入 req.setAttribute,异步阶段读取或由 ASYNC 过滤恢复装饰线程池(TtlExecutors)或通过 Java Agent 字节码无侵入增强
适用异步入口同时兼容 asyncContext.start() 与自定义业务线程池适用于 AsyncListener 回调与 asyncContext.dispatch() 视图派发适合应用自主管理的 ExecutorService、CompletableFuture 等
外部依赖零依赖,纯 JDK 与 Servlet 标准实现零依赖,直接复用 Servlet 请求域对象需引入第三方库,容器内部线程池需配合 TtlRunnable 或 Agent
侵入性与心智成本中等,需在提交异步任务处显式调用包装方法业务层若不持有 req 引用,在异步纯业务方法中仍需配合 ThreadLocal低侵入,配置好线程池包装或 Agent 后业务代码无感知
典型组合方式用于 asyncContext.start() 与异步业务任务执行阶段作为底层兜底载体,配合 AsyncListener 与 DispatcherType.ASYNC 使用中大型微服务项目中统一替代手写任务包装器

由于 asyncContext.start(Runnable) 直接将任务交由 Tomcat 内部线程池调度,应用代码通常无法拿到容器底层 Executor 实例进行装饰,因此将显式任务包装器(或 TtlRunnable.get)与HttpServletRequest 属性暂存 + DispatcherType.ASYNC 过滤组合使用,是 Servlet 异步架构下最稳健且可移植的工程方案。

实战: AsyncContext 上下文透传 ​

先编写通用的异步任务上下文传播包装器 ContextPropagator,封装“捕获 -> 重放 -> 还原”三步闭环:

java
// 1. 异步任务上下文传播工具,将快照绑定到任务执行生命周期而非线程生命周期
public final class ContextPropagator {

  public static Runnable wrap(Runnable task) {
    // 2. 在提交线程(Tomcat 工作线程)立即捕获当前上下文快照
    RequestContext snapshot = RequestContextHolder.get();

    return () -> {
      // 3. 保存异步工作线程原有现场,避免嵌套提交时破坏外层上下文
      RequestContext previous = RequestContextHolder.get();
      try {
        if (snapshot != null) {
          RequestContextHolder.set(snapshot);
        } else {
          RequestContextHolder.clear();
        }
        task.run();
      } finally {
        // 4. 任务结束立即恢复原现场或清空,杜绝污染异步线程池
        if (previous != null) {
          RequestContextHolder.set(previous);
        } else {
          RequestContextHolder.clear();
        }
      }
    };
  }
}

接着改造入口 Filter,开启 asyncSupported = true,并将 RequestContext 同步缓存在 HttpServletRequest 属性中,以支持 DispatcherType.ASYNC 二次派发阶段的上下文恢复,同时坚持在 finally 中无条件清理当前工作线程:

java
// 1. 异步链路上的所有 Filter 均须开启 asyncSupported = true,并同时处理 ASYNC 二次派发
@WebFilter(
    urlPatterns = "/*",
    asyncSupported = true,
    dispatcherTypes = {DispatcherType.REQUEST, DispatcherType.ASYNC}
)
public class AsyncRequestContextFilter implements Filter {

  private static final String CONTEXT_ATTR = RequestContext.class.getName();

  @Override
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
      throws IOException, ServletException {
    HttpServletRequest req = (HttpServletRequest) request;

    // 2. 优先复用首次 REQUEST 暂存的上下文;若不存在则解析并缓存至请求属性供 ASYNC 阶段恢复
    RequestContext context = (RequestContext) req.getAttribute(CONTEXT_ATTR);
    if (context == null) {
      String traceId = req.getHeader("X-Trace-Id");
      if (traceId == null || traceId.isEmpty()) {
        traceId = UUID.randomUUID().toString();
      }
      context = new RequestContext(traceId, resolveUserId(req), req.getRemoteAddr());
      req.setAttribute(CONTEXT_ATTR, context);
    }

    // 3. 无论是否开启异步,当前容器线程退出过滤链时都必须立即清理,绝不可跳过 remove
    try {
      RequestContextHolder.set(context);
      chain.doFilter(request, response);
    } finally {
      RequestContextHolder.clear();
    }
  }

  private String resolveUserId(HttpServletRequest req) {
    HttpSession session = req.getSession(false);
    return (session != null) ? (String) session.getAttribute("loginUserId") : "ANONYMOUS";
  }
}

最后在异步 Servlet 中通过 ContextPropagator.wrap 包装待执行的异步业务任务,使下游 OrderService 在切换至异步工作线程后依然能够无侵入地读取到当前请求的 traceId 与 userId,并在任务收尾时确保 asyncContext.complete() 与异步线程清理双双落袋:

java
// 1. 必须声明 asyncSupported = true,允许当前 Servlet 挂起请求并开启异步模式
@WebServlet(urlPatterns = "/async/order", asyncSupported = true)
public class AsyncOrderServlet extends HttpServlet {

  private final OrderService orderService = new OrderService();

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
    // 2. 开启异步上下文并配置超时时间,当前工作线程随后即将释放回 Tomcat 线程池
    AsyncContext asyncContext = req.startAsync();
    asyncContext.setTimeout(5000L);

    // 3. 包装业务任务捕获当前线程快照,并交由容器异步线程池执行
    Runnable wrappedTask = ContextPropagator.wrap(() -> {
      try {
        // 4. 在异步工作线程中直接读取透传过来的 RequestContext
        String result = orderService.createOrder();
        HttpServletResponse asyncResp = (HttpServletResponse) asyncContext.getResponse();
        asyncResp.setContentType("text/plain;charset=UTF-8");
        asyncResp.getWriter().write(result);
      } catch (IOException ex) {
        throw new UncheckedIOException(ex);
      } finally {
        // 5. 无论成功或异常均必须结束异步周期,防止连接一直挂起直至超时
        asyncContext.complete();
      }
    });

    asyncContext.start(wrappedTask);
  }
}

至此,Servlet ThreadLocal 从底层的 ThreadLocalMap 数组与斐波那契散列、线性探测读写清理源码、弱引用内存泄漏、父子线程传递,到 Servlet 请求上下文统一管理、线程池复用防污染以及 AsyncContext 跨线程透传的完整知识链路已经全部闭环。