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.三、android 9
device	設備型號	iPhone XR、小米9
udid	設備惟一標示
apiVersion	API 版本號	v1.一、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 種方案：

1、服務方提供相應的查詢接口，調用方在請求超時後進行查詢，若是查到了，表示請求處理成功了，沒查到就走失敗流程。

2、調用方只管重試，服務方保證一次和屢次的請求結果是同樣的。

對於第二種方案，就須要服務方的接口支持冪等性。

大體設計思路是這樣的：

1. 調用接口前，先獲取一個全局惟一的令牌（Token）
2. 調用接口時，將 Token 放到 Header 頭中
3. 解析 Header 頭，驗證是否爲有效 Token，無效直接返回失敗
4. 完成業務邏輯後，將業務結果與 Token 進行關聯存儲，設置失效時間
5. 重試時不要從新獲取 Token，用要上次的 Token

小結

限流設計、熔斷設計、降級設計，這些就很少說了，由於大部分都用不到，當用上了基本上也都在網關中加這些功能。

暫時就想到這麼多，規範這東西不是一成不變的，發現有不妥的及時調整吧。

大家接口的輸入輸出 Key，命名是用駝峯仍是下劃線？歡迎留言。

推薦閱讀

• 一線技術管理者究竟在管什麼事？
• 一我的被提拔，不只僅是能力，而是信任