ThreadLocal 本身不防泄漏，关键在于主动管理 ThreadLocalMap：其 Entry 的 key 是弱引用、value 是强引用，线程池中易产生 key 为 null 而 value 滞留的 stale entry，必须通过 try-finally 中调用 threadLocal.remove() 彻底删除 Entry；静态声明 + 封装 clear() 方法 + 在 Filter/Interceptor/afterExecute() 中统一清理；避免存大对象、资源类或 Spring Bean；虚线程应优先用 ScopedValue。
ThreadLocal 本身不防泄漏，真正起作用的是你对 ThreadLocalMap 的主动管理。关键不是“用 ThreadLocalMap 防泄漏”，而是理解它怎么存数据、为什么容易漏、以及怎样正确清理。
ThreadLocalMap 的结构决定泄漏风险
每个线程内部都有一个 ThreadLocalMap，它的 Entry 是这样的：
- key：ThreadLocal 实例的弱引用 —— GC 可随时回收，回收后 key 变成 null
- value：你 set 进去的对象，是强引用 —— 只要 Entry 还在，value 就不会被 GC
线程池里线程长期存活，Entry 不自动清空；key 回收后留下“stale entry”（key=null，value 还占着），value 就卡死在堆里，越积越多就 OOM。
必须显式 remove()，不能靠 set(null) 或等线程结束
set(null) 只是把 value 设为 null，Entry 还在 map 里，key 已经可能是 null，这仍是脏项。唯一可靠方式是调用 threadLocal.remove()，它会真正从 ThreadLocalMap 中删除整个 Entry。
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
立即学习“Java免费学习笔记（深入）”；
- 写法必须带 try-finally：即使业务抛异常，也要保证 remove 执行
- 示例：不要只在正常流程末尾 remove，要包在 finally 里
静态声明 + 统一清理入口更安全
ThreadLocal 建议声明为 private static final，避免重复创建，也防止 key 被意外回收。但这也意味着它几乎永生，value 更得靠你手动清。
- 封装 clear() 方法，比如 UserContext.clear()，内部调用 threadLocal.remove()
- 在 Web 场景中，统一在 Filter 的 doFilter 或 Spring Interceptor 的 afterCompletion 里调用 clear()
- 在线程池场景，可继承 ThreadPoolExecutor，重写 afterExecute()，兜底调用所有已知 ThreadLocal 的 remove()
避开高危用法，从源头减小风险
不是所有数据都适合放 ThreadLocal：
- 禁止存大对象：如 Map、List、IO 缓冲区、完整用户上下文（>100KB 就算大）
- 禁止存需显式释放的资源：Connection、FileInputStream、自定义缓存实例
- 避免持有 Spring Bean 或 Service 引用 —— 可能拖慢整个上下文卸载
- 虚线程（Java 21+）优先用 ScopedValue，ThreadLocal 清理机制未适配其高频启停
