ThreadLocal内存泄漏与线程串号：从源码原理到线程池工程实践

1. "用户A看到了用户B的数据"：一次串号事故背后的ThreadLocal真相

先从一个真实的线上事故说起。某个内部管理系统的接口，偶尔会出现用户A登录后，请求列表接口返回了用户B的订单数据。一开始怀疑是缓存失效、数据库连接串了，查了半天都没结果。直到有同学注意到，事故总是发生在某个线上请求比较密集的时间段，而且出问题的请求，恰好都落到了同一个Tomcat线程上。

定位过程很直接：在这个老项目里，登录拦截器会把当前登录用户塞到一个静态的ThreadLocal里，业务代码随时通过UserHolder.get()取用户。而问题就出在这里——请求处理完之后，代码并没有清理这个ThreadLocal。Web容器的工作线程是复用的，Tomcat处理完用户A的请求后线程不会销毁，ThreadLocal里保留的还是用户A的信息。当这个线程被分配去处理用户B的请求时，如果某个异步回调或者后置逻辑没有重新set用户，读到的就是上一个用户A的残留数据。用户串了，业务自然跟着串。

ThreadLocal在并发编程里是个很特殊的角色。它的核心作用通俗讲就是：让同一个变量在每个线程里各有一份独立副本。正因为这种"与线程绑定"的特性，它在处理用户上下文、请求追踪ID、数据库连接、事务信息等场景中几乎是绕不开的工具。但也是因为这个特性，一旦你用错方式，就会出现上面这种"线程池串数据"事故，甚至引发内存泄漏。

这篇文章不会停留在"ThreadLocal怎么用"的层面，而是把设计原理、常见误区和工程实践串起来讲清楚。既适合刚接触并发编程的读者建立整体认识，也适合有一定经验、但踩过ThreadLocal相关坑的同学做一次系统性复盘。

2. 先理解ThreadLocal到底在解决什么问题

2.1 线程隔离：为什么需要"每个线程各拿各的"

并发编程里最烦人的就是共享资源竞争。多个线程同时操作同一个变量，轻则数据错乱，重则直接抛异常。常规思路是加锁，用synchronized、Lock把并发访问变成串行。但有些场景本质上是"假共享"——每个线程需要的数据根本不一样，只不过是同一段代码在同时执行而已。这时候加锁反而是最笨的解法，因为锁会把本来可以并行的操作强行排队，白白牺牲性能。

ThreadLocal提供了另一种思路：既然大家都要用这个变量，但又不想互相干扰，那就别共享了，每个线程自己持有一份变量副本。线程读到的永远是自己那份，像锁竞争、可见性、原子性这些问题在一开始就不存在。

举一个最典型的例子，SimpleDateFormat不是线程安全的，它的parse()和format()内部会修改一个Calendar对象。如果多个线程共享一个SimpleDateFormat实例，格式化结果时好时坏。你当然可以在每次使用时new一个新的，但频繁创建对象的开销并不小，尤其在高并发场景下。用ThreadLocal给每个线程保存一份SimpleDateFormat，既避免了加锁，也避免了频繁创建：

java复制private static final ThreadLocal<SimpleDateFormat> DATE_FORMAT =
        ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

public String formatTime(long millis) {
    return DATE_FORMAT.get().format(new Date(millis));
}

这样每个线程各自持有一个SimpleDateFormat实例，互不干扰，代码也干净。

2.2 ThreadLocal的三个典型业务场景

ThreadLocal的典型使用场景可以归为三类，理解这三类场景，就会明白它的设计动机。

第一类是线程上下文传递。请求进入系统后，经过拦截器、过滤器、业务逻辑、DAO层等多个环节，某些数据（当前登录用户、租户ID、请求ID）几乎所有环节都要用到。如果每个方法都把用户对象作为参数一层层传下去，接口签名会变得非常啰嗦，而且中间任何一层漏传就断链了。把用户信息放进ThreadLocal，整条调用链路内任何位置都能直接取到，取完再清理，这是最常见的用法。

