RESTful API接口設計標准及規范

RESTful發展背景及簡介

網絡應用程序，分為前端和后端兩個部分。當前的發展趨勢，就是前端設備層出不窮（手機、平板、桌面電腦、其他專用設備…）。因此，必須有一種統一的機制，方便不同的前端設備與后端進行通信。這導致API構架的流行，甚至出現"APIFirst"的設計思想。RESTful API是目前比較成熟的一套互聯網應用程序的API設計理論。

REST（Representational State Transfer）表述性狀態轉換，REST指的是一組架構約束條件和原則。 如果一個架構符合REST的約束條件和原則，我們就稱它為RESTful架構。REST本身並沒有創造新的技術、組件或服務，而隱藏在RESTful背后的理念就是使用Web的現有特征和能力， 更好地使用現有Web標准中的一些准則和約束。雖然REST本身受Web技術的影響很深， 但是理論上REST架構風格並不是綁定在HTTP上，只不過目前HTTP是唯一與REST相關的實例。 

URI

URI 表示資源，資源一般對應服務器端領域模型中的實體類。

URI規范

• 不用大寫；
• 用中杠-不用下杠_；
• 參數列表要encode；
• URI中的名詞表示資源集合，使用復數形式。

資源集合 vs 單個資源

URI表示資源的兩種方式：資源集合、單個資源。

資源集合：

/zoos //所有動物園
/zoos/1/animals //id為1的動物園中的所有動物

單個資源：

/zoos/1 //id為1的動物園
/zoos/1;2;3 //id為1，2，3的動物園

避免層級過深的URI

/在url中表達層級，用於按實體關聯關系進行對象導航，一般根據id導航。

過深的導航容易導致url膨脹，不易維護，如 GET /zoos/1/areas/3/animals/4，盡量使用查詢參數代替路徑中的實體導航，如GET /animals?zoo=1&area=3；

對Composite資源的訪問

服務器端的組合實體必須在uri中通過父實體的id導航訪問。

組合實體不是first-class的實體，它的生命周期完全依賴父實體，無法獨立存在，在實現上通常是對數據庫表中某些列的抽象，不直接對應表，也無id。一個常見的例子是 User — Address，Address是對User表中zipCode/country/city三個字段的簡單抽象，無法獨立於User存在。必須通過User索引到Address：GET /user/1/addresses

Request

通過標准HTTP方法對資源CRUD。

GET：查詢

GET /zoos
GET /zoos/1
GET /zoos/1/employees

POST：創建單個資源。POST一般向“資源集合”型uri發起

POST /animals  //新增動物
POST /zoos/1/employees //為id為1的動物園雇佣員工

PUT：更新單個資源（全量），客戶端提供完整的更新后的資源。與之對應的是 PATCH，PATCH 負責部分更新，客戶端提供要更新的那些字段。PUT/PATCH一般向“單個資源”型uri發起。

PUT /animals/1
PUT /zoos/1

DELETE：刪除

DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals  //刪除id為1的動物園內的所有動物

安全性和冪等性

• 安全性：不會改變資源狀態，可以理解為只讀的；
• 冪等性：執行1次和執行N次，對資源狀態改變的效果是等價的。

復雜查詢

查詢可以捎帶以下參數：

錯誤處理

• 不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；
• 正確設置http狀態碼，不要自定義；
• Response body 提供 ① 錯誤的代碼（日志/問題追查）；② 錯誤的描述文本（展示給用戶）。

對第三點的實現稍微多說一點：

Java 服務器端一般用異常表示 RESTful API 的錯誤。API 可能拋出兩類異常：業務異常和非業務異常。業務異常由自己的業務代碼拋出，表示一個用例的前置條件不滿足、業務規則沖突等，比如參數校驗不通過、權限校驗失敗。非業務類異常表示不在預期內的問題，通常由類庫、框架拋出，或由於自己的代碼邏輯錯誤導致，比如數據庫連接失敗、空指針異常、除0錯誤等等。

業務類異常必須提供2種信息：

• 如果拋出該類異常，HTTP 響應狀態碼應該設成什么；
• 異常的文本描述；

在Controller層使用統一的異常攔截器：

• 設置 HTTP 響應狀態碼：對業務類異常，用它指定的 HTTP code；對非業務類異常，統一500；
• Response Body 的錯誤碼：異常類名
• Response Body 的錯誤描述：對業務類異常，用它指定的錯誤文本；對非業務類異常，線上可以統一文案如“服務器端錯誤，請稍后再試”，開發或測試環境中用異常的 stacktrace，服務器端提供該行為的開關。

常用的http狀態碼及使用場景：