1. 版本號(hào)

　　在 RESTful API 中，API 接口應(yīng)該盡量兼容之前的版本。但是，在實(shí)際業(yè)務(wù)開(kāi)發(fā)場(chǎng)景中，可能隨著業(yè)務(wù)需求的不斷迭代，現(xiàn)有的 API 接口無(wú)法支持舊版本的適配，此時(shí)如果強(qiáng)制升級(jí)服務(wù)端的 API 接口將導(dǎo)致客戶端舊有功能出現(xiàn)故障。實(shí)際上，Web 端是部署在服務(wù)器，因此它可以很容易為了適配服務(wù)端的新的 API 接口進(jìn)行版本升級(jí)，然而像 Android 端、IOS 端、PC 端等其他客戶端是運(yùn)行在用戶的機(jī)器上，因此當(dāng)前產(chǎn)品很難做到適配新的服務(wù)端的 API 接口，從而出現(xiàn)功能故障，這種情況下，用戶必須升級(jí)產(chǎn)品到最新的版本才能正常使用。

　　為了解決這個(gè)版本不兼容問(wèn)題，在設(shè)計(jì) RESTful API 的一種實(shí)用的做法是使用版本號(hào)。一般情況下，我們會(huì)在 url 中保留版本號(hào)，并同時(shí)兼容多個(gè)版本。

　　1【GET】 /v1/users/{user_id} // 版本 v1 的查詢用戶列表的 API 接口

　　2【GET】 /v2/users/{user_id} // 版本 v2 的查詢用戶列表的 API 接口

　　現(xiàn)在，我們可以不改變版本 v1 的查詢用戶列表的 API 接口的情況下，新增版本 v2 的查詢用戶列表的 API 接口以滿足新的業(yè)務(wù)需求，此時(shí)，客戶端的產(chǎn)品的新功能將請(qǐng)求新的服務(wù)端的 API 接口地址。雖然服務(wù)端會(huì)同時(shí)兼容多個(gè)版本，但是同時(shí)維護(hù)太多版本對(duì)于服務(wù)端而言是個(gè)不小的負(fù)擔(dān)，因?yàn)榉?wù)端要維護(hù)多套代碼。這種情況下，常見(jiàn)的做法不是維護(hù)所有的兼容版本，而是只維護(hù)最新的幾個(gè)兼容版本，例如維護(hù)最新的三個(gè)兼容版本。在一段時(shí)間后，當(dāng)絕大多數(shù)用戶升級(jí)到較新的版本后，廢棄一些使用量較少的服務(wù)端的老版本API 接口版本，并要求使用產(chǎn)品的非常舊的版本的用戶強(qiáng)制升級(jí)。

　　注意的是，“不改變版本 v1 的查詢用戶列表的 API 接口”主要指的是對(duì)于客戶端的調(diào)用者而言它看起來(lái)是沒(méi)有改變。而實(shí)際上，如果業(yè)務(wù)變化太大，服務(wù)端的開(kāi)發(fā)人員需要對(duì)舊版本的 API 接口使用適配器模式將請(qǐng)求適配到新的API 接口上。

　　2. 資源路徑

　　RESTful API 的設(shè)計(jì)以資源為核心，每一個(gè) URI 代表一種資源。因此，URI 不能包含動(dòng)詞，只能是名詞。注意的是，形容詞也是可以使用的，但是盡量少用。一般來(lái)說(shuō)，不論資源是單個(gè)還是多個(gè)，API 的名詞要以復(fù)數(shù)進(jìn)行命名。此外，命名名詞的時(shí)候，要使用小寫、數(shù)字及下劃線來(lái)區(qū)分多個(gè)單詞。這樣的設(shè)計(jì)是為了與 json 對(duì)象及屬性的命名方案保持一致。例如，一個(gè)查詢系統(tǒng)標(biāo)簽的接口可以進(jìn)行如下設(shè)計(jì)。

　　1【GET】 /v1/tags/{tag_id}

　　同時(shí)，資源的路徑應(yīng)該從根到子依次如下:

　　1/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

　　我們來(lái)看一個(gè)“添加用戶的角色”的設(shè)計(jì)，其中“用戶”是主資源，“角色”是子資源。

　　1【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用戶的角色

　　有的時(shí)候，當(dāng)一個(gè)資源變化難以使用標(biāo)準(zhǔn)的 RESTful API 來(lái)命名，可以考慮使用一些特殊的 actions 命名。

　　1/{resources}/{resource_id}/actions/{action}

　　舉個(gè)例子，“密碼修改”這個(gè)接口的命名很難完全使用名詞來(lái)構(gòu)建路徑，此時(shí)可以引入 action 命名。

　　1【PUT】 /v1/users/{user_id}/password/actions/modify // 密碼修改

　　3. 請(qǐng)求方式

　　可以通過(guò) GET、 POST、 PUT、 PATCH、 DELETE 等方式對(duì)服務(wù)端的資源進(jìn)行操作。其中：

　　●GET：用于查詢資源

　　●POST：用于創(chuàng)建資源

　　●PUT：用于更新服務(wù)端的資源的全部信息

　　●PATCH：用于更新服務(wù)端的資源的部分信息

　　●DELETE：用于刪除服務(wù)端的資源。