第二类是线程安全对象的线程本地化。比如上面提到的SimpleDateFormat，以及Random、加密算法工具类等非线程安全对象，在并发环境下希望复用实例又不想加锁，通过ThreadLocal给每个线程持有独立副本。严格说这属于"用空间换线程安全"。

第三类是保存数据库连接或事务上下文。一个事务内的多个DAO操作需要共用同一个Connection。事务管理器在开启事务后把连接放进ThreadLocal，DAO层从ThreadLocal中取出连接执行SQL，保证所有操作都落在同一个事务里。Spring的TransactionSynchronizationManager就是这么干的。

2.3 心里先记下三个方法：set、get、remove

使用层面，ThreadLocal的API极其简单，核心就三个方法：

java复制ThreadLocal<String> context = new ThreadLocal<>();
context.set("value");     // 给当前线程设置值
String v = context.get(); // 从当前线程取值，没设置过则返回 null
context.remove();         // 移除当前线程的值

写起来很简单，但这三个方法背后的东西一点都不简单。尤其get()的返回值受初始值影响，set(null)和remove()也不是等价操作，这些坑后面会展开讲。在继续往下之前，你只需要先建立一个大前提：ThreadLocal本身不存储数据，数据实际是存在当前线程对象里的。下一节就从源码层面看它的真实结构。

3. 源码视角下的ThreadLocal：一张藏在Thread内部的Map

3.1 ThreadLocal不存值，每个Thread自带一张Map

很多初学者第一次接触ThreadLocal时，想当然地以为ThreacLocal内部有个Map，key是线程，value是值。事实刚好反过来：真正存数据的是Thread对象，ThreadLocal只是作为Map的key出现。

看JDK源码，Thread类内部有两个字段：

java复制ThreadLocal.ThreadLocalMap threadLocals = null;
ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

threadLocals就是存放"当前线程专属数据"的地方。当你调用threadLocal.set(value)时，实际上执行的是：

java复制public void set(T value) {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);
    if (map != null) {
        map.set(this, value);
    } else {
        createMap(t, value);
    }
}

拿到当前线程，取出线程自带的ThreadLocalMap，以当前ThreadLocal对象作为key，把value放进去。换句话说，一个线程拥有一个ThreadLocalMap，ThreadLocalMap里可以放多个ThreadLocal对应的多组数据。这样的设计让一个线程同时使用很多个ThreadLocal变量成为可能。假如反过来由ThreadLocal持有一个全局Map，以线程为key存储，那就退化成了共享变量，还得处理Map本身的线程安全问题，完全没有意义。

3.2 弱引用Key、强引用Value，为什么这样设计

ThreadLocalMap里的每个元素叫Entry，看它的定义：

java复制static class Entry extends WeakReference<ThreadLocal<?>> {
    Object value;

    Entry(ThreadLocal<?> k, Object v) {
        super(k);
        value = v;
    }
}

注意，Entry继承了WeakReference，也就是说Entry对ThreadLocal对象的引用是弱引用，但value是普通强引用。

为什么要用弱引用？我们来推演一下。假设用户上下文ThreadLocal是在一个方法里创建的局部变量，方法执行完、请求结束，这个ThreadLocal对象本身按理说应该可以被回收。如果Entry对ThreadLocal是强引用，那么只要线程还活着，ThreadLocal对象就永远不被回收——可它已经没有任何业务代码在使用了，这就成了实实在在的内存泄漏。改用弱引用后，当外部对ThreadLocal的强引用消失，下一次GC时ThreadLocal对象就会被回收，Entry的key随即变成null。后续访问这个Entry时，判断key为null就可以把它当作脏数据清理掉。

那value为什么不是弱引用？设想一下，如果value也是弱引用，ThreadLocal里存的业务数据随时可能被GC回收，这数据还怎么用？value承载的是真正的业务数据，生命周期应该跟随线程的使用周期，由代码显式控制，而不是交给GC的弱引用规则。

3.3 get、set、remove的实现逻辑，以及那条只被弱引用牵着的线

get()的逻辑也很清晰：

java复制public T get() {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);
    if (map != null) {
        ThreadLocalMap.Entry e = map.getEntry(this);
        if (e != null) {
            @SuppressWarnings("unchecked")
            T result = (T) e.value;
            return result;
        }
    }
    return setInitialValue();
}

