什麼是 RESTful

百度一下 RESTful，查到的資料很多都講得不清楚，看完了都不知道說的是啥，導致很多人對 RESTful 不甚瞭解。來看一下常見的解釋：

（1）神一樣的描述

REST 並不是“休息”的意思，而是 Representational State Transfer 的簡稱，即 表現層狀態轉移。

“表現層狀態轉移”是什麼鬼？

（2）雲裡霧裡的描述

• REST 指的是 一組架構約束條件和原則，如果一個架構符合 REST 的約束條件和原則，就稱之為 RESTful 架構。
• RESTful 是一種軟件架構風格，而不是標準。

這能看懂一點了，但還是雲裡霧裡的。

（3）大神的總結

再看知乎大神 Ivony 的一句話精闢概括：

用 URL 定位資源，用 HTTP 動詞（GET，POST，DELETE，PUT）描述操作。

RESTful 是一種 web 服務設計風格，風格意思就是大家默認的但不是強制的。

RESTful 詳解

1、用 URL 定位資源

REST 的主體是資源，所謂“資源”，就是網絡上的一個具體信息，例如：一張圖片，一段文字、一種服務。總之就是一個實際存在的東西，而 URL 就是用來指向這個資源的。

例如：

https://api.example.com/users

這個 URL 一看就知道是對 user 資源的操作。URL 中只使用名詞來指定資源，不包含操作。為什麼呢？

如果要包含操作，那至少有增刪改查四種，那麼上例中的一個接口至少要變成四個：

https://api.example.com/add_user
https://api.example.com/delete_user
https://api.example.com/update_use
https://api.example.com/get_user

太多了，不夠簡潔。

2、用 HTTP 動詞描述操作

那怎麼描述操作呢？答案就是用 HTTP 動詞。

HTTP 動詞，可能很多人第一眼看到的時候有點蒙，不知道是啥，其實就是我們請求網頁時用的 GET、POST 等操作。我們平時用的最多的就是 GET 和 POST（例如寫爬蟲的時候，基本都是這兩種），常用的還有 PUT、PATCH、DELETE 。

對資源的操作，無外乎 CRUD（增刪改查），RESTful 中，每個 HTTP 動詞對應一個 CRUD 操作。

• GET：對應 Retrieve 操作（查詢操作）
• POST：對應 Create 操作
• DELETE：對應 Delete 操作
• PUT：對應 Update 操作
• PATCH：對應 Update 操作

3、 POST 和 PUT 的區別

一般說到 HTTP 動詞對應 CRUD 的時候，PUT 都是對應 Update 操作的。但其實，PUT 也可以做 Create 操作。二者的區別在於：

• URL：POST 不需要指定到個體，例如新增 user 的接口 POST /api/users。 PUT 的 URL 需要指定到具體的個體，例如 PUT /api/users/1，如果 1 這個 user 存在，則 Update，否則 Create。這個很好理解，POST 確定是新增，insert 的時候是不需要 where 條件的；PUT 則不行，update 的時候不加 where，幹過的小夥伴請舉手。另外，PUT 的時候，也不是每個 user 就要建一個接口的，這裡需要用到的就是路由，一般是寫成 PUT /api/users/{id}，這樣就具有一般性了。路由在這裡就不展開講了。
• 冪等性：PUT 是冪等的，而 POST 是非冪等的。關於冪等性，見下文。

4、 PATCH 和 PUT 的區別

PATCH 是 2010 後成為的正式 http 方法，它是對 PUT 的補充。在沒有 PATCH 之前，都是用 PUT 進行更新操作，這時候我們的接口中通常會有一個邏輯規則，如：如果對象的一個屬性值為null，那麼就不更新該屬性（字段）值，通過這種方式來避免全部覆蓋的操作。現在有了 PATCH 就解決了這種判斷，在 PUT 操作中不管屬性是不是 null，都進行更新，在 PATCH 接口中就對非 null 的進行更新。另外，PATCH 是非冪等的。

5、 變通的 POST

