Java ThreadLocal 核心原理與實戰：線程隔離變量的正確使用姿勢

經典應用場景

實戰：鏈路追蹤 TraceId 自動傳遞

public final class TraceContext {
    private static final ThreadLocal TRACE_ID = ThreadLocal.withInitial(() -> UUID.randomUUID().toString().replace("-", ""));
    private static final ThreadLocal SPAN_ID = ThreadLocal.withInitial(() -> "0");

    public static String getTraceId() { return TRACE_ID.get(); }
    public static String getSpanId() { return SPAN_ID.get(); }
    public static void setTraceId(String traceId) { TRACE_ID.set(traceId); }
    public static void setSpanId(String spanId) { SPAN_ID.set(spanId); }
    public static void clear() { TRACE_ID.remove(); SPAN_ID.remove(); }

    /** 子 Span 生成 */
    public static String nextSpanId() {
        String parent = SPAN_ID.get();
        String child = parent + "." + (parent.split("\\.").length + 1);
        SPAN_ID.set(child);
        return child;
    }
}

// Filter 中調用
@Component @Order(1)
public class TraceFilter implements Filter {
    @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        String traceId = ((HttpServletRequest)req).getHeader("X-Trace-Id");
        if (traceId != null) TraceContext.setTraceId(traceId);
        try { chain.doFilter(req, res); }
        finally { TraceContext.clear(); } // 必須清理，防內存洩漏
    }
}

// Logback Pattern 引用
%d{yyyy-MM-dd HH:mm:ss} [%X{traceId}] %msg%n

內存洩漏陷阱與防範

⚠️ 核心原因：ThreadLocalMap 的 Key 是 WeakReference。當 ThreadLocal 對象被 GC 回收（如動態創建的匿名類），Key 變 null，但 Value 強引用仍存活，導致 Entry 永駐 Map，隨線程池線程長期存活 → OOM。

防範三板斧

1. 静態常量持有 ThreadLocal：private static final ThreadLocal TL = ThreadLocal.withInitial(...)，確保 Key 永不被 GC；
2. 用完必調 remove()：try { ... } finally { TL.remove(); }，尤其在線程池場景；
3. 避免動態創建 ThreadLocal：循環/請求中 `new ThreadLocal<>()` 會產生大量弱引用 Key 殭屍 Entry。

InheritableThreadLocal：父子線程傳遞

// 父線程設置
InheritableThreadLocal ctx = new InheritableThreadLocal<>();
ctx.set("parent-value");

// 子線程自動繼承副本
new Thread(() -> System.out.println(ctx.get())).start(); // 輸出 parent-value

注意：線程池復用線程時，不會自動繼承（因非新建線程）。需配合 ThreadPoolTaskDecorator (Spring) 或手動傳遞。

生產級替代：TransmittableThreadLocal (TTL)

    com.alibaba
    transmittable-thread-local
    2.14.1

// TTL 自動傳遞給線程池子任務
TransmittableThreadLocal ttl = new TransmittableThreadLocal<>();
ttl.set("trace-123");
executor.submit(() -> System.out.println(ttl.get())); // 輸出 trace-123

阿里開源 TTL 解決了線程池場景下的上下文傳遞難題，廣泛用於鏈路追蹤、租戶隔離等領域。

總結

1. ThreadLocal 實現線程隔離，核心場景：上下文傳遞、非線程安全對象複用、請求級緩存；
2. 靜態常量 + try-finally remove() 是防內存洩漏鐵律；
3. 線程池場景必須用 TTL 或手動裝飾器傳遞上下文；
4. 濫用 ThreadLocal 會導致代碼隱式依賴難追蹤，僅在「跨層傳遞參數極其痛苦」時使用。