ThreadLocal 原理与内存泄漏：弱引用的坑

// 服务运行 3 天后，运维导出 Heap Dump（4.2GB）
// MAT (Memory Analyzer Tool) 分析结果：

Dominator Tree:
  ThreadLocalMap$Entry[]          retained: 3.1 GB
    └── Entry[0..1999999]         retained: 2.8 GB
         └── UserContext × 2000000  ← 200 万个用户上下文对象！
              ├── userId: Long
              ├── tenantId: String
              └── permissions: List<String>

// 根因：Filter 中 set 了 ThreadLocal，但忘了 remove
// 线程池中的线程被复用，Entry 永远不会被清理

/* ─── 场景 1：数据库连接管理（类似 Spring 的实现思路） ─── */
public class DBUtil {
    private static final ThreadLocal<Connection> connHolder = new ThreadLocal<>();

    public static Connection getConnection() {
        Connection conn = connHolder.get();
        if (conn == null) {
            conn = dataSource.getConnection();
            connHolder.set(conn);
        }
        return conn;
    }

    public static void close() {
        Connection conn = connHolder.get();
        if (conn != null) { conn.close(); connHolder.remove(); }
    }
}

/* ─── 场景 2：SimpleDateFormat 线程安全 ─── */
private static final ThreadLocal<SimpleDateFormat> sdfHolder =
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

String formatted = sdfHolder.get().format(new Date());

/* ─── 场景 3：请求上下文（Spring Security 的思路） ─── */
public class UserContext {
    private static final ThreadLocal<UserInfo> holder = new ThreadLocal<>();
    public static void set(UserInfo user) { holder.set(user); }
    public static UserInfo get() { return holder.get(); }
    public static void clear() { holder.remove(); }
}

/* ─── 场景 4：MDC TraceId ─── */
MDC.put("traceId", UUID.randomUUID().toString());
// logback 日志格式: %d [%X{traceId}] %-5level %msg%n

public void set(T value) {
    // 1. 获取当前线程
    Thread t = Thread.currentThread();

    // 2. 获取该线程的 ThreadLocalMap
    ThreadLocalMap map = getMap(t);  // return t.threadLocals;

    if (map != null) {
        // 3. 以 this（当前 ThreadLocal 实例）为 key 存入 map
        map.set(this, value);
    } else {
        // 4. 首次使用，为线程创建 ThreadLocalMap
        createMap(t, value);
    }
}

// ThreadLocalMap.set() 内部逻辑（简化）：
private void set(ThreadLocal<?> key, Object value) {
    Entry[] tab = table;
    int len = tab.length;
    // 用 ThreadLocal 的 threadLocalHashCode 计算槽位
    int i = key.threadLocalHashCode & (len - 1);

    for (Entry e = tab[i]; e != null; e = tab[i = nextIndex(i, len)]) {
        ThreadLocal<?> k = e.get();  // 弱引用获取 key

        if (k == key)        // 找到同一个 ThreadLocal → 更新 value
            { e.value = value; return; }
        if (k == null)       // key 已被 GC → 替换过期 Entry
            { replaceStaleEntry(key, value, i); return; }
    }
    // 没找到 → 新建 Entry
    tab[i] = new Entry(key, value);
    // 检查是否需要扩容（threshold = len * 2/3）
    if (++size >= threshold) rehash();
}

public T get() {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);

    if (map != null) {
        ThreadLocalMap.Entry e = map.getEntry(this);
        if (e != null) {
            @SuppressWarnings("unchecked")
            T result = (T) e.value;
            return result;
        }
    }
    // map 为空 或 没找到 Entry → 调用 initialValue()
    return setInitialValue();
}

private T setInitialValue() {
    T value = initialValue();  // 默认返回 null
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);
    if (map != null)
        map.set(this, value);
    else
        createMap(t, value);
    return value;
}

// 强引用：只要引用存在，GC 绝不回收
Object obj = new Object();   // obj 是强引用

// 软引用：内存不足时才回收（适合做缓存）
SoftReference<Object> soft = new SoftReference<>(obj);

// 弱引用：下次 GC 必定回收（不管内存够不够）
WeakReference<Object> weak = new WeakReference<>(obj);

// 虚引用：随时可回收，无法通过它获取对象（仅用于跟踪回收）
PhantomReference<Object> phantom = new PhantomReference<>(obj, queue);

