此文已由作者鄭華斌授權網易雲社區發布。

REST這詞我們常常掛在嘴邊，比如“開發一個rest接口”，又比如Spring項目的代碼：

@RestControllerpublic class CommonController {    @RequestMapping("/")    public String index() {        return "Welcome to Yanxuan DMS!";
    }

CommonController使用了@RestController註解，顧名思義，告訴讀者這是一個Rest接口的實現。然而以@RestController註解的接口卻不一定符合Rest原則。結合最近的項目，總結下常見的違背Rest設計的一些做法。

一、一律使用POST或者GET方法

典型的錯誤做法：無論什麽請求，一律用POST，或者‘增刪改’用POST，‘查’用GET。

其實REST有個原則叫統一接口（uniform interface），統一接口原則建議了各http方法的使用場合，

1. GET：獲取資源，返回消息頭和消息表示，即header和body。

2. HEAD：獲取資源元數據，返回消息頭

3. DELETE：刪除資源

4. POST：REST設計中，POST通常用來為一個已有資源創建一個從屬資源（subordinate resource），如AWS S3的POST Object(或者稱web post)接口。

5. PUT：創建或修改一個資源

PUT和POST的區別比較微妙，這裏拿AWS S3（或者參考網易對象存儲NOS）的接口設計來舉例。其中AWS S3的詳細API文檔參見：http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html。 S3有兩種資源，桶（bucket）和對象（object），對象從屬於某個桶。

創建一個桶的接口為：

PUT /BucketName  HTTP/1.1
Host: s3.amazonaws.com

創建/修改一個對象的PUT Object接口為：

PUT /BucketName/ObjectName  HTTP/1.1
Host: s3.amazonaws.com[對象數據]

AWS S3同時提供了POST Object接口，同樣可以創建/修改一個對象，如下

POST /BucketName HTTP/1.1Host: s3.amazonaws.comContent-Type: multipart/form-data; boundary=9431149156168[包含對象數據的body]

獲取對象的GET Object接口為：

GET /BucketName/ObjectName  HTTP/1.1
Host: s3.amazonaws.com

同樣的創建/修改一個對象，一個用PUT方法，另一個用POST方法，為什麽？關鍵在於URL，PUT請求的目標URL（這裏為/BucketName/ObjectName），就是將來用於獲取該對象的URL，即PUT Object和GET Object的URL是一致的。但是POST Object的URL與GET ObjectURL不一樣，POST 請求只知道父資源的URL（即/BucketName），表示在該父資源下創建新資源，至於新資源的確切URL，是由服務器決定的，一般來說是POST請求的響應應該包含一個Location消息頭，其包含新建從屬資源的URL。

安全性safe和冪等性idempotent

REST設計還應該遵循安全性和冪等性約束，如下：

1. GET和HEAD應當是安全的：GET和HEAD請求不應該導致服務器狀態發生改變

2. GET、HEAD、PUT和DELETE應當是冪等的：向一個URL發送多次PUT和DELETE請求，跟只做過一次請求一樣。比如PUT不能是append語義，否則不冪等。GET和HEAD也是冪等。

統一接口原則的好處：

1. 給一個資源URI，不用看文檔就知道可以有GET、DELETE等操作及其意義，世界通用。

2. 安全性和冪等性增加了http的可靠性：如果請求沒成功（但也許已成功了），只需重新發一次即可，不用擔心副作用。

二、HTTP Code一律返回200

典型的錯誤做法：無論成功失敗，HTTP Code一律返回200，具體錯誤信息交由json body裏的內容來判斷，舉例如下，

某甲服務xxx接口的響應如下

HTTP/1.1 200 OK{    "status":1,  //1: 成功  0: 參數異常 -1: 失敗
    "message":"" //返回的消息
    成功時返回的數據
}

某乙服務xxx接口的響應如下

HTTP/1.1 200 OK{    "code":200,  //1: 成功  0: 參數異常 -1: 失敗
    "msg":"" //code非200時返回的錯誤信息
    "data":{成功時返回的數據內容} 
}

其實RESTful的設計的一個標誌特征是充分並正確利用HTTP響應碼，典型的如：

• 200 -- OK，成功

• 301 -- Moved Permanently，重定向

• 400 -- Bad Request，錯誤的請求，比如缺少參數或者參數值不對

• 403 -- Forbidden，無權限訪問

• 404 -- Not Found，url不存在

• 500 -- Internal Server Error，系統錯誤，如數據庫訪問失敗或者bug導致的錯誤

設計REST接口應該遵循上面的響應碼，語義明確並通用。如果像上面例子那樣，任何情況都一律返回200，而具體成功與否需要到http響應消息體裏去解析，而且不同的服務或開發者自定義消息體的格式，那麽服務調用方就需要針對不同的服務寫不同的判斷邏輯，增加系統交互復雜性。

有些通用的客戶端，會針對301自動處理重定向，針對500以上的響應自動重試，而一律返回200的設計是沒法使用這些特性的，只能調用方一一自個處理。

三、 面向操作而不是面向資源的url設計

典型的錯誤做法：設計的URI是面向操作而不是面向資源的，舉例如下，

某系統 設計的渠道相關的URI是這樣的：

1. 新增渠道

   POST /xhr/thirdparty/admin/channel/add.json?{渠道信息參數}

2. 編輯渠道

POST /xhr/thirdparty/admin/channel/update.json?{渠道信息參數}

1. 刪除渠道

POST /xhr/thirdparty/admin/channel/delete.json?channelId=id

這裏的接口設計有三個特點：

1. http方法都是POST；

2. URI裏攜帶操作信息，如URI裏出現“add”，“update”，“delete”等字眼；

3. 同一個資源由於操作不一樣而URI不一樣。

其實REST式的設計中，URI即是資源的名稱，也是資源的地址，因為不同的操作而資源地址不一樣是不合適的。資源的操作（方法信息）應該由統一接口來表示，即http 方法PUT、POST、GET、DELETE等，而不應該放到URI中。

對照統一接口和面向資源這兩個特征來設計，上面的接口RESTful化可以是這樣的：

1. 新增渠道

POST /xhr/thirdparty/admin/channel

[渠道具體信息]

1. 修改渠道

PUT /xhr/thirdparty/admin/channel?channelId=id 或者PUT /xhr/thirdparty/admin/channel/${id}

[渠道具體信息]

1. 刪除渠道

DELETE /xhr/thirdparty/admin/channel?channelId=id或者DELETE /xhr/thirdparty/admin/channel/${id}

渠道的地址為/xhr/thirdparty/admin/channel?channelId=id或者/xhr/thirdparty/admin/channel/${id}，重在url唯一。

參考文獻

《RESTful Web Services》

相關文章：
【推薦】 3招搞定APP註冊作弊

總結常見的違背Rest原則的接口設計做法