API 介面設計規範
概述
這篇文章分享 API 介面設計規範，目的是提供給研發人員做參考。
規範是死的，人是活的，希望自己定的規範，不要被打臉。
路由命名規範
| 動作 | 字首 | 備註 |
|---|---|---|
| 獲取 | get | get{XXX} |
| 獲取 | get | get{XXX}List |
| 新增 | add | add{XXX} |
| 修改 | update | update{XXX} |
| 儲存 | save | save{XXX} |
| 刪除 | delete | delete{XXX} |
| 上傳 | upload | upload{XXX} |
| 傳送 | send | send{XXX} |
請求方式
| 請求方式 | 描述 |
|---|---|
| GET | 獲取資料 |
| POST | 新增資料 |
| PUT | 更新資料 |
| DELETE | 刪除資料 |
請求引數
Query
url?後面的引數，存放請求介面的引數資料。
Header
請求頭，存放公共引數、requestId、token、加密欄位等。
Body
Body 體，存放請求介面的引數資料。
公共引數
APP 端請求
| 引數 | 說明 | 備註 |
|---|---|---|
| network | 網路 | WIFI、4G |
| operator | 運營商 | 中國聯通/移動 |
| platform | 平臺 | iOS、Android |
| system | 系統 | ios 13.3、android 9 |
| device | 裝置型號 | iPhone XR、小米9 |
| udid | 裝置唯一標示 | |
| apiVersion | API 版本號 | v1.1、v1.2 |
WEB 端請求
| 引數 | 說明 | 備註 |
|---|---|---|
| appKey | 授權Key | 字串 |
呼叫方需向服務方申請 appKey（請求時使用） 和 secretKey（加密時使用）。
安全規範
敏感引數加密處理
登入密碼、支付密碼，需加密後傳輸，建議使用非對稱加密。
其他規範
- 引數命名規範 建議使用駝峰命名，首字母小寫。
- requestId 建議攜帶唯一標示追蹤問題。
返回引數
| 引數 | 型別 | 說明 | 備註 |
|---|---|---|---|
| code | Number | 結果碼 | 成功=1 失敗=-1 未登入=401 無許可權=403 |
| showMsg | String | 顯示資訊 | 系統繁忙，稍後重試 |
| errorMsg | String | 錯誤資訊 | 便於研發定位問題 |
| data | Object | 資料 | JSON 格式 |
若有分頁資料返回的，格式如下：
{
"code": 1,
"showMsg": "success",
"errorMsg": "",
"data": {
"list": [],
"pagination": {
"total": 100,
"currentPage": 1,
"prePageCount": 10
}
}
}安全規範
敏感資料脫敏處理
使用者手機號、使用者郵箱、身份證號、支付賬號、郵寄地址等要進行脫敏，部分資料加 * 號處理。
其他規範
- 屬性名命名時，建議使用駝峰命名，首字母小寫。
- 屬性值為空時，嚴格按型別返回預設值。
- 金額型別/時間日期型別的屬性值，如果僅用來顯示，建議後端返回可以顯示的字串。
- 業務邏輯的狀態碼和對應的文案，建議後端兩者都返回。
- 呼叫方不需要的屬性，不要返回。
簽名設計
簽名驗證沒有確定的規範，自己制定就行，可以選擇使用 對稱加密、非對稱加密、單向雜湊加密 等，分享下原來寫的簽名驗證，供參考。
- Go 簽名驗證
- PHP 簽名驗證
日誌平臺設計
日誌平臺有利於故障定位和日誌統計分析。
日誌平臺的搭建可以使用的是 ELK 元件，使用 Logstash 進行收集日誌檔案，使用 Elasticsearch 引擎進行搜尋分析，最終在 Kibana 平臺展示出來。
冪等性設計
我們無法保證介面的每一次呼叫都是有返回結果的，要考慮到出現網路異常的情況。
舉個例子，訂單建立時，我們需要去減庫存，這時介面發生了超時，呼叫方進行了重試，這時是否會多扣一次庫存？
解決這類問題有 2 種方案：
一、服務方提供相應的查詢介面，呼叫方在請求超時後進行查詢，如果查到了，表示請求處理成功了，沒查到就走失敗流程。
二、呼叫方只管重試，服務方保證一次和多次的請求結果是一樣的。
對於第二種方案，就需要服務方的介面支援冪等性。
大致設計思路是這樣的：
- 呼叫介面前，先獲取一個全域性唯一的令牌（Token）
- 呼叫介面時，將 Token 放到 Header 頭中
- 解析 Header 頭，驗證是否為有效 Token，無效直接返回失敗
- 完成業務邏輯後，將業務結果與 Token 進行關聯儲存，設定失效時間
- 重試時不要重新獲取 Token，用要上次的 Token
小結
限流設計、熔斷設計、降級設計，這些就不多說了，因為大部分都用不到，當用上了基本上也都在閘道器中加這些功能。
暫時就想到這麼多，規範這東西不是一成不變的，發現有不妥的及時調整吧。
推薦閱讀
- 一線技術管理者究竟在管什麼事？
- 一個人被提拔，不僅僅是能力，而是信任