按照 REST 建議，查詢操作要使用 GET 方法，但是實際情況中處理起來比較麻煩，如：報表統計查詢，需要傳遞的參數很多，如果採用 GET 方法，那麼接口接收的參數非常多，接口很難看，通常會封裝為 java 對象，但 GET 方法又不支持對象傳參，所以很蛋疼；

對於這種情況，最簡單的方式就是改成 POST 方式，而且很多公司都是這麼幹的。可見 REST 只是建議，並非強制約束。

補充：冪等性

冪等（Idempotence）本來是一個數學上的概念，定義就不說了，看了頭暈。

後來拓展到計算機領域，描述為：

一個操作、方法或者服務，其任意多次執行所產生的影響均與一次執行的影響相同。

一個冪等的方法，使用同樣的參數，對它進行多次調用和一次調用，對系統產生的影響是一樣的。所以，對於冪等的方法，不用擔心重複執行會對系統造成任何改變。

舉個例子，用戶 X 的手機話費餘額為 2 元，他用支付寶給手機充了 100 元話費，如果將這個操作描述為“給 X 的賬戶餘額增加 100 元”那就是非冪等的，重複操作幾次運營商就虧大了。但是，如果將這個操作描述為“將 X 的賬戶餘額設置為 102 元”，那這個操作就是冪等的。簡單來說：

• 冪等操作：將賬戶 X 的餘額設置為 102 元；
• 非冪等操作：將賬戶 X 的餘額增加 100 元。

注意：這裡的冪等性的例子並不嚴謹，本文主要不是講冪等性的，所以只是舉個簡單的例子，不做深入探討。

RESTful 的其他細節

1、命名規則

• （1）全部小寫，用 _ 或 - 線連接。

例如我在上面給出的例子 ：

https://api.example.com/add_user

之所以不用駝峰命名法，是因為早期的 URI 一般都是表示服務器上的文件路徑，而不同服務器對大小寫的敏感性是不同的，為了兼容不同服務器所以才規定不能混用大小寫字母。

• （2）URL 中只用名詞指定資源，因為 REST 的核心是資源，而表示資源的詞語天然就是名詞。
• （3）資源用複數表示。

2、 版本

一種方法是在 URL 中添加版本號，例如：

https://api.example.com/v1/users

另一種方法是將版本號加在 HTTP 請求頭信息的 Accept 字段中，例如：

Accept: version=1.0

雖然有很多博客裡推薦裡說是推薦在 header 裡添加版本信息，因為不同的版本表示的資源依然是同一個，所以不應該用不同的 URL。但是以我目前瞭解到的情況來看，絕大多數公司都是將版本號放在 URL 中的，並且推薦這麼做，簡單直觀。

網上能找到的版本號加在 URL 中的例子，都是如我上例所示的寫法。但是 Jack_Zeng 指出，這樣寫容易有歧義，會讓人誤以為 v1 也是資源的一部分，一般都是這麼寫：

https://api.example.com/users?api-version=1
 

3、 HTTP 狀態碼

知乎上另一大神對 RESTful 的解釋，相比於 Ivony 多了一句話，他用了三句話來描述：

• 看 Url 就知道要什麼
• 看 http method 就知道幹什麼
• 看 http status code 就知道結果如何

前兩句和 Ivony 的是一個意思。這第三句我覺得總結得也很經典。

http 狀態碼有 100 多種，我們並不需要全部用到，只需要瞭解其中常用的就可以了

• 200 – OK – 一切正常
• 201 – OK – 新資源已經被創建
• 204 – OK – 資源刪除成功
• 304 – 沒有變化，客戶端可以使用緩存數據
• 400 – Bad Request – 調用不合法，確切的錯誤應該在 error payload 中描述
• 401 – 未認證，調用需要用戶通過認證
• 403 – 不允許的，服務端正常解析和請求，但是調用被回絕或者不被允許
• 404 – 未找到，指定的資源不存在
• 422 – 不可指定的請求體 – 只有服務器不能處理實體時使用，比如圖像不能被格式化，或者重要字段丟失
• 500 – Internal Server Error – 標準服務端錯誤，開發人員應該儘量避開這種錯誤