ThreadLocal是 Java 中用于实现线程本地存储的重大工具类，常被用会话在登录态传递、数据连连接保持等场景，本文将详细介绍 ThreadLocal。

一、基本概念

1.1 定义

java.lang.ThreadLocal<T> 是一个泛型类，用于创建线程局部变量。每个线程访问该变量时，都会拥有自己独立的、初始化后的副本。

1.2 设计目的

解决多线程环境下共享变量的并发问题。
避免通过参数显式传递上下文信息（如用户身份、事务 ID、数据库连接等）。
实现“以空间换时间”：每个线程持有一份数据副本，避免加锁带来的性能开销。

二、基本使用示例

public class ThreadLocalExample {
    private static ThreadLocal<Integer> threadLocalValue = ThreadLocal.withInitial(() -> 0);

    public static void main(String[] args) throws InterruptedException {
        Runnable task = () -> {
            int value = threadLocalValue.get();
            System.out.println(Thread.currentThread().getName() + " 初始值: " + value);
            threadLocalValue.set(value + 1);
            System.out.println(Thread.currentThread().getName() + " 修改后: " + threadLocalValue.get());
        };

        Thread t1 = new Thread(task, "Thread-1");
        Thread t2 = new Thread(task, "Thread-2");

        t1.start();
        t2.start();

        t1.join();
        t2.join();

        // 主线程访问
        System.out.println("Main thread: " + threadLocalValue.get());
    }
}

输出示例：

Thread-1 初始值: 0
Thread-1 修改后: 1
Thread-2 初始值: 0
Thread-2 修改后: 1
Main thread: 0

每个线程都有自己的 Integer 副本，互不影响。

三、核心方法

方法	描述
T get()	返回当前线程的线程局部变量副本的值。若未设置，则调用 initialValue() 初始化。
void set(T value)	设置当前线程的线程局部变量副本的值。
void remove()	移除当前线程的线程局部变量副本。超级重大！防止内存泄漏。
protected T initialValue()	返回此线程局部变量的初始值。默认返回 null。一般通过匿名内部类或 withInitial() 覆盖。

3.1 withInitial(Supplier<? extends S> supplier)

Java 8 引入的静态工厂方法，用于更简洁地指定初始值：

ThreadLocal<String> local = ThreadLocal.withInitial(() -> "default");

等价于：


ThreadLocal<String> local = new ThreadLocal<String>() {
    @Override
    protected String initialValue() {
        return "default";
    }
};

四、底层实现原理

4.1 数据结构

ThreadLocal 并不是把数据存在自己内部，而是将数据存储在 每个线程的 Thread 对象中的 ThreadLocalMap 成员变量里。

关键点：

每个 Thread 实例都有一个 ThreadLocal.ThreadLocalMap threadLocals 字段。
ThreadLocalMap 是 ThreadLocal 的静态内部类，类似 HashMap，但使用 线性探测法 解决哈希冲突。
ThreadLocalMap 的 key 是 ThreadLocal 对象本身（弱引用），value 是实际存储的值。 ThreadLocal 内存结构图示例：两个线程，每个线程 ThreadLocal 包含两个 entry。

限行探测法示例图

4.2 存储流程（set）

调用 threadLocal.set(value)。
获取当前线程 Thread.currentThread()。
获取该线程的 ThreadLocalMap（若无则创建）。
以当前 ThreadLocal 实例为 key，value 为 value，存入 map。

4.3 读取流程（get）

获取当前线程。
获取其 ThreadLocalMap。
以当前 ThreadLocal 为 key 查找 entry。
若存在则返回 value；否则调用 initialValue() 初始化并存入。

4.4 弱引用（WeakReference）与内存泄漏

ThreadLocalMap 中的 key 是 ThreadLocal 的 弱引用（WeakReference）。
当 ThreadLocal 实例没有强引用指向它时，GC 会回收 key，但 value 不会被回收（由于 value 是强引用）。
如果线程长期存活（如线程池中的线程），这些“key 为 null 但 value 仍存在”的 entry 就会造成 内存泄漏。

内存泄漏示意图

如何避免内存泄漏？

✅ 务必在使用完 ThreadLocal 后调用 remove()！

try {
    threadLocal.set(value);
    // ... 业务逻辑
} finally {
    threadLocal.remove(); // 清理！
}

注意：即使不调用 remove()，ThreadLocalMap 在后续 get/set 操作中也会进行 探测式清理（expungeStaleEntries），但不能依赖此机制，应主动清理。

五、典型应用场景

5.1 用户上下文传递（如登录用户信息）

public class UserContext {
    private static final ThreadLocal<User> currentUser = new ThreadLocal<>();

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

    public static User getCurrentUser() {
        return currentUser.get();
    }

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

在 Web 应用中，可在 Filter 中设置，在 Controller/Service 中直接获取，无需层层传参。

5.2 数据库连接/事务管理

Spring 的 DataSourceUtils 使用 ThreadLocal 管理同一个线程内的数据库连接，实现事务一致性。

5.3 SimpleDateFormat 线程安全问题

SimpleDateFormat 非线程安全，可用 ThreadLocal 包装：

private static final ThreadLocal<SimpleDateFormat> DATE_FORMAT =
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

注：Java 8+ 推荐使用 DateTimeFormatter（线程安全）替代。

5.4 日志追踪（Trace ID / Span ID）

在分布式系统中，为每个请求生成唯一 TraceID，并通过 ThreadLocal 在同一线程内传递，便于日志串联。

六、注意事项与最佳实践

✅ 最佳实践

及时清理：使用 try-finally 或 try-with-resources（需自定义封装）确保 remove() 被调用。
避免滥用：不要用 ThreadLocal 存储大对象或生命周期不可控的对象。
线程池场景尤其小心：线程复用会导致脏数据或内存泄漏。
优先思考替代方案：如能通过方法参数传递，尽量不用 ThreadLocal。

❌ 常见误区

误以为 ThreadLocal 是“线程安全的容器”——它只是隔离了数据，并非同步工具。
忘记 remove()，导致内存泄漏或数据污染（线程池中下一个任务看到上一个任务的数据）。
在异步任务中使用 ThreadLocal（如 CompletableFuture、@Async），由于异步任务运行在不同线程，无法继承原线程的 ThreadLocal 值。

⚠️ 异步场景解决方案：使用 TransmittableThreadLocal（阿里巴巴开源）或 InheritableThreadLocal（仅适用于父子线程，且子线程必须在父线程启动时创建）。

七、InheritableThreadLocal

InheritableThreadLocal 是 ThreadLocal 的子类，允许子线程继承父线程的 ThreadLocal 值。

InheritableThreadLocal<String> itl = new InheritableThreadLocal<>();
itl.set("parent-value");

new Thread(() -> {
    System.out.println(itl.get()); // 输出 "parent-value"
}).start();

局限性：

仅在线程创建时复制一次，之后父子线程各自独立。
不适用于线程池（线程是预先创建的，无法继承）。

八、推荐源码阅读

ThreadLocal.set()

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

ThreadLocal.get()

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();
}

ThreadLocalMap.Entry（弱引用 key）

static class Entry extends WeakReference<ThreadLocal<?>> {
    /** The value associated with this ThreadLocal. */
    Object value;

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

九、总结

特性	说明
线程隔离	每个线程拥有独立副本
非线程安全容器	用于隔离而非同步
内存泄漏风险	必须手动 remove()
适用场景	上下文传递、线程安全单例、事务管理等
慎用场景	异步、线程池、大对象存储