協議
http https（使用HTTPS協議，以確保交互數據的傳輸安全）
域名
專門的api應用使用獨立域名 https://api.example.com 簡單的可使用api前綴區分 https://www.example.com/api
版本控制
接口版本的控制，可以在程序發布時，不同版本的業務邏輯在一定程度上避免受到影響。
https://api.example.com/v{n}
- 應該將API的版本號放入URL。
- 采用多版本并存，增量發布的方式。
- n代表版本號，分為整型和浮點型
- 整型： 大功能版本， 如v1、v2、v3 ...
- 浮點型： 補充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
URL規則
- 在RESTful架構中，每個網址代表一種資源(resource),所以網址中不能有動詞，只能有名詞。 【所用的名詞往往與數據庫的表格名對應】
- 數據庫中的表一般都是同種記錄的"集合"(collection),所以API中的名詞也應該使用復數。
例子 https://api.example.com/v1/products https://api.example.com/v1/users https://api.example.com/v1/employees
請求方式
- GET（SELECT）： 從服務器取出資源（一項或多項）。
- POST（CREATE）： 在服務器新建一個資源。
- PUT（UPDATE）： 在服務器更新資源（客戶端提供改變后的完整資源）。
- DELETE（DELETE）： 從服務器刪除資源。
例子： GET /v1/products 獲取所有商品 GET /v1/products/ID 獲取某個指定商品的信息 POST /v1/products 新建一個商品 PUT /v1/products/ID 更新某個指定商品的信息 DELETE /v1/products/ID 刪除某個商品 GET /v1/products/ID/purchases 列出某個指定商品的所有投資者 GET /v1/products/ID/purchases/ID 獲取某個指定商品的指定投資者信息
方法命名也要具有一定規范
- 新增 以“add”為前綴。例如add{XXX}
- 刪除 以“delete”為前綴。例如delete{XXX}
- 修改 以“updata”為前綴。例如updata{XXX}
- 獲取 以“get”為前綴。例如get{XXX}
- 獲取 以“get”為前綴、“List”為后綴。例如get{XXX}List
- 保存 以“save”為前綴。例如save{XXX}
- 發送 以“send”為前綴。例如send{XXX}
- 上傳 以“upload”為前綴。例如upload{XXX}
請求參數
- cookie
- request header： 可以存放requestId，token,加密字段等
- 請求body數據 ：針對入參數據，后端必須做數據驗證
- 地址欄參數
響應格式
response：
----------------------------------------
{
status: 200, // 詳見【status】
data: {
code: 1, // 詳見【code】
data: {} || [], // 數據
message: '成功', // 存放響應信息提示,顯示給客戶端用戶【須語義化中文提示】
sysMessage: 'success' // 存放響應信息提示,調試使用,中英文都行
... // 其它參數，如 total【總記錄數】等
},
msg: '成功', // 存放響應信息提示,顯示給客戶端用戶【須語義化中文提示】
sysMsg: 'success' // 存放響應信息提示,調試使用,中英文都行
}
status
200: OK 400: Bad Request 500：Internal Server Error 401：Unauthorized 403：Forbidden 404：Not Found
code
1: 獲取數據成功 | 操作成功 0：獲取數據失敗 | 操作失敗
前后端約定
后端
- 后端需要保證JSON格式的合法性，前端不對格式的合法性做判斷
- 金額格式：所有金額以元為單位，顯示性的后臺返回的是格式化之后的，例如：6,800
- 時間格式: 盡量以一致格式的字符串傳遞 2019-01-01 12:12:12
- 數據接口中定義的key集合是后端返回的子集，即key不缺失（參考數據格式，允許傳遞更多數據）
- key使用駝峰命名，首字母小寫
- 空對象請使用[]
- 空列表請使用[]
- 空字符串請使用''
- 默認數字請使用0
- 盡量避免使用null undefined
- 響應頭Content-Type為"Application/json; charset=UTF-8"
- 接口應該攜帶requestId唯一標示用來追蹤問題
- 敏感度高的數據，客戶端和服務器通過約定的算法，對傳遞的參數值進行簽名匹配，防止參數在請求過程中被抓取篡改。
- 包含用戶隱私的字段數據，需要加*號。如：手機號，身份證，用戶郵箱，支付賬號，郵寄地址等。
"phone":"150*****000", "idCard":"3500**********0555", "email":"40*****00@qq.com"
前端
- 請求頭 application/x-www-form-urlencoded
- 請求字段使用駝峰命名，首字母小寫
- 一個頁面盡量只有一個拉取接口，減少類似這種的連續請求。
- 當請求需要緩存并且有需要及時更新的情況，可以分多個請求。
文檔
這個無需多說，在系統對接的時候，有文檔絕對是個福音。
- 盡量采用自動化接口文檔，可以做到在線測試，同步更新。
- 應包含：接口BASE地址、接口版本、接口模塊分類等。
- 每個接口應包含： 接口地址：不包含接口BASE地址。 請求方式: get、post、put、delete等。 請求參數：數據格式【默認JSON、可選form data】、數據類型、是否必填、中文描述。 響應參數：類型、中文描述。
- 特殊code映射碼表
瘦客戶端
客戶端任何的修改都是需要發版的，發版需要審核流程。
- 客戶端盡量只負責展示邏輯，不處理業務邏輯
- 客戶端不處理金額的計算
- 客戶端少處理請求參數的校驗與約束提示
接口日志
方便故障定位，錯誤重放，日志統計分析等
上傳/下載
上傳/下載，參數增加文件md5，用于完整性校驗
性能優化
合并接口
字段簡寫
無用字段清理
圖片裁剪
局部刷新
預加載
其他
接口安全，防參數篡改
頻率的控制
數據存儲
是否需要依賴于第三方
服務降級，熔斷和限流
拆分
擴展性
適配性
冪等
重復提交
部署
緩存穿透、緩存雪崩和緩存擊穿
是否需要白名單
預加載
重試
異步
服務端推送或者客戶端拉取數據
隔離（例如內網的中臺服務，后端服務）
健康檢查，后臺大盤監控可視化，故障主動通知
