做后端這些年我最怕的不是業(yè)務(wù)邏輯復(fù)雜而是那些看起來(lái)平平無(wú)奇的第三方API調(diào)用。它們藏在你代碼里的任何一個(gè)角落平時(shí)靜如處子一旦線上流量上來(lái)立刻教你做人內(nèi)存飆紅、線程池打滿、響應(yīng)一個(gè)比一個(gè)慢。更折磨人的是你翻半天日志異常信息要么根本沒(méi)有要么跟事故現(xiàn)場(chǎng)八竿子打不著。這篇文章就是我從一堆API調(diào)用事故里挑出來(lái)的精煉復(fù)盤——15個(gè)出現(xiàn)頻率最高的使用錯(cuò)誤每個(gè)都給你講明白背后的原因、現(xiàn)場(chǎng)長(zhǎng)什么樣、怎么解決以及真出事的時(shí)候怎么快速定位。內(nèi)容覆蓋內(nèi)存泄漏、異步傳輸異常、連接管理、序列化、冪等性、重試策略這些高頻雷區(qū)適合所有寫(xiě)業(yè)務(wù)代碼時(shí)經(jīng)常跟RESTful API、消息隊(duì)列、第三方SDK打交道的開(kāi)發(fā)者。1. API使用錯(cuò)誤為什么總是防不勝防1.1 錯(cuò)誤的本質(zhì)不是不會(huì)調(diào)而是生命周期管理不到位先說(shuō)個(gè)結(jié)論絕大多數(shù)API調(diào)用錯(cuò)誤并不是因?yàn)槟悴粫?huì)調(diào)API而是對(duì)一次調(diào)用從生到死的完整鏈路缺少掌控。一次普通的HTTP請(qǐng)求涉及的東西遠(yuǎn)不止發(fā)出去、收回來(lái)這兩步——連接怎么建立、響應(yīng)流什么時(shí)候關(guān)閉、超時(shí)誰(shuí)來(lái)兜底、異常往哪拋、回調(diào)在哪個(gè)線程跑、內(nèi)存里的響應(yīng)體何時(shí)釋放這些環(huán)節(jié)只要有一個(gè)疏忽線上就會(huì)積累隱患。我見(jiàn)過(guò)太多代碼把API調(diào)用當(dāng)成一次性買賣new一個(gè)客戶端對(duì)象發(fā)起請(qǐng)求拿到結(jié)果然后……就沒(méi)有然后了。對(duì)象沒(méi)人關(guān)流沒(méi)人關(guān)異常沒(méi)人理。短時(shí)間看不出問(wèn)題連續(xù)跑幾個(gè)小時(shí)或者流量翻倍內(nèi)存就肉眼可見(jiàn)地往上爬。這種問(wèn)題最坑的地方在于它不是立刻爆炸而是慢慢爛掉等你去查的時(shí)候現(xiàn)場(chǎng)早就被各種無(wú)關(guān)日志淹沒(méi)了。所以這篇文章的底層思路就一條把API調(diào)用當(dāng)成一個(gè)有生命周期的完整事務(wù)來(lái)管理。連接、請(qǐng)求、響應(yīng)、異常、資源釋放、數(shù)據(jù)轉(zhuǎn)換每一個(gè)環(huán)節(jié)都要有明確的歸屬和兜底方案。下面這15個(gè)錯(cuò)誤本質(zhì)上都是生命周期某個(gè)環(huán)節(jié)掉了鏈子。1.2 事故的三級(jí)跳從偶發(fā)超時(shí)到服務(wù)不可用根據(jù)我的觀察API濫用引發(fā)的事故幾乎總是沿著同樣的路徑發(fā)展。第一級(jí)偶發(fā)超時(shí)和零星報(bào)錯(cuò)。日志里偶爾出現(xiàn)TimeoutException、Connection reset但重試一下就好了沒(méi)人當(dāng)回事。第二級(jí)內(nèi)存和線程資源告警。隨著流量上來(lái)內(nèi)存曲線變成鋸齒狀線程池活躍度居高不下GC越來(lái)越頻繁。這是資源泄漏的典型信號(hào)。第三級(jí)連鎖故障。某個(gè)依賴服務(wù)的API徹底不可用線程池被打滿新請(qǐng)求全部排隊(duì)最終整個(gè)應(yīng)用假死。你發(fā)現(xiàn)沒(méi)有第一級(jí)出現(xiàn)的時(shí)候其實(shí)才是最好修的時(shí)機(jī)。但絕大多數(shù)團(tuán)隊(duì)都會(huì)拖到第三級(jí)。下面這些錯(cuò)誤每一個(gè)都可能成為引爆第二級(jí)和第三級(jí)的導(dǎo)火索越早處理越好。2. 內(nèi)存泄漏歸檔四個(gè)最常見(jiàn)的隱形殺手2.1 錯(cuò)誤一只調(diào)用API不關(guān)閉響應(yīng)流這是Java系和Python系新手最容易踩的坑而且?guī)缀趺刻於加腥瞬?。起因很?jiǎn)單很多HTTP客戶端庫(kù)在發(fā)起請(qǐng)求后返回的響應(yīng)對(duì)象底層是持有一個(gè)輸入流的這個(gè)流承載著網(wǎng)絡(luò)連接。你不關(guān)閉它連接就永遠(yuǎn)無(wú)法歸還給連接池最終還是撐爆進(jìn)程的文件描述符。舉個(gè)最典型的反例// 反面教材 HttpClient client HttpClient.newHttpClient(); HttpResponseString response client.send(request, BodyHandlers.ofString()); String body response.body(); // 看起來(lái)是拿到了字符串實(shí)際上底層InputStream沒(méi)關(guān)這段代碼在Java 11的HttpClient里BodyHandlers.ofString()看似已經(jīng)把流讀干凈了但底層socket通道依然占用著。真正嚴(yán)格的做法是用ofInputStream()配合try-with-resources或者顯式關(guān)閉。Python的requests庫(kù)沒(méi)有這個(gè)問(wèn)題因?yàn)樗诘讓訋湍阕隽饲謇淼绻阌玫氖莚equests的流式響應(yīng)# Python里流式響應(yīng)不主動(dòng)關(guān)閉連接也會(huì)泄漏 resp requests.get(url, streamTrue) data resp.content # resp.close() 忘了調(diào)解決方案其實(shí)就一句話凡是能返回流的API必須保證流的關(guān)閉時(shí)機(jī)與你使用它的生命周期嚴(yán)格對(duì)應(yīng)。Java系優(yōu)先用try-with-resourcesPython優(yōu)先用with或try/finally。提示判斷你有沒(méi)有犯這個(gè)錯(cuò)最直接的辦法是看線上日志里有沒(méi)有大量Connection reset by peer、Too many open files。這兩個(gè)報(bào)錯(cuò)十有八九是響應(yīng)流沒(méi)關(guān)。2.2 錯(cuò)誤二長(zhǎng)生命周期對(duì)象持有短生命周期引用如果說(shuō)關(guān)流是新手坑那這個(gè)就是老手也容易犯的經(jīng)典錯(cuò)誤。場(chǎng)景通常是你在一個(gè)長(zhǎng)期存活的組件里比如單例服務(wù)、全局管理器持有一個(gè)Map或List把API響應(yīng)結(jié)果或請(qǐng)求上下文往里面塞但用完之后忘了移除。舉個(gè)我實(shí)際排查過(guò)的案例某系統(tǒng)的網(wǎng)關(guān)層為了緩解下游壓力把外部API的響應(yīng)按請(qǐng)求參數(shù)緩存到一個(gè)靜態(tài)ConcurrentHashMap里。參數(shù)組合是無(wú)窮的緩存卻從不清理上線兩周后堆內(nèi)存直接爆掉。我當(dāng)時(shí)做dump分析發(fā)現(xiàn)這個(gè)Map占用了堆內(nèi)存的68%。解決這類問(wèn)題有兩種思路如果緩存是必要的必須引入淘汰機(jī)制。最簡(jiǎn)單的用一個(gè)固定容量的LRU容器或者給緩存加TTL配合后臺(tái)任務(wù)定時(shí)清理。不要相信這段代碼很快會(huì)重構(gòu)這種話。如果緩存不是必要的直接刪除靜態(tài)持有。內(nèi)存泄漏的本質(zhì)不是對(duì)象太多而是對(duì)象被不該持有它的對(duì)象一直引用著導(dǎo)致GC無(wú)法回收。不要讓你的一次性數(shù)據(jù)跑到長(zhǎng)生命周期容器里。2.3 錯(cuò)誤三靜態(tài)集合無(wú)界增長(zhǎng)把內(nèi)存當(dāng)數(shù)據(jù)庫(kù)用跟錯(cuò)誤二很像但更隱蔽。這類問(wèn)題往往是順手造成的——業(yè)務(wù)代碼里需要一個(gè)臨時(shí)的統(tǒng)計(jì)容器、一個(gè)事件回調(diào)注冊(cè)表、一個(gè)請(qǐng)求追蹤列表直接用靜態(tài)字段或者全局單例的Map裝起來(lái)。結(jié)果這個(gè)臨時(shí)容器比業(yè)務(wù)代碼活得還久。舉一個(gè)典型的消息推送SDK的例子SDK內(nèi)部維護(hù)了一個(gè)回調(diào)注冊(cè)表每次調(diào)用registerCallback()就把回調(diào)對(duì)象存進(jìn)一個(gè)靜態(tài)列表。如果SDK使用者沒(méi)有調(diào)用對(duì)應(yīng)的unregisterCallback()那么這個(gè)回調(diào)對(duì)象以及它捕獲的所有變量注意Java/Python的閉包是會(huì)捕獲外部作用域變量的就永遠(yuǎn)不會(huì)被回收。這種問(wèn)題我建議從API設(shè)計(jì)層面解決凡是提供注冊(cè)類方法的SDK或工具類必須同時(shí)提供對(duì)應(yīng)的注銷方法而且文檔里要用醒目的方式寫(xiě)清楚。如果你是自己寫(xiě)代碼原則就一條注冊(cè)了什么用完必須注銷跟鎖一樣加鎖的地方必須有解鎖。2.4 錯(cuò)誤四監(jiān)聽(tīng)器/回調(diào)注冊(cè)后壓根不注銷這個(gè)在WebSocket長(zhǎng)連接、消息訂閱、事件總線的場(chǎng)景里特別常見(jiàn)。很多開(kāi)發(fā)者只關(guān)注怎么訂閱完全不關(guān)注什么時(shí)候取消訂閱。短連接問(wèn)題不大長(zhǎng)連接場(chǎng)景下你每訂閱一次就是往事件總線的監(jiān)聽(tīng)器列表里加一個(gè)對(duì)象反復(fù)建立連接再斷開(kāi)監(jiān)聽(tīng)器越積越多。我遇到過(guò)最離譜的一個(gè)案例某交易系統(tǒng)的行情訂閱模塊每次斷線重連都會(huì)new一個(gè)新的監(jiān)聽(tīng)器注冊(cè)到事件總線但不移除舊的。業(yè)務(wù)高峰期經(jīng)歷了幾百次重連之后每次行情推送都要遍歷幾萬(wàn)個(gè)月久失修的監(jiān)聽(tīng)器對(duì)象CPU直接打滿GC耗時(shí)從50毫秒漲到3秒。解決方案分兩層應(yīng)用層在重連、會(huì)話銷毀的鉤子里必須先解除舊監(jiān)聽(tīng)器再注冊(cè)新監(jiān)聽(tīng)器?？蚣軐尤绻阕约簩?xiě)發(fā)布訂閱組件建議對(duì)每個(gè)訂閱者維護(hù)一個(gè)弱引用集合WeakHashMap或弱引用隊(duì)列這樣即使調(diào)用方忘記注銷只要業(yè)務(wù)對(duì)象不再被強(qiáng)引用GC也能正常回收至少不會(huì)造成內(nèi)存泄漏爆炸。內(nèi)存泄漏這部分總結(jié)一下99%的API相關(guān)內(nèi)存泄漏本質(zhì)都是資源或?qū)ο鬀](méi)有沿著它的生命周期被正確釋放。你在寫(xiě)調(diào)用代碼的那一刻就要問(wèn)自己三件事這個(gè)連接什么時(shí)候關(guān)這個(gè)對(duì)象什么時(shí)候不再被引用如果調(diào)用方忘了釋放系統(tǒng)能自愈嗎3. 異步傳輸異常回調(diào)、線程與并發(fā)亂局3.1 錯(cuò)誤五異步異常沒(méi)人接直接黑盒消失異步API和同步API最大的區(qū)別在于同步方法里try-catch能兜住異常異步方法里異常發(fā)生的位置和時(shí)機(jī)是漂移的你沒(méi)在正確的地方接住它它就會(huì)默默消失。用CompletableFuture舉例// 反面教材異常丟失 CompletableFuture.supplyAsync(() - apiClient.callRemote()) .thenApply(response - parse(response)); // 如果apiClient.callRemote()拋異常這個(gè)異常沒(méi)人處理你看著好像流程沒(méi)問(wèn)題但實(shí)際線上是某個(gè)請(qǐng)求靜默失敗日志里什么都沒(méi)有。更麻煩的是如果異常是在回調(diào)鏈的中間階段拋出的而你沒(méi)有在每個(gè)thenApply/exceptionally之間接住后面的所有環(huán)節(jié)都不會(huì)執(zhí)行且沒(méi)有任何記錄。正確做法是給每條異步鏈路的終點(diǎn)加一個(gè)全局兜底處理。CompletableFuture.supplyAsync(() - apiClient.callRemote()) .thenApply(response - parse(response)) .exceptionally(ex - { // 記錄完整異常棧和關(guān)鍵上下文 logger.error(api call failed, context{}, traceId, ex); return defaultResult; });Python的asyncio里對(duì)應(yīng)的問(wèn)題則是忘記await協(xié)程。很多Python開(kāi)發(fā)者以為調(diào)用了異步函數(shù)就等于執(zhí)行了實(shí)際上如果你不await協(xié)程只是被創(chuàng)建異常堆棧會(huì)被event loop打印一段警告然后丟掉業(yè)務(wù)上表現(xiàn)為偶爾丟失一條數(shù)據(jù)某個(gè)任務(wù)沒(méi)執(zhí)行但不知道為啥。記住一句話異步代碼里異常要靠鏈?zhǔn)教幚聿皇悄銓?xiě)了try-catch就萬(wàn)事大吉要確保try-catch放在正確的位置并且每一層異步轉(zhuǎn)換函數(shù)都要處理錯(cuò)誤分支。3.2 錯(cuò)誤六超時(shí)設(shè)置缺失或設(shè)置不合理一次API調(diào)用涉及多個(gè)超時(shí)維度很多人就設(shè)一個(gè)timeout參數(shù)其實(shí)遠(yuǎn)遠(yuǎn)不夠。最典型的HTTP請(qǐng)求至少有三個(gè)超時(shí)連接超時(shí)建立TCP連接的最大等待時(shí)間。讀取超時(shí)等待響應(yīng)數(shù)據(jù)的最大間隔時(shí)間。整體請(qǐng)求超時(shí)整次調(diào)用的總時(shí)長(zhǎng)上限。如果你只設(shè)了連接超時(shí)比如10秒但讀取超時(shí)用默認(rèn)的0表示無(wú)限等待那么一旦對(duì)端收到請(qǐng)求后一直不返回?cái)?shù)據(jù)你的線程就會(huì)無(wú)限期掛在那。線上表現(xiàn)就是線程池被一群半死不活的連接占滿新請(qǐng)求全部排隊(duì)系統(tǒng)吞吐量崩塌。我做過(guò)一次線程池監(jiān)控發(fā)現(xiàn)某個(gè)服務(wù)有40%的線程處于WAITING狀態(tài)超過(guò)2分鐘原因就是對(duì)端服務(wù)在GC時(shí)有長(zhǎng)達(dá)數(shù)十秒的停頓而我們這邊的讀取超時(shí)是無(wú)窮大。修復(fù)方式很簡(jiǎn)單給每個(gè)維度設(shè)置合理的超時(shí)并遵循一個(gè)原則整體請(qǐng)求超時(shí)必須大于連接超時(shí)和讀取超時(shí)但小于你所在線程池能容忍的最大等待時(shí)間。常見(jiàn)的合理配置是連接超時(shí)3~5秒讀取超時(shí)10~30秒整體超時(shí)不超過(guò)60秒。具體看業(yè)務(wù)對(duì)實(shí)時(shí)性的要求但我強(qiáng)烈建議你寧可超時(shí)設(shè)短一點(diǎn)觸發(fā)重試也不要設(shè)超長(zhǎng)把線程全拖死。3.3 錯(cuò)誤七線程池配置不當(dāng)導(dǎo)致的異步變同步與線程泄漏異步API通過(guò)回調(diào)或Future解耦了調(diào)用方線程但如果你把異步任務(wù)丟進(jìn)一個(gè)線程池里執(zhí)行線程池本身就會(huì)成為新的瓶頸。常見(jiàn)的兩個(gè)錯(cuò)誤第一線程池核心線程數(shù)設(shè)為0或過(guò)小配合無(wú)界隊(duì)列。某個(gè)項(xiàng)目里用new ThreadPoolExecutor(0, Integer.MAX_VALUE, 60L, TimeUnit.SECONDS, new SynchronousQueue())看似很靈活實(shí)際上每來(lái)一個(gè)任務(wù)就new一個(gè)線程線程創(chuàng)建開(kāi)銷極大高并發(fā)下線程數(shù)飆到幾千CPU光在線程切換上就耗掉大半。線程池要按業(yè)務(wù)量預(yù)估并發(fā)度核心線程數(shù)建議設(shè)置為機(jī)器可用核數(shù)的2倍到4倍并設(shè)置一個(gè)有界隊(duì)列滿了之后走拒絕策略或調(diào)用方兜底。第二把異步回調(diào)里又嵌套了同步阻塞調(diào)用。比如在異步回調(diào)里調(diào)用另一個(gè)同步API且不設(shè)置超時(shí)這個(gè)回調(diào)線程就被卡住了線程池的活躍線程只會(huì)越來(lái)越多最終整個(gè)池子被長(zhǎng)連接占滿后續(xù)任務(wù)全部排隊(duì)。這種情況算線程泄漏。排查線程池問(wèn)題有個(gè)很直觀的手段周期性打印線程池的活躍線程數(shù)、隊(duì)列長(zhǎng)度、拒絕次數(shù)。這三個(gè)指標(biāo)任何一個(gè)持續(xù)增長(zhǎng)都要立刻定位原因。尤其是拒絕次數(shù)從0變成非0的那一刻基本宣告線程池已滿。3.4 錯(cuò)誤八共享可變狀態(tài)引發(fā)的并發(fā)數(shù)據(jù)錯(cuò)亂這是并行調(diào)用同一API的衍生問(wèn)題。多個(gè)線程同時(shí)調(diào)用外部API時(shí)如果代碼里用了共享的可變狀態(tài)來(lái)存中間結(jié)果就會(huì)產(chǎn)生競(jìng)態(tài)條件。最常見(jiàn)的兩個(gè)場(chǎng)景用同一個(gè)SimpleDateFormat非線程安全做時(shí)間格式化導(dǎo)致解析結(jié)果隨機(jī)出錯(cuò)。多線程同時(shí)寫(xiě)同一個(gè)非線程安全的Map或List輕則數(shù)據(jù)覆蓋重則拋出ConcurrentModificationException。還有一類尤其隱蔽ThreadLocal使用后不清理。很多API做身份信息或租戶信息的上下文傳遞時(shí)會(huì)用ThreadLocal。但如果你用了線程池線程是復(fù)用的上一次請(qǐng)求的ThreadLocal數(shù)據(jù)會(huì)殘留到下一次請(qǐng)求里。正確做法是在請(qǐng)求結(jié)束的finally塊里調(diào)用ThreadLocal.remove()。解決并發(fā)問(wèn)題的原則很簡(jiǎn)單優(yōu)先讓變量局部化每個(gè)請(qǐng)求都有自己的上下文對(duì)象不要在多個(gè)線程之間共享可變數(shù)據(jù)。必須要共享的用線程安全容器或者加鎖并清楚鎖的粒度。3.5 錯(cuò)誤九回調(diào)地獄與信號(hào)丟失異步API經(jīng)常需要在一個(gè)回調(diào)完成后再發(fā)起另一個(gè)調(diào)用代碼會(huì)層層嵌套。除了可讀性差更致命的問(wèn)題是如果中間某一步回調(diào)沒(méi)有被觸發(fā)整條鏈路就會(huì)死等。比如上游服務(wù)回調(diào)協(xié)議里設(shè)置了2秒超時(shí)但代碼沒(méi)做超時(shí)處理網(wǎng)絡(luò)丟包時(shí)回調(diào)永遠(yuǎn)不會(huì)來(lái)請(qǐng)求就掛在那一直到進(jìn)程退出。解決這個(gè)問(wèn)題的核心工具是超時(shí)信號(hào)機(jī)制。以JavaScript的Promise.race為例function callWithTimeout(promise, timeoutMs) { let timer; const timeoutPromise new Promise((_, reject) { timer setTimeout(() reject(new Error(timeout)), timeoutMs); }); return Promise.race([promise, timeoutPromise]).finally(() clearTimeout(timer)); }這個(gè)模式在Java里可以借助Future.get(timeout)或者CompletableFuture.orTimeout()實(shí)現(xiàn)。核心思想就一句任何異步調(diào)用都必須在規(guī)定時(shí)間內(nèi)產(chǎn)生一個(gè)明確結(jié)果成功或失敗不能允許無(wú)限期不明不白地等待。4. 協(xié)議與數(shù)據(jù)層連接池、冪等、序列化與分頁(yè)的坑4.1 錯(cuò)誤十HTTP連接池配置與實(shí)際壓測(cè)嚴(yán)重不符HTTP客戶端大多有連接池機(jī)制來(lái)復(fù)用TCP連接但很多人只改一個(gè)maxConnections參數(shù)就覺(jué)得夠了其實(shí)坑遠(yuǎn)不止這個(gè)。連接池至少要關(guān)注三個(gè)維度每個(gè)路由的最大連接數(shù)如果你調(diào)用的是多個(gè)域名的API總連接數(shù)不等于每個(gè)域名都能分到maxConnections。默認(rèn)情況下每個(gè)主機(jī)的連接數(shù)上限跟總連接數(shù)上限是分開(kāi)的只調(diào)總連接數(shù)而忽略maxConnectionsPerHost仍然會(huì)在高并發(fā)下創(chuàng)建大量新連接?？臻e連接存活時(shí)間連接池里的空閑連接如果長(zhǎng)時(shí)間不用會(huì)被服務(wù)端斷開(kāi)。很多連接池默認(rèn)的evictIdleConnections間隔很長(zhǎng)你以為復(fù)用的是老連接實(shí)際每次請(qǐng)求都要重新握手表現(xiàn)為大量TCP握手時(shí)間和偶發(fā)的Connection reset。Keep-Alive的配置一致性客戶端和服務(wù)端的keep-alive值如果不一致服務(wù)端先關(guān)了連接客戶端再?gòu)?fù)用就會(huì)報(bào)連接被重置。配置連接池沒(méi)有萬(wàn)能答案但有一個(gè)實(shí)操技巧啟動(dòng)一臺(tái)壓測(cè)機(jī)模擬小流量、中流量、峰值流量三檔壓測(cè)觀察新連接創(chuàng)建速率和連接池等待時(shí)間。如果新連接創(chuàng)建速率始終很高說(shuō)明連接池復(fù)用率低優(yōu)先調(diào)大per-route上限如果等待時(shí)間長(zhǎng)優(yōu)先調(diào)大總連接數(shù)。壓完再上線別拍腦袋。4.2 錯(cuò)誤十一忽略接口冪等性重試釀成大禍API調(diào)用失敗后重試是常見(jiàn)策略但如果你調(diào)用的接口不保證冪等重試就會(huì)產(chǎn)生副作用。最慘痛的一個(gè)案例是支付場(chǎng)景某系統(tǒng)在第三方支付接口超時(shí)后自動(dòng)重試三次每次重試都重新創(chuàng)建支付單結(jié)果用戶被扣了三筆錢客服電話被打爆。正確的做法是在調(diào)用外部API前生成唯一的請(qǐng)求ID冪等鍵帶著請(qǐng)求ID去調(diào)用。第三方支持冪等就靠這個(gè)ID去重第三方不支持你也要在自己的系統(tǒng)里記錄這個(gè)ID和請(qǐng)求狀態(tài)防止本地重試產(chǎn)生重復(fù)。區(qū)分重試安全和重試不安全兩類接口。查詢類接口隨便重試創(chuàng)建/支付/修改類接口必須顯示做冪等控制。標(biāo)準(zhǔn)可以在接口文檔里約定但你自己代碼里一定要有這層意識(shí)。一條經(jīng)驗(yàn)送給大家給你的所有外部調(diào)用都加上請(qǐng)求ID透?jìng)鞑还軐?duì)端用不用你自己的日志、監(jiān)控、排查都能靠它在全鏈路串起來(lái)。4.3 錯(cuò)誤十二序列化/反序列化的隱性陷阱API調(diào)用中JSON是最常見(jiàn)的傳輸格式但序列化這層薄薄的東西出的怪問(wèn)題一點(diǎn)不比并發(fā)少。忽略未知字段導(dǎo)致報(bào)錯(cuò)某些HTTP客戶端默認(rèn)配置下響應(yīng)JSON里出現(xiàn)了代碼里沒(méi)有定義的字段直接拋UnrecognizedPropertyException。解決辦法是配置FAIL_ON_UNKNOWN_PROPERTIESfalse但要注意這會(huì)掩蓋字段名拼寫(xiě)錯(cuò)誤。更穩(wěn)妥的做法是在開(kāi)發(fā)環(huán)境打開(kāi)嚴(yán)格模式生產(chǎn)環(huán)境放寬。循環(huán)引用導(dǎo)致序列化棧溢出兩個(gè)對(duì)象互相引用序列化時(shí)無(wú)限遞歸。用JsonIgnore或DTO拆分解決但最根本的辦法是在API邊界設(shè)計(jì)DTO不要把內(nèi)部實(shí)體直接暴露出去。時(shí)間格式不一致服務(wù)端返回yyyy-MM-dd HH:mm:ss你這邊期望ISO 8601解析直接炸。這種問(wèn)題在跨團(tuán)隊(duì)協(xié)作里格外常見(jiàn)建議統(tǒng)一用ISO 8601格式并顯式聲明時(shí)區(qū)。理論上說(shuō)序列化層的問(wèn)題最好解決但實(shí)際排查最費(fèi)時(shí)間因?yàn)閳?bào)錯(cuò)信息往往模棱兩可。我的建議是用單元測(cè)試把DTO的序列化和反序列化全覆蓋每個(gè)接口的字段增刪改都要跑一遍測(cè)試再上線比你線上debug省事一萬(wàn)倍。4.4 錯(cuò)誤十三分頁(yè)與游標(biāo)處理不當(dāng)調(diào)用列表類API的時(shí)候分頁(yè)是繞不開(kāi)的新手可能覺(jué)得就是pageSizepageNum兩個(gè)參數(shù)的事但踩過(guò)坑的都知道沒(méi)這么簡(jiǎn)單。數(shù)據(jù)量大的分頁(yè)越翻越慢基于offset的分頁(yè)在MySQL或某些搜索引擎里頁(yè)碼越深性能越差因?yàn)閿?shù)據(jù)庫(kù)要掃描全部前序數(shù)據(jù)才能定位到offset。如果API支持cursor游標(biāo)分頁(yè)優(yōu)先用游標(biāo)不要用頁(yè)碼。分頁(yè)期間數(shù)據(jù)變化導(dǎo)致重復(fù)或丟失用戶在翻第2頁(yè)時(shí)第1頁(yè)的數(shù)據(jù)新增了一條基于頁(yè)碼的翻頁(yè)就會(huì)導(dǎo)致同一數(shù)據(jù)出現(xiàn)兩次或者漏掉某條。游標(biāo)分頁(yè)方式下數(shù)據(jù)是按某個(gè)唯一排序鍵切片相對(duì)更穩(wěn)定。總頁(yè)數(shù)計(jì)算錯(cuò)誤totalCount / pageSize要向上取整這個(gè)小學(xué)數(shù)學(xué)問(wèn)題在真實(shí)項(xiàng)目里出現(xiàn)過(guò)不止一次。分頁(yè)這塊的經(jīng)驗(yàn)是先看文檔支持哪種分頁(yè)方式如果兩種都支持直接選游標(biāo)如果只支持頁(yè)碼分頁(yè)在數(shù)據(jù)量小萬(wàn)級(jí)以下的場(chǎng)景里用也沒(méi)大礙但數(shù)據(jù)量上來(lái)以后一定要評(píng)估是否要切到游標(biāo)。5. 穩(wěn)定性與可觀測(cè)性把事故從根上掐滅5.1 錯(cuò)誤十四重試機(jī)制要么沒(méi)有要么過(guò)度到拖垮下游重試策略是API調(diào)用里的雙刃劍。沒(méi)有重試一次網(wǎng)絡(luò)抖動(dòng)就會(huì)讓一個(gè)請(qǐng)求失敗盲目重試更可能在故障時(shí)引發(fā)重試風(fēng)暴——下游服務(wù)已經(jīng)過(guò)載你還在瘋狂地重試進(jìn)一步加重下游負(fù)擔(dān)最終兩邊一起崩潰。重試策略的合理設(shè)計(jì)必須兼顧幾個(gè)變量重試次數(shù)一般建議1~2次不要超過(guò)3次。超過(guò)3次的重試更多的是一種焦慮而不是有效策略。退避策略不要用固定間隔重試要用指數(shù)退避比如1秒、2秒、4秒并且在重試間隔里加入隨機(jī)抖動(dòng)。如果沒(méi)有抖動(dòng)所有實(shí)例在同一瞬間重試相當(dāng)于制造了一波新的流量尖峰?？焖偈∪绻e(cuò)誤碼明確是4xx參數(shù)錯(cuò)誤、鑒權(quán)失敗這種錯(cuò)誤重試一萬(wàn)次都不會(huì)成功應(yīng)該直接失敗不要浪費(fèi)資源。只有5xx和網(wǎng)絡(luò)層錯(cuò)誤才值得重試。熔斷如果連續(xù)失敗次數(shù)達(dá)到一定閾值比如10次直接打開(kāi)熔斷開(kāi)關(guān)讓請(qǐng)求快速失敗不再穿透到下游過(guò)一段時(shí)間再放一批流量探測(cè)是否恢復(fù)。重試技術(shù)本身不復(fù)雜但把它跟業(yè)務(wù)結(jié)合考慮——哪些錯(cuò)誤值得重試、重試對(duì)下游的壓力有多大、全局并發(fā)重試會(huì)不會(huì)導(dǎo)致雪崩——這些問(wèn)題比代碼本身重要得多。5.2 錯(cuò)誤十五日志里該有的信息沒(méi)有不該有的全都有API調(diào)用日志是最后一道防線。很多系統(tǒng)出問(wèn)題排查不了不是因?yàn)閱?wèn)題多復(fù)雜而是日志里既沒(méi)有關(guān)鍵信息又堆滿了廢話。常見(jiàn)的日志問(wèn)題有三個(gè)層面打印超大響應(yīng)體有的開(kāi)發(fā)者圖省事直接把整個(gè)API響應(yīng)體打到日志里。一個(gè)幾MB的響應(yīng)體在高并發(fā)下會(huì)極大拖慢日志寫(xiě)入速度嚴(yán)重時(shí)甚至拖垮磁盤IO。日志應(yīng)該只記錄狀態(tài)碼、耗時(shí)、錯(cuò)誤消息摘要。如果你確實(shí)需要完整的響應(yīng)體用于排查把它寫(xiě)到獨(dú)立的日志文件或存儲(chǔ)里做好級(jí)別控制別打到主日志流。日志缺失traceId處理API調(diào)用鏈路時(shí)一次用戶請(qǐng)求可能會(huì)經(jīng)歷多處遠(yuǎn)程調(diào)用。沒(méi)有traceId你連這條報(bào)錯(cuò)和那次請(qǐng)求是不是同一條鏈路都判斷不了。我強(qiáng)烈建議在API調(diào)用入口生成一個(gè)traceId透?jìng)鞯较掠嗡腥罩竞屯獠空{(diào)用的請(qǐng)求頭里。敏感信息泄露把token、密碼、密鑰直接打到日志里日志文件一旦被讀取就是重大安全事故。日志脫敏不是來(lái)不及處理的事是必須做的底線。關(guān)于日志調(diào)優(yōu)我的建議是分三個(gè)級(jí)別錯(cuò)誤日志打印異常堆棧和關(guān)鍵上下文業(yè)務(wù)日志記錄traceId、調(diào)用方、耗時(shí)調(diào)試日志記錄完整參數(shù)和響應(yīng)。日常運(yùn)行時(shí)只開(kāi)前兩級(jí)排查問(wèn)題時(shí)再動(dòng)態(tài)調(diào)到調(diào)試級(jí)別。千萬(wàn)別嫌麻煩。5.3 排查實(shí)操內(nèi)存泄漏定位三板斧不論前面的預(yù)防做得怎么樣線上總會(huì)有一些漏網(wǎng)之魚(yú)。真遇到內(nèi)存泄漏了按這三步走基本能快速定位第一板斧觀察內(nèi)存曲線。通過(guò)監(jiān)控系統(tǒng)看堆內(nèi)存的GC趨勢(shì)。健康的內(nèi)存曲線是鋸齒狀的每次GC后內(nèi)存回落泄漏的曲線是階梯狀或者緩慢上行的GC后內(nèi)存回不到低位。這一步能確認(rèn)確實(shí)泄漏了而不是還沒(méi)釋放。第二板斧抓堆轉(zhuǎn)儲(chǔ)文件。在內(nèi)存偏高的時(shí)候執(zhí)行jmap -dump:formatb,fileheap.bin pid或者用監(jiān)控工具自動(dòng)觸發(fā)抓取。Java平臺(tái)用MAT或JProfiler分析Python平臺(tái)可以用tracemalloc模塊記錄內(nèi)存分配棧。第三板斧找支配樹(shù)頂部的對(duì)象。用MAT打開(kāi)堆轉(zhuǎn)儲(chǔ)文件查看Dominator Tree重點(diǎn)分析占據(jù)內(nèi)存最多的對(duì)象是什么、被誰(shuí)持有引用。正常情況下你會(huì)看到某個(gè)Map、List或byte[]數(shù)組占據(jù)大頭然后順著引用鏈一路找上去基本上就是那個(gè)萬(wàn)惡之源。我自己遇到過(guò)的情況九成以上都指向某個(gè)靜態(tài)Map無(wú)界增長(zhǎng)、某個(gè)Netty緩沖區(qū)沒(méi)釋放、或者某個(gè)緩存框架的key過(guò)期策略沒(méi)生效。定位到之后修起來(lái)都很快難的是定位本身。5.4 排查實(shí)操異步異常和超時(shí)的定位技巧異步鏈路排查比同步難因?yàn)閳?bào)錯(cuò)信息經(jīng)常沒(méi)有足夠的上下文。我的做法是全程透?jìng)鱰raceId在入口生成traceId放進(jìn)線程上下文和日志MDC外部調(diào)用時(shí)放進(jìn)HTTP頭的自定義字段。這樣無(wú)論異步鏈路怎么跳轉(zhuǎn)每條日志都能串成一條線。捕獲異常時(shí)一定要保留原始堆棧不要用ex.getMessage()替代異常傳遞不要吞異常后只打一行字。日志里要有完整堆棧、當(dāng)前線程名、traceId、參數(shù)摘要這四個(gè)元素缺一不可。給所有異步調(diào)用設(shè)置明確的超時(shí)并且把超時(shí)這個(gè)事件本身也當(dāng)成一種需要記錄的異常單獨(dú)打點(diǎn)。這樣你可以在監(jiān)控里看到超時(shí)率這個(gè)指標(biāo)而不是只能看到異常數(shù)。遇到那種沒(méi)報(bào)錯(cuò)但就是沒(méi)結(jié)果的詭異場(chǎng)景優(yōu)先查超時(shí)和回調(diào)注冊(cè)是不是服務(wù)端根本沒(méi)回調(diào)是不是回調(diào)URL變了是不是回調(diào)因?yàn)樾蛄谢”混o默吞掉了順著這個(gè)思路查效率會(huì)高很多。6. 15個(gè)錯(cuò)誤速查表與最終建議6.1 錯(cuò)誤與解決方案速查表編號(hào)錯(cuò)誤類型典型現(xiàn)象根本原因解決方案1響應(yīng)流未關(guān)閉文件描述符耗盡、Connection reset底層輸入流未歸還連接池try-with-resources / with顯式關(guān)閉2長(zhǎng)生命周期持有短引用堆內(nèi)存緩慢增長(zhǎng)單例/靜態(tài)容器持有一次性對(duì)象不用靜態(tài)容器緩存臨時(shí)數(shù)據(jù)或加TTL淘汰3靜態(tài)集合無(wú)界增長(zhǎng)內(nèi)存爆滿、GC時(shí)間飆升注冊(cè)表/緩存無(wú)清理機(jī)制弱引用、容量限制、顯式注銷4監(jiān)聽(tīng)器未注銷事件推送越來(lái)越慢回調(diào)對(duì)象積壓在事件總線重連/銷毀時(shí)先解綁框架層用弱引用兜底5異步異常沒(méi)人接請(qǐng)求靜默失敗無(wú)日志異步鏈路缺少異常兜底鏈路終點(diǎn)加exceptionally/全局處理6超時(shí)設(shè)置不合理線程池被打滿、吞吐量崩塌讀取超時(shí)或整體超時(shí)未配置全維度設(shè)超時(shí)整體線程池容忍上限7線程池配置不當(dāng)線程數(shù)暴漲、拒絕執(zhí)行核心線程數(shù)過(guò)小或隊(duì)列無(wú)界預(yù)估并發(fā)度設(shè)核心線程數(shù)和有界隊(duì)列8共享可變狀態(tài)偶發(fā)數(shù)據(jù)錯(cuò)亂、字段丟失多線程同一變量/ThreadLocal殘留上下文局部化ThreadLocal顯式remove9回調(diào)地獄與信號(hào)丟失請(qǐng)求無(wú)限掛起無(wú)超時(shí)信號(hào)機(jī)制Promise.race/Future.get超時(shí)兜底10連接池配置錯(cuò)誤頻繁TCP握手、連接重置per-route連接數(shù)小、空閑連接未清理壓測(cè)驗(yàn)證per-route配置和keep-alive一致11忽略接口冪等性重復(fù)下單、重復(fù)扣款超時(shí)重試造成重復(fù)提交請(qǐng)求ID冪等鍵區(qū)分冪等/非冪等接口12序列化/反序列化踩坑解析失敗、循環(huán)引用、時(shí)間格式錯(cuò)DTO定義不嚴(yán)謹(jǐn)DTO嵌套邊界、時(shí)間格式統(tǒng)一、完整單測(cè)13分頁(yè)處理不當(dāng)深翻頁(yè)越來(lái)越慢、數(shù)據(jù)重復(fù)offset分頁(yè)和并發(fā)變更問(wèn)題優(yōu)先游標(biāo)分頁(yè)數(shù)據(jù)量大時(shí)淘汰offset14重試機(jī)制缺失或過(guò)度單次失敗/重試風(fēng)暴未區(qū)分錯(cuò)誤類型無(wú)退避抖動(dòng)指數(shù)退避抖動(dòng)4xx不重試加熔斷15日志記錄不當(dāng)排障困難、敏感信息泄露日志無(wú)traceId、內(nèi)容過(guò)多無(wú)重點(diǎn)分級(jí)日志traceId透?jìng)髅撁?.2 如果只讓我留三條建議表格是拿來(lái)快速參考的但如果這篇文章你只能記住三件事我希望能是這三條第一所有API調(diào)用都要有一個(gè)完整的生命周期意識(shí)。連接會(huì)占資源、流要關(guān)閉、回調(diào)要注銷、緩存要淘汰。你在寫(xiě)調(diào)用代碼的那一刻想清楚什么情況下它會(huì)被釋放后面的內(nèi)存泄漏至少能少一半。第二所有異步調(diào)用都要有超時(shí)兜底和異常兜底。異步API真正危險(xiǎn)的地方不是性能而是沒(méi)有結(jié)果和沒(méi)有報(bào)錯(cuò)。給每條異步鏈路都加上超時(shí)信號(hào)和全局異常處理線上詭異消失的問(wèn)題會(huì)少很多。第三可觀測(cè)性建設(shè)絕對(duì)不能省。沒(méi)有traceId、沒(méi)有全鏈路日志、沒(méi)有內(nèi)存曲線監(jiān)控那你排查一次API問(wèn)題的時(shí)間足夠別人排查三次。我寫(xiě)到這里其實(shí)最想說(shuō)的一件事就是API踩坑是每個(gè)做后端的人必經(jīng)的路踩坑不要緊重要的是踩完能不能總結(jié)出一套套路來(lái)——哪些坑高頻、怎么預(yù)防、出了事怎么快速定位。這篇文章里的15個(gè)錯(cuò)誤是我自己踩過(guò)或者幫別人排查過(guò)的真實(shí)經(jīng)驗(yàn)合集希望能讓你少走一些彎路。如果你也有遇到過(guò)特別匪夷所思的API問(wèn)題歡迎按同樣的思路——癥狀、原因、排查過(guò)程——拆解出來(lái)多交流多復(fù)盤比看十篇教程都有用。