前言

這篇文章，主要想總結自己在設計RESTful API的一系列經驗于思考。

有些規范可能與標準規范有所出入，但是所有的考量都是基于『減少重復工作，增加可讀性可維護性』而出發的。話說回來，我一直覺得 RESTful API 設計，確實沒有很明顯的公認規范（如果你是指發明者的那篇論文，估計沒多少人詳細閱讀過，而且其作者只是提出了一系列概念而已）。網上的教程，似乎都是千篇一律的（我嚴重懷疑：都是 “借鑒or拷貝” 阮一峰老師的那幾篇文章），僵硬而且呆板，有點教條化（從來沒有人懷疑它們嗎，反正我按照這些教條設計API，沒有感受到多少樂趣）。

以上，并不是全部否定，好東西要充分吸收，不好的東西，要融合自己的理解，加以改造。

對 RESTful API 的認識

說到這個，似乎又要談及『RESTful 是對資源的抽象』、『結合了HTTP 的特點』云云。不過這些都是一些沒用的套話，沒啥營養價值，而我想從另外的角度談論這個。

既然是 API，一般都符合 API 的一般模式：

ResultType ApiName(ParamType )1. 接口參數，即形參。可以是 string，int，以及其他任意可以稱之為參數的東西 2. 接口返回值。可以是 string，int，以及其他任意可以稱之為返回值的東西 3. 接口名（簽名) 復制代碼

我們來看看 RESTful 是如何對應上這個模式的：

HttpResponse URL(HttpRequest)1. HttpRequest：包括請求頭，URL參數，請求body參數 2. HttpResponse: 包括響應頭，響應的body 復制代碼

這樣來看，RESTful API 無非是一種特殊的API 而已，通用的 API 設計法則，同樣適合 RESTful，只不過非變換形式而已。

那么我們大概有哪些比較通用的標準呢？大概有這些：

接口命名，必須做到清晰。一般來說，做到『動賓短語』即可。

接口數量，越少越好。三個不如兩個，兩個不如一個，一個不如沒有，最好的 API 就是『沒有API』。

有明確的輸入輸出。念念不忘必有回響，總是有返回值，告訴調用端，我到底做了什么，做得怎么樣，即：反饋。

下面就來看看這些標準，是如何影響下文的內容的，：）。

URL設計，及其反模式

URL 就是接口簽名，而簽名必須做到清晰，沒有歧義。

有統一的前綴 & 版本化

如果后端架構是服務化的，那么有可能每個服務會對外提供公共的 RESTful API，那么有個統一的前綴格式，會比較好，比如：

/SERVICE_NAME/v1/users or /APP_NAME/v2/users 復制代碼

盡量短小

同一份資源，可以有不同的路徑，去理解它。比如：

User -- 1：N --> Server-- 1:N --> Client ... 更加復雜的實體映射關系1. /users/{user_id}/servers/{server_id}/clients 2. /clients一般大家傾向于選項 1（但是實體關聯關系特復雜時，會縮短URL）， 不過選項2 也是一個不錯的選擇，總而言之，口味問題吧。 復制代碼

數量盡量少

接口數量越少越好，能合并的接口就盡量合并。比如，這樣的情況：

獲取用戶列表信息：GET /users 獲取單個用戶信息：GET /users/{id}坦白說，獲取一個與獲取一批，似乎并沒有什么語義上的差別， 但是后端的同學就不一樣了，他可能需要寫兩個 View Class。 所以只保留批量的接口，查詢一個時，用 URL 參數傳遞就行了。 復制代碼

這樣的情況：

PUT /users/{id} PUT /users直接合并到一個接口里面做就行了，PUT 一個 user與 PUT 一群 user，有啥本質的不同嗎？ 復制代碼

還有這樣極端的情況：

DELETE /users/{id}刪除一個user與刪除一批user，有啥不同？ 如果要一次刪除100 個 user，難道讓前端同學，調 100 次這個接口？ 多一次調用，就多一次風險（如網絡問題）， 這個時候就別守著 RESTful 那些個教條了，接口的可用性、效率性，更加重要。這個時候，不如設計成這樣（至于 DELETE 接口能不能傳Request body，這里不討論）： POST /users_deletion {"user_ids": [1, 2, 3, 4, 5] } 復制代碼

返回值設計

前面有說到，HttpResponse中，我們可以利用：

Response Headers 可以做少量文章，如自定義一個HeaderStatus Code 按照基本規范來，該404的404，該200的200Response body 基本都是圍繞這個做文章 復制代碼

Response body 既要能正常返回信息，出錯了也要告訴出錯原因（錯誤碼），出錯詳情。所以我們大概可以設計成這樣：

{是否成功boolean "is_success":錯誤碼是多少number|null "err_code":錯誤信息string|null "err_msg": 錯誤詳情（可選）string|null "err_detail":出錯的時哪個服務string|null "provider": 正常返回時的數據"response_data": {} } 復制代碼

這樣，前端調用 API ，就有章法可循了，不至于盲目。

字段命名規范

沒有很明確的規范，但是盡量跟隨數據庫的風格，即：下劃線風格。 這樣，在 序列化整個 Model 時，也許會很方便。

其他規范

接口限流

參考 GitHub 的風格。

接口安全

這個沒法系統化，可以參考網絡上相關文章。

與50位技術專家面對面20年技術見證，附贈技術全景圖

總結

以上是生活随笔為你收集整理的基于工程经验的『RESTful接口设计规范』的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。