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

01 領域模型

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

這樣設計有幾個好處：

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

圖片

02 選擇合適的 HTTP Methods

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

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

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

03 冪等

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

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

04 選擇合適的HTTP 狀態(tài)碼

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

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

05 版本控制

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

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

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

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

06 語義化 API 路徑

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

提高語義化的方法有：

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

07 批量處理

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

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

08 查詢語言設計

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

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

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

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