　　這里，使用“用戶”的案例進(jìn)行回顧通過(guò) GET、 POST、 PUT、 PATCH、 DELETE 等方式對(duì)服務(wù)端的資源進(jìn)行操作。

　　1【GET】 /users # 查詢用戶信息列表

　　2【GET】 /users/1001 # 查看某個(gè)用戶信息

　　3【POST】 /users # 新建用戶信息

　　4【PUT】 /users/1001 # 更新用戶信息(全部字段)

　　5【PATCH】 /users/1001 # 更新用戶信息(部分字段)

　　6【DELETE】 /users/1001 # 刪除用戶信息

　　4. 查詢參數(shù)

　　RESTful API 接口應(yīng)該提供參數(shù)，過(guò)濾返回結(jié)果。其中，offset 指定返回記錄的開(kāi)始位置。一般情況下，它會(huì)結(jié)合 limit 來(lái)做分頁(yè)的查詢，這里 limit 指定返回記錄的數(shù)量。

　　【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20

　　同時(shí)，orderby 可以用來(lái)排序，但僅支持單個(gè)字符的排序，如果存在多個(gè)字段排序，需要業(yè)務(wù)中擴(kuò)展其他參數(shù)進(jìn)行支持。

　　【GET】 /{version}/{resources}/{resource_id}?orderby={field} [asc|desc]

　　為了更好地選擇是否支持查詢總數(shù)，我們可以使用 count 字段，count 表示返回?cái)?shù)據(jù)是否包含總條數(shù)，它的默認(rèn)值為 false。

　　【GET】 /{version}/{resources}/{resource_id}?count=[true|false]

　　上面介紹的 offset、 limit、 orderby 是一些公共參數(shù)。此外，業(yè)務(wù)場(chǎng)景中還存在許多個(gè)性化的參數(shù)。我們來(lái)看一個(gè)例子。

　　【GET】 /v1/categorys/{category_id}/apps/{app_id}?enable=[1|0]&os_type={field}&device_ids={field,field,…}

　　注意的是，不要過(guò)度設(shè)計(jì)，只返回用戶需要的查詢參數(shù)。此外，需要考慮是否對(duì)查詢參數(shù)創(chuàng)建數(shù)據(jù)庫(kù)索引以提高查詢性能。

　　5. 狀態(tài)碼

　　使用適合的狀態(tài)碼很重要，而不應(yīng)該全部都返回狀態(tài)碼 200，或者隨便亂使用。這里，列舉在實(shí)際開(kāi)發(fā)過(guò)程中常用的一些狀態(tài)碼，以供參考。

　　6. 異常響應(yīng)

　　當(dāng) RESTful API 接口出現(xiàn)非 2xx 的 HTTP 錯(cuò)誤碼響應(yīng)時(shí)，采用全局的異常結(jié)構(gòu)響應(yīng)信息。

　　7. 請(qǐng)求參數(shù)

　　在設(shè)計(jì)服務(wù)端的 RESTful API 的時(shí)候，我們還需要對(duì)請(qǐng)求參數(shù)進(jìn)行限制說(shuō)明。例如一個(gè)支持批量查詢的接口，我們要考慮最大支持查詢的數(shù)量。

　　【GET】 /v1/users/batch?user_ids=1001,1002 // 批量查詢用戶信息

　　參數(shù)說(shuō)明

　　- user_ids: 用戶ID串，最多允許 20 個(gè)。

　　此外，在設(shè)計(jì)新增或修改接口時(shí)，我們還需要在文檔中明確告訴調(diào)用者哪些參數(shù)是必填項(xiàng)，哪些是選填項(xiàng)，以及它們的邊界值的限制。

　　8. 響應(yīng)參數(shù)

　　針對(duì)不同操作，服務(wù)端向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范。

　　1【GET】 /{version}/{resources}/{resource_id} // 返回單個(gè)資源對(duì)象

　　2【GET】 /{version}/{resources} // 返回資源對(duì)象的列表

　　3【POST】 /{version}/{resources} // 返回新生成的資源對(duì)象

　　4【PUT】 /{version}/{resources}/{resource_id} // 返回完整的資源對(duì)象

　　5【PATCH】 /{version}/{resources}/{resource_id} // 返回完整的資源對(duì)象

　　6【DELETE】 /{version}/{resources}/{resource_id} // 狀態(tài)碼 200，返回完整的資源對(duì)象。

　　7 // 狀態(tài)碼 204，返回一個(gè)空文檔

　　如果是單條數(shù)據(jù)，則返回一個(gè)對(duì)象的 JSON 字符串。

　　如果是列表數(shù)據(jù)，則返回一個(gè)封裝的結(jié)構(gòu)體。

　　一個(gè)完整的案例

　　最后，我們使用一個(gè)完整的案例將前面介紹的知識(shí)整合起來(lái)。這里，使用“獲取用戶列表”的案例。

　　更多關(guān)于“Java培訓(xùn)”的問(wèn)題，歡迎咨詢千鋒教育在線名師。千鋒已有十余年的培訓(xùn)經(jīng)驗(yàn)，課程大綱更科學(xué)更專業(yè)，有針對(duì)零基礎(chǔ)的就業(yè)班，有針對(duì)想提升技術(shù)的好程序員班，高品質(zhì)課程助力你實(shí)現(xiàn)java程序員夢(mèng)想。