無規(guī)矩不成方圓，聊一聊 Spring Boot 中 RESTful 接口設(shè)計(jì)規(guī)范
在設(shè)計(jì)接口時(shí)，有很多因素要考慮，如接口的業(yè)務(wù)定位，接口的安全性，接口的可擴(kuò)展性、接口的穩(wěn)定性、接口的跨域性、接口的協(xié)議規(guī)則、接口的路徑規(guī)則、接口單一原則、接口過濾和接口組合等諸多因素，本篇文章將簡要分析這些因素。
一 規(guī)范性建議
1.職責(zé)原則
在設(shè)計(jì)接口時(shí)，必須明確接口的職責(zé)，即接口類型，接口應(yīng)解決什么業(yè)務(wù)問題等。
2.單一性原則
在明確接口職責(zé)的條件下，盡量做到接口單一，即一個(gè)接口只做一件事，而非兩件以上。很多非資深接口設(shè)計(jì)者，在設(shè)計(jì)接口時(shí)，總認(rèn)為接口所做的事越多，越牛叉，這是非常嚴(yán)重的錯(cuò)誤認(rèn)識(shí)。
3.協(xié)議規(guī)范
在設(shè)計(jì)接口時(shí)，應(yīng)明確接口協(xié)議，是采用HTTP協(xié)議,HTTPS協(xié)議還是FTP協(xié)議，要根據(jù)具體情況來定。
FTP協(xié)議(File Transfer Protocol，簡稱FTP)，是一套標(biāo)準(zhǔn)的文件傳輸協(xié)議，用于傳輸文件，如.txt，.csv等，一般文件傳輸，采用FTP協(xié)議。
HTTP協(xié)議，適用一般對(duì)安全性要求比較低或沒要求的業(yè)務(wù)情景。
HTTPS=HTTP+SSL,適用于對(duì)安全性要求較高的業(yè)務(wù)情景。
4.路徑規(guī)則
由于api獲取的是一種資源，所以網(wǎng)址中盡量為名詞，而非動(dòng)詞。
/api/v1.0/pruduct/2019
/api/v1.0/users/2019
5.http請(qǐng)求方式
接口基本訪問協(xié)議：get(獲取)，post(新增)，put(修改)和delete(刪除)。
- get /users：列出所有用戶
- get /users/id：根據(jù)id獲取用戶
- post /user：新增用戶
- put /user/id：根據(jù)用戶id更新用戶
- delete /user/id：根據(jù)用戶id刪除用戶
6.域名
一般地，域名分為主域名和專有域名，主域名適合api長期不變或變化較少的業(yè)務(wù)，專有域名是解決具體的專有業(yè)務(wù)的。
以百度舉例：
(1)主域名:www.baidu.com
(2)產(chǎn)品服務(wù)類
- 百度文庫：https://wenku.baidu.com/
- 百度知道：https://zhidao.baidu.com/
- 百度資訊：https://zhidao.baidu.com/
(3)市場(chǎng)活動(dòng)類
- 百度公益：http://gongyi.baidu.com
- 百度logo：http://logo.baidu.com/
- 百度世界：https://baiduworld.baidu.com
7.跨域考慮
在明確域名的情況下，一定要考慮接口是否跨域，以及跨域應(yīng)采用的技術(shù)手段等。
8.api版本
對(duì)于接口的url，應(yīng)加版本號(hào)http://api.demo.com/vk6zqhab033oa/，如 ，其中d表示版本號(hào),如v1.0,v2.0。
例子：獲取產(chǎn)品號(hào)為2019,版本號(hào)為v1.0的版本號(hào)的產(chǎn)品信息。
/api/v1.0/Pruducts/2019
9.適度過濾信息
當(dāng)記錄數(shù)比較多時(shí)(如 SELECT * FROM TBName)，因適當(dāng)添加一些條件對(duì)數(shù)據(jù)進(jìn)行過濾，如TOP,分頁,分組，排序和WHERE條件等。
下面是一些常見的參數(shù)。
- limit=100：返回100條數(shù)據(jù)
- offset=101：從第101條數(shù)據(jù)開始返回
- page=10：指第10頁
- per_page=100：每頁100條數(shù)據(jù)
- sortby=name：排序字段
- order=desc：降序
- group=groupName:分組
- producy_type=1：篩選條件
10.返回?cái)?shù)據(jù)格式
返回?cái)?shù)據(jù)格式，一般包括三個(gè)字段：
(1)失敗情況(狀態(tài)碼、錯(cuò)誤碼和錯(cuò)誤描述)。
{
“status”:0,//狀態(tài)碼 0-表示失敗，1-表示成功
“error_code”:”2003”,//錯(cuò)誤碼，一般在設(shè)計(jì)時(shí)定義
“error_des”:”身份驗(yàn)證失敗”//錯(cuò)誤描述，一般在設(shè)計(jì)時(shí)定義
}
(2)成功情況(標(biāo)識(shí)id,數(shù)據(jù)對(duì)象,狀態(tài)碼)。
”sid“:”sh20190111”,//token id
”users“:{
”id“:”al201901111341”,//用戶id
“name”:”Alan_beijing”,//用戶名
“addr”:”用戶地址”
},
“status”:1//狀態(tài)碼 0-表示失敗，1-表示成功
}
11.安全性原則
接口暴露的考慮，接口并發(fā)量的考慮，接口防攻擊的考慮，接口跨域的考慮等。
12.可擴(kuò)展性原則
在設(shè)計(jì)接口時(shí)，充分考慮接口的可擴(kuò)展性。
13.定義api界限
任何api，從權(quán)限上，可歸結(jié)為匿名api和非匿名api，前者不需要驗(yàn)證，后者需要驗(yàn)證
14.定義api返回碼。
在api設(shè)計(jì)時(shí)，要定好api返回碼，如：
- 1 --授權(quán)過期
- 404--未找到資源
- 500--內(nèi)部服務(wù)器錯(cuò)誤
- 600--賬號(hào)被鎖
二 反規(guī)范性建議
存在這樣一種業(yè)務(wù)場(chǎng)景：某個(gè)接口需要返回多個(gè)api接口組合的結(jié)果 ，在類似的業(yè)務(wù)場(chǎng)景下，所設(shè)計(jì)的接口，具有一定的反規(guī)范性。
1.Request
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
]
2.Responce
{
status:0,
msg:'',
data:[
{status:1,msg:'',data:[]},
{status:1,msg:'',data:{}}
]
}
三 實(shí)例
假設(shè)存在這樣一個(gè)一個(gè)業(yè)務(wù)：一個(gè)ERP系統(tǒng)，需要提供兩個(gè)接口，一個(gè)是用戶訪問接口(需要驗(yàn)證)，另一個(gè)是用戶注冊(cè)接口(不需要驗(yàn)證)。
根據(jù)本篇文章一，二部分的建議，我們來設(shè)計(jì)滿足該業(yè)務(wù)需求的接口。
(一)定義統(tǒng)一參數(shù)
1.定義統(tǒng)一輸入?yún)?shù)
2.定義統(tǒng)一輸出參數(shù)
3.定義統(tǒng)一錯(cuò)誤碼
(二)定義接口授權(quán)類別
如下為定義接口授權(quán)類別
(三)用戶接口
1.用戶注冊(cè)
2.Request
3.Responce
4.code示例?
Request:
{
"mobile":13636595499,
"verify_code":"987654",
"pwd":"123456"
}
Responce:
(1)error
{
"status":0,
"error_code":1001，
"error_desc":"手機(jī)驗(yàn)證碼已失效"
}
(2)succed
{
"sid":"sh201901141529",
"uid":1,
"status":1
}
(四)用戶登錄
1.登錄接口概述
2.Request
3.Responce
4.Code
Responce:
1.error
{
"status":0,
"error_code":1002,
"error_desc":"密碼錯(cuò)誤"
}
2.succeed
{
"sid":"sh201901141529",
"user":{
"id":1,
"username":"",
age:0,
gender:0
},
"status":1
}
作者：Alan_beijing
www.cnblogs.com/wangjiming
