寫接口的人多把接口寫明白的人少。能跑通的接口和能在線上活過三個(gè)大促的接口中間隔的不是框架版本而是一堆在敲回車前覺得“以后再說”的小決定。能跑通只是起點(diǎn)能在異常流量下保持?jǐn)?shù)據(jù)正確才是接口的真正及格線。SpringBoot讓一個(gè)空服務(wù)三分鐘就能啟動(dòng)也讓那些省略掉的細(xì)節(jié)在流量放大后變成事故。今天聊的不是JVM調(diào)優(yōu)不是分庫(kù)分表而是每個(gè)controller里都會(huì)遇到的、讓人熟視無睹的邊界問題?！緟?shù)校驗(yàn)信任是Bug的溫床】如果你現(xiàn)在打開項(xiàng)目搜索Controller里的方法參數(shù)也許能看到大量沒有Valid的實(shí)體。前端說“用戶名必填”后端就信了等第三方誤傳空串接口開始返回讓你臉紅的500。不校驗(yàn)參數(shù)的接口等于把異常的解釋權(quán)交給數(shù)據(jù)庫(kù)、框架甚至遠(yuǎn)程客戶端。常見誤解是加了Validated就萬事大吉卻忘了它不會(huì)級(jí)聯(lián)校驗(yàn)內(nèi)部嵌套的DTO用錯(cuò)分組又會(huì)放過本不該放過的字段。更值得留意的是DTO與實(shí)體不應(yīng)該混用。讓實(shí)體直接承擔(dān)HTTP請(qǐng)求體會(huì)在未來擴(kuò)展實(shí)體字段時(shí)意外擴(kuò)大接口暴露面。在一切追求快的年代把DTO和Entity分開不叫“代碼冗余”叫守住接口的邊界。校驗(yàn)失敗的信息也要統(tǒng)一最好通過全局異常把MethodArgumentNotValidException翻譯成固定的錯(cuò)誤碼和參數(shù)名而不是讓前端看到“must not be null”這種原生態(tài)判決書。【統(tǒng)一響應(yīng)不僅僅是一層殼】為了便于客戶端處理團(tuán)隊(duì)習(xí)慣封裝ResultT但封裝很快衍生新花樣有的返回code有的返回status成功時(shí)data有值失敗時(shí)塞一段英文文本在message里。沒有約定的一致響應(yīng)體接口文檔越厚越堵不住客戶端代碼的互相拆臺(tái)。一個(gè)容易被忽略的點(diǎn)是data里只應(yīng)該放真正的業(yè)務(wù)結(jié)果traceId和timestamp等元數(shù)據(jù)別混進(jìn)業(yè)務(wù)模型。真正想清楚響應(yīng)體的團(tuán)隊(duì)能讓前端只用一次攔截器處理完所有情況業(yè)務(wù)成功、參數(shù)非法、認(rèn)證失敗、系統(tǒng)異常。如果你把HttpStatus與業(yè)務(wù)碼混在一起網(wǎng)關(guān)重試的時(shí)候就不知道按什么語義處理你的響應(yīng)。業(yè)務(wù)碼需要分層參數(shù)錯(cuò)誤、業(yè)務(wù)規(guī)則錯(cuò)誤、外部依賴錯(cuò)誤、未知系統(tǒng)錯(cuò)誤每一類都應(yīng)有明確的數(shù)字區(qū)間。【異常處理把“哦”變成“這里錯(cuò)了”】寫接口時(shí)很多人以為用try-catch包住業(yè)務(wù)代碼就可以但在線上成千上萬行日志不能靠catch看清。沒有全局異常處理的接口排錯(cuò)過程就像在深夜檔案室找一本沒有編號(hào)的書。推薦建立RestControllerAdvice把異常按類別映射到統(tǒng)一的錯(cuò)誤碼參數(shù)校驗(yàn)失敗映射到400認(rèn)證/授權(quán)失敗映射到401/403業(yè)務(wù)異常映射到獨(dú)立業(yè)務(wù)碼未預(yù)期異常降級(jí)到500。更隱蔽的坑是advice類中的異常處理方法順序子類異常的處理方法若寫在父類異常之后可能永遠(yuǎn)不會(huì)被觸發(fā)。處理器的優(yōu)先級(jí)和順序和異常本身一樣需要被測(cè)試覆蓋。此外不要將堆棧直接返回給客戶端但要把traceId放進(jìn)響應(yīng)體。一個(gè)可落地的經(jīng)驗(yàn)讓客服的反饋從“系統(tǒng)報(bào)錯(cuò)了”進(jìn)化成“錯(cuò)誤碼A0032訂單號(hào)88時(shí)間戳是……”你在凌晨三點(diǎn)會(huì)感激這個(gè)設(shè)計(jì)?！救罩緞e讓排查請(qǐng)求變成考古】很多接口的“日志”只是方法入口打一行“xxx進(jìn)來了”然后就沒有然后。請(qǐng)求失敗后你連它走到哪一步都不知道。沒有traceId的日志是一堆沒有頁(yè)碼的碎紙。從網(wǎng)關(guān)或過濾器生成traceId扔進(jìn)MDC配合logback的pattern輸出整條鏈路的日志就能被一鍵聚合。但記錄日志要克制用戶密碼、手機(jī)號(hào)、身份證號(hào)一旦出現(xiàn)在日志里那已經(jīng)不是技術(shù)問題而是安全事故。日志應(yīng)該記錄什么入?yún)⒅淮蛴”匾拿撁絷P(guān)鍵值出參打印狀態(tài)和耗時(shí)外部調(diào)用記錄目標(biāo)和耗時(shí)。好的接口日志不在于量而在于是否能在五步之內(nèi)重現(xiàn)一次請(qǐng)求的完整路徑。對(duì)每一次“用戶說報(bào)錯(cuò)了你說查不了”的窘境都需要在日志設(shè)計(jì)階段提前考慮好?！緝绲扔脩暨h(yuǎn)比你想象的更執(zhí)著】雙擊保存、網(wǎng)絡(luò)超時(shí)、支付回調(diào)重復(fù)通知這些場(chǎng)景在真實(shí)世界中的頻率遠(yuǎn)高于開發(fā)環(huán)境。如果寫接口沒有冪等保護(hù)一次支付回調(diào)可能創(chuàng)建兩筆訂單一個(gè)保存操作重復(fù)插入N條記錄。沒有冪等設(shè)計(jì)的寫接口是在邀請(qǐng)用戶和上游系統(tǒng)幫你制造臟數(shù)據(jù)。實(shí)現(xiàn)冪等不能用簡(jiǎn)單的if (exists) return因?yàn)閮蓚€(gè)并發(fā)請(qǐng)求都查不到歷史記錄仍會(huì)同時(shí)插入。通常需要兩條防線第一道是Redis token或狀態(tài)機(jī)前置判斷攔截絕大多數(shù)重復(fù)請(qǐng)求第二道是數(shù)據(jù)庫(kù)唯一鍵或樂觀鎖版本號(hào)在最后關(guān)頭擋住并發(fā)穿透。只有當(dāng)重復(fù)請(qǐng)求拿到和第一次相同的結(jié)果冪等才開始成立。還要想清楚Redis中的令牌消費(fèi)與數(shù)據(jù)庫(kù)寫入不是原子操作令牌消費(fèi)失敗是否要業(yè)務(wù)回滾回滾后如果恢復(fù)請(qǐng)求重放是否應(yīng)該重新返回原結(jié)果這些問題在寫設(shè)計(jì)文檔時(shí)就要回答?！静l(fā)SpringBoot并不保證正確性】Controller默認(rèn)是線程安全的嗎不單例bean中的共享變量才是噩夢(mèng)源泉。許多人寫SQL時(shí)想得清楚回到代碼里卻忘記加鎖。典型的賬戶扣減邏輯先select余額判斷足夠再update兩個(gè)線程同時(shí)讀100同時(shí)減10最終余額變成90而不是80。如果每次都先select再update并發(fā)一旦升高事故不是“萬一”而是“必然”。正確做法是在SQL層用原子條件set balance balance - ? where balance ?或者在更新語句加上版本號(hào)判斷。SpringBoot讓事務(wù)管理變得簡(jiǎn)單但鎖的粒度和隔離級(jí)別需要你自己決定。最怕的是用分布式事務(wù)的復(fù)雜度去解決一個(gè)本該用版本號(hào)解決的簡(jiǎn)單問題。上線前問自己這個(gè)數(shù)據(jù)會(huì)被多個(gè)線程同時(shí)修改嗎樂觀鎖夠不夠要不要Redis分布式鎖把并發(fā)思考前置接口才能扛過峰值。【事務(wù)邊界別讓一個(gè)請(qǐng)求把數(shù)據(jù)庫(kù)擰成麻繩】事務(wù)經(jīng)常被加到service方法上但很多人沒想清楚它的邊界。一個(gè)大事務(wù)如果包住遠(yuǎn)程調(diào)用、消息發(fā)送、文件下載會(huì)導(dǎo)致連接長(zhǎng)期被占用線程池耗盡只是時(shí)間問題。事務(wù)不是越大越安全把外部調(diào)用移到事務(wù)提交之后才是對(duì)自己數(shù)據(jù)庫(kù)連接的愛護(hù)。另一個(gè)暗坑是事務(wù)方法必須通過代理調(diào)用在類內(nèi)部用this調(diào)用會(huì)讓Transactional靜默失效spring初學(xué)者的接口因此常常死在“有事務(wù)注解卻不存在事務(wù)”的幻覺里。在寫接口前先梳理一下這個(gè)請(qǐng)求涉及幾條SQL、是否必須同一數(shù)據(jù)源、能不能異步處理。接口里最貴重的資源不是CPU而是那些有限且不可置疑的連接與線程?！痉猪?yè)別把慢查詢藏進(jìn)“下一頁(yè)”】分頁(yè)是列表接口的標(biāo)配它也是慢查詢高發(fā)地。多數(shù)人會(huì)用PageHelper或Spring Data的PageRequest卻忘了對(duì)pageSize限流。一個(gè)max size不設(shè)限的分頁(yè)接口等同于為“拖垮數(shù)據(jù)庫(kù)”提供了合規(guī)入口。如果需要做導(dǎo)出請(qǐng)走異步任務(wù)而不是把第10000頁(yè)的數(shù)據(jù)直接拉進(jìn)HTTP響應(yīng)。當(dāng)頁(yè)碼足夠大時(shí)深分頁(yè)需要掃描大量行再丟棄性能會(huì)急劇惡化。深分頁(yè)場(chǎng)景更適合游標(biāo)分頁(yè)用唯一有序字段的where條件代替offset每次只取一頁(yè)。排序參數(shù)也必須用白名單校驗(yàn)不能把外部字符串直接拼進(jìn)order by否則就為SQL注入開了一扇后門。【接口版本你欠舊調(diào)用方一個(gè)交代】服務(wù)越來越被多方調(diào)用時(shí)版本邊界就能決定事故范圍。如果一開始沒有版本策略后續(xù)任何破壞性變更都可能讓整個(gè)系統(tǒng)變成一場(chǎng)災(zāi)難。沒有版本管理的接口等于把自己釘在“永遠(yuǎn)不能改”的十字架上。有人把版本寫進(jìn)URL簡(jiǎn)單直接但每個(gè)大版本都要復(fù)制一套controller用Accept-Version請(qǐng)求頭管理版本則更考驗(yàn)路由設(shè)計(jì)。重要的不是選哪種形式而是提前約好兼容窗口。還要考慮“破壞性變更”不止是刪除字段字段類型變化、枚舉增加取值、默認(rèn)值修改都是潛在不兼容點(diǎn)。建立契約測(cè)試用消費(fèi)者驅(qū)動(dòng)的模式發(fā)布變更才能讓接口升級(jí)不那么像賭博。【安全認(rèn)證通過不等于權(quán)限過關(guān)】接口安全最容易出現(xiàn)的問題是前置攔截器校驗(yàn)完token就放行到controllerService里直接拿請(qǐng)求參數(shù)中的userId去查詢卻不判斷這個(gè)userId是不是當(dāng)前人。認(rèn)證解決“你是誰”鑒權(quán)解決“你能做什么”這兩個(gè)概念經(jīng)常被混為一談。如果用了Spring Security建議在controller或service方法上使用PreAuthorize(hasAuthority(order:update))這類表達(dá)式而不是在方法里到處寫if/else。任何接口都不要相信前端傳來的“當(dāng)前用戶”當(dāng)前用戶只能從SecurityContextHolder中取值。JWT要設(shè)過期時(shí)間RefreshToken單獨(dú)設(shè)計(jì)。不要為了少數(shù)客戶端的方便把有效期拉長(zhǎng)到一年那等于給未來的數(shù)據(jù)泄露案提前準(zhǔn)備好長(zhǎng)期的犯罪時(shí)間?！疚臋n與契約別等三個(gè)月后再來猜字段】SpringBoot集成Swagger/OpenAPI非常容易難的是文檔與代碼同步。很多接口的注解停留在上線那天后來字段改了文檔忘了改前端照著舊文檔傳參后端默默返回400。一個(gè)不能與代碼自動(dòng)校驗(yàn)的接口文檔最終會(huì)成為誤導(dǎo)工具。可以在CI中跑OpenAPI schema的diff一旦對(duì)外字段發(fā)生破壞性修改就讓構(gòu)建失敗迫使開發(fā)者顯式?jīng)Q定版本升級(jí)。接口能否長(zhǎng)期健康不取決于注釋寫得多優(yōu)美而在于契約是否被自動(dòng)化守護(hù)。每一個(gè)對(duì)外接口都應(yīng)當(dāng)有明確的example、錯(cuò)誤碼清單、限流閾值和維護(hù)人否則三個(gè)月后填坑的還是你自己?！境瑫r(shí)與限流給依賴和流量都戴上韁繩】最常見的接口事故是Controller調(diào)第三方HTTP服務(wù)時(shí)沒有超時(shí)對(duì)端響應(yīng)緩慢你的tomcat線程被占滿隨后新請(qǐng)求排隊(duì)鏈路雪崩。不設(shè)超時(shí)的接口等于把自己服務(wù)的可用性押注在別人的響應(yīng)速度上。無論RestTemplate還是WebClient連接超時(shí)與讀取超時(shí)都必須顯式配置。另一步是保護(hù)自身限流方案可以選Guava、RedisLua或Sentinel但核心在于失敗反饋。當(dāng)流量超過閾值返回429并附帶Retry-After讓客戶端知道何時(shí)重試而不是用500刺激客戶端無限重試。超時(shí)、重試與熔斷是三個(gè)不同概念重試必須配合冪等熔斷要設(shè)置半開恢復(fù)冷冰冰的超時(shí)配置無法替代整個(gè)鏈路的穩(wěn)定性設(shè)計(jì)?；氐侥莻€(gè)新建Controller的午后。我們總傾向于告訴自己“先實(shí)現(xiàn)再優(yōu)化”可一旦接口部署到公網(wǎng)所有不守規(guī)則的細(xì)節(jié)都會(huì)被流量放大。決定一個(gè)接口穩(wěn)定性的往往不是架構(gòu)上的靈光一現(xiàn)而是這些邊界處反復(fù)被磨過的約束。SpringBoot把開發(fā)門檻降得很低但這恰恰要求我們主動(dòng)抬高審美線。把每一個(gè)接口當(dāng)成要交付的API去設(shè)計(jì)把每一次參數(shù)校驗(yàn)當(dāng)成一扇門去鎖把每一次日志輸出當(dāng)成向未來的自己傳遞線索。能做到這些你寫的就不僅僅是一個(gè)可以運(yùn)行的接口而是可以在生產(chǎn)環(huán)境中真正被信任的服務(wù)。