threadlocal 的核心是 thread 持有 threadlocalmap，而非 threadlocal 存数据；key 为弱引用、value 为强引用，易致内存泄漏；需在作用域结束前调用 remove() 防泄漏和线程池污染。

要真正掌握 ThreadLocal，不能只记 set/get/remove 这几个方法，得从它解决的实际问题出发，再一层层拆开底层逻辑和真实场景里的雷区。

核心设计：不是“ThreadLocal 存数据”，而是“Thread 存 ThreadLocalMap”

这是绝大多数人一开始就想错的地方。ThreadLocal 本身并不存储任何线程的数据；真正存数据的是每个 Thread 对象内部的 threadLocals 字段，它是一个 ThreadLocalMap 类型的哈希表。

这个 Map 的结构很特别：

• key 是当前 ThreadLocal 实例（弱引用）
• value 是你通过 set() 存进去的变量副本（强引用）
• Entry 继承自 WeakReference，所以 key 可能被 GC 回收，但 value 不会自动跟着清掉

正因为 key 是弱引用，而 value 是强引用，才埋下了内存泄漏的根因——后面会重点讲。

Java注释规范Skills

当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。

下载

典型用法：三类高频场景必须熟练

不用死记 API，而是按需求归类记忆：

• 上下文透传：比如 Web 请求中的 traceId、userId、language。在过滤器里 set，在任意 Service 或工具类里 get，全程不传参
• 非线程安全对象复用：如 SimpleDateFormat、DecimalFormat、Jackson ObjectMapper（部分版本）。用 ThreadLocal 包一层，避免频繁 new，又杜绝并发异常
• 框架级状态管理：Spring 的事务同步管理器、MyBatis 的 SqlSession、日志框架的 MDC，底层全靠 ThreadLocal 绑定线程生命周期

必踩的坑：内存泄漏与线程池污染

这两个问题在生产环境最致命，而且往往延迟暴露：

• 内存泄漏：ThreadLocalMap 中的 key 被回收后，Entry 变成“幽灵条目”（key==null，value 还活着），如果线程长期存活（比如线程池里的线程），value 就一直占着堆内存，且无法被访问到
• 线程池污染：线程被复用时，上一个请求 set 的值没 remove，下一个请求 get 到的就是脏数据——用户 A 的 token 出现在用户 B 的日志里，这种事故极难排查

应对方式很简单但必须强制执行：

• 所有 set 操作后，务必在作用域结束前调用 remove()
• 在 Web 场景中，统一在 Filter 或 Interceptor 的 finally 块里 clear
• 使用 try-finally 或 try-with-resources（配合自定义 CloseableThreadLocal）来兜底

进阶要点：initialValue 与 InheritableThreadLocal

这两个功能常被忽略，但在复杂场景中很关键：

• initialValue() 是 get() 的兜底逻辑。如果没 set 过就直接 get，会触发一次 initialValue() 创建默认值。推荐用 withInitial(Supplier) 静态工厂方法，更简洁安全
• InheritableThreadLocal 允许子线程继承父线程的值，适用于 ForkJoinPool 或手动创建子线程的场景。但注意：普通线程池（如 ThreadPoolExecutor）默认不继承，需额外包装或改用 TransmittableThreadLocal（阿里开源，支持线程池透传）

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南