基於工程經驗的『RESTful介面設計規範』

文章摘要： 1. 介面引數2. 介面返回值

這篇文章，主要想總結自己在設計RESTful API的一系列經驗于思考。

有些規範可能與標準規範有所出入，但是所有的考量都是基於『減少重複工作，增加可讀性可維護性』而出發的。話說回來，我一直覺得 RESTful API 設計，確實沒有很明顯的公認規範（如果你是指發明者的那篇論文，估計沒多少人詳細閱讀過，而且其作者只是提出了一系列概念而已）。網上的教程，似乎都是千篇一律的（我嚴重懷疑：都是「借鑑or拷貝」阮一峰老師的那幾篇文章），僵硬而且呆板，有點教條化（從來沒有人懷疑它們嗎，反正我按照這些教條設計API，沒有感受到多少樂趣）。

以上，並不是全部否定，好東西要充分吸收，不好的東西，要融合自己的理解，加以改造。

對 RESTful API 的認識

說到這個，似乎又要談及『RESTful 是對資源的抽象』、『結合了HTTP 的特點』云云。不過這些都是一些沒用的套話，沒啥營養價值，而我想從另外的角度談論這個。

既然是 API，一般都符合 API 的一般模式：

ResultType ApiName(ParamType )

1. 介面引數，即形參。可以是 string，int，以及其他任意可以稱之為引數的東西
2. 介面返回值。可以是 string，int，以及其他任意可以稱之為返回值的東西
3. 介面名（簽名)

我們來看看 RESTful 是如何對應上這個模式的：

HttpResponse URL(HttpRequest)

1. HttpRequest：包括請求頭，URL引數，請求body引數
2. HttpResponse: 包括響應頭，響應的body

這樣來看，RESTful API 無非是一種特殊的API 而已，通用的 API 設計法則，同樣適合 RESTful，只不過非變換形式而已。

那麼我們大概有哪些比較通用的標準呢？大概有這些：

介面命名，必須做到清晰。一般來說，做到『動賓短語』即可。
介面數量，越少越好。三個不如兩個，兩個不如一個，一個不如沒有，最好的 API 就是『沒有API』。
有明確的輸入輸出。念念不忘必有迴響，總是有返回值，告訴呼叫端，我到底做了什麼，做得怎麼樣，即：反饋。

下面就來看看這些標準，是如何影響下文的內容的，：）。

URL設計，及其反模式

URL 就是介面簽名，而簽名必須做到清晰，沒有歧義。

有統一的字首 & 版本化

如果後端架構是服務化的，那麼有可能每個服務會對外提供公共的 RESTful API，那麼有個統一的字首格式，會比較好，比如：

/SERVICE_NAME/v1/users
or
/APP_NAME/v2/users

儘量短小

同一份資源，可以有不同的路徑，去理解它。比如：

User -- 1：N --> Server-- 1:N --> Client ... 更加複雜的實體對映關係

1. /users/{user_id}/servers/{server_id}/clients
2. /clients

一般大家傾向於選項 1（但是實體關聯關係特複雜時，會縮短URL），
不過選項2 也是一個不錯的選擇，總而言之，口味問題吧。

數量儘量少

介面數量越少越好，能合併的介面就儘量合併。比如，這樣的情況：

獲取使用者列表資訊：GET /users
獲取單個使用者資訊：GET /users/{id}

坦白說，獲取一個與獲取一批，似乎並沒有什麼語義上的差別，
但是後端的同學就不一樣了，他可能需要寫兩個 View Class。
所以只保留批量的介面，查詢一個時，用 URL 引數傳遞就行了。

這樣的情況：

PUT /users/{id}
PUT /users

直接合併到一個介面裏面做就行了，PUT 一個 user與 PUT 一群 user，有啥本質的不同嗎？

還有這樣極端的情況：

DELETE /users/{id}

刪除一個user與刪除一批user，有啥不同？
如果要一次刪除100 個 user，難道讓前端同學，調 100 次這個介面？
多一次呼叫，就多一次風險（如網路問題），
這個時候就別守著 RESTful 那些個教條了，介面的可用性、效率性，更加重要。

這個時候，不如設計成這樣（至於 DELETE 介面能不能傳Request body，這裏不討論）：
POST /users_deletion
{
    "user_ids": [1, 2, 3, 4, 5]
}

返回值設計

前面有說到，HttpResponse中，我們可以利用：

Response Headers
可以做少量文章，如自定義一個Header

Status Code
按照基本規範來，該404的404，該200的200

Response body
基本都是圍繞這個做文章

Response body 既要能正常返回資訊，出錯了也要告訴出錯原因（錯誤碼），出錯詳情。所以我們大概可以設計成這樣：

{
    是否成功
    boolean "is_success":
    錯誤碼是多少
    number|null "err_code":
    錯誤資訊
    string|null "err_msg": 
    錯誤詳情（可選）
    string|null "err_detail":
    出錯的時哪個服務
    string|null "provider": 
    
    正常返回時的資料
    "response_data": {

    }
}

這樣，前端呼叫 API ，就有章法可循了，不至於盲目。