關于RESTful一些注意事項，接口開發規范

前些天發現了一個巨牛的人工智能學習網站，通俗易懂，風趣幽默，忍不住分享一下給大家。點擊跳轉到教程。

最近在研究restful，公司開發要使用，所以自己就去網上找了好些資料，并整理了一套公司開發的接口規范。當然，我也只是剛剛入坑。還不是很全面。但是這就是一個過程。一點點，總會好起來的。以下是就是RESTful接口規范：

一、???URI

URI規范

1.不用大寫；

2.用中杠?-?不用下杠?_?；

3.參數列表要encode；

4.URI中的名詞表示資源集合，使用復數形式。

5.在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞（特殊情況可以使用動詞），而且所用的名詞往往與數據庫的表格名對應。

資源集合?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?；

二、???版本

應該將API的版本號放入到URI中

???????????https://api.example.com/v1/zoos

三、?Request

HTTP方法

通過標準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的動物園內的所有動物

HEAD / OPTION/ PATCH用的不多，就不多解釋了。

HEAD：獲取資源的元數據

OPTIONS：獲取信息，關于資源的哪些屬性是客戶端可以改變的

PATCH：在服務器更新資源（客戶端提供改變的屬性）

安全性和冪等性

1.?????安全性?：不會改變資源狀態，可以理解為只讀的；

2.?????冪等性?：執行1次和執行N次，對資源狀態改變的效果是等價的。

.	安全性	冪等性
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

安全性和冪等性均不保證反復請求能拿到相同的response。以?DELETE為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

復雜查詢

查詢可以捎帶以下參數：

.	示例	備注
過濾條件	?type=1&age=16	允許一定的uri冗余，如?/zoos/1?與?/zoos?id=1
排序	?sort=age&order=asc	指定返回結果按照哪個屬性排序，以及排序順序
投影	?whitelist=id,name,email
分頁	? page=2&per_page=100	指定第幾頁，以及每頁的記錄數

Bookmarker

經常使用的、復雜的查詢標簽化，降低維護成本。

如：GET /trades?status=closed&sort=created,desc

快捷方式：GET /trades#recently-closed或者GET /trades/recently-closed

狀態碼

????服務器向用戶返回的狀態碼和提示信息，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。

§200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。

§201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。

§202 Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務）

§204 NO CONTENT - [DELETE]：用戶刪除數據成功。

§400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。

§401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。

§403 Forbidden - [*]?表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。

§404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。

§406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。

§410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。

§422 Unprocesable entity - [POST/PUT/PATCH]?當創建一個對象時，發生一個驗證錯誤。

§500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。

狀態碼的完全列表參見這里

URI失效

隨著系統發展，總有一些API失效或者遷移，對失效的API，返回404 not found?或?410 gone；對遷移的API，返回?301重定向。

四、Response

1.????不要包裝：

response的?body?直接就是數據，不要做多余的包裝。錯誤示例：

{

???"success":true,

???"data":{"id":1,"name":"xiaotuan"},

}

2.????各HTTP方法成功處理后的數據格式：

·	response 格式
GET	單個對象、集合
POST	新增成功的對象
PUT/PATCH	更新成功的對象
DELETE	空

五、錯誤處理

1.?????不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；

2.?????正確設置http狀態碼，不要自定義；

3.?????Response body提供

即:返回的信息中將error作為鍵名，出錯信息作為鍵值即可

1)錯誤的代碼（日志/問題追查）；

2)錯誤的描述文本（展示給用戶）。

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

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

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

1.?????如果拋出該類異常，HTTP響應狀態碼應該設成什么；

2.?????異常的文本描述；

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

1.?????設置?HTTP響應狀態碼：對業務類異常，用它指定的?HTTPcode；對非業務類異常，統一500；

2.?????Response Body的錯誤碼：異常類名

3.?????Response Body的錯誤描述：對業務類異常，用它指定的錯誤文本；對非業務類異常，線上可以統一文案如“服務器端錯誤，請稍后再試”，開發或測試環境中用異常的?stacktrace，服務器端提供該行為的開關。

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

狀態碼	使用場景
400 bad request	常用在參數校驗
401 unauthorized	未經驗證的用戶，常見于未登錄。如果經過驗證后依然沒權限，應該?403（即?authentication和authorization的區別）。
403 forbidden	無權限
404 not found	資源不存在
500 internal server error	非業務類異常
503 service unavaliable	由容器拋出，自己的代碼不要拋這個異常