ThreadLocal内存泄漏是线程复用下清理缺失的必然结果，因Entry.key为弱引用而value为强引用，导致key=null后value仍驻留；须在finally中remove、静态声明、避免大对象，并通过堆分析、工具封装与静态扫描防控。
ThreadLocal内存泄漏不是偶然现象，而是线程复用场景下清理缺失的必然结果。关键不在“会不会 leak”，而在于“什么时候 leak、怎么被发现、怎么确保不漏”。
为什么ThreadLocal容易泄露
根本原因在于 ThreadLocalMap.Entry 的引用设计：key 是弱引用（指向 ThreadLocal 实例），value 是强引用（指向业务对象）。当 ThreadLocal 实例本身被回收（比如局部变量置 null），key 变成 null，但 value 仍被 Entry 强引用着，无法被 GC 回收。
在线程池中，线程长期存活，这个“key=null + value=强引用”的 Entry 就一直卡在 map 里，越积越多，最终拖垮堆内存。
- Thread → threadLocals（强引用）→ ThreadLocalMap → Entry
- Entry.key：WeakReference<ThreadLocal>（可被 GC）
- Entry.value：Object（强引用，GC 不动它）
如何快速定位泄漏点
不要等 OOM 才行动。一旦怀疑 ThreadLocal 泄漏，优先从堆转储（heap dump）切入：
- 用 MAT 或 JProfiler 打开 dump 文件，搜索 java.lang.ThreadLocal$ThreadLocalMap$Entry
- 筛选出 key == null 的 Entry，再看它们的 value 类型——往往就是你存进去的 UserContext、TraceInfo、Connection 等业务对象
- 检查这些 value 对象的保留集（Retained Set），确认是否被某个长期存活的线程（如 pool-1-thread-3）直接持有
- 结合代码搜索所有 .set(…) 调用点，重点排查没配 .remove() 或没进 finally 的分支
必须遵守的清理规范
清理不是“可选项”，是使用 ThreadLocal 的强制前置条件。规范动作要嵌入编码习惯：
- 所有 set() 操作后，必须有对应的 remove()，且必须放在 finally 块 中，防止异常跳过清理
- 避免在方法内直接 new ThreadLocal()；统一声明为 static final，并配套提供 clear() 工具方法
- 禁止将大对象（如 List、Map、DTO）直接塞进 ThreadLocal；如需缓存，考虑 size 限制或改用 SoftReference 包装
- 在线程池场景下，在任务 execute 前后自动清理：重写 ThreadPoolExecutor 的 beforeExecute/afterExecute，或使用 TransmittableThreadLocal（TTL）的增强版 cleanup 机制
推荐的工程化防护手段
靠人盯代码不可靠，要靠机制兜底：
- 封装 ThreadLocal 工具类，例如 ContextHolder，所有 get/set/clear 都走统一入口，clear 内部自动做 null 判断和 try-catch
- 在测试环境开启 JVM 参数 -XX:+PrintGCDetails -XX:+PrintGCTimeStamps，配合监控观察 Full GC 频率与老年代占用趋势
- 静态扫描接入：用 SonarQube 或自定义 PMD 规则，检测 ThreadLocal.set() 后 3 行内无 remove() 或 finally 的模式
- 对关键上下文类（如 RequestContext）增加 finalize 日志或弱引用监听，上线初期捕获未清理实例