先找当前线程的map，再根据当前ThreadLocal实例找Entry，找到就返回value；找不到就调用setInitialValue()。setInitialValue()内部会调用initialValue()方法，如果创建ThreadLocal时没有重写initialValue()，默认返回null。所以第一次get()返回null，不一定是没set过，也可能是set的初始值本身就是null。

remove()方法做的事就一件：从当前线程的Map中删除以这个ThreadLocal为key的Entry。

java复制public void remove() {
    ThreadLocalMap m = getMap(Thread.currentThread());
    if (m != null) {
        m.remove(this);
    }
}

理解了这三段代码，你就明白：ThreadLocal的生命周期实际上是"ThreadLocal对象被弱引用牵在Map的key上，value被强引用绑在Entry上"。只要线程存活、且ThreadLocalMap中的Entry未被清理，value就会一直存在。这条线是整个ThreadLocal内存模型的枢纽，也是后面内存泄漏问题分析的关键。

3.4 0x61c88647：ThreadLocalMap的哈希魔法

既然ThreadLocalMap是一张Map，就绕不开哈希和冲突。ThreadLocalMap没有采用HashMap那种"数组+链表+红黑树"的结构，而是用了开放寻址法中的线性探测。每个ThreadLocal实例创建时都会分配一个哈希值：

java复制private final int threadLocalHashCode = nextHashCode();

private static AtomicInteger nextHashCode = new AtomicInteger();
private static final int HASH_INCREMENT = 0x61c88647;

private static int nextHashCode() {
    return nextHashCode.getAndAdd(HASH_INCREMENT);
}

0x61c88647这个数字不是随便选的，它和黄金分割数有关。ThreadLocalMap的初始容量是16，扩容阈值是容量的三分之二（threshold = len * 2 / 3）。用0x61c88647作为步长递增生成的哈希值，分布到2的幂次大小的数组里，能够保证散列非常均匀，降低线性探测时的冲突概率。这也是ThreadLocalMap为什么不需要像HashMap那样用链表处理严重碰撞的原因之一——大部分情况下一个槽位就能命中。

哈希冲突时，ThreadLocalMap会从计算出的索引位置开始，依次向后查找空位插入；查找时也顺着探测路径寻找key相等的Entry。这里有个隐蔽的问题：如果中间某个Entry的key已经变成null（弱引用被回收），查找时就要用expungeStaleEntry()顺带清理掉这类脏Entry，否则可能影响后续key的寻址。这也是为什么get()和set()在特定情况下会触发内部清理动作——不过这种清理是"顺手的、不保证的"，千万不要把"回收value"的希望寄托在它上面。

4. 内存泄漏深度剖析：弱引用为什么没能救下value

4.1 一条无法主动断开的强引用链

ThreadLocal的内存泄漏问题，网上讨论很多，但不少讨论只停留在"弱引用会导致泄漏"这个层面，这是不准确的。弱引用本身并不会导致泄漏，真正的问题出在value那条强引用链上。

当一个ThreadLocal对象不再被业务代码使用时，由于Entry对key是弱引用，ThreadLocal对象可以被GC回收，Entry的key变成null。但Entry里的value仍然被一条强引用链牢牢牵着：

code复制Thread 对象
  -> ThreadLocalMap
    -> Entry
      -> value（强引用）

这条链路上没有一个是弱引用。只要线程不结束、ThreadLocalMap不清理这个Entry，value就永远无法被GC回收。即便key已经变成null，成了一个没有业务意义的"尸体Entry"，value依然占着内存。

在普通场景下，如果线程是短命的，比如每次请求由新线程处理，线程处理完就结束，Thread对象连同它的ThreadLocalMap一起变为不可达，整套数据被GC回收，问题不明显。但只要有线程复用，这个问题就会被无限放大——服务端的工作线程、线程池里的线程，生命周期往往和JVM一样长。

4.2 线程池场景为什么会雪上加霜

