【原創文章，轉載請注明原文章地址，謝謝！】

摘要，本文主要是簡單討論RESTful的相關設計問題，包括資源設計，動作設計和響應設計。

資源設計

在本系列第一篇文章中已經通過一個優惠券的例子給大家簡單闡述了一下資源的設計，包括二級資源的設計。下面我們來看下詳細的資源設計方案：
前面我們已經了解到，在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的”集合”（collection），所以API中的名詞也應該使用復數。
例如，針對一個動物園應用，可能涉及到的資源就應該有：
https://api.example.com/v1/zoos：動物園資源
https://api.example.com/v1/animals：動物資源
https://api.example.com/v1/employees：飼養員資源
注意設計的方案，最后一個單詞都是名詞并且都是復數。對于簡單的應用來說，一般一個資源就對應一個表，這樣的設計已經足夠。但是更多的情況，面對復雜的應用，因為HTTP提供的接口是有限的（HTTP一共就提供了常用的5種請求方式，所以能表示的對一個資源的操作是有限的）怎么抽取出合適的資源，也是一個相對來說比較困難的事情。這個在我們后面的實戰示例中會提到。

動作設計

先來看看REST中針對HTTP常用動作的一些固定的含義：

• GET（SELECT）：表示從服務器取出資源（一項或多項）。
• POST（CREATE）：表示在服務器新建一個資源。
• PUT（UPDATE）：表示在服務器更新資源（客戶端需要提供改變后的完整資源）。
• PATCH（UPDATE）：表示在服務器更新資源（客戶端需要提供改變的屬性【可以簡單理解為補丁】）。
• DELETE（DELETE）：表示從服務器刪除資源。

以上五個是最常用的請求方式；另外還有兩個：

• HEAD：獲得一個資源的元數據，比如一個資源的hash值或者最后修改日期；
• OPTIONS：獲得客戶針對一個資源能夠實施的操作；這個主要是作為Hypermedia 存在（在最佳實踐中介紹）

下面列幾個簡單的動作示例，示例格式 HTTP動作 URL：說明

• GET /zoos：列出所有動物園
• POST /zoos：新建一個動物園
• GET /zoos/ID：獲取某個指定動物園的信息（ID即指定動物園id）
• PUT /zoos/ID：更新某個指定動物園的信息（瀏覽器端需要提供該動物園的全部信息）
• PATCH /zoos/ID：更新某個指定動物園的信息（瀏覽器端需要提供該動物園的部分信息）
• DELETE /zoos/ID：刪除某個動物園
• GET /zoos/ID/animals：列出某個指定動物園的所有動物（animals為二級資源路徑）
• DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物animals為二級資源路徑，前面一個id是指定動物園id，后面一個id是指定動物id）

返回結果

返回結果也是HTTP協議中非常重要的組成部分，客戶端完全通過返回結果來斷定請求的結果，包括異常等。

返回值類型

即針對不同的請求方式，應該返回什么標準的內容。但是注意，具體返回什么樣式的內容，是通過頭信息來規定的。下面直接使用一些案例來說明：

• GET /collection：規定返回資源對象的列表（數組）
• GET /collection/resource：規定返回單個資源對象
• POST /collection：規定返回新生成的資源對象
• PUT /collection/resource：規定返回完整的資源對象
• PATCH /collection/resource：規定返回完整的資源對象
• DELETE /collection/resource：規定返回一個空文檔

Content Type

一個API可以允許返回JSON，XML甚至HTML等文檔格式；具體的文檔格式由頭信息規定。而頭信息來源于兩點，一個是請求頭中的Accept Type，表示客戶端需要請求的表現層數據格式。一個是響應頭中的Content Type，表示本次請求服務器端返回的數據格式。

另外，完全也可以通過URI后綴來表示請求格式，比如GET /animals.json用來表示請求json格式的動物列表數據，使用GET /animals.xml來表示請求XML格式的動物列表數據，但是更建議使用請求頭來表示，不要把數據類型和資源混淆。

返回狀態碼

返回狀態碼在HTTP/1.1協議中是一個非常重要的概念。表示了本次請求的一個最終的效果，也是客戶端判定本次請求結果的第一個入口。返回狀態碼非常多，下面簡單列舉了常用的返回狀態碼說明（格式：狀態碼 狀態碼說明 適合的請求類型：解釋）：

• 200 OK - [GET]：服務器成功返回用戶請求的數據。
• 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功（但是大部分情況下，使用200也是可以的）。
• 202 Accepted - [*]：表示一個請求已經進入后臺排隊（針對異步請求，或者后臺服務需要一定處理時間的請求）
• 204 NO CONTENT - [DELETE]：用戶刪除數據成功（但是大部分情況下，使用200也是可以的）。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等（冪等的意思是針對一個數據，多次實施相同的操作效果是一致的。比如多次刪除一條數據，最后的效果是一樣的，即這條數據被刪除，那么刪除操作是冪等的，而對于++運算符，每次操作的結果都是在上一次數據值上面加1，所以++操作不是冪等的）的。
• 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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。

小結

在本節中，主要針對RESTful的常見的設計做出了一些解釋，到此，關于RESTful的基本概念介紹完畢，要真正的去理解和體會RESTful的好處，還需要在實際的開發中慢慢看。從下一篇文章開始，進入RESTful的開發基礎介紹。

總結

以上是生活随笔為你收集整理的Java开发RESTful（三）RESTful设计的全部內容，希望文章能夠幫你解決所遇到的問題。

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