ThreadLocal這個東西我一開始接觸的時候覺得它不過就是個線程隔離的變量盒子直到線上出現(xiàn)了用戶數(shù)據(jù)串號的故障我才把這玩意兒從源碼到實戰(zhàn)徹底翻了個底朝天。排查那次故障時我點開線程棧去看ThreadLocal.getMap到底返回了什么才發(fā)現(xiàn)問題遠比想象中隱蔽。如果你在做Java后端開發(fā)尤其是寫完接口要處理并發(fā)、線程池、鏈路追蹤這些場景ThreadLocal絕對值得你花一天時間把它吃透。這篇文章我會把getMap背后的設(shè)計、內(nèi)存泄漏的坑、線程池下的實戰(zhàn)規(guī)范全部拆開講全部來自我真實排查和重構(gòu)代碼時積累的經(jīng)驗。1. ThreadLocal到底是什么從一次線上問題說起1.1 共享變量為什么出問題先說那次線上事故。我們有一個報表服務(wù)每個用戶請求進來之后攔截器會往ThreadLocal里塞當(dāng)前用戶的信息方便后續(xù)Service層隨時取用。上線一周后客服反饋用戶A登錄后看到了用戶B的訂單數(shù)據(jù)。這種情況屬于典型的用戶數(shù)據(jù)串號是并發(fā)場景下共享變量引發(fā)的隱性故障。裸用static變量肯定出事因為所有線程共享同一份內(nèi)存。局部變量又沒法在調(diào)用鏈里往下傳總不能每個方法都加一個參數(shù)帶上userId。那時候我們用的是ThreadLocal.set(userId)看起來隔離了但為什么還是串號呢因為服務(wù)器用線程池處理請求線程在處理完用戶A請求后不會銷毀而是被放回池里復(fù)用。如果下一次用戶B的請求被分配到同一個線程而ThreadLocal里的userId沒有清理B拿到的是A的殘留數(shù)據(jù)。這個案例引出了ThreadLocal的兩面性它確實能做線程隔離但如果不理解它的生命周期反而會制造地獄級Bug。1.2 ThreadLocal的解決思路與生活類比ThreadLocal的名字有點誤導(dǎo)直譯是“線程本地”但它本身不是線程它是存放在線程對象上的一個盒子。每個線程內(nèi)部都有一個獨立的Map叫ThreadLocalMapThreadLocal對象只是這個Map的key。當(dāng)你調(diào)用threadLocal.set(value)實際動作是把value放到當(dāng)前線程的Map里調(diào)用threadLocal.get()就是從當(dāng)前線程的Map里取出對應(yīng)key的value。我習(xí)慣用一個類比公司有一排儲物柜每個柜子對應(yīng)一個員工。員工往柜子里放私人物品別人看不到也拿不到。ThreadLocal就是那把刻著編號的鑰匙每個員工線程用自己的鑰匙打開自己的柜子存取東西。你絕不會因為拿錯了鑰匙而打開別人的柜子因為柜子本身就鎖在員工的工位號上。這個設(shè)計解決的核心痛點只有一個讓同一份數(shù)據(jù)在同一個線程的整個執(zhí)行鏈路里可以被隨時訪問同時不被其他線程污染。注意“同一個線程”這句話它是后續(xù)所有原理和坑的基石。1.3 核心API與基礎(chǔ)用法ThreadLocal的API非常少就四個常用方法set(T value)把值寫入當(dāng)前線程的ThreadLocalMap中。get()從當(dāng)前線程的ThreadLocalMap讀取值如果key不存在或已過期會返回初始值。remove()把當(dāng)前線程ThreadLocalMap中對應(yīng)的key刪掉。withInitial(Supplier? extends S supplier)創(chuàng)建時指定初始值用lambda比重寫initialValue()更簡潔。// 最簡單的用法 public class UserContext { private static final ThreadLocalLong CURRENT_USER_ID new ThreadLocal(); public static void setUserId(Long userId) { CURRENT_USER_ID.set(userId); } public static Long getUserId() { return CURRENT_USER_ID.get(); } public static void clear() { CURRENT_USER_ID.remove(); } }注意set和get是實例方法但所有線程共享同一個ThreadLocal實例。同一個實例在不同線程里會映射到各自的ThreadLocalMap的獨立條目所以天然隔離。新手容易誤以為new ThreadLocal()就自動隔離了實際上隔離的是“訪問行為”不是“對象本身”。2. 源碼級拆解getMap方法背后的秘密2.1 ThreadLocalMap的數(shù)據(jù)結(jié)構(gòu)很多看源碼的人一開始都會卡在ThreadLocalMap上因為它不是一個普通的HashMap而是一個自定義的靜態(tài)內(nèi)部類。它內(nèi)部維護了一個Entry數(shù)組Entry的key就是ThreadLocal對象value就是線程需要的值。關(guān)鍵代碼在Thread類里// Thread類內(nèi)部 ThreadLocal.ThreadLocalMap threadLocals null;每個Thread對象都持有這樣一個Map字段。而ThreadLocal.getMap(Thread t)就是把這個字段取出來// ThreadLocal類內(nèi)部 ThreadLocalMap getMap(Thread t) { return t.threadLocals; }這個方法就一行但它是理解ThreadLocal的鑰匙。因為set、get、remove所有操作的第一步都是先拿到getMap(currentThread)如果Map為空就創(chuàng)建并初始化。所以當(dāng)你使用ThreadLocal時實際上是在操作當(dāng)前線程對象里的一個Map字段而不是在操作ThreadLocal本身。ThreadLocalMap內(nèi)部為什么不直接復(fù)用HashMap因為它要做一件事探測式清理過期Entry并且key需要專門用一個繼承WeakReference的內(nèi)部類來包裝。這兩個機制是專門為內(nèi)存生命周期設(shè)計的后面展開講。2.2 get() 與 set() 的完整鏈路看get方法的源碼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; } } return setInitialValue(); }流程很清楚拿到當(dāng)前線程。通過getMap(t)獲取當(dāng)前線程的ThreadLocalMap。如果Map不為空用當(dāng)前ThreadLocal實例作為key調(diào)用getEntry(this)查Entry。如果Entry存在直接返回value。如果Map為空或Entry不存在調(diào)用setInitialValue()設(shè)置初始值。getEntry(this)不是簡單的數(shù)組按下標(biāo)取值它先根據(jù)ThreadLocal對象的哈希值定位到數(shù)組下標(biāo)如果該下標(biāo)上的Entry是當(dāng)前ThreadLocal直接返回否則會從該下標(biāo)繼續(xù)向后遍歷尋找相同的key遇到Entry的key為null表示已過期時會調(diào)用expungeStaleEntry做清理。這是get操作會觸發(fā)清理的原因之一。set方法同樣先拿到getMap(t)public void set(T value) { Thread t Thread.currentThread(); ThreadLocalMap map getMap(t); if (map ! null) { map.set(this, value); } else { createMap(t, value); } }如果當(dāng)前線程從沒用過ThreadLocalgetMap返回null就會走createMap。createMap其實就是new ThreadLocalMap(this, firstValue)這個構(gòu)造器會初始化一個默認大小16的Entry數(shù)組并設(shè)置閾值。注意一點set方法找到相同key時只覆蓋value如果key相同但value是null也會正常覆蓋不會觸發(fā)清理。只有key已經(jīng)是null的過期Entry才在set時被探測清理。2.3 為什么ThreadLocal的key是弱引用Entry的聲明長這樣static class Entry extends WeakReferenceThreadLocal? { Object value; Entry(ThreadLocal? k, Object v) { super(k); value v; } }key被包裝在WeakReference里ThreadLocal對象的強引用鏈斷掉后key就不會阻止GC回收。這是設(shè)計上最重要的決策。我打個比方ThreadLocalMap的Entry鑰匙是弱引用鎖柜子里的物品是強引用。如果ThreadLocal這個鑰匙在外面沒人拿著了Java隨手會把鑰匙收走但柜子里的物品還在這就產(chǎn)生了“鑰匙空位但值占位”的過期Entry。如果不清理這個物品就一直占著線程里的內(nèi)存。弱引用本身不是目的真正的目的是配合清理機制避免更嚴重的泄漏。但弱引用也讓過期Entry的識別變得容易key為null的Entry就是已回收鑰匙的殘留物。如果沒有弱引用而用強引用哪怕業(yè)務(wù)代碼里已經(jīng)把ThreadLocal對象設(shè)成null了Map里還牢牢握著key線程不被回收那它就一直在清理機制也無從下手。2.4 初始容量與閾值計算ThreadLocalMap的初始容量是16閾值是容量乘2除以3。這個0.66的負載因子比HashMap的0.75小是因為ThreadLocalMap的probe探測是線性尋址越早擴容越能減少沖突和過期Entry堆積。在set過程中當(dāng)數(shù)組的size超過閾值時會執(zhí)行rehash()。rehash會先做一輪全量清理把所有過期Entry刪掉如果刪完之后size仍然超過閾值減閾值/4就擴容。擴容時容量翻倍并對所有Entry重新計算下標(biāo)。這里下標(biāo)不是普通的hash取模而是根據(jù)ThreadLocal的threadLocalHashCode位運算得到的private final int threadLocalHashCode nextHashCode(); private static AtomicInteger nextHashCode new AtomicInteger(); private static final int HASH_INCREMENT 0x61c88647;0x61c88647是斐波那契散列的黃金分割數(shù)它能讓ThreadLocal哈希碼在數(shù)組長度取模后的分布比較均勻避免rehash和探測鏈過長。這個細節(jié)知道即可面試會加分但實戰(zhàn)中不需要重寫。3. 內(nèi)存泄漏與ThreadLocalMap的探針清理機制3.1 內(nèi)存泄漏場景重現(xiàn)很多人一提ThreadLocal就說“會內(nèi)存泄漏”這話只說對了一半。嚴格說ThreadLocal本身不會必然泄漏關(guān)鍵在于“Thread對象長命而ThreadLocal對象短命”的組合。出一個最經(jīng)典的場景你寫了一個靜態(tài)的ThreadLocal變量在線程里set了一個大對象比如幾十MB的List但用完后既沒有remove也沒法讓ThreadLocal對象被回收因為靜態(tài)變量一直持有著它的強引用。線程回收到線程池后這個線程繼續(xù)生存于是它Map里的過期Entry就牢牢拽著哪個大對象。線程池里幾百個線程每個都殘留幾十MBOOM分分鐘的事。更隱蔽的是Tomcat這類Servlet容器它們默認也會用線程池處理請求而且會根據(jù)并發(fā)量調(diào)整線程數(shù)量。線程不消亡ThreadLocalMap里的殘留值就一直占用堆內(nèi)存。3.2 expungeStaleEntry探測清理JDK在設(shè)計時已經(jīng)考慮了這種風(fēng)險所以提供了“探測式清理”的兜底。核心方法就是expungeStaleEntry(int staleSlot)。它做三件事把staleSlot位置上的Entry的value置為null并把這個位置清空。從staleSlot的下一個位置開始遍歷數(shù)組直到遇到null槽位。在遍歷過程中如果遇到Entry的key為null同樣釋放value并清空位置這叫連續(xù)清理如果Entry的key不為null會重新計算它的哈希下標(biāo)如果下標(biāo)和當(dāng)前槽位不一致就挪到更近的、更合適的空位這本質(zhì)是一次就地rehash。這個清理動作不是全表掃描整個Map而是從過期位置開始向后探測到第一個空槽為止。這樣在元素不多時清理成本可控。get和set方法里遇到過期Entry時都會觸發(fā)這個清理。還有一處叫cleanSomeSlots在每次插入或者替換value時對數(shù)級別的遍歷一些槽位來掃描過期Entry。這些機制合起來就是盡量降低過期Entry對內(nèi)存的長期占用。但它們都不是交易性的替代品只是“盡力而為”的清理。3.3 線程池復(fù)用場景下的致命坑線程池復(fù)用時線程本體存活期可能覆蓋幾十上百個業(yè)務(wù)請求。假如業(yè)務(wù)代碼里每個請求都set了一個新對象但不remove下一次請求復(fù)用這條線程時如果ThreadLocal實例是同一個靜態(tài)變量set會覆蓋舊value不會累積但如果你每次動態(tài)new ThreadLocal()只在一個請求里使用那這個ThreadLocal對象沒有外部強引用key變成nullvalue就殘留了。即使不new新ThreadLocal如果value是那種重型的、帶有連接資源或緩存內(nèi)容的引用舊的value被新value覆蓋前依然活著直到下一次set觸發(fā)覆蓋和清理路徑覆蓋本身其實沒問題問題在于生命周期被無謂拉長。我見過一個最典型的錯誤寫法是在RPC框架里用ThreadLocal存儲請求上下文代碼長這樣RequestContext context new RequestContext(); context.setTraceId(traceId); CONTEXT_THREAD_LOCAL.set(context); // 調(diào)服務(wù) Object result rpcService.call(); // 忘記remove這個RPC線程如果來自公共線程池traceId和整個請求上下文就會泄漏給下一個被復(fù)用同一個線程的請求。輕則日志串traceId重則權(quán)限上下文套用用戶數(shù)據(jù)串號。線程池場景下必須在finally里remove。正確模板try { contextHolder.set(userContext); doBiz(); } finally { contextHolder.remove(); }永遠不要把清理動作放在try之外也不要放在if分支里。finally是唯一可靠的位置。4. 實戰(zhàn)業(yè)務(wù)系統(tǒng)中的ThreadLocal使用規(guī)范4.1 上下文信息透傳userId、traceId最常見的場景就是登錄態(tài)和鏈路追蹤。我在項目里通常封裝兩個獨立的上下文工具類一個存用戶身份一個存鏈路日志信息。用戶身份上下文的實現(xiàn)要格外謹慎因為它涉及權(quán)限。我不建議直接把整個用戶對象塞進去更建議只塞userId或userIdtenantId。對象塞進去雖然方便但也會帶來兩個問題一是對象體積大殘留內(nèi)存更明顯二是如果對象里還掛著一堆懶加載的數(shù)據(jù)庫代理對象線程池場景下可能在讀的時候拋異常。鏈路追蹤的traceId也推薦用ThreadLocal因為一個請求在同一個線程內(nèi)的所有日志關(guān)鍵字段都可以通過MDC切面自動注入。Spring Boot下用logback的MDC時底層就是ThreadLocalMap。如果不用MDC而是自己寫traceId透傳同樣要小心線程池場景下的隔離問題。4.2 線程池場景下必須remove嗎遇到“必須”兩個字我的回答是并不是所有情況下都必須要remove只要你的ThreadLocal的key是全局靜態(tài)的并且value可以被覆蓋不remove在大多數(shù)業(yè)務(wù)場景不會產(chǎn)生串號。比如只存一個當(dāng)前線程生成的隨機批次號下一個請求進來set覆蓋了舊值舊值在覆蓋時被回收從功能層面看不出問題。但這樣寫等于把正確性押注在了“下一次一定會有set”這個假設(shè)上。如果代碼里有些分支根本不set,直接get那就會讀到上一個請求留下的值。這也是很多莫名其妙的偶發(fā)Bug的來源。所以我在團隊里的編碼規(guī)范強制要求凡是在業(yè)務(wù)入口往ThreadLocal set了內(nèi)容必須在當(dāng)前處理流程結(jié)束時在finally里remove。不要依賴覆蓋不要依賴清理機制。理由很簡單remove的代價幾乎為零而不remove的風(fēng)險是串號和泄漏。4.3 InheritableThreadLocal和TransmittableThreadLocal的選型父線程想把自己的ThreadLocal傳給子線程最簡單的是InheritableThreadLocal。它在線程創(chuàng)建時用父線程Map里的值初始化子線程的Map。這在一個請求里創(chuàng)建少量子線程、且子線程不會復(fù)用時會比較有用。但InheritableThreadLocal有兩個缺陷第一它只能在線程創(chuàng)建的那一瞬間拷貝一次線程池里的線程早就創(chuàng)建好了不會動態(tài)獲取父線程最新值第二拷貝是淺拷貝如果value是可變對象子線程改了會影響父線程反之亦然。真正應(yīng)對異步和線程池場景的是阿里開源的TransmittableThreadLocalTTL。它給線程池的每個任務(wù)包裝了一層裝飾器任務(wù)提交時捕獲當(dāng)前線程ThreadLocal快照任務(wù)執(zhí)行前把快照放到執(zhí)行任務(wù)的線程里任務(wù)結(jié)束再恢復(fù)。我做過一次選型對比結(jié)論是純串行執(zhí)行直接用ThreadLocal。簡單創(chuàng)建一次性子線程InheritableThreadLocal夠用。線程池異步執(zhí)行、需要透傳traceId或用戶上下文必須用TTL包裝線程池。TTL的使用很簡單比如TtlExecutors.getTtlExecutorService(executorService)或者用TtlRunnable.get(runnable)。這是目前解決線程池透傳最成熟的方案沒有之一。4.4 參數(shù)配置與性能影響ThreadLocal的讀寫性能非常高因為它是純內(nèi)存數(shù)組操作沒有鎖。在單線程持續(xù)訪問場景下要比ConcurrentHashMap快得多。但有些人誤以為ThreadLocal支持跨線程共享這是不準(zhǔn)確的。對性能影響最大的其實不是讀寫本身而是清理和擴容。如果一個線程里使用的ThreadLocal數(shù)量極多比如超過16個Map就會反復(fù)觸發(fā)rehash和cleanSomeSlots每次插入都可能做額外的探測掃描。不過一般的業(yè)務(wù)場景里線程的ThreadLocal數(shù)量都在個位數(shù)完全不用焦慮。值得注意的倒是JVM參數(shù)和線程數(shù)量。如果你的線程池線程數(shù)很大又有大量大對象放在ThreadLocal里不清理老年代會快速膨脹。排查時可以堆dump看吧看到大量ThreadLocalMap$Entry帶著大對象指向業(yè)務(wù)類八成就是沒remove了。5. 常見問題與排查技巧實錄5.1 為什么ThreadLocal.get()返回nullget返回null常見有四種原因第一次調(diào)用get之前沒有調(diào)用過set并且初始值也沒有設(shè)置。當(dāng)前線程不是之前set的那個線程。比如你用異步線程執(zhí)行任務(wù)子線程里get不到父線程set的值。ThreadLocal對象不是同一個實例。比如每次方法里都new一個ThreadLocal后續(xù)自然讀不到。已經(jīng)執(zhí)行了remove后續(xù)又去get。其中第三點最隱蔽。尤其在一些工具類里寫成了靜態(tài)方法但方法內(nèi)部用new ThreadLocal()來存取那每次調(diào)用都是全新的key完全無法產(chǎn)生隔離效果。5.2 鏈路追蹤中ThreadLocal不生效我們遇到過的一個問題在主線程設(shè)置的traceId子線程打印時丟失。那時候根本沒用InheritableThreadLocal用的是普通ThreadLocal所以子線程的Map是空的自然get不到。后來用異步HttpClient或者MQ生產(chǎn)者時也有類似問題。MQ生產(chǎn)者發(fā)送消息時消息體里需要攜帶traceId但如果traceId放在ThreadLocal且發(fā)送回調(diào)再另一個線程回調(diào)里get就是null。正確做法是在發(fā)送前的入口線程把traceId取出來顯式塞到消息頭不要等到發(fā)送回調(diào)再去ThreadLocal里找。排查這類問題可以在關(guān)鍵入口和出口打點打印線程名和Thread.currentThread().getId()立刻能看出是不是線程發(fā)生了切換。5.3 如何用arthas檢查ThreadLocalMap內(nèi)容線上排查ThreadLocal殘留我喜歡用arthas。用thread命令列出所有線程找到目標(biāo)線程ID后通過getstatic或者ognl表達式訪問Thread實例的threadLocals字段。示例thread -n 1 # 找到目標(biāo)線程的id之后 ognl -x 3 #tjava.lang.ThreadgetAllStackTraces().keySet()[0], #t.getThreadLocals()不過我實際中更常用的思路是直接heap dump后用MAT或jhat搜索ThreadLocalMap$Entry看它的value是否有業(yè)務(wù)對象殘留。arthas適合快速確認某個線程里有沒有值但要把整個池子的殘留清點一遍還是dump更直觀。5.4 熱點排查速查表癥狀可能原因快速解法線程池復(fù)用時出現(xiàn)上一個用戶的數(shù)據(jù)ThreadLocal未remove在finally里remove日志traceId亂串線程池線程復(fù)用時traceId未清理用TTL或每次任務(wù)執(zhí)行前set老年代漲得快內(nèi)存泄漏ThreadLocal里放了大對象Dumpheap確認并remove異步子線程get不到值線程切換用TransmittableThreadLocal或顯式傳參兩個類各自讀取的ThreadLocal相互覆蓋使用了同名靜態(tài)變量或非靜態(tài)實例確保ThreadLocal是final static且序號唯一最后再分享一個小細節(jié)我后來把所有ThreadLocal變量都封裝成獨立的Context類提供靜態(tài)方法對上層只暴露set/get/clear。初期多花一點建模時間能避免后面排查時滿世界找不到ThreadLocal的坑。每次清完用戶上下文記得在clear里順便把可能嵌套的其他ThreadLocal一并remove防住那種一個請求里同時用了多個上下文工具類卻只清理一個的場景。