ThreadLocal 内存泄漏详解-阿里西西

前言

本文带你在 30 分钟内彻底理解 ThreadLocal 的内存泄漏问题，并附带可直接运行的复现脚本，帮助你在面试或生产场景中快速验证与防护。

1. 内容概述

ThreadLocal 用于为每个线程提供独立的存储空间，常见于：

请求上下文传递（如用户 ID、traceId）
线程级缓存（数据库连接、临时对象）
线程状态隔离（例如线程安全的 SimpleDateFormat）

但如果使用不当，ThreadLocal 会导致严重内存泄漏，尤其在线程池环境下。

2. 学习目标

常见使用场景与业务价值
ThreadLocal 内部结构及引用模型
内存泄漏根因与安全使用方法
可复现的泄漏与安全示例

3. 核心内容

3.1 常见使用场景

场景	作用	示例
上下文传递	避免方法参数层层传递	Web 框架用户 ID
线程缓存	减少重复创建对象开销	数据库连接、配置缓存
状态隔离	线程安全工具类	SimpleDateFormat

3.2 关系模型及源码剖析

ThreadLocal 内部结构

ThreadLocal架构图 .jpg

Thread 持有 ThreadLocalMap 的强引用
ThreadLocalMap.Entry.key 是弱引用
Entry.value 是强引用业务对象

泄漏原理

线程存活，Map 强引用 value，key 被 GC，value 就这样被卡在线程上，没人管它

当外部 ThreadLocal 无强引用时，key 会被 GC 回收，但 value 仍被 Entry 强引用
如果线程长期存活（线程池核心线程），value 永远无法回收 → 内存泄漏

3.3 内存泄漏复现脚本

（1）不 remove（泄漏版本）

ThreadLocal<BigObject> local = new ThreadLocal<>();
local.set(new BigObject()); // 故意不 remove
logMemory();

（2）加 remove（安全版）

ThreadLocal<BigObject> local = new ThreadLocal<>();
local.set(new BigObject());
logMemory();
local.remove(); // 手动清理，避免泄漏

（3）可直接运行完整脚本

import java.lang.management.ManagementFactory;
import java.lang.management.MemoryMXBean;
import java.lang.management.MemoryUsage;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class ThreadLocalLeakDemo {
    static class BigObject { byte[] data = new byte[5 * 1024 * 1024]; }

    public static void main(String[] args) {
        ExecutorService pool = Executors.newFixedThreadPool(10);

        for (int i = 0; i < 200; i++) {
            pool.execute(() -> {
                ThreadLocal<BigObject> local = new ThreadLocal<>();
                local.set(new BigObject()); //放入线程私有变量
                logMemory(); //打印堆日志
                // local.remove(); // 注释掉为泄漏版
            });
        }
    }

    private static void logMemory() {
        MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
        MemoryUsage heapUsage = memoryBean.getHeapMemoryUsage();
        long used = heapUsage.getUsed() / (1024 * 1024);
        long max = heapUsage.getMax() / (1024 * 1024);
        System.out.printf("Heap used: %d MB / %d MB%n", used, max);
    }
}

JVM 参数：

-Xms100m -Xmx100m -XX:+HeapDumpOnOutOfMemoryError

注意：如果使用命令行运行JVM参数，一定要放在 java 命令和类名之间，否则不会生效。

3.4 安全使用模板

public class SafeThreadLocal<T> {
    private final ThreadLocal<T> threadLocal = new ThreadLocal<>();

    public void set(T value) { threadLocal.set(value); }
    public T get() { return threadLocal.get(); }
    public void remove() { threadLocal.remove(); } // 核心防泄漏
}

业务场景示例（Web 请求上下文）：

try {
    SafeThreadLocal.CURRENT_USER_ID.set(1001L);
    return userService.getUserName();
} finally {
    SafeThreadLocal.CURRENT_USER_ID.remove();
}