线程池里的线程执行完一个任务后并不会销毁，而是回到池里等待下一个任务。假设有一个线程池固定10个线程，每个任务都往一个静态ThreadLocal里塞一些数据，任务结束后不清理。这些value会一直挂在某几个线程的ThreadLocalMap里，线程换了一茬又一茬任务，旧数据始终不移除。积累到一定程度，要么GC压力增大，要么直接内存溢出。

而且这种泄漏还有一个隐蔽性：它不是一次性暴涨，而是随着任务数缓慢增长。你甚至会看到堆内存使用率像一个非常平缓的阶梯，一格格往上爬。如果长时间不处理，一个长期运行的线程池服务会因为持有大量"无主"value而把堆内存耗尽。

真正的现场复现很简单。注意，触发条件有两个：一是ThreadLocal对象外部强引用消失（比如ThreadLocal不是静态字段，而是方法内局部变量）；二是线程存活且没有调用remove。第二个条件在线程池场景几乎必然存在。

这里要特别提示一个误区：**如果ThreadLocal被static final字段持有，key永远不变成null，那value由于key活着的ThreadLocalMap强引用? Entry持有对key弱引用，但static字段持有ThreadLocal强引用，Entry的弱引用是否让key被回收呢？实际上，由于static字段的存在，ThreadLocal对象不会被回收，key也不为null。value会一直存在，除非remove。**这也是非常常见的泄漏原因。很多团队把ThreadLocal定义成static final，然后在使用后忘记remove，造成每个线程的Map里都留着一个持续可达的Entry。业务代码和线程池叠加，才是生产中绝大多数ThreadLocal内存泄漏的真正面貌。

4.3 定位泄漏现场：Heap Dump和对象引用分析

真遇到疑似ThreadLocal泄漏，不要靠猜，用工具定位。

第一步，先确认是不是有大量同类的"残留对象"。用jmap导出一份堆快照：

bash复制jmap -dump:live,format=b,file=heap.hprof <pid>

第二步，把hprof文件导入MAT（Eclipse Memory Analyzer），用"Histogram"查看实例数量靠前的类。如果你发现某个上下文对象、用户对象、请求体对象的实例数量异常多，远超预期，右键选择"List Objects -> with outgoing references"查看它们是被谁引用的。

排查引用链时会看到类似这样的路径：

code复制线程对象
  -> java.lang.ThreadLocal$ThreadLocalMap
    -> java.lang.ThreadLocal$ThreadLocalMap$Entry[] 
      -> value

沿着这条路径基本可以确定value是被某个线程的ThreadLocalMap持有，再结合该Entry的key是否为null或者指向哪个ThreadLocal，就能定位是哪段业务代码set之后没有remove。

如果不想用MAT这么重的工具，也可以用jhsdb或者在线排查工具。还有一种更轻量的办法：在代码里临时加一段监控，定时扫描某几个关键线程池线程的ThreadLocalMap中entry数量。不过一般到了这个阶段，Heap Dump已经足够说明问题。

4.4 remove()不只是"删掉值"，它切断的是整条引用链

有些同学觉得remove()和set(null)差不多，都是把value清掉。翻开ThreadLocalMap.remove()源码就会发现完全不是一回事。remove()会定位到对应Entry，然后执行：

java复制e.clear();       // 清除弱引用，即 key 置为 null
expungeStaleEntry(i);  // 清理这个槽位，并把后续受影响的entry重新排列

e.clear()将Entry对ThreadLocal的弱引用断开，expungeStaleEntry把table对应位置置为null，同时value引用也会被断开。整个过程不只是把value设成null，而是彻底把这条Entry从Map中移除，让key、value、Entry本身都变成不可达对象，GC可以完整回收。所以工程上清理ThreadLocal只有一个正解：remove()。

5. 避坑清单：线程池、父子线程传递与高频误用

5.1 线程池中必须清理，但"在哪里清理"有讲究

线程池场景的ThreadLocal清理，理念上只有一句话：任务结束时清理。但实现时很多人都会踩坑，因为"任务结束"的位置并不总是那么直观。

直接在线程池里提交一个任务，任务内部使用ThreadLocal，最安全的写法是在finally中清理：

