做后端這些年我算是把API這兩個字從喜歡寫到看吐了。很多團隊的RESTful接口設計說白了就是把URL當成動詞命名大賽getUserInfo、deleteOrderByID、checkOrderStatus……這類路由一多整個接口層就變成了一堆函數(shù)名的HTTP搬運工。更麻煩的是調(diào)用方拿到這種接口根本不知道怎么猜、怎么復用前端聯(lián)調(diào)天天吵第三方對接文檔寫了一厚本還是被反復問。這篇文章想聊的就是RESTful接口設計里那些真正決定協(xié)作效率和系統(tǒng)穩(wěn)定性的東西資源怎么建模、URL怎么寫才不算亂來、狀態(tài)碼怎么選才語義清晰、錯誤響應怎么設計才能讓調(diào)用方一眼看懂以及我做過的幾次接口重構(gòu)復盤。不是教科書式的理論復述是踩過坑之后覺得早該這么干的經(jīng)驗總結(jié)。1. 先說清楚REST不是URL美學而是一套資源建模思想很多團隊以為RESTful就是把URL寫好看一點實際上這只看到了皮毛。REST的核心思想是把系統(tǒng)里的一切業(yè)務對象都抽象為資源客戶端通過統(tǒng)一的方法HTTP動詞對資源做操作服務端負責資源的存儲、校驗和狀態(tài)轉(zhuǎn)移。URL只是資源的位置標識不是操作指令。1.1 偽RESTful接口長什么樣我見過最典型的偽RESTful寫法就是接口路徑里全是動詞POST /api/order/getOrderInfo GET /api/order/deleteItem POST /api/user/checkPassword POST /api/order/updateStatus這種寫法的問題在于它把HTTP當成了RPC調(diào)用通道URL命名完全面向動作而不是面向?qū)ο?。結(jié)果就是接口列表越寫越長因為每增加一個動作就要新增一個URL調(diào)用方也沒法從URL推斷出數(shù)據(jù)和操作之間的關系每次都要翻文檔才能確定這個接口到底傳什么、返回什么、刪了會不會不可恢復。為什么會普遍出現(xiàn)這種現(xiàn)象一方面是因為很多開發(fā)者最早的編程習慣是寫函數(shù)拿到需求第一反應是我需要一個查訂單的方法于是直接就寫成了getOrderInfo另一方面是團隊缺乏一個統(tǒng)一的建模過程接口設計變成了誰開發(fā)誰拍腦袋風格全憑個人習慣。1.2 資源、表示與狀態(tài)轉(zhuǎn)移三句話建立建模意識要把RESTful做對先記住三個詞資源Resource、表示Representation、狀態(tài)轉(zhuǎn)移State Transfer。資源系統(tǒng)中的業(yè)務對象比如用戶、訂單、評論、發(fā)票每個對象有一個唯一的URI標識。表示資源在某個時刻的狀態(tài)表現(xiàn)通常是JSON或XML包含資源屬性和超媒體鏈接。狀態(tài)轉(zhuǎn)移通過HTTP方法改變資源狀態(tài)比如創(chuàng)建是POST更新是PUT/PATCH刪除是DELETE。用生活類比把服務端想象成一個圖書館資源是書架上的書。你去圖書館是通過書的位置URI找到書而不是通過動作名稱getBookFromShelf去找。書的內(nèi)容會變狀態(tài)轉(zhuǎn)移但書的位置不應該變。你的URL只負責告訴別人書在哪至于借走、還回、修補那是方法HTTP動詞的事。1.3 為什么必須在設計前先把資源地圖畫出來我在實際項目里發(fā)現(xiàn)接口設計得亂往往不是寫代碼的時候才亂的而是需求評審階段就沒有做資源識別。推薦做法是拿到業(yè)務需求后先枚舉出一份名詞清單把里面所有業(yè)務對象列出來再分析對象之間是什么關系一對一、一對多、多對多最后才決定URL層級和查詢方式。比如一個二手交易系統(tǒng)名詞清單大致是用戶、商品、訂單、支付單、退款單、評價、收藏。那接口方向就很清晰了/users /users/{id} /users/{id}/orders /products /products/{id} /orders /orders/{id} /refunds有了這份資源地圖你再去看改商品狀態(tài)該用哪個URL就不會糾結(jié)了。它一定落在/products/{id}的資源上通過PATCH改字段而不是單獨發(fā)明一個/product/changeStatus。2. URL規(guī)范讓名詞說話把動詞請出路徑URL是接口的門面也是調(diào)用方最容易感知的部分。一套穩(wěn)定、可預測、一眼就能看懂寫的是什么資源的URL規(guī)范比任何注釋都更能減少溝通成本。2.1 資源命名的基本規(guī)則我自己長期用的規(guī)則可以當成一套默認約定全部小寫路徑中單詞間用連字符-不要用下劃線_。原因是URL大小寫敏感不同團隊、不同網(wǎng)關對大小寫的處理不一致小寫是最省事的公約連字符在讀URL時更自然手機上也不容易看錯。資源名用復數(shù)。/users、/orders不要寫/user。復數(shù)代表的是一類資源的集合語義上更統(tǒng)一也方便后續(xù)加/users/{id}時保持一致性。路徑里只放名詞不放動詞。動詞語義交給HTTP方法這是RESTful的核心分界線。單個資源的標識用數(shù)字ID或UUID都可但在URL里不要出現(xiàn)ID這個字眼直接用值/users/123而不是/users/userId/123。2.2 子資源要不要嵌套嵌套幾層當資源之間存在明確從屬關系時可以用嵌套表達/users/{id}/orders表示某個用戶的所有訂單。嵌套層級一般不要超過兩層超過兩層調(diào)用方和文檔都會亂。舉個例子/blogs/123/comments/456這種三層結(jié)構(gòu)其實可以接受但如果寫成/regions/1/cities/2/districts/3/streets/4這種四五層的維護起來就是災難。遇到這種情況建議把鏈條底部的資源單獨拉平用查詢參數(shù)代替GET /comments?blog_id123comment_id456這樣路徑更短也更容易做緩存和權(quán)限控制。關鍵是團隊里要有一條明確規(guī)則超過兩層扁平化。2.3 常見反例自查清單我整理了一份很實用的對照表接口審查的時候直接拿著過一遍就行錯誤寫法正確寫法理由/api/getUser?id1GET /users/1動詞進了URL資源被拆散/api/deleteOrder?id1DELETE /orders/1刪除是HTTP方法的事/api/updateOrderStatusPATCH /orders/1狀態(tài)字段只是資源的一部分/api/checkOrderStatus?orderId1GET /orders/1/status狀態(tài)子資源化更清晰/api/user_savePOST /users不統(tǒng)一下劃線違和小寫連字符約定/api/getList?typeorderGET /orders同一個接口的另一種表達類型靠查詢參數(shù)細化這份清單價值在于它是從大量實際代碼里提煉出的高頻問題。接口評審時拿著它一票否決可以擋住一大半當場覺得沒毛病三個月后想重構(gòu)的設計。2.4 什么時候允許動作出現(xiàn)在路徑里規(guī)則總有例外。我允許動詞進入路徑只發(fā)生在一種場景這個操作本質(zhì)上不是對單個資源的簡單增刪改查而是一個領域動作或者說一次狀態(tài)機轉(zhuǎn)移。比如POST /tickets/123/cancel POST /orders/123/confirm這類接口雖然路徑里有動作但它是資源內(nèi)部的業(yè)務動作而且用POST天然表達了這個操作不是冪等的/有副作用的語義。如果你也想這么干我的建議是這種端點要克制一個資源最多四五個多了說明你的資源建模粒度有問題該把動作拆成狀態(tài)字段了。3. HTTP方法與狀態(tài)碼語義用對了調(diào)用方才能少寫一堆判斷接口設計里最容易被忽略、卻又最影響調(diào)用方體驗的是HTTP方法和狀態(tài)碼的語義是否準確。我接第三方API的時候最怕的不是報錯而是所有接口都返回200錯誤全藏在body里那才是災難。3.1 方法語義與冪等性先明確一組方法的基本語義和冪等特性方法語義冪等性典型場景GET讀取資源冪等查詢詳情、列表POST創(chuàng)建資源非冪等下單、注冊PUT全量替換資源冪等更新整個資源PATCH部分更新資源不保證修改部分字段DELETE刪除資源冪等刪除某個ID冪等性為什么重要因為網(wǎng)絡是不靠譜的客戶端超時后會重試。如果接口不冪等重試一次就重復下一次單、重復插一條數(shù)據(jù)后果很嚴重。我見過一個線上事故客戶端因為超時重試了三次結(jié)果POST創(chuàng)建訂單接口被執(zhí)行了三次庫存直接對不上。后來我們給所有POST接口加了冪等鍵才解決。3.2 狀態(tài)碼怎么選才不擰巴選狀態(tài)碼的核心邏輯很簡單2xx表示請求正常完成4xx表示錯誤出在客戶端參數(shù)、權(quán)限、資源不存在5xx表示錯誤出在服務端。但落到具體場景時很多人會糾結(jié)。我的默認選擇是這樣創(chuàng)建成功返回201帶Location頭指向新資源。查詢、更新、刪除成功返回200刪除成功返回204最標準也可以返回200但團隊內(nèi)部要統(tǒng)一。請求參數(shù)缺損或格式錯誤返回400。身份驗證失敗返回401沒有權(quán)限返回403。資源不存在返回404。資源沖突比如創(chuàng)建重復數(shù)據(jù)、狀態(tài)變更沖突返回409。參數(shù)合法但業(yè)務規(guī)則不滿足比如余額不足返回422。這里有一個非常常見的坑把業(yè)務校驗失敗錯誤地返回成500。我見過不少后端把用戶余額不足直接return 500因為覺得這是業(yè)務異常。問題是客戶端看到5xx會認為服務端掛了從而觸發(fā)重試而余額不足這種業(yè)務錯誤重試一萬次也沒用。這種接口設計造成的不僅是調(diào)用方困惑還可能引發(fā)重試風暴。業(yè)務校驗失敗一律4xx這是底線。3.3 200 業(yè)務錯誤碼到底能不能用很多公司內(nèi)部的接口規(guī)范喜歡把HTTP狀態(tài)碼固定為200然后響應體里用code字段表示成功失敗比如{code: -1, msg: error}。我不反對在內(nèi)部網(wǎng)關、BFF層這么玩因為很多老系統(tǒng)的HTTP客戶端封裝不允許讀4xx響應體統(tǒng)一200是為了兼容。但如果你做的是面向公網(wǎng)、面向多團隊協(xié)作的API我的建議是嚴格執(zhí)行HTTP狀態(tài)碼語義。原因是狀態(tài)碼本身是一種機器可讀的協(xié)議如果全部200調(diào)用方就必須解析body才能判斷結(jié)果這會讓成功/失敗的判斷標準散落在每個客戶端里長期維護成本極高。我實際觀測到的效果是采用完整狀態(tài)碼語義之后調(diào)用方SDK可以統(tǒng)一在HTTP層處理錯誤業(yè)務層代碼干凈一大截。4. 接口的長期演進設計版本、過濾、分頁、排序一鍋端很多接口剛上線時只有一個列表接口沒有任何可擴展性設計。等到業(yè)務迭代發(fā)現(xiàn)無法在不破壞老調(diào)用方的前提下加字段、改參數(shù)只能硬著頭皮v2重寫。其實把這個環(huán)節(jié)想清楚生命周期會舒服很多。4.1 版本控制放URL還是放Header版本號最直觀、最不容易被忽略的做法是放在URL路徑里比如/v1/users。好處是文檔、網(wǎng)關、日志都能直接看到缺點是路徑會變丑而且一旦客戶端把v1記死遷移成本照樣存在。也有團隊把版本號放在Header里比如Accept: application/vnd.example.v1json這種做法的優(yōu)點是URL干凈但實際調(diào)試和排查問題很麻煩——看日志時很容易忽略Header導致同一個URL你根本分不清調(diào)的是哪個版本。我的結(jié)論是對外API版本號放URL。對內(nèi)API如果前端是自家團隊統(tǒng)一管理Header方案可以用但要做好規(guī)范。至于版本策略我建議大改增版本小改向后兼容新增字段、新增可選參數(shù)直接加到現(xiàn)有版本不影響老調(diào)用方刪除字段、改變已有字段含義、修改狀態(tài)碼語義必須開新版本。4.2 分頁怎么做page/page_size 還是 cursor常規(guī)列表數(shù)據(jù)量不大時用最簡單直觀的page和page_size就行GET /orders?page2page_size20響應里帶上總條數(shù)和分頁信息{ items: [], page: 2, page_size: 20, total: 156, total_pages: 8 }但當你面對的是大數(shù)據(jù)量高并發(fā)場景比如千萬級用戶的動態(tài)列表page分頁會出現(xiàn)兩個問題大頁碼偏移量掃描慢并發(fā)寫入期間翻頁可能會看到重復或遺漏的數(shù)據(jù)。這時候要用游標分頁cursor-based pagination一般用創(chuàng)建時間或ID做游標GET /orders?cursoreyJpZCI6MTIzfQlimit20游標分頁的響應不返回total而是返回next_cursor和has_more客戶端拿著next_cursor繼續(xù)翻即可。我的經(jīng)驗是常規(guī)管理后臺、中小規(guī)模業(yè)務用page即可面向C端用戶、數(shù)據(jù)量增長快的場景從一開始就用cursor避免上線一年后重構(gòu)。4.3 過濾、排序與字段裁剪過濾條件統(tǒng)一用查詢參數(shù)命名用單數(shù)名詞枚舉值用文檔明確列出GET /orders?statuspaidpayment_methodalipaystart_time2024-01-01end_time2024-02-01排序建議白名單化約定sortcreated_at表示升序sort-created_at表示降序。服務端只接受白名單內(nèi)的字段防止調(diào)用方傳任意SQL字段導致注入風險GET /orders?sort-created_at,id字段裁剪sparse fields也是一種被大多數(shù)人忽略的優(yōu)化手段?？蛻舳丝梢詡鱢ieldsid,amount,status服務端只返回這些字段。它在面向公網(wǎng)API里能顯著節(jié)約帶寬尤其是移動端弱網(wǎng)場景效果立竿見影。缺點是服務端多做一層字段映射校驗但相比對端用戶的流量節(jié)省這點開銷很值。4.4 一個可以直接抄作業(yè)的列表接口示例把上面這些全部揉到一起一個完整且規(guī)范的列表接口大約長這樣curl https://api.example.com/v1/orders?statuspaidsort-created_atpage1page_size20fieldsid,amount,status,created_at響應體{ items: [ { id: ord_20240101_001, amount: 99.5, status: paid, created_at: 2024-01-01T10:00:00Z } ], page: 1, page_size: 20, total: 145, total_pages: 8 }這個示例我建議直接存為團隊模板。業(yè)務千差萬別但列表接口的骨架就是這些要素把骨架固定下來新增接口時只需要填充業(yè)務字段。5. 錯誤響應才是接口的下半場把報錯信息當成一等公民設計接口查詢和操作只是前半場真正考驗設計功力的是錯誤響應。我調(diào)試過很多第三方API最崩潰的體驗是返回了一個既沒有錯誤碼、也沒有trace_id的字符串你根本不知道是參數(shù)錯了、權(quán)限錯了、還是服務端崩了。設計良好的錯誤響應是接口質(zhì)量的試金石。5.1 一套能落地的統(tǒng)一錯誤結(jié)構(gòu)推薦錯誤響應體長這樣{ error: { code: ORDER_NOT_FOUND, message: 訂單不存在或已被刪除, details: [ { field: order_id, message: 傳入的 order_id 不存在 } ], trace_id: 9f8e7d6c5b4a3210 } }幾個關鍵點code是穩(wěn)定、可枚舉的錯誤碼調(diào)用方用code做分支判斷不要解析message的文案。message是給人看的要給出發(fā)生了什么、為什么、怎么辦三個信息。details用于批量字段校驗時列明每個字段的具體問題前端能直接映射到表單上。trace_id是定位服務端日志的錨點每次請求生成一個唯一ID客戶端報障時把trace_id甩給后端排查時間直接少一半。5.2 HTTP狀態(tài)碼和業(yè)務錯誤碼各管各的這里要區(qū)分清楚HTTP狀態(tài)碼是傳送層的粗粒度語義業(yè)務錯誤碼是業(yè)務層的細粒度語義。兩者要對應但不要互相替代。我自己維護的映射經(jīng)驗是大致這樣HTTP 狀態(tài)碼錯誤碼段典型場景400PARAM_ERROR 前綴參數(shù)缺失、格式錯誤、枚舉值不合法401AUTH_ERROR 前綴未認證、密鑰錯誤、token過期403FORBIDDEN_ERROR 前綴無權(quán)限、被風控攔截404NOT_FOUND 前綴資源不存在409CONFLICT 前綴重復創(chuàng)建、狀態(tài)沖突422BUSINESS_ERROR 前綴業(yè)務規(guī)則不滿足429RATE_LIMIT 前綴觸發(fā)限流5xxSERVER_ERROR 前綴服務端未知異常調(diào)用方只需要在HTTP層做一次粗判斷進入業(yè)務層后用code做細處理。兩者各管各的既不會All-200也不會什么都往4xx里塞。5.3 三類不該出現(xiàn)的接口錯誤設計第一類把后端堆棧、SQL語句、整段的異常堆棧直接透傳給客戶端。這既不安全也對調(diào)用方毫無價值。服務端錯誤只暴露一個概括性message細節(jié)留到日志里。第二類同一個接口在不同版本、不同分支下錯誤響應結(jié)構(gòu)一會兒是{code: 1}一會兒是{errorCode: 1}一會兒又變成了error字符串。這種接口會讓調(diào)用方SDK沒法統(tǒng)一解析只能一層層if-else。解決方式就是全量接入統(tǒng)一錯誤結(jié)構(gòu)老接口逐步收斂。第三類忽略了限流錯誤429和重試指引?？蛻舳瞬l(fā)打過來服務端直接Connection reset客戶端也不知道要不要重試、等多久重試。正確做法是返回429同時帶上Retry-After頭告訴調(diào)用方請在3秒后再試。這個頭在HTTP協(xié)議里就有不用自己發(fā)明。5.4 冪等鍵和重試策略接口健壯性的最后一公里網(wǎng)絡不可靠超時重試在所難免所以寫接口的時候要把客戶端會重試當成默認前提。對非冪等的創(chuàng)建類接口建議支持冪等鍵Idempotency-Key調(diào)用方在請求頭里帶上Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000服務端以這個key為維度做去重和緩存響應。第一次創(chuàng)建成功第二次重試直接返回第一次的結(jié)果不重復執(zhí)行。這樣既能保證可靠性又不會讓客戶端提心吊膽地試著提交第二次。重試策略上我給團隊定的規(guī)則是GET請求可以自動重試兩到三次POST請求必須支持冪等鍵才能重試DELETE/PUT本身冪等可以重試但同樣要控制并發(fā)。好接口不光是能響應還要讓調(diào)用方的錯誤處理邏輯變得簡單可預測。6. 一次真實的重構(gòu)復盤從天天被投訴到接口穩(wěn)定運行理論講再多不如看一次真實重構(gòu)過程。這個項目是一個面向B端商戶的訂單服務系統(tǒng)歷史負債很深前端和第三方對接方都叫苦連天。我們用了大概兩個迭代來重構(gòu)接口層這里完整還原一遍思路。6.1 原始接口的問題清單接手時的老接口長這樣POST /order/getOrderInfo POST /order/deleteItem GET /order/getOrderListByStatus POST /order/updateOrderStatus一眼就能看出問題全部過程化命名POST和GET用得毫無規(guī)律。進一步梳理后問題清單更扎眼查詢列表接口用POST返回數(shù)據(jù)還要翻好幾層才能拿到數(shù)組。刪除接口叫deleteItem但真實邏輯是把訂單項標記為停用不刪數(shù)據(jù)。錯誤響應三種格式并存有的返回{code: -1, msg: 失敗}有的直接字符串error: xxx還有的返回{status: failed, reason: ...}。狀態(tài)碼全返回200客戶端只能通過解析msg里的文字判斷錯誤原因而且msg文案前后不一致。6.2 排查與設計過程我們做的第一件事不是急著寫新接口而是整理了一份對接方報錯類型統(tǒng)計表把所有客戶端最常見的報錯場景列出來。發(fā)現(xiàn)有三大類分不清是參數(shù)錯誤還是權(quán)限錯誤客戶端日志里出現(xiàn)一批unexpected status 401 unauthorized之類的報錯但實際是token過期沒有刷新服務端錯誤信息卻沒有提示用戶該重新授權(quán)。遇到業(yè)務校驗失敗時響應不清晰調(diào)用方只能盲猜。列表接口沒有統(tǒng)一分頁每個子接口自己造一套參數(shù)。這個過程讓我深刻體會到客戶端報錯信息混亂的根源往往不是客戶端代碼寫得差而是服務端沒有給出足夠的錯誤語義。一個帶明確code、message、trace_id的錯誤響應本身就能消化掉大量溝通成本。第二件事是畫新的資源地圖。我們把訂單服務里的名詞全部枚舉出來訂單、訂單項、物流、發(fā)票、售后、結(jié)算。然后確立一套新的URL規(guī)范GET /v1/orders POST /v1/orders GET /v1/orders/{id} PATCH /v1/orders/{id} DELETE /v1/orders/{id} GET /v1/orders/{id}/items POST /v1/orders/{id}/cancel同時定了狀態(tài)碼和錯誤碼映射表、統(tǒng)一錯誤結(jié)構(gòu)、分頁和排序規(guī)范。舊接口保留兼容期不做刪除但新接口一律按新規(guī)范走。第三件事是做兼容遷移。我們不搞一刀切而是用三個月時間走雙寫老調(diào)用方繼續(xù)用老接口新調(diào)用方和愿意改造的存量方切到新接口。期間對老接口做一層防腐層把老請求翻譯成新邏輯保證數(shù)據(jù)一致。三個月后老接口訪問量降到個位數(shù)才正式下線。6.3 重構(gòu)后的實際效果幾個數(shù)據(jù)變化非常直觀客戶端錯誤處理代碼從每個頁面各寫一套收斂為SDK里統(tǒng)一一套前端整體錯誤處理代碼減少約六成。對接第三方時對方不再反復問這個接口為什么報錯因為錯誤碼和message已經(jīng)把原因講清楚了排障時間從按小時計降到按分鐘計。新增接口的評審成本大幅下降因為資源建模和規(guī)范已經(jīng)固定新需求只需要套模板。如果讓我給一個最值得記住的建議接口設計這件事寧可設計階段多開兩次評審、多花兩天討論資源建模也別上線后讓幾十個調(diào)用方陪著你踩坑。RESTful不是銀彈但把資源、URL、狀態(tài)碼、錯誤響應這幾個基礎決策做對系統(tǒng)的協(xié)作效率會有一個非常明顯的提升。最后再分享一個小技巧給團隊維護一份接口反例與正例對照表每次代碼評審的時候打開對照一遍比反復講理論有用得多。