REST 簡介

REST 是一個術(shù)語的縮寫，REpresentational State Transfer，中文直譯「表征狀態(tài)轉(zhuǎn)移」，這是個很拗口的詞。我的建議是先不要強行理解，直接看怎么做，等對實施細(xì)節(jié)有一些了解后，再來看名字會有更深刻的理解。REST 是一套風(fēng)格約定，RESTful 是它的形容詞形式；比如一套實現(xiàn)了 REST 風(fēng)格的接口，可以稱之為 RESTful 接口。

REST 對請求的約定

REST 用來規(guī)范應(yīng)用如何在 HTTP 層與 API 提供方進行數(shù)據(jù)交互；在現(xiàn)階段，你應(yīng)該已經(jīng)很熟悉 GET 和 POST 請求；甚至有可能因為受限于后端框架限制等原因，你的整個應(yīng)用全都是用這兩種 HTTP 方法來完成的。這樣無疑浪費了 HTTP 協(xié)議的潛力，而 REST 則充分利用了 HTTP 規(guī)范中的方法，達到接口描述的語義化。

REST 描述了 HTTP 層里客戶端和服務(wù)器端的數(shù)據(jù)交互規(guī)則；客戶端通過向服務(wù)器端發(fā)送 HTTP（s）請求，接收服務(wù)器的響應(yīng)，完成一次 HTTP 交互。這個交互過程中，REST 架構(gòu)約定兩個重要方面就是 HTTP 請求的所采用方法，以及請求的鏈接。

在請求層面，REST 規(guī)范可以簡單粗暴抽象成以下兩個規(guī)則：

1. 請求 API 的 URL 表示用來定位資源；

2. 請求的 METHOD 表示對這個資源進行的操作；

以下將以這兩個規(guī)則為基礎(chǔ)，描述如何構(gòu)造一個符合 REST 規(guī)范的請求。

一、API 的 URL

URL 用來定位資源，跟要進行的操作區(qū)分開，這就意味這 URL 不該有任何動詞；

下面示例中的 get、create、search 等動詞，都不應(yīng)該出現(xiàn)在 REST 架構(gòu)的后端接口路徑中。在以前，這些接口中的動名詞通常對應(yīng)后臺的某個函數(shù)。比如：

/api/getUser
/api/createApp
/api/searchResult
/api/deleteAllUsers

當(dāng)我們需要對單個用戶進行操作時，根據(jù)操作的方式不同可能需要下面的這些接口：

/api/getUser （用來獲取某個用戶的信息，還需要以參數(shù)方式傳入用戶 id 信息）
/api/updateUser （用來更新用戶信息）
/api/deleteUser （用來刪除單個用戶）
/api/resetUser （重置用戶的信息）

更有甚者，可能在更新用戶不同信息時，提供不同的接口，比如：

/api/updateUserName
/api/updateUserEmail
/api/updateUser

這樣的弊端在于：首先加上了動詞，肯定是使 URL 更長了；其次對一個資源實體進行不同的操作就是一個不同的 URL，造成 URL 過多難以管理。

其實當(dāng)你回過頭看「URL」 這個術(shù)語的定義時，更能理解這一點。URL 的意思是統(tǒng)一資源定位符，這個術(shù)語已經(jīng)清晰的表明，一個 URL 應(yīng)該用來定位資源，而不應(yīng)該摻入對操作行為的描述。

在 REST 架構(gòu)的鏈接應(yīng)該是這個樣子：

URL 中不應(yīng)該出現(xiàn)任何表示操作的動詞，鏈接只用于對應(yīng)資源；
URL 中應(yīng)該單復(fù)數(shù)區(qū)分，推薦的實踐是永遠(yuǎn)只用復(fù)數(shù)；比如 GET /api/users 表示獲取用戶的列表；如果獲取單個資源，傳入 ID，比如 /api/users/123 表示獲取單個用戶的信息；
按照資源的邏輯層級，對 URL 進行嵌套，比如一個用戶屬于某個團隊，而這個團隊也是眾多團隊之一；那么獲取這個用戶的接口可能是這樣：

GET /api/teams/123/members/234 表示獲取 id 為 123 的小組下，id 為234 的成員信息

按照類似的規(guī)則，可以寫出如下的接口

/api/teams （對應(yīng)團隊列表）
/api/teams/123 （對應(yīng) ID 為 123 的團隊）
/api/teams/123/members （對應(yīng) ID 為 123 的團隊下的成員列表）
/api/teams/123/members/456 （對應(yīng) ID 為 123 的團隊下 ID 未 456 的成員）

二、API 請求的方法

在很多系統(tǒng)中，幾乎只用 GET 和 POST 方法來完成了所有的接口操作；這個行為類似于全用 DIV 來布局。實際上，我們不只有GET 和 POST 可用，在 REST 架構(gòu)中，有以下幾個重要的請求方法：GET，POST，PUT，PATCH，DELETE。這幾個方法都可以與對數(shù)據(jù)的 CRUD 操作對應(yīng)起來。

