理解RESTful Api設計

REST

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

原則

• 網路上的所有事物都被抽象為資源
• 每個資源都有一個唯一的資源識別符號
• 同一個資源具有多種表現形式(xml，json 等)
• 對資源的各種操作不會改變資源識別符號
• 所有的操作都是無狀態的

資源（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 等）則不再介紹。

• GET: 獲取目標資源。
• HEAD: 獲取（傳輸）目標資源的後設資料資訊。該方法與 GET 相同，但是不傳遞內容體。
• POST: 建立新資源，對於複雜查詢而言，提交查詢表單給查詢服務也是常用 POST 的（當然其他幾個能做的它也能做）。
• PUT: 替換已有資源(整體)。
• PATCH: 修改已有資源(區域性)。
• DELETE: 刪除資源。

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

https://docs.github.com/en/rest/codespaces/codespaces

https://docs.github.com/en/rest/checks/runs

https://docs.github.com/en/rest/checks/suites

如果按照這幾個約束條件來看的話，僅當滿足三個約束條件的才能認為是 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}

3. 作為查詢字串引數來指定資源的版本

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

4. 在 http 的 header 中增加自定檔頭設定版本號。

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

成熟度模型

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

• Level 0: 定義一個 URI，所有操作是對此 URI 發出的 POST 請求。
• Level 1: 為各個資源單獨建立 URI。
• Level 2: 使用 HTTP 方法來定義對資源執行的操作。
• Level 3: 使用超媒體（HATEOAS: Hypermedia As The Engine Of Application State，參見 HATEOAS - Wikipedia ）。
  誠然，對於這個成熟度模型，我一般都只會去達到前三個級別，雖然 Roy Fielding明確表示 ，Level 3 才是真正的 RESTful Api，對於 Level 3 級別，其實並沒有理解到其具體奧妙。因為我們面對的是 UI，用 UI 去連結操作，那麼對於 Level 3 返回的超媒體而言，又如何表現呢？

參考檔案

• https://docs.github.com/en/rest
• https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
• https://www.infoq.cn/minibook/web-based-apps-archit-design
• https://florimond.dev/en/posts/2018/08/restful-api-design-13-best-practices-to-make-your-users-happy/
• https://gitbook.cn/books/5dcaef6522061f2f65418f25/index.html
• https://gitbook.cn/gitchat/activity/5ec21576ef4eff0c0bf709ba

2022-05-24,望技術有成後能回來看見自己的腳步