接口規(guī)范用來約束接口的一致性呵燕。一堆不統(tǒng)一的接口，不利于前后端代碼復用翠语，增加前后端接口聯(lián)調成本叽躯，降低開發(fā)效率。
下面是我們團隊的接口規(guī)范肌括。
協(xié)議
為確保數據交互安全点骑，正式地址用HTTPS協(xié)議。
接口url
- 路徑以
api開始。如/api/student/list - 路徑中的英文字母使用小寫字母黑滴。
- 路徑中的單詞分隔用
-憨募。
請求方法
- 不改變數據的接口用 GET。如: 獲取列表接口跷跪，詳情接口馋嗜。
- 改變數據的接口用 POST。如: 新增接口吵瞻，編輯接口葛菇，刪除接口。
說明: 如果嚴格的按照HTTP方法的語義橡羞，新增接口應該用 PUT眯停，刪除接口應該用 DELETE。我們團隊認為新增卿泽，刪除接口均用 POST莺债，易于記憶。這個細節(jié)签夭，對整體的代碼質量也沒有影響齐邦。
請求參數
- POST 的數據都會放在body里。用
x-www-form-urlencoded格式第租。 - token 放請求頭中的 Authorization 字段措拇。Authorization值的格式:
Bearer token值。 - 接口版本 放請求頭中的 Version 字段慎宾。
響應
返回json類型數據丐吓。如
{
"errorCode": 0,
"errorMsg": "",
"data": {}// 或 []
}
說明:
- errorCode: 錯誤碼。errorCode 為
- 0: 沒有報錯趟据。
- 401: 未登錄或登錄過期券犁，需重新登錄。
- errorMsg: 錯誤信息汹碱。沒有報錯粘衬，不返回 errorMsg 字段。
- data: 主體內容咳促。對于列表接口色难，data 是數組類型的。
- 響應字段用駝峰命名法等缀。
列表接口
url
以 list 結尾枷莉。 如: /api/goods/list。
請求方法
GET尺迂。
請求參數
篩選條件
篩選條件: where笤妙。where 的值是 encodeURIComponent(JSON.stringify({列名1: 值, 列名2: 值, ...}))冒掌。如: 篩選年齡(age)為20的學生，url 是 /api/student/list?where=%7B%22age%22%3A20%7D蹲盘。
列的篩選規(guī)則：
- 精確搜索:
列名股毫。 - 模糊搜索:
列名__like。 - 大于:
列名__gt召衔。 用于數字和日期的列铃诬。 - 大于等于:
列名__gte。 - 小于:
列名__lt苍凛。 - 小于等于:
列名__lte趣席。
分頁信息
- 頁數: pageAt。
- 每頁的數量: pageLimit醇蝴。
如: /api/student/list?pageAt=2&pageLimit=10宣肚。
如果不傳分頁參數，默認返回第一頁的10條數據悠栓。
排序信息
排序信息: order霉涨。order的值為: encodeURIComponent(JSON.stringify([{列名1: "asc(升序) 或 desc(降序)"}]))。
支持多個排序值惭适。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": [],
"pager": {
"pageAt": 1,// 當前頁
"total": 21// 總條數
}
}
詳情接口
url
以 detail/:id 結尾笙瑟。 如: /api/goods/detail/3。
請求方法
GET癞志。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": {
"id": 1,
// 更多字段
}
}
新增接口
url
以 add 結尾往枷。 如: /api/goods/add。
請求方法
POST今阳。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": {
"id": 1,
}
}
data中的id為新增成功的數據的id师溅。
編輯接口
url
以 edit/:id 結尾茅信。如: /api/goods/edit/3盾舌。
請求方法
POST。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": {}
}
刪除接口
url
以 del/:id 結尾蘸鲸。如: /api/goods/del/3妖谴。
請求方法
POST。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": {}
}
審核接口
url
以 audit/:id 結尾酌摇。如: /api/goods/audit/3膝舅。
請求方法
POST。
響應
{
"errorCode": 0,
"errorMsg": "",
"data": {}
}
接口文檔要求
- 用 Postman 寫窑多。
- 每個字段必須有備注仍稀。
- 變化的值配置在環(huán)境中。如接口的域名埂息。環(huán)境指一系列包含接口上下文變量的集合技潘。
