Restful API 設計的 8 個訣竅
在設計 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 代表完全匹配。
本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源:https://mp.weixin.qq.com/s/maHZxoYlt960n7RzonLdmQ