java复制ExecutorService pool = Executors.newFixedThreadPool(8);

pool.submit(() -> {
    try {
        UserContext.set(user);
        // 业务逻辑
    } finally {
        UserContext.clear();
    }
});

这样做的好处是无论业务逻辑是否抛出异常，ThreadLocal都会被清理干净。不能只放在正常路径的末尾，因为一旦抛出异常，后面的清理代码根本不执行，残留数据就留在线程里了。

如果你的业务是在Spring的过滤器或拦截器里设置上下文，那么清理逻辑可以统一放在finally块或afterCompletion中，这样业务层就不必关心ThreadLocal的清理，框架统一兜底。反过来，如果业务代码自己往ThreadLocal塞数据，那清理责任就在这一段业务代码本身，不要总是指望框架帮你做。

5.2 父子线程自动传递？InheritableThreadLocal和它的边界

默认情况下，子线程不会继承父线程的ThreadLocal数据。你可能会想：能不能让线程池里的任务自动拿到提交任务线程的上下文？这正是InheritableThreadLocal想做的事情。

InheritableThreadLocal继承自ThreadLocal，重写了childValue()等方法。当父线程创建新线程时，新线程的inheritableThreadLocals会从父线程的inheritableThreadLocals复制一份。这样新线程一启动，就能直接读到父线程设置的值。

但这里有个致命限制：它只在new Thread()创建线程的那一刻拷贝一次。也就是说，如果父线程在创建子线程之后又修改了自己的值，子线程里已经拷贝好的值不会跟着变；如果子线程是从线程池里复用的，线程池里的线程早就创建好了，根本不会经历"父线程创建子线程"的过程，所以也就不会拷贝父线程的值。现实中我们大量使用线程池，InheritableThreadLocal在这类场景下基本失效。

所以，跨线程池传递上下文，JDK自带的两个类都不够用。实际工程中要么用TransmittableThreadLocal配合TtlExecutors封装线程池，要么在提交任务时手动捕获并传递父线程的值。手动传递的写法反而很好理解：

java复制String traceId = TraceContext.getTraceId();
pool.submit(() -> {
    try {
        TraceContext.setTraceId(traceId);
        // 业务逻辑
    } finally {
        TraceContext.clear();
    }
});

先捕获需要传递的值，再在新的任务线程中重新set，执行完清理。没有魔法，全是显式操作，反而最不容易出错。

5.3 set(null)清不掉、initialValue重写陷阱、全局静态ThreadLocal隐患

这几个都是身边同事反复踩过的坑，我挨个说。

先说set(null)。有些同学认为set(null)之后value变成null，效果等同remove。表面看似乎没问题——你get到的是null了。但ThreadLocalMap的Entry仍然存在，key仍然引用着ThreadLocal对象，Entry占据的数组槽位也没有释放。连续用不同的ThreadLocal变量set(null)，反复几次，ThreadLocalMap里的脏Entry越积越多，最终导致Map越来越大、哈希探测越来越慢。正确的清理动作永远是remove()，没有替代方案。

再说initialValue()的重写问题。创建一个ThreadLocal时，可以通过继承并重写initialValue()来提供初始值：

java复制ThreadLocal<User> userHolder = new ThreadLocal<>() {
    @Override
    protected User initialValue() {
        return new User("anonymous");
    }
};

这种写法本身没问题。但要注意，initialValue()是一个可以被子类覆盖的方法。如果你设计了一个ThreadLocal工具类，并有子类继承它去改初始值逻辑，不同调用方拿到同一个ThreadLocal实例时，get()的首次行为会不一致。更稳妥的做法是直接用静态工厂方法ThreadLocal.withInitial(Supplier)，把初始值的提供逻辑固定下来，减少继承覆写的自由度。

最后是全局静态ThreadLocal的隐患。业务代码里把ThreadLocal声明为static final没问题，这意味着所有线程共享同一个ThreadLocal对象作为key，每个线程各自存放一份value，这套机制本来就支持。但很多人因此松懈了清理动作，觉得"反正key是强引用不会泄漏"。事实是，key不会变成null不代表value不会滞留——value依然跟着线程走，线程不清、remove不调，value就一直在。尤其在Web应用和线程池场景中，static ThreadLocal配不清理，等于每个工作线程永久背着一个业务对象。这里的教训是：ThreadLocal用static没问题，但static不是不清理的挡箭牌。

