在設(shè)計(jì) RESTful API 時(shí)，有幾個(gè)關(guān)鍵要點(diǎn)需要特別注意，因?yàn)檫@些要點(diǎn)如果處理不好，容易導(dǎo)致錯(cuò)誤或降低 API 的可用性和維護(hù)性。

01 領(lǐng)域模型

在設(shè)計(jì) RESTful API 的路徑結(jié)構(gòu)時(shí)，可以參考領(lǐng)域模型。在領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)思想中，領(lǐng)域模型構(gòu)成了軟件的邏輯結(jié)構(gòu)。

這樣設(shè)計(jì)有幾個(gè)好處：

• 領(lǐng)域模型往往都是名詞，和 API Path 保持一致。
• 領(lǐng)域模型往往為樹形結(jié)構(gòu)，可以很好地轉(zhuǎn)換為 API Path。
• 團(tuán)隊(duì)成員能保持風(fēng)格統(tǒng)一的 API 設(shè)計(jì)。

圖片

02 選擇合適的 HTTP Methods

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

因此，定義基本的幾個(gè) HTTP Methods 可以簡(jiǎn)化 API 設(shè)計(jì)，這取決于團(tuán)隊(duì)風(fēng)格。

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

03 冪等

提前進(jìn)行冪等性設(shè)計(jì)可以提高 API 的健壯性。

• GET 類型的 API 具有天然的冪等性，所以避免在 GET 類型的 API 中實(shí)現(xiàn)數(shù)據(jù)的變更操作。
• PUT、DELETE 類型的 API 應(yīng)該特別注意實(shí)現(xiàn)上盡量冪等，這樣在 API 調(diào)用出錯(cuò)重試時(shí)不會(huì)帶來意外的結(jié)果。
• POST 為新增操作，理論上來說不應(yīng)該實(shí)現(xiàn)為冪等，但在必要時(shí)可以通過輸入?yún)?shù)設(shè)計(jì)為冪等。

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

和 HTTP Methods 類似，HTTP 狀態(tài)碼也非常多。根據(jù)經(jīng)驗(yàn)，開發(fā)者在選擇使用哪一個(gè)狀態(tài)碼時(shí)，非常容易犯錯(cuò)，且難以在團(tuán)隊(duì)內(nèi)達(dá)成統(tǒng)一。

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

05 版本控制

提前為 API 設(shè)計(jì)版本號(hào)可以簡(jiǎn)化后期的改造和升級(jí)工作。

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

• 使用 Path 前綴，將版本號(hào)放到 API Path 的前面。
• 使用 Query 參數(shù)。
• 使用 Header 參數(shù)。

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

06 語義化 API 路徑

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

提高語義化的方法有：

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

07 批量處理

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

• 使用 batch/bulk 作為關(guān)鍵字，放置到路徑末尾。
• 當(dāng)需要批量查詢數(shù)據(jù)時(shí)，通過 Query 參數(shù)代替 Path 參數(shù)。

08 查詢語言設(shè)計(jì)

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

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

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

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