// getEntry 时会顺手清理脏 Entry
private Entry getEntry(ThreadLocal<?> key) {
    int i = key.threadLocalHashCode & (table.length - 1);
    Entry e = table[i];

    if (e != null && e.get() == key) {
        return e;  // 直接命中
    } else {
        // 线性探测过程中，遇到 key=null 的脏 Entry 会调用清理
        return getEntryAfterMiss(key, i, e);
        // getEntryAfterMiss 内部调用 expungeStaleEntry(i)
    }
}

// expungeStaleEntry：清理指定位置的脏 Entry 及其后续的连续段
private int expungeStaleEntry(int staleSlot) {
    Entry[] tab = table;
    int len = tab.length;

    // 1. 清除脏 Entry 的 value 引用
    tab[staleSlot].value = null;  // ← 解除强引用，value 可被 GC
    tab[staleSlot] = null;        // ← 清除整个 Entry
    size--;

    // 2. 继续向后扫描，重新放置被挤偏的 Entry 或清理更多脏 Entry
    Entry e;
    int i;
    for (i = nextIndex(staleSlot, len); (e = tab[i]) != null; i = nextIndex(i, len)) {
        ThreadLocal<?> k = e.get();
        if (k == null) {  // 又一个脏 Entry
            e.value = null;
            tab[i] = null;
            size--;
        } else {
            // 重新 hash 这个 Entry，放到正确位置
        }
    }
    return i;
}

public class UserContextFilter implements Filter {
    private static final ThreadLocal<UserContext> USER_HOLDER = new ThreadLocal<>();

    @Override
    public void doFilter(ServletRequest req, ServletResponse resp,
                         FilterChain chain) throws IOException {
        try {
            UserContext ctx = parseUser(req);
            USER_HOLDER.set(ctx);  // 设置上下文
            chain.doFilter(req, resp);
        } finally {
            USER_HOLDER.remove();  // ← 必须在 finally 中清理！
            // 不能用 remove() 以外的方法，不能用 clear()
            // 不能漏掉，不能放在 try 块中（异常时会跳过）
        }
    }
}

ThreadLocal<String> tl = new InheritableThreadLocal<>();
tl.set("main-thread-value");

new Thread(() -> {
    // 子线程可以读到父线程的值！
    System.out.println(tl.get());  // 输出: main-thread-value
}).start();

// 原理：Thread.init() 时，如果父线程的 inheritableThreadLocals 不为空，
// 会把整个 Map 拷贝给子线程（浅拷贝，共享 value 引用）

// Maven: com.alibaba:transmittable-thread-local:2.14.x

// 1. 使用 TTL 替代 ThreadLocal
TransmittableThreadLocal<UserContext> ctx = new TransmittableThreadLocal<>();

// 2. 包装线程池（关键步骤！）
ExecutorService pool = TtlExecutors.getTtlExecutorService(
    Executors.newFixedThreadPool(10)
);

// 3. 提交任务时，TTL 会自动 capture → replay → restore
ctx.set(new UserContext("user-123"));

pool.submit(() -> {
    // 线程池线程能正确读到提交时的值！
    UserContext user = ctx.get();  // user-123
    processRequest(user);
});

/*
 * TTL 的三步机制：
 * ① capture：任务提交时，快照当前线程所有 TTL 的值
 * ② replay：任务执行前，把快照值设置到执行线程
 * ③ restore：任务执行后，恢复执行线程之前的值
 */

/* ─── 配合 Spring + 线程池的完整配置 ─── */
@Configuration
public class AsyncConfig {

    @Bean("taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("async-ttl-");
        // 用 TTL 装饰，确保 @Async 方法能正确传递上下文
        executor.setTaskDecorator(new TtlTaskDecorator());
        executor.initialize();
        return executor;
    }
}

/* ─── 自定义 TaskDecorator（Spring 集成） ─── */
public class TtlTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        // TtlRunnable 会自动 capture/replay/restore
        return TtlRunnable.get(runnable);
    }
}

/* ─── 使用方式 ─── */
@Service
public class OrderService {
    @Async("taskExecutor")
    public CompletableFuture<Void> processAsync() {
        // 即使在不同线程执行，也能拿到正确的用户上下文
        UserContext user = UserContextHolder.get();
        log.info("processing order for user: {}", user.getUserId());
        return CompletableFuture.completedFuture(null);
    }
}