作者：涂根華

https://www.cnblogs.com/tugenhua0707/p/12153857.html

RESTful是目前最流行的API設計規范，它是用于Web數據接口的設計。從字面可以看出，他是Rest式的接口，所以我們先了解下什么是Rest。

REST與技術無關，它代表的是一種軟件架構風格，REST它是 Representational State Transfer的簡稱，中文的含義是: "表征狀態轉移" 或 "表現層狀態轉化"。

它是基于HTTP、URI、XML、JSON等標準和協議，支持輕量級、跨平臺、跨語言的架構設計。

為什么使用RESTful API設計規范？

在很久以前，工作時間長的同學肯定經歷過使用velocity語法來編寫html模板代碼，

也就是說我們的前端頁面放在服務器端那邊進行編譯的，更準確的可以理解為 "前后端沒有進行分離"。

那么在那個時候，頁面、數據及模板渲染操作都是放在服務器端進行的，

但是這樣做有一個很大的缺點是:?后期維護比較麻煩，前端開發人員還必須掌握velocity相關的語法。

因此為了解決這個問題慢慢就出現了前后端分離的思想: 即后端負責數據接口, 前端負責數據渲染, 前端只需要請求下api接口拿到數據，然后再將數據顯示出來。

因此后端開發人員需要設計api接口，因此為了統一規范: 社區就出現了 RESTful API 規范。

其實該規范很早就有的，只是最近慢慢流行起來，RESTful API 可以通過一套統一的接口為所有web相關提供服務，實現前后端分離。

Rest 設 計 原 則

那么怎么樣可以設計成REST的架構規范呢??

需要符合如下的一些原則：

每一個URI代表一種資源;

同一種資源有多種表現形式(xml/json);

所有的操作都是無狀態的；

規范統一接口；

返回一致的數據格式；

可緩存(客戶端可以緩存響應的內容)。

符合上述REST原則的架構方式被稱作為 RESTful 規范。

理解為什么所有的操作需要無狀態呢?

http請求本身是無狀態的，它是基于 client-server 架構的，

客戶端向服務器端發的每一次請求都必須帶有充分的信息能夠讓服務器端識別到，請求的一些信息通常會包含在URL的查詢參數中或header中，

服務器端能夠根據請求的各種參數, 不需要保存客戶端的狀態, 直接將數據返回給客戶端。

無狀態的優點是：可以大大提高服務器端的健狀性和可擴展性。

客戶端可以通過token來標識會話狀態。從而可以讓該用戶一直保持登錄狀態。

理解規范統一的接口

Rest接口約束定義為: 資源識別；請求動作；響應信息; 它表示通過uri表示出要操作的資源，通過請求動作(http method)標識要執行的操作，通過返回的狀態碼來表示這次請求的執行結果。

可能看上面的解釋還不夠理解，下面我通過自己的理解來解釋下上面的具體含義：

比如說，我在未使用Rest規范之前，我們可能有增刪改查等接口，

因此我們會設計出類似這樣的接口:

?/xxx/newAdd (新增接口), /xxx/delete(刪除接口), /xxx/query (查詢接口), /xxx/uddate(修改接口)等這樣的。

增刪改查有四個不同的接口，維護起來可能也不好，

因此如果我們現在使用Restful規范來做的話，對于開發設計來說可能就只需要一個接口就可以了，比如設計該接口為 /xxx/apis 這樣的一個接口就可以了。

然后請求方式(method)有：

GET--查詢(從服務器獲取資源);?

POST---新增(從服務器中新建一個資源);?

PUT---更新(在服務器中更新資源)；

DELETE---刪除(從服務器刪除資源)；

PATCH---部分更新(從服務器端更新部分資源) 等這些方式來做，

也就是說我們使用RESTful規范后，我們的接口就變成了一個了，

要執行增刪改查操作的話，我們只需要使用不同的請求動作(http method)方式來做就可以了，

然后服務器端返回的數據也可以是相同的，只是我們前端會根據狀態碼來判斷請求成功或失敗的狀態值來判斷。

具體有那些狀態碼我們下面會講解到。

理解返回一致的數據格式

服務器端返回的數據格式可以是XML、或json. 或者直接返回狀態碼的方式。

比如返回錯誤的格式json數據如下:

{ "code": 401, "status": "error", "message": '用戶沒有權限', "data": null}

返回正確的數據格式的json數據一般可以為如下:

{ "code": 200, "status": "success", "data": [{ "userName": "tugenhua", "age": 31 }]}

URL及參數設計規范

uri設計規范

uri末尾不需要出現斜杠/；

在uri中使用斜杠/是表達層級關系的；

在uri中可以使用連接符-, 來提升可讀性。比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可讀性更好。

在uri中不允許出現下劃線字符_；

在uri中盡量使用小寫字符；

在uri中不允許出現文件擴展名。比如接口為 /xxx/api, 不要寫成 /xxx/api.php ，這樣的是不合法的。

在uri中使用復數形式。

具體可以看：

https://blog.restcase.com/7-rules-for-rest-api-uri-design/

在RESTful架構中，每個uri代表一種資源，因此uri設計中不能使用動詞，只能使用名詞，并且名詞中也應該盡量使用復數形式。

使用者應該使用相應的http動詞 GET、POST、PUT、PATCH、DELETE等操作這些資源即可。

那么在我們未使用RESTful規范之前，我們是如下方式來定義接口的，形式是不固定的，并且沒有統一的規范。比如如下形式:

