服務端指南 | 良好的 API 設計指南

樑桂釗發表於2017-08-03
服務端API

設計一套良好的 API 介面。
原文地址：服務端指南 | 良好的 API 設計指南
部落格地址：blog.720ui.com/

版本號

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

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

【GET】  /v1/users/{user_id}  // 版本 v1 的查詢使用者列表的 API 介面
【GET】  /v2/users/{user_id}  // 版本 v2 的查詢使用者列表的 API 介面複製程式碼

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

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

資源路徑

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

【GET】  /v1/tags/{tag_id}複製程式碼

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

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}複製程式碼

我們來看一個“新增使用者的角色”的設計，其中“使用者”是主資源，“角色”是子資源。

【POST】  /v1/users/{user_id}/roles/{role_id} // 新增使用者的角色複製程式碼

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

/{resources}/{resource_id}/actions/{action}複製程式碼

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

【PUT】  /v1/users/{user_id}/password/actions/modify // 密碼修改複製程式碼

請求方式

可以通過 GET、 POST、 PUT、 PATCH、 DELETE 等方式對服務端的資源進行操作。其中，GET 用於查詢資源，POST 用於建立資源，PUT 用於更新服務端的資源的全部資訊，PATCH 用於更新服務端的資源的部分資訊，DELETE 用於刪除服務端的資源。

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

【GET】          /users                # 查詢使用者資訊列表
【GET】          /users/1001           # 檢視某個使用者資訊
【POST】         /users                # 新建使用者資訊
【PUT】          /users/1001           # 更新使用者資訊(全部欄位)
【PATCH】        /users/1001           # 更新使用者資訊(部分欄位)
【DELETE】       /users/1001           # 刪除使用者資訊複製程式碼

查詢引數

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,…}複製程式碼

注意的是，不要過度設計，只返回使用者需要的查詢引數。此外，需要考慮是否對查詢引數建立資料庫索引以提高查詢效能。

狀態碼

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

狀態碼 描述
200 請求成功
201 建立成功
400 錯誤的請求
401 未驗證
403 被拒絕
404 無法找到
409 資源衝突
500 伺服器內部錯誤

異常響應

當 RESTful API 介面出現非 2xx 的 HTTP 錯誤碼響應時，採用全域性的異常結構響應資訊。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "code": "INVALID_ARGUMENT",
    "message": "{error message}",
    "cause": "{cause message}",
    "request_id": "01234567-89ab-cdef-0123-456789abcdef",
    "host_id": "{server identity}",
    "server_time": "2014-01-01T12:00:00Z"
}複製程式碼

請求引數

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

【GET】     /v1/users/batch?user_ids=1001,1002      // 批量查詢使用者資訊
引數說明
- user_ids: 使用者ID串，最多允許 20 個。複製程式碼

此外，在設計新增或修改介面時，我們還需要在文件中明確告訴呼叫者哪些引數是必填項，哪些是選填項，以及它們的邊界值的限制。

【POST】     /v1/users                             // 建立使用者資訊
請求內容
{
    "username": "lgz",                 // 必填, 使用者名稱稱, max 10
    "realname": "樑桂釗",               // 必填, 使用者名稱稱, max 10
    "password": "123456",              // 必填, 使用者密碼, max 32
    "email": "lianggzone@163.com",     // 選填, 電子郵箱, max 32
    "weixin": "LiangGzone",            // 選填，微信賬號, max 32
    "sex": 1                           // 必填, 使用者性別[1-男 2-女 99-未知]
}複製程式碼

響應引數

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

【GET】     /{version}/{resources}/{resource_id}      // 返回單個資源物件
【GET】     /{version}/{resources}                    // 返回資源物件的列表
【POST】    /{version}/{resources}                    // 返回新生成的資源物件
【PUT】     /{version}/{resources}/{resource_id}      // 返回完整的資源物件
【PATCH】   /{version}/{resources}/{resource_id}      // 返回完整的資源物件
【DELETE】  /{version}/{resources}/{resource_id}      // 狀態碼 200，返回完整的資源物件。
                                                      // 狀態碼 204，返回一個空文件複製程式碼

如果是單條資料，則返回一個物件的 JSON 字串。

HTTP/1.1 200 OK
{
    "id" : "01234567-89ab-cdef-0123-456789abcdef",
    "name" : "example",
    "created_time": 1496676420000,
    "updated_time": 1496676420000,
    ...
}複製程式碼

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

HTTP/1.1 200 OK
{
    "count":100,
    "items":[
        {
            "id" : "01234567-89ab-cdef-0123-456789abcdef",
            "name" : "example",
            "created_time": 1496676420000,
            "updated_time": 1496676420000,
            ...
        },
        ...
    ]
}複製程式碼

一個完整的案例

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

【GET】     /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 獲取使用者列表
功能說明：獲取使用者列表
請求方式：GET
引數說明
- keyword: 模糊查詢的關鍵字。[選填]
- enable: 啟用狀態[1-啟用 2-禁用]。[選填]
- offset: 獲取位置偏移，從 0 開始。[選填]
- limit: 每次獲取返回的條數，預設為 20 條，最大不超過 100。 [選填]
響應內容
HTTP/1.1 200 OK
{
    "count":100,
    "items":[
        {
            "id" : "01234567-89ab-cdef-0123-456789abcdef",
            "name" : "example",
            "created_time": 1496676420000,
            "updated_time": 1496676420000,
            ...
        },
        ...
    ]
}
失敗響應
HTTP/1.1 403 UC/AUTH_DENIED
Content-Type: application/json
{
    "code": "INVALID_ARGUMENT",
    "message": "{error message}",
    "cause": "{cause message}",
    "request_id": "01234567-89ab-cdef-0123-456789abcdef",
    "host_id": "{server identity}",
    "server_time": "2014-01-01T12:00:00Z"
}
錯誤程式碼
- 403 UC/AUTH_DENIED    授權受限複製程式碼

（完）

更多精彩文章，盡在「服務端思維」微信公眾號！

相關文章