概述
這篇文章分享 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
}
}
}
安全規范
敏感數據脫敏處理
用戶手機號、用戶郵箱、身份證號、支付賬號、郵寄地址等要進行脫敏，部分數據加 * 號處理。
其他規范
- 屬性名命名時，建議使用駝峰命名，首字母小寫。
- 屬性值為空時，嚴格按類型返回默認值。
- 金額類型/時間日期類型的屬性值，如果僅用來顯示，建議后端返回可以顯示的字符串。
- 業務邏輯的狀態碼和對應的文案，建議后端兩者都返回。
- 調用方不需要的屬性，不要返回。
簽名設計
簽名驗證沒有確定的規范，自己制定就行，可以選擇使用 對稱加密、非對稱加密、單向散列加密 等，分享下原來寫的簽名驗證，供參考。
日志平台設計
日志平台有利於故障定位和日志統計分析。
日志平台的搭建可以使用的是 ELK 組件，使用 Logstash 進行收集日志文件，使用 Elasticsearch 引擎進行搜索分析，最終在 Kibana 平台展示出來。
冪等性設計
我們無法保證接口的每一次調用都是有返回結果的，要考慮到出現網絡異常的情況。
舉個例子，訂單創建時，我們需要去減庫存，這時接口發生了超時，調用方進行了重試，這時是否會多扣一次庫存？
解決這類問題有 2 種方案：
一、服務方提供相應的查詢接口，調用方在請求超時后進行查詢，如果查到了，表示請求處理成功了，沒查到就走失敗流程。
二、調用方只管重試，服務方保證一次和多次的請求結果是一樣的。
對於第二種方案，就需要服務方的接口支持冪等性。
大致設計思路是這樣的：
- 調用接口前，先獲取一個全局唯一的令牌（Token）
- 調用接口時，將 Token 放到 Header 頭中
- 解析 Header 頭，驗證是否為有效 Token，無效直接返回失敗
- 完成業務邏輯后，將業務結果與 Token 進行關聯存儲，設置失效時間
- 重試時不要重新獲取 Token，用要上次的 Token
小結
限流設計、熔斷設計、降級設計，這些就不多說了，因為大部分都用不到，當用上了基本上也都在網關中加這些功能。
暫時就想到這么多，規范這東西不是一成不變的，發現有不妥的及時調整吧。
你們接口的輸入輸出 Key，命名是用駝峰還是下划線？歡迎留言。