容易产生“ThreadLocal 持有 Map”的错觉

一、类结构层：静态内部类的"归属"错觉

public class ThreadLocal<T> {
// ...
static class ThreadLocalMap {
static class Entry extends WeakReference<ThreadLocal<?>> {
Object value;
Entry(ThreadLocal<?> k, Object v) { ... }
}
private Entry[] table;
// ...
}
}

ThreadLocalMap 是 ThreadLocal 的静态内部类，这在 Java 语法里表达的是"命名空间归属"——它被嵌套在 ThreadLocal 的类定义里，所以全名是 ThreadLocal.ThreadLocalMap。

但关键要区分两件事：

• 静态内部类 ≠ 实例成员。static 修饰意味着 ThreadLocalMap 与任何 ThreadLocal 实例都没有关联，它不持有外部类引用，也不能访问外部类的实例字段。它只是一个"逻辑上归 ThreadLocal 管"的独立类。

• 类定义的位置 ≠ 运行时对象的持有关系。ThreadLocalMap 类被写在 ThreadLocal.java 里，只说明"这个 Map 是 ThreadLocal 机制专用的"，不说明"某个 ThreadLocal 对象里存了一个 Map"。

对比一下：如果写成 private ThreadLocalMap map; 这样的实例字段，那才是真正的"ThreadLocal 实例持有 Map"。而实际源码里 ThreadLocal 的实例字段只有 private final int threadLocalHashCode，没有任何 Map 引用。

 

二、源码组织层：同一个文件里的强耦合

ThreadLocalMap 的源码和 ThreadLocal 写在同一个 .java 文件里，而且它的 Entry、set、getEntry、expungeStaleEntry 等逻辑大量直接操作 ThreadLocal 的 threadLocalHashCode 字段、调用 ThreadLocal 的静态方法（如 nextHashCode()）。这种"同文件、互相引用"的组织方式，让人在阅读时自然地把两者当成一个整体——"ThreadLocal 机制"这个整体里包含 Map，于是误读成"ThreadLocal 对象里包含 Map"。

但从对象图看，实际关系是：

Thread 实例 ──持有──> ThreadLocalMap 实例 ──Entry[]──> Entry(弱引用Key=ThreadLocal, value=数据)
ThreadLocal 实例 ──仅作为Key被引用──> Entry

三、API 设计层：调用方视角的"我存了数据"

从使用者视角看：

ThreadLocal<String> tl = new ThreadLocal<>();
tl.set("hello");   // 看起来像 tl 存了 "hello"
tl.get();          // 看起来像从 tl 取 "hello"

set/get 都挂在 ThreadLocal 实例上，调用者手里只有 tl 这一个对象，数据"进"了 tl、"出"自 tl。这种 API 形态天然让人把 ThreadLocal 当成数据的容器。而实际上 set 的内部是：

public void set(T value) {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);   // 拿的是当前线程的 map
    if (map != null) map.set(this, value);  // this 作为 key
    else createMap(t, value);
}

this（ThreadLocal 实例）只是 Key，Map 是从 Thread.currentThread() 上取的。API 把"当前线程的 Map"这个真正容器完全隐藏了，调用者感知不到 Thread 的存在。