1. 版本號

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

　　為了解決這個版本不兼容問題，在設計 RESTful API 的一種實用的做法是使用版本號。一般情況下，我們會在 url 中保留版本號，并同時兼容多個版本。

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

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

　　現在，我們可以不改變版本 v1 的查詢用戶列表的 API 接口的情況下，新增版本 v2 的查詢用戶列表的 API 接口以滿足新的業務需求，此時，客戶端的產品的新功能將請求新的服務端的 API 接口地址。雖然服務端會同時兼容多個版本，但是同時維護太多版本對于服務端而言是個不小的負擔，因為服務端要維護多套代碼。這種情況下，常見的做法不是維護所有的兼容版本，而是只維護最新的幾個兼容版本，例如維護最新的三個兼容版本。在一段時間后，當絕大多數用戶升級到較新的版本后，廢棄一些使用量較少的服務端的老版本API 接口版本，并要求使用產品的非常舊的版本的用戶強制升級。

　　注意的是，“不改變版本 v1 的查詢用戶列表的 API 接口”主要指的是對于客戶端的調用者而言它看起來是沒有改變。而實際上，如果業務變化太大，服務端的開發人員需要對舊版本的 API 接口使用適配器模式將請求適配到新的API 接口上。

　　2. 資源路徑

　　RESTful API 的設計以資源為核心，每一個 URI 代表一種資源。因此，URI 不能包含動詞，只能是名詞。注意的是，形容詞也是可以使用的，但是盡量少用。一般來說，不論資源是單個還是多個，API 的名詞要以復數進行命名。此外，命名名詞的時候，要使用小寫、數字及下劃線來區分多個單詞。這樣的設計是為了與 json 對象及屬性的命名方案保持一致。例如，一個查詢系統標簽的接口可以進行如下設計。

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

　　同時，資源的路徑應該從根到子依次如下:

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

　　我們來看一個“添加用戶的角色”的設計，其中“用戶”是主資源，“角色”是子資源。

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

　　有的時候，當一個資源變化難以使用標準的 RESTful API 來命名，可以考慮使用一些特殊的 actions 命名。

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

　　舉個例子，“密碼修改”這個接口的命名很難完全使用名詞來構建路徑，此時可以引入 action 命名。

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

　　3. 請求方式

　　可以通過 GET、 POST、 PUT、 PATCH、 DELETE 等方式對服務端的資源進行操作。其中：

　　●GET：用于查詢資源

　　●POST：用于創建資源

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

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

　　●DELETE：用于刪除服務端的資源。

　　這里，使用“用戶”的案例進行回顧通過 GET、 POST、 PUT、 PATCH、 DELETE 等方式對服務端的資源進行操作。

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

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

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

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

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

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

　　4. 查詢參數

　　RESTful API 接口應該提供參數，過濾返回結果。其中，offset 指定返回記錄的開始位置。一般情況下，它會結合 limit 來做分頁的查詢，這里 limit 指定返回記錄的數量。

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

　　同時，orderby 可以用來排序，但僅支持單個字符的排序，如果存在多個字段排序，需要業務中擴展其他參數進行支持。

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

　　為了更好地選擇是否支持查詢總數，我們可以使用 count 字段，count 表示返回數據是否包含總條數，它的默認值為 false。

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

　　上面介紹的 offset、 limit、 orderby 是一些公共參數。此外，業務場景中還存在許多個性化的參數。我們來看一個例子。

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

　　注意的是，不要過度設計，只返回用戶需要的查詢參數。此外，需要考慮是否對查詢參數創建數據庫索引以提高查詢性能。

　　5. 狀態碼

　　使用適合的狀態碼很重要，而不應該全部都返回狀態碼 200，或者隨便亂使用。這里，列舉在實際開發過程中常用的一些狀態碼，以供參考。

　　6. 異常響應

　　當 RESTful API 接口出現非 2xx 的 HTTP 錯誤碼響應時，采用全局的異常結構響應信息。

　　7. 請求參數

　　在設計服務端的 RESTful API 的時候，我們還需要對請求參數進行限制說明。例如一個支持批量查詢的接口，我們要考慮最大支持查詢的數量。

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

　　參數說明

　　- user_ids: 用戶ID串，最多允許 20 個。

　　此外，在設計新增或修改接口時，我們還需要在文檔中明確告訴調用者哪些參數是必填項，哪些是選填項，以及它們的邊界值的限制。

　　8. 響應參數

　　針對不同操作，服務端向用戶返回的結果應該符合以下規范。

　　1【GET】 /{version}/{resources}/{resource_id} // 返回單個資源對象

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

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

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

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

　　6【DELETE】 /{version}/{resources}/{resource_id} // 狀態碼 200，返回完整的資源對象。

　　7 // 狀態碼 204，返回一個空文檔

　　如果是單條數據，則返回一個對象的 JSON 字符串。

　　如果是列表數據，則返回一個封裝的結構體。

　　一個完整的案例

　　最后，我們使用一個完整的案例將前面介紹的知識整合起來。這里，使用“獲取用戶列表”的案例。

　　更多關于“Java培訓”的問題，歡迎咨詢千鋒教育在線名師。千鋒已有十余年的培訓經驗，課程大綱更科學更專業，有針對零基礎的就業班，有針對想提升技術的好程序員班，高品質課程助力你實現java程序員夢想。