通俗講解 RESTful

1 什麼是 RESTful

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

（1）神同樣的描述 REST 並非「休息」的意思，而是 Representational State Transfer 的簡稱，即 表現層狀態轉移。

「表現層狀態轉移」是什麼鬼？

（2）雲裏霧裏的描述

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

這能看懂一點了，但仍是雲裏霧裏的。

（3）大神的總結 再看知乎大神 Ivony 的一句話精闢歸納：

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

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

2 RESTful 詳解

2.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.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 操做

2.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 是非冪等的。關於冪等性，見下文。

2.4 PATCH 和 PUT 的區別

PATCH 是 2010 後成爲的正式 http 方法，它是對 PUT 的補充。在沒有 PATCH 以前，都是用 PUT 進行更新操做，這時候咱們的接口中一般會有一個邏輯規則，如：若是對象的一個屬性值爲null，那麼就不更新該屬性（字段）值，經過這種方式來避免所有覆蓋的操做。如今有了 PATCH 就解決了這種判斷，在 PUT 操做中無論屬性是否是 null，都進行更新，在 PATCH 接口中就對非 null 的進行更新。另外，PATCH 是非冪等的。

2.5 變通的 POST

按照 REST 建議，查詢操做要使用 GET 方法，可是實際狀況中處理起來比較麻煩，如：報表統計查詢，須要傳遞的參數不少，若是採用 GET 方法，那麼接口接收的參數很是多，接口很難看，一般會封裝爲 java 對象，但 GET 方法又不支持對象傳參，因此很蛋疼；

對於這種狀況，最簡單的方式就是改爲 POST 方式，並且不少公司都是這麼幹的。可見 REST 只是建議，並不是強制約束。

補充：冪等性

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

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

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

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

舉個例子，用戶 X 的手機話費餘額爲 2 元，他用支付寶給手機充了 100 元話費，若是將這個操做描述爲「給 X 的帳戶餘額增長 100 元」那就是非冪等的，重複操做幾回運營商就虧大了。可是，若是將這個操做描述爲「將 X 的帳戶餘額設置爲 102 元」，那這個操做就是冪等的。簡單來講：

• 冪等操做：將帳戶 X 的餘額設置爲 102 元；
• 非冪等操做：將帳戶 X 的餘額增長 100 元。

注意：這裏的冪等性的例子並不嚴謹，本文主要不是講冪等性的，因此只是舉個簡單的例子，不作深刻探討。

3 RESTful 的其餘細節

3.1 命名規則

• （1）所有小寫，用 _ 或 - 線鏈接。

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

https://api.example.com/add_user
複製代碼

之因此不用駝峯命名法，是由於早期的 URI 通常都是表示服務器上的文件路徑，而不一樣服務器對大小寫的敏感性是不一樣的，爲了兼容不一樣服務器因此才規定不能混用大小寫字母。

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

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.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 – 標準服務端錯誤，開發人員應該儘可能避開這種錯誤

參考資料：

• www.zhihu.com/question/28…
• blog.csdn.net/mingjia1987…