5.4 容易忽略的框架集成冲突：MDC、RequestContextHolder和异步链路

很多人没用过原生ThreadLocal，但一定用过Logback的MDC。org.slf4j.MDC底层就是ThreadLocal的封装，用来保存traceId、userId等日志上下文。在Web请求线程里设置好MDC，日志输出就可以自动带上traceId，排查问题时非常方便。但一旦业务代码里使用线程池执行异步任务，子线程里往往没有traceId，日志就对不上了。这也是"ThreadLocal不跨线程传递"在日志链路上的体现。

同样的道理，Spring的RequestContextHolder也是基于ThreadLocal保存当前请求的ServletRequestAttributes。如果在异步线程里调用RequestContextHolder.getRequestAttributes()，大概率拿到的是null。很多团队刚开始做异步化时都会在这里栽跟头。

这类问题的解决方案跟5.2节基本一致：要么手动把父线程的上下文值传递到异步任务中，要么引入TransmittableThreadLocal并包装线程池，让上下文在任务提交、执行、归还时自动传递和清理。设计异步链路时，一开始就要考虑上下文传递问题，否则改造到一半会发现大量日志串号或取不到请求上下文，返工成本很高。

6. 从"会用"到"用对"：工程化封装与最佳实践

6.1 用工具类收口ThreadLocal的API

直接在业务代码里到处new ThreadLocal()，随后又手动set/get/remove，代码会变得很散，容易出现有人set了忘remove的情况。工程上更推荐的做法是把ThreadLocal封装成一个上下文工具类，只暴露语义化的set/get/clear方法，隐藏ThreadLocal实例本身。这样做的另一个好处是：将来如果需要把上下文从ThreadLocal迁移成其他传递机制，只需修改一个类。

java复制public class UserContext {

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

    private UserContext() {
    }

    public static void set(User user) {
        HOLDER.set(user);
    }

    public static User get() {
        return HOLDER.get();
    }

    public static void clear() {
        HOLDER.remove();
    }
}

使用方不需要知道内部是不是ThreadLocal，只关心UserContext.set()和UserContext.clear()的语义。如果有一天你想把UserContext改成用TransmittableThreadLocal，或者改成从某个异步上下文中读取，内部实现悄悄换掉，调用方完全无感。

6.2 清理动作的统一时机：拦截器与finally

ThreadLocal最佳实践里，最重要也最容易被忽略的一条是：set和clear要成对出现，而且clear要放在finally中。如果上下文是在一个请求的入口处设置的，那么最理想的位置是请求出口的finally逻辑里。

Spring MVC环境可以这样统一处理：

java复制@Component
public class UserContextInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        User user = parseUser(request);
        UserContext.set(user);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
                                Object handler, Exception ex) {
        UserContext.clear();
    }
}

在preHandle中设置用户，在afterCompletion中清理。afterCompletion在视图渲染完成之后、请求完全结束之前调用，无论过程中有没有抛异常都会执行，正好承担清理职责。

对于纯手写的线程池任务，没有拦截器可用，那就乖乖在任务内部try-finally。

java复制pool.execute(() -> {
    UserContext.set(user);
    try {
        doBiz();
    } finally {
        UserContext.clear();
    }
});

我个人还习惯在编写这种代码时加一个原则：如果不确定这个方法的清理逻辑由谁负责，就在方法入口处先set，然后立刻问自己"什么时候remove"；三秒钟答不出来，就改用显式传参。

6.3 初始化方式、大对象存放、跨线程链路：三个自查点

第一，初始化方式建议统一用ThreadLocal.withInitial()。它比匿名内部类重写initialValue()更清爽，还能显著减少重复代码。比如一个保存随机数的ThreadLocal可以这样：

java复制private static final ThreadLocal<Random> RANDOM =
        ThreadLocal.withInitial(Random::new);

