深入理解RESTful Api設計

REST

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

原則

• 網(wǎng)絡上的所有事物都被抽象為資源
• 每個資源都有一個唯一的資源標識符
• 同一個資源具有多種表現(xiàn)形式(xml，json 等)
• 對資源的各種操作不會改變資源標識符
• 所有的操作都是無狀態(tài)的

資源（Resources）

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

表述（REpresentations）

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

狀態(tài)移交（State Transfer）

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

RESTful Api

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

以往 Api 設計

在 MVC 項目中，經(jīng)常都是設計成動賓結構給 ajax 調(diào)用

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

可有時卻因為沒有統(tǒng)一的規(guī)范，多人協(xié)作時，對于動詞的描述上也沒有統(tǒng)一，時長出現(xiàn)了類似如下的各類叫法，不能說這種情況有什么弊端，畢竟這種方式也是正常工作著。

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

相比之下，RESTful Api 提供了更為標準化，規(guī)范化的 URL 寫法。

設計規(guī)范

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

HTTP 動詞

對于一個系統(tǒng)而言，對外提供的功能總體上劃分為兩類：

• 獲取系統(tǒng)資源，主要包括讀取資源和資源描述信息。
• 對系統(tǒng)資源進行變更，主要包括寫入資源，對已有資源狀態(tài)的變更，刪除已有資源。

對于這其中使用到的一些動詞，使用 HTTP 的動詞描述來承擔對資源執(zhí)行的行為，動詞通常使用以下幾種。對于 HTTP1.1 規(guī)范中的其他幾個動詞（如 OPTIONS 等）則不再介紹。

• GET: 獲取目標資源。
• HEAD: 獲?。▊鬏敚┠繕速Y源的元數(shù)據(jù)信息。該方法與 GET 相同，但是不傳遞內(nèi)容體。
• POST: 創(chuàng)建新資源，對于復雜查詢而言，提交查詢表單給查詢服務也是常用 POST 的（當然其他幾個能做的它也能做）。
• PUT: 替換已有資源(整體)。
• PATCH: 修改已有資源(局部)。
• DELETE: 刪除資源。

URI

URI 作為統(tǒng)一資源標識符，其本質(zhì)是標識資源，就像進入圖書館，任一本書都應具有在哪個樓層，哪個區(qū)域，哪個書架等等標識信息，來唯一確定這本書，于資源而言，更是如此，對于 URI 的設計，規(guī)范是使用名詞來定位資源，比如常見的

GET/Api/Users/{id}

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

對于資源的單復數(shù)格式，盡管規(guī)范是盡可能使用復數(shù)，但并沒有說哪條紀律或是約束限制說一定要使用復數(shù)，這無需強制約束，按照自身統(tǒng)一即可。畢竟有些不可數(shù)名詞，沒有復數(shù)格式，那么還是沿用本身，而對于整體風格為復數(shù)下，卻又顯得格格不入。

面向資源

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

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

于數(shù)據(jù)庫而言，表與表間構成了一張龐大的網(wǎng)，有時還不好找到定位資源的入口

如果按照單表進行 URI 設計，那么則成了面向表服務建模，這又造成了底層的服務細節(jié)統(tǒng)統(tǒng)對外暴露，因此需要避免創(chuàng)建僅反映數(shù)據(jù)庫內(nèi)部結構的 API。

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

那么則可以獨立設計聚合(此處忽略底層數(shù)據(jù)庫中表是如何設計的，僅考慮聚合)，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 設計，如果習慣了，不想改變，仍然可以使用著動詞(后續(xù)提到該部分違反約束)，但若想改變，就得換個思路去考慮設計了

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

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

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

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

先是以下簡單的查詢

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

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

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

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

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

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

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

//獲取最近的循環(huán)周期
GET/Api/Plans/{id}/LatestCycleDate

//獲取最近的記錄(根據(jù)時間，狀態(tài)過濾后的第一條)
GET/Api/Orders/Latest

...

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

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 的路上了。

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

狀態(tài)碼

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

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

}
}

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

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 階段的狀態(tài)碼不會涉及，具體的各響應碼參見如下圖

版本號

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

1. 不考慮版本，內(nèi)部使用、短暫的生命周期下不考慮資源的變更或是直接對資源本身進行了換新如此變更到新的 url 上。
2. 為每個資源的 URI 添加一個版本號。

GET/Api/v2/Orders/{id}

1. 作為查詢字符串參數(shù)來指定資源的版本

GET/Api/Orders/{id}?version=2

1. 在 http 的 header 中增加自定標頭設置版本號。

GET/Api/Orders/{id}
Custom-Header:version=2

成熟度模型

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

• Level 0: 定義一個 URI，所有操作是對此 URI 發(fā)出的 POST 請求。
• Level 1: 為各個資源單獨創(chuàng)建 URI。
• Level 2: 使用 HTTP 方法來定義對資源執(zhí)行的操作。
• Level 3: 使用超媒體（HATEOAS: 「H」ypermedia 「A」s 「T」he 「E」ngine 「O」f 「A」pplication 「S」tate，參見 HATEOAS - Wikipedia ）。

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