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