第二，不要在ThreadLocal里存放重对象。ThreadLocal的一个价值是对象在线程内复用，所以很多人会把byte[]、复杂业务对象整个塞进去。可你要知道，这东西在线程池里不会主动释放，一旦线程被复用，旧对象就一直霸占内存。如果确实需要临时保存大数据量对象，最好在finally中remove()，且存放时间做到最小化。

第三，异步链路要提前设计上下文传递策略。是手动传参，还是引入TransmittableThreadLocal？如果团队里已经使用了类似框架，工具类封装可以减少替换成本。如果项目比较轻量，我个人更推荐显式传参而不是引入额外依赖，显式传参的代码虽然看起来啰嗦，但逻辑可读性最好，调试也直观。

6.4 一个规范示例：从入口到落地的完整模板

最后给一个可以直接"抄作业"的完整模板，覆盖了过滤器设置、业务读取、统一清理的逻辑。假设是一个REST接口，需要通过登录Token解析用户信息，并在一次请求线程内共享。

java复制@Component
public class UserContextFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        try {
            User user = parseUserFromToken(httpRequest.getHeader("Authorization"));
            if (user != null) {
                UserContext.set(user);
            }
            chain.doFilter(request, response);
        } finally {
            UserContext.clear();
        }
    }

    private User parseUserFromToken(String token) {
        // 解析逻辑省略，返回User对象或null
        return null;
    }
}

这个模板其实只做了三件事：请求进来时从凭证解析用户并放入上下文；执行业务链路；请求结束时在finally中移除。不管业务代码是否抛出异常，用户上下文都不会残留在工作线程上，线程池复用场景下的"串用户"问题从根本上被堵死。

6.5 线程池提交场景下的任务封装补充

如果项目中大量在线程池里提交需要父子上下文传递的任务，同时又不想在每一个Runnable里写try-finally，可以封装一个静态方法统一处理：

java复制public class ContextTaskWrapper {

    public static Runnable wrap(Runnable task) {
        String traceId = TraceContext.getTraceId();
        return () -> {
            TraceContext.setTraceId(traceId);
            try {
                task.run();
            } finally {
                TraceContext.clear();
            }
        };
    }
}

使用时这样提交：

java复制pool.submit(ContextTaskWrapper.wrap(() -> {
    // 这里能拿到提交任务时的traceId
}));

封装的好处是，把"捕获上下文-设置上下文-执行任务-清理上下文"这几步收敛到一个方法里，避免各业务方各自乱写。当然，如果团队引入了TransmittableThreadLocal，这类wrapper基本可以由框架替代，但背后的清理思想是通用的。

7. 我在项目中反复踩坑后总结的几条纪律

ThreadLocal不是一个复杂的类，但它的"坑"往往不在类本身，而在使用它的环境。总结我自己的经验，核心纪律有四条。

一是ThreadLocal与线程池同用时，必须考虑清理时机。任何从线程池取线程执行的任务，只要在线程里set了ThreadLocal，就必须在同一个任务范围内remove。这条经验来自线上事故的代价，也是全篇最重要的实践原则。

二是永远不要用set(null)代替remove。set(null)只改变了value的取值，map里的Entry还在，key可能还活着。只要调用一次remove，才能断开Entry的完整引用链。养成习惯后，看到有人写threadLocal.set(null)我都会提醒改用remove()。

三是跨线程传递要先判断到底用的是哪种ThreadLocal。普通ThreadLocal连父子线程都不传，InheritableThreadLocal只在new Thread()时传一次，线程池里要传递上下文用TransmittableThreadLocal或手动捕获传参。不要想当然地认为提交到线程池的任务能自动拿到父线程的上下文。

四是用Tool类封装并限制ThreadLocal暴露面。业务代码越少直接接触ThreadLocal API，出错概率越低。一个只暴露set/get/clear语义的上下文类，配合拦截器在finally中统一清理，可以让ThreadLocal相关的使用规范真正落地。

说实话，ThreadLocal本身不难，难的是时刻记住"数据跟线程走，线程不一定跟你的请求走"。想明白这一点，ThreadLocal的绝大多数坑都能避开。