REST

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

原則

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

資源（Resources）

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

表述（REpresentations）

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

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

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

RESTful Api

與 REST 相比多了一個(gè) ful，就英語層面來說是一個(gè)形容詞，RESTful 翻譯成中文為“REST 式的”，滿足了 REST 架構(gòu)風(fēng)格的應(yīng)用程序設(shè)計(jì)的 Api 則便是 RESTful Api，即 REST 式的 Api。

以往 Api 設(shè)計(jì)

在 MVC 項(xiàng)目中，經(jīng)常都是設(shè)計(jì)成動(dòng)賓結(jié)構(gòu)給 ajax 調(diào)用

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

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

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

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

設(shè)計(jì)規(guī)范

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

HTTP 動(dòng)詞

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

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

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

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

URI

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

GET/Api/Users/{id}

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

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

面向資源

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

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

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

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

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

那么則可以獨(dú)立設(shè)計(jì)聚合(此處忽略底層數(shù)據(jù)庫(kù)中表是如何設(shè)計(jì)的，僅考慮聚合)，URI 的設(shè)計(jì)也圍繞著聚合這一資源來進(jìn)行，這樣一來，URI 的設(shè)計(jì)便成了如下結(jié)構(gòu)

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"
}

嵌套層級(jí)結(jié)構(gòu)不會(huì)太深，因?yàn)樘畹膶蛹?jí)結(jié)構(gòu)往往也意味著這個(gè)聚合的設(shè)計(jì)或許存在一點(diǎn)問題。

約束設(shè)計(jì)

對(duì)于 Post、Put、Patch 和 Delete 這些操作來講，面向聚合設(shè)計(jì) 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作為郵件服務(wù)資源
PATCH/Api/Notifications/{id}/MessageStatus
PATCH/Api/Notifications/MessageStatus/batches
PATCH/Api/Orders/{id}/OrderItem/{itemId}/PayStatus

POST/Api/Orders/exports//返回導(dǎo)出資源
POST/Api/exportServices//提交給導(dǎo)出服務(wù)資源
POST/Api/exportServices/Sendmail
POST/Api/InviteParseServices//提交給解析服務(wù)資源

...

當(dāng)然也有一些夾雜著動(dòng)詞，習(xí)以為常的 Api 設(shè)計(jì)，如果習(xí)慣了，不想改變，仍然可以使用著動(dòng)詞(后續(xù)提到該部分違反約束)，但若想改變，就得換個(gè)思路去考慮設(shè)計(jì)了

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

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

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

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

先是以下簡(jiǎn)單的查詢

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
//分頁(yè)
GET/Api/Orders?Page=1&Limit=10
//也可以拆分成如下兩個(gè)此處資源為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

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

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

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

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

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

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

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

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

...

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

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

Github中也還是有動(dòng)詞描述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

如果按照這幾個(gè)約束條件來看的話，僅當(dāng)滿足三個(gè)約束條件的才能認(rèn)為是 RESTful Api，而滿足一個(gè)或是兩個(gè)約束條件的為 Http Api，那么我們或許是一直在追隨 RESTful Api 的路上了。

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

狀態(tài)碼

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

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

}
}

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

版本號(hào)

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

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

GET/Api/v2/Orders/{id}

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

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

1. 在 http 的 header 中增加自定標(biāo)頭設(shè)置版本號(hào)。

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

成熟度模型

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

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

誠(chéng)然，對(duì)于這個(gè)成熟度模型，我一般都只會(huì)去達(dá)到前三個(gè)級(jí)別，雖然 Roy Fielding明確表示 ，Level 3 才是真正的 RESTful Api，對(duì)于 Level 3 級(jí)別，其實(shí)并沒有理解到其具體奧妙。因?yàn)槲覀兠鎸?duì)的是 UI，用 UI 去鏈接操作，那么對(duì)于 Level 3 返回的超媒體而言，又如何表現(xiàn)呢？