Restful 是什麼？？

REST

REST(REpresentational State Transfer）是 Roy Fielding 博士於 2000 年在他的博士論文中提出來的一種軟件架構風格 (一組架構約束條件和原則)。在該論文的 中文譯本 中翻譯是 "表述性狀態移交"。

原則

資源（Resources）

資源是一種信息實體或者說是一個具體信息，能夠被想象出名字。比如多個圖書館，那麼便是可使用的圖書館資源，而圖書館內，多個樓層，那麼便擁有了多個樓層的資源，各樓層提供了不同服務，那麼服務也是資源。在互聯網中，可以用一個 URI（統一資源定位符）指向它，每種資源對應一個特定的 URI（如同一本書，按照書頁碼去定位哪一頁，目的是定位資源）。訪問這個特定 URI 便獲取到了這個對應的資源。

表述（REpresentations）

資源的表述是一段對於資源在某個特定時刻的狀態的描述，通過表述捕獲資源，並在組件間 (客戶 / 服務器) 移交該表述。表述有多種格式，如 HTML/XML/JSON / 純文本 / 圖片 / 視頻 / 音頻等。具體的表述格式，可以在 HTTP 請求頭信息中用 Accept 和 Content-Type 字段指定，請求 / 響應方向的表述通常使用不同的格式。

狀態移交（State Transfer）

對於組件間而言 (客戶 / 服務器)，資源的請求是一個互動過程。通過表述捕獲資源當前或是預期的狀態，相當於獲得了資源的狀態。通過移交代表資源的表述，來將資源在組件的兩者之間進行傳遞，進而改變應用狀態。如當客戶端獲取了資源後，自身狀態處於穩定，當再次獲取資源後自身狀態再次處於穩定。客戶端操作並對服務端發起請求，在資源上執行各種動作而打破資源自身狀態，達到客戶端操作所期望狀態。

RESTful Api

與 REST 相比多了一個 ful，就英語層面來說是一個形容詞，RESTful 翻譯成中文爲 “REST 式的”，滿足了 REST 架構風格的應用程序設計的 Api 則便是 RESTful Api，即 REST 式的 Api。

以往 Api 設計

在 MVC 項目中，經常都是設計成動賓結構給 ajax 調用

/getCustomers
/getCustomersByName
/getCustomersByPhone
/getNewCustomers
/verifyCredit
/saveCustomer
/updateCustomer
/deleteCustomer

可有時卻因爲沒有統一的規範，多人協作時，對於動詞的描述上也沒有統一，時長出現了類似如下的各類叫法，不能說這種情況有什麼弊端，畢竟這種方式也是正常工作着。

/getCustomers
/getAllCustomer
/getCustomerList
/getPagedCustomer
/queryCustomers
/queryAllCustomers
/queryCustomerList
...

相比之下，RESTful Api 提供了更爲標準化，規範化的 URL 寫法。

設計規範

考慮 Api 設計時，URI 中不能有動詞，URI 的目的是定位資源，而具體的對資源的操作，是藉助 HTTP 的動詞完成，與早期 Api 設計相比，本身的思路是不同的，原來更多的是考慮函數式編程或者叫做面向行爲的服務建模，比如 RPC，遠程調用一個函數，那麼 Api 設計便是會考慮爲動詞名詞格式，而對於 REST 風格來講，是面向資源的服務建模。而對於資源而言，可以是對象、數據或是查詢服務。

HTTP 動詞

對於一個系統而言，對外提供的功能總體上劃分爲兩類：

對於這其中使用到的一些動詞，使用 HTTP 的動詞描述來承擔對資源執行的行爲，動詞通常使用以下幾種。對於 HTTP1.1 規範中的其他幾個動詞（如 OPTIONS 等）則不再介紹。

URI

URI 作爲統一資源標識符，其本質是標識資源，就像進入圖書館，任一本書都應具有在哪個樓層，哪個區域，哪個書架等等標識信息，來唯一確定這本書，於資源而言，更是如此，對於 URI 的設計，規範是使用名詞來定位資源，比如常見的

GET /Api/Users/{id}

這樣便按照 id 值，來唯一定位這一 User

對於資源的單複數格式，儘管規範是儘可能使用複數，但並沒有說哪條紀律或是約束限制說一定要使用複數，這無需強制約束，按照自身統一即可。畢竟有些不可數名詞，沒有複數格式，那麼還是沿用本身，而對於整體風格爲複數下，卻又顯得格格不入。

面向資源

資源的組織決定着 URI 的展示方式，對於底層數據庫而言，也許 Order 模型有若干張表來支撐存儲，對外總體是提供着 Order 服務。這樣一來，如果按照底層數據庫表來考慮 Api 設計，則會陷入無盡的關係處理中，比如 Order 下有 OrderItem,OrderItem 下有 OrderItemAttachment，如果按照這個思路去實現 Api 設計時，那麼 URI 的設計上則會存在多級情況。

POST /Api/Orders
POST /Api/Orders/{id}/OrderItems
POST /Api/Orders/{id}/OrderItems/{itemId}/OrderItemAttachments
POST /Api/Orders/{id}/OrderItems/{itemId}/OrderItemAttachments/{}/...
...

於數據庫而言，表與表間構成了一張龐大的網，有時還不好找到定位資源的入口

如果按照單表進行 URI 設計，那麼則成了面向表服務建模，這又造成了底層的服務細節統統對外暴露，因此需要避免創建僅反映數據庫內部結構的 API。

在領域驅動設計中，聚合這一概念，將具有強相關的實體和值對象納入到一起，形成獨立空間、業務邏輯內聚於聚合之中，同生共死。面向聚合進行 Api 設計，多級路由的嵌套結構緩和許多，如需求上考慮 Order 創建時一定需要有 OrderItem 的存在，那麼則對於這兩者而言是捆綁的關係，而對於 OrderItemAttachment 而言，不是必要的。

那麼則可以獨立設計聚合 (此處忽略底層數據庫中表是如何設計的，僅考慮聚合)，URI 的設計也圍繞着聚合這一資源來進行，這樣一來，URI 的設計便成了如下結構

POST /Api/Orders 
{
    "locationId": 1,
    "productIds": [
        1,
        2,
        3
    ]
}

POST /Api/Orders/{id}/OrderItems 
{
    "productIds": [
        4,
        5,
        6
    ]
}

POST /Api/OrderItemAttachments 
{
    "orderItemId": 1,
    "fileUrl": "xxx"
}

嵌套層級結構不會太深，因爲太深的層級結構往往也意味着這個聚合的設計或許存在一點問題。

約束設計

對於 Post、Put、Patch 和 Delete 這些操作來講，面向聚合設計 URI 基本可以有路可循。

比如以下一些常見的 URI

POST /Api/Orders
POST /Api/Orders/{id}/OrderItems
POST /Api/OrderItemAttachment
PUT /Api/Orders/{id}
PUT /Api/Orders/{id}/OrderItems/{itemId}
PUT /Api/OrderItemAttachments/{id}
PATCH /Api/Orders/{id}/Address
PATCH /Api/Orders/{id}/OrderItems/{id}/Amount
PATCH /Api/OrderItemAttachments/{id}/FileUrl
DELETE /Api/Orders/{id}
DELETE /Api/Orders/Batches
DELETE /Api/Orders/{id}/OrderItems/{id}
DELETE /Api/OrderItemAttachments/{id}
POST /Api/Invites/emailTemplate

PATCH /Api/Invites/{id}/Sendmail //Sendmail 作爲郵件服務資源
PATCH /Api/Notifications/{id}/MessageStatus
PATCH /Api/Notifications/MessageStatus/batches
PATCH /Api/Orders/{id}/OrderItem/{itemId}/PayStatus

POST /Api/Orders/exports //返回導出資源
POST /Api/exportServices //提交給導出服務資源
POST /Api/exportServices/Sendmail
POST /Api/InviteParseServices //提交給解析服務資源

...

當然也有一些夾雜着動詞，習以爲常的 Api 設計，如果習慣了，不想改變，仍然可以使用着動詞 (後續提到該部分違反約束)，但若想改變，就得換個思路去考慮設計了

POST /Api/Account/Login
POST /Api/Account/Logout
POST /Api/Account/Register

比如，Login/Logout 操作的目標資源是什麼？如果把登錄的用戶當作在系統中存儲的資源來看便可以認爲已上線的用戶信息，取個資源名字，在線用戶 (onlineUser)，然後對其執行行爲。而對於 Register 來講，則更是容易轉換了，註冊本身是對 Account 的操作行爲，其本質是創建一個沒有過的用戶。那麼直接去掉註冊即可了，如認可改變可以按照如下設計，如仍習慣現有，則不改即可，並沒有什麼約束、紀律限制說一定要遵循。

POST /Api/Accounts
POST /Api/OnlineUsers
//如下需要結合 Authorization，不直接在 URI 中傳遞參數
DELETE /Api/OnlineUsers

主要是對於查詢類的操作，設計起來複雜一些，無論是實際開發中還是按照二八原則，大部分操作都是查詢操作，並且查詢起來天馬行空。

先是以下簡單的查詢

GET /Api/Orders
GET /Api/Orders/{id}
GET /Api/Orders/{id}/OrderItems
GET /Api/Orders/{id}/OrderItems/{id}

// 篩選
GET /Api/Orders?Name=xxx&LocationId=xxx
// 分頁
GET /Api/Orders?Page=1&Limit=10
// 也可以拆分成如下兩個此處資源爲 Page
GET /Api/Orders/Page?Page=1&Limit=10
GET /Api/Orders/PageCount?Page=1&Limit=10
// 排序
GET /Api/Orders?Sort=Name%20DESC
GET /Api/Orders?Sort=Name%20DESC,CreationTime%20ASC

然後再爲一些常見場景下的 (對於查詢類的，聚合的邊界應消失了，更多的應該是將各種資源串聯起來)

// UI 上需要知道某個資源是否存在
GET /Api/Orders?name=xxx
HEAD /Api/Orders?name=xxx
能夠查詢到狀態碼返回 204
找不到狀態碼返回 404

// 文件下載
GET /Api/OrderFiles/{id}/Url

// 報表分析(將報表分析的結果作爲虛擬資源)
GET /Api/AnalyseResults

// 返回指定條件下的總數
GET /Api/Locations/{id}/OrderCount?Status[]&Status[]=2&CreationTime=2022-05-01

// UI 上下拉框所需要的基礎數據
GET /Api/Locations/Names?page=1&limit=30&search=xxx
{
  "id": "xxx",
  "name": "xxx"
}

// 獲取最近的循環週期
GET /Api/Plans/{id}/LatestCycleDate

// 獲取最近的記錄(根據時間，狀態過濾後的第一條)
GET /Api/Orders/Latest

...

實際使用中，算了算也只有百分之八十左右的接口是按照 RESTful Api 的規範使用着的，總是有些接口，不能或是難以用簡單的描述就能解決。比如如下幾個接口，我便直接違反着約束 (不能有動詞，只能使用名詞)。

PATCH /Api/Invites/{id}/Approval
PATCH /Api/Invites/{id}/Decline
PATCH /Api/Invites/{id}/Reject
...

Github 中也還是有動詞描述 https://docs.github.com/en/rest/codespaces/codespaces#start-a-codespace-for-the-authenticated-user

https://docs.github.com/en/rest/codespaces/codespaces#stop-a-codespace-for-the-authenticated-user

https://docs.github.com/en/rest/checks/runs#rerequest-a-check-run

https://docs.github.com/en/rest/checks/suites#rerequest-a-check-suite

如果按照這幾個約束條件來看的話，僅當滿足三個約束條件的才能認爲是 RESTful Api，而滿足一個或是兩個約束條件的爲 Http Api，那麼我們或許是一直在追隨 RESTful Api 的路上了。

面對這部分難以描述或是無法組織的接口，個人認爲直接違反一些約束即可，總歸是隻有少部分接口僅滿足一個到兩個約束。

狀態碼

HTTP 中使用狀態碼來表示着請求的成功與否，我們可以直接使用它，而無需在返回值中再包裹一層 code/message，儘管在 mvc 中，我也很喜歡這麼做。

{
  "code":200,
  "message":"",
  "data":{
    
  }
}

對 HTTP 的狀態碼接觸越多後，越發覺得思路偏了，不應該將請求響應的狀態碼與業務中行爲的成功與否進行隔離開，因爲 HTTP 本身是應用層協議（超文本移交協議），是爲業務服務的。如何在網絡層面上把一個請求發送出去，再接收到響應，這是 TCP 協議來保障的。假設網絡層如果請求失敗了，那麼應用層都無法進行，因此結合狀態碼與返回內容（當出現異常時仍然返回狀態碼與錯誤描述信息）。如下 HTTP 的狀態碼覆蓋了絕大部分場景。當客戶端需要追蹤問題時，查看對應請求的狀態碼，結合其對應的解釋說明，便可以去定位相關的問題，當然，前提是真的返回了符合場景下的狀態碼。

  1. Informational responses (100–199)

  2. Successful responses (200–299)

  3. Redirection messages (300–399)

  4. Client error responses (400–499)

  5. Server error responses (500–599)

在 Api 中，100 階段的狀態碼不會涉及，具體的各響應碼參見如下圖

版本號

對外提供的資源服務地址需要存在版本控制，以便於客戶端應用能夠訪問到對應的資源，版本號的規劃有如下幾種方式，具體使用哪種得依靠具體的情況而分析：

  1. 不考慮版本，內部使用、短暫的生命週期下不考慮資源的變更或是直接對資源本身進行了換新如此變更到新的 url 上。

  2. 爲每個資源的 URI 添加一個版本號。

GET /Api/v2/Orders/{id}
  1. 作爲查詢字符串參數來指定資源的版本
GET /Api/Orders/{id}?version=2
  1. 在 http 的 header 中增加自定標頭設置版本號。
GET /Api/Orders/{id}
Custom-Header: version=2

成熟度模型

2008 年 Leonard Richardson 爲 Web API 提出了以下成熟度模型 ：

誠然，對於這個成熟度模型，我一般都只會去達到前三個級別，雖然 Roy Fielding 明確表示 ，Level 3 纔是真正的 RESTful Api，對於 Level 3 級別，其實並沒有理解到其具體奧妙。因爲我們面對的是 UI，用 UI 去鏈接操作，那麼對於 Level 3 返回的超媒體而言，又如何表現呢？

參考文檔

作者：微笑刺客 D

來源：www.cnblogs.com/CKExp/p/16306835.html

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/oJkNOwWzVH3VtsDHL9WMNw

猜你喜歡