【Read】，資源的讀取，用 GET 請求；比如：

GET /api/users  （ 表示讀取用戶列表）

GET 應(yīng)當(dāng)實現(xiàn)為一個安全方法。用于獲取數(shù)據(jù)而不應(yīng)該產(chǎn)生副作用。

【Created】，資源的創(chuàng)建，用 POST 方法；

POST 是一個非冪等的方法，多次調(diào)用會造成不同效果；

冪等（Idempotent）：如果對服務(wù)器資源的多次請求與一次請求造成的副作用是一樣的的話，那這個請求方法可以被認(rèn)為是冪等。

比如下面的請求會在服務(wù)器上創(chuàng)建一個 name 屬性為 'John Snow' 的用戶；多次請求就會創(chuàng)建多個這樣的用戶。

POST /api/users
{
  "name": "John Snow"
}

【Update】，資源的更新。用于更新的 HTTP 方法有兩個，PUT 和 PATCH。

他們都應(yīng)當(dāng)被實現(xiàn)為冪等方法，即多次同樣的更新請求應(yīng)當(dāng)對服務(wù)器產(chǎn)生同樣的副作用。

PUT 和 PATCH 有各自不同的使用場景：

PUT 用于更新資源的全部信息，在請求的 body 中需要傳入修改后的全部資源主體；

而 PATCH 用于局部更新，在 body 中只需要傳入需要改動的資源字段。

設(shè)想服務(wù)器中有以下用戶資源 /api/users/123

{
 "id": 123,
 "name": "Original",
 "age": 20
}

當(dāng)我們往后臺發(fā)送更新請求時，PATCH 和 PUT 造成的效果是不一樣。

PUT /api/users/123
{
 "name": "PUT Update"
}

上述 PUT 請求操作后的內(nèi)容是：

{
 "id": 123,
 "name": "PUT Update"
}

可以觀察到，資源原有的 age 字段被清除掉了。

而如果改用 PATCH 的話，

PATCH /api/users/123
{
 "name": "PATCH Update"
}

更新后的內(nèi)容是：

{
 "id": 123,
 "name": "PATCH Update",
 "age": 20
}

請求中指定的 name 屬性被更新了，而原有的 age 屬性則保持不變。

PATCH 的作用在于如果一個資源有很多字段，在進行局部更新時，只需要傳入需要修改的字段即可。否則在用 PUT 的情況下，你不得不將整個資源模型全都發(fā)送回服務(wù)器，造成網(wǎng)絡(luò)資源的極大浪費。

【Delete】，資源的刪除，相應(yīng)的請求 HTTP 方法就是 DELETE。這個也應(yīng)當(dāng)被實現(xiàn)為一個冪等的方法。如:

DELETE /api/users/123

用于刪除服務(wù)器上 ID 為 123 的資源，多次請求產(chǎn)生副作用都是，是服務(wù)器上 ID 為 123 的資源不存在。

三、分頁、過濾

REST 風(fēng)格的接口地址，表示的可能是單個資源，也可能是資源的集合；當(dāng)我們需要訪問資源集合時，設(shè)計良好的接口應(yīng)當(dāng)接受參數(shù)，允許只返回滿足某些特定條件的資源列表。

比如支持以 offset 和 limit 參數(shù)來進行分頁；

GET /api/users?offset=0&limit=20

支持提供關(guān)鍵詞進行搜索，以及排序

GET /api/users?keyword=john&sort=age

支持根據(jù)字段進行過濾

GET /api/users?gender=male

設(shè)計合適的 API URL，以及選擇合適的請求方法，可以語義化的描述一個 HTTP 請求的操作。

當(dāng)我們都熟悉且遵循這樣的規(guī)范后，基本可以看到一個 REST 風(fēng)格的接口就知道如何使用這個接口進行 CRUD 操作了。比如下面這面這個接口就表示搜索 ID 為 123 的圖書館的書，并且書的信息里包含關(guān)鍵字「game」，返回前十條滿足條件的結(jié)果。

GET /api/libraries/123/books?keyword=game&sort=price&limit=10&offset=0

同樣，下面這個請求的意思也就很明顯了吧。

PATCH /api/companies/123/employees/234
{
    "salary": 2300
}

總結(jié)

限于篇幅限制，本文僅從請求的角度選取了幾個重點描述了實現(xiàn) RESTful 接口需要滿足的基本要求。關(guān)于 REST 的更多詳細(xì)規(guī)范，可以參考這個倉庫。

轉(zhuǎn)自：RESTful 接口實現(xiàn)簡明指南

總結(jié)

以上是生活随笔為你收集整理的RESTful 接口实现简明指南的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。