http://xxx.com/api/getallUsers; // GET請求方式，獲取所有的用戶信息http://xxx.com/api/getuser/1; // GET請求方式，獲取標識為1的用戶信息http://xxx.com/api/user/delete/1 // GET、POST 刪除標識為1的用戶信息http://xxx.com/api/updateUser/1 // POST請求方式 更新標識為1的用戶信息http://xxx.com/api/User/add // POST請求方式，添加新的用戶

如上我們可以看到，在未使用Restful規范之前，接口形式是不固定的，沒有統一的規范，

下面我們來看下使用RESTful規范的接口如下，兩者之間對比下就可以看到各自的優點了。

http://xxx.com/api/users; // GET請求方式 獲取所有用戶信息http://xxx.com/api/users/1; // GET請求方式 獲取標識為1的用戶信息http://xxx.com/api/users/1; // DELETE請求方式 刪除標識為1的用戶信息http://xxx.com/api/users/1; // PATCH請求方式，更新標識為1的用戶部分信息http://xxx.com/api/users; // POST請求方式 添加新的用戶

如上我們可以看到，增刪改成我們都是使用同一個api接口，只是請求的方式 GET(查詢)、POST(新增)、DELETE(刪除)、PACTH(部分更新)來代表的是增刪改查操作的方式。

然后開發獲取到該請求的header頭部信息，就可以知道是什么方式來請求數據的了。

HTTP請求規范

GET (SELECT): 查詢；從服務器取出資源。

POST(CREATE): 新增; 在服務器上新建一個資源。

PUT(UPDATE): 更新; 在服務器上更新資源(客戶端提供改變后的完整資源)。

PATCH(UPDATE): 更新；在服務器上更新部分資源(客戶端提供改變的屬性)。

DELETE(DELETE): 刪除; 從服務器上刪除資源。

參數命名規范

參數推薦采用下劃線命名的方式。比如如下demo:

http://xxx.com/api/today_login // 獲取今天登錄的用戶。http://xxx.com/api/today_login&sort=login_desc // 獲取今天登錄的用戶、登錄時間降序排序。

http狀態碼相關的

狀態碼范圍

客戶端的每一次請求, 服務器端必須給出回應，回應一般包括HTTP狀態碼和數據兩部分。

1xx: 信息，請求收到了，繼續處理。

2xx: 代表成功. 行為被成功地接收、理解及采納。

3xx: 重定向。

4xx: 客戶端錯誤，請求包含語法錯誤或請求無法實現。

5xx: 服務器端錯誤。

2xx 狀態碼

200 OK [GET]: 服務器端成功返回用戶請求的數據。

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

202 Accepted 表示一個請求已經進入后臺排隊(一般是異步任務)。

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

4xx狀態碼

400：Bad Request - [POST/PUT/PATCH]: 用戶發出的請求有錯誤，服務器不理解客戶端的請求，未做任何處理。

401: Unauthorized; 表示用戶沒有權限(令牌、用戶名、密碼錯誤)。

403：Forbidden: 表示用戶得到授權了，但是訪問被禁止了, 也可以理解為不具有訪問資源的權限。

404：Not Found: 所請求的資源不存在，或不可用。

405：Method Not Allowed: 用戶已經通過了身份驗證, 但是所用的HTTP方法不在它的權限之內。

406：Not Acceptable: 用戶的請求的格式不可得(比如用戶請求的是JSON格式，但是只有XML格式)。

410：Gone - [GET]: 用戶請求的資源被轉移或被刪除。且不會再得到的。

415: Unsupported Media Type: 客戶端要求的返回格式不支持，比如，API只能返回JSON格式，但是客戶端要求返回XML格式。

422：Unprocessable Entity: 客戶端上傳的附件無法處理，導致請求失敗。

429：Too Many Requests: 客戶端的請求次數超過限額。

5xx 狀態碼

5xx 狀態碼表示服務器端錯誤：

500：INTERNAL SERVER ERROR; 服務器發生錯誤。

502：網關錯誤。

503: Service Unavailable 服務器端當前無法處理請求。

504：網關超時。

統一返回數據格式

RESTful規范中的請求應該返回統一的數據格式。

對于返回的數據，一般會包含如下字段:

code: http響應的狀態碼。

status: 包含文本, 比如：'success'(成功), 'fail'(失敗), 'error'(異常) HTTP狀態響應碼在500-599之間為 'fail';?

在400-499之間為 'error', 其他一般都為 'success'。

對于響應狀態碼為 1xx, 2xx, 3xx 這樣的可以根據實際情況可要可不要。

當status的值為 'fail' 或 'error'時，需要添加 message 字段，用于顯示錯誤信息。

data: 當請求成功的時候, 返回的數據信息。但是當狀態值為 'fail' 或 'error' 時，data僅僅包含錯誤原因或異常信息等。

返回成功的響應JSON格式一般為如下:

{ "code": 200, "status": "success", "data": [{ "userName": "tugenhua", "age": 31 }]}

返回失敗的響應json格式為如下:

{ "code": 401, "status": "error", "message": '用戶沒有權限', "data": null}

歡迎在留言區說出你的想法，大家一起討論。

你“在看”我嗎？

總結

以上是生活随笔為你收集整理的restful api接口规范_如何理解RESTful API设计规范？的全部內容，希望文章能夠幫你解決所遇到的問題。

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