在設計 RESTful API 時，有幾個關鍵要點需要特別注意，因為這些要點如果處理不好，容易導致錯誤或降低 API 的可用性和維護性。

01 領域模型

在設計 RESTful API 的路徑結構時，可以參考領域模型。在領域驅動設計思想中，領域模型構成了軟件的邏輯結構。

這樣設計有幾個好處：

• 領域模型往往都是名詞，和 API Path 保持一致。
• 領域模型往往為樹形結構，可以很好地轉換為 API Path。
• 團隊成員能保持風格統一的 API 設計。

圖片

02 選擇合適的 HTTP Methods

HTTP 協議提供了非常多種 Methods，但對于應用系統而言，使用過多的 HTTP Methods 會給開發者帶來困擾。

因此，定義基本的幾個 HTTP Methods 可以簡化 API 設計，這取決于團隊風格。

例如，PATCH 在很多時候會給團隊造成困擾，開發者往往不能清晰地辨別在何種場景下使用 PATCH 還是 PUT，因此根據團隊約定，可以統一使用 PUT。

03 冪等

提前進行冪等性設計可以提高 API 的健壯性。

• GET 類型的 API 具有天然的冪等性，所以避免在 GET 類型的 API 中實現數據的變更操作。
• PUT、DELETE 類型的 API 應該特別注意實現上盡量冪等，這樣在 API 調用出錯重試時不會帶來意外的結果。
• POST 為新增操作，理論上來說不應該實現為冪等，但在必要時可以通過輸入參數設計為冪等。

04 選擇合適的HTTP 狀態碼

和 HTTP Methods 類似，HTTP 狀態碼也非常多。根據經驗，開發者在選擇使用哪一個狀態碼時，非常容易犯錯，且難以在團隊內達成統一。

比較好的方法是，定義有限的 HTTP 狀態碼來使用即可，來簡化應用開發的難度。例如，當發生校驗錯誤時，統一返回 400，當發生業務錯誤時，統一返回 419。

05 版本控制

提前為 API 設計版本號可以簡化后期的改造和升級工作。

API 版本信息通常有三種方式：

• 使用 Path 前綴，將版本號放到 API Path 的前面。
• 使用 Query 參數。
• 使用 Header 參數。

比較推薦的方法是使用 Path 前綴，對于提供者和消費者來說都非常容易理解，且不會侵入其它的業務參數。

06 語義化 API 路徑

讓 API Path 保持語義化可以增加 API 的辨識度，讓消費者更容易在文檔中找到合適的 API。

提高語義化的方法有：

• 區分名詞的單復數，避免錯誤單詞拼寫。
• 盡量使用資源名稱代替動作。
• 如果實在無法避免動詞，也盡可能將動詞放到路徑末尾，并使用 POST method。

07 批量處理

提前為批量 API 設定一套規則，讓批量 API 更加語義化。我們可以進行約定：

• 使用 batch/bulk 作為關鍵字，放置到路徑末尾。
• 當需要批量查詢數據時，通過 Query 參數代替 Path 參數。

08 查詢語言設計

提前設計一套具有拓展性的查詢規則，可以讓 API 更加靈活。

• 分頁：預留分頁參數關鍵字。
• 排序：預留排序參數關鍵字，以及排序的方向。例如通過 sort=name:asc,age:desc 表達根據名稱正序，年齡倒序排序。
• 過濾：設置靈活的過濾條件語法，可以定義一些指令來實現更加靈活的過濾方式。例如，

GET /v1/users?age=gt:20,lt:50&name=match:lisa&gender=eq:male

其中，gt 代表大于，lt 代表小于，match 代表模糊搜索，eq 代表完全匹配。