【Java工程師必備素質】你設計的介面，夠優雅嗎？

Java · 發表 2019-04-29 11:05:15

摘要：公眾號後臺回覆 “ 資料 ” 獲取作者獨家祕製學習資料在設計介面時，有很多因素要考慮：介面的業務定位介面的安全性介面的可擴充套件性介面的穩定性介面的跨域性介面的協議規則介面的路徑規則 ...

公眾號後臺回覆 “ 資料 ”

獲取作者獨家祕製學習資料

在設計介面時，有很多因素要考慮：

介面的業務定位
介面的安全性
介面的可擴充套件性
介面的穩定性
介面的跨域性
介面的協議規則
介面的路徑規則
介面單一原則
介面過濾及介面組合

本篇文章將簡要分析這些因素。

一規範性建議

1.職責原則

在設計介面時，必須明確介面的職責，即介面型別，介面應解決什麼業務問題等

2.單一性原則

在明確介面職責的條件下，儘量做到介面單一，即一個介面只做一件事，而非兩件以上。

很多非資深介面設計者，在設計介面時，總認為介面所做的事越多，越牛叉，這是非常嚴重的錯誤認識。

3.協議規範

在設計介面時，應明確介面協議，是採用HTTP協議,HTTPS協議還是FTP協議，要根據具體情況來定。

(1) FTP協議 (File Transfer Protocol，簡稱FTP)，是一套標準的檔案傳輸協議，用於傳輸檔案，如.txt，.csv等，一般檔案傳輸，採用FTP協議

(2) HTTP協議，適用一般對安全性要求比較低或沒要求的業務情景

(3) HTTPS=HTTP+SSL ,適用於對安全性要求較高的業務情景

4.路徑規則

由於api獲取的是一種資源，所以網址中儘量為名詞，而非動詞

/api/v1.0/Product/2019

/api/v1.0/Users/2019

5.http請求方式

介面基本訪問協議：get(獲取)，post(新增)，put(修改)和delete(刪除)

get /users：列出所有使用者

get /users/id：根據id獲取使用者

post /user：新增使用者

put /user/id：根據使用者id更新使用者

delete /user/id：根據使用者id刪除使用者

6.域名

一般地，域名分為主域名和專有域名，主域名適合api長期不變或變化較少的業務，專有域名是解決具體的專有業務的

以百度舉例：

(1)主域名:www.baidu.com

(2)產品服務類

百度文庫：https://wenku.baidu.com/

百度知道：https://zhidao.baidu.com/

百度資訊： https://zhidao.baidu.com/

(3)市場活動類

百度公益：http://gongyi.baidu.com

百度logo：http://logo.baidu.com/

百度世界：https://baiduworld.baidu.com

7.跨域考慮

在明確域名的情況下，一定要考慮介面是否跨域，以及跨域應採用的技術手段等

8.api版本

對於介面的url，應加版本號http://api.demo.com/v{d}/，如，其中d表示版本號,如v1.0,v2.0

例子：獲取產品號為2019,版本號為v1.0的版本號的產品資訊

/api/v1.0/Pruducts/2019

9.適度過濾資訊

當記錄數比較多時(如 SELECT * FROM TBName)，應適當新增一些條件對資料進行過濾，如TOP,分頁,分組，排序和WHERE條件等

下面是一些常見的引數。

?limit=100：返回100條資料

?offset=101：從第101條資料開始返回

?page=10：指第10頁

per_page=100：每頁100條資料

?sortby=name：排序欄位

?order=desc：降序

？group=groupName:分組

?producy_type=1：篩選條件

10.返回資料格式

返回資料格式，一般包括三個欄位：

(1)失敗情況(狀態碼、錯誤碼和錯誤描述)

{

 “status”:0,//狀態碼 0-表示失敗，1-表示成功

 “error_code”:“2003”,//錯誤碼，一般在設計時定義

 “error_des”:“身份驗證失敗”//錯誤描述，一般在設計時定義

}

(2)成功情況(標識id,資料物件,狀態碼)

{

 “sid“:“sh20190111”,//token id

 “users”:{

“id”:“al201901111341”,//使用者id

“name”:“Alan_beijing”,//使用者名稱

“addr”:“使用者地址”

},

 “status”:1//狀態碼 0-表示失敗，1-表示成功

}

11.安全性原則

介面暴露的考慮，介面併發量的考慮，介面防攻擊的考慮，介面跨域的考慮等

12.可擴充套件性原則

在設計介面時，充分考慮介面的可擴充套件性。

13.定義api界限

任何api，從許可權上，可歸結為匿名api和非匿名api，前者不需要驗證，後者需要驗證

14.定義api返回碼

在api設計時，要定好api返回碼，如

1 --授權過期
404--未找到資源
500--內部伺服器錯誤
600--賬號被鎖

二反規範性建議

存在這樣一種業務場景：某個介面需要返回多個api介面組合的結果，在類似的業務場景下，所設計的介面，具有一定的反規範性。

1.Request

data:[
 {url:'api1',type:'get',data:{...}},
 {url:'api2',type:'get',data:{...}},
]

2.Response

{
 status:0,
 msg:'',
 data:[
{status:1,msg:'',data:[]},
{status:1,msg:'',data:{}}
 ]
}

三例項

假設存在這樣一個一個業務：一個ERP系統，需要提供兩個介面，一個是使用者訪問介面(需要驗證)，另一個是使用者註冊介面(不需要驗證)。

根據本篇文章一，二部分的建議，我們來設計滿足該業務需求的介面

（一）定義統一引數

1.定義統一輸入引數

2.定義統一輸出引數

3.定義統一錯誤碼

（二）定義介面授權類別

如下為定義介面授權類別

（三）使用者介面

1.使用者註冊

2.Request

3.Responce

4.code示例

Request:
{
 "mobile":13636595499,
 "verify_code":"987654",
 "pwd":"123456"
}

Responce:
(1)error
{
 "status":0,
 "error_code":1001，
 "error_desc":"手機驗證碼已失效"
}
(2)succed
{
 "sid":"sh201901141529",
 "uid":1,
 "status":1
}

（四）使用者登入

1.登入介面概述

2.Request

3.Response

4.Code

Responce:
1.error
{
 "status":0,
 "error_code":1002,
 "error_desc":"密碼錯誤"
}
2.succeed
{
 "sid":"sh201901141529",
 "user":{
"id":1,
"username":"",
age:0,
gender:0
 },
 "status":1
}

End

作者：Alan

來源：

https://www.cnblogs.com/wangjiming/p/10256546.html

歡迎長按下圖關注公眾號 石杉的架構筆記 ，後臺回覆“ 資料 ”，獲取作者獨家祕製學習資料！

BAT架構經驗傾囊相授

【Java工程師必備素質】你設計的介面，夠優雅嗎？

獲取作者獨家祕製學習資料

End

您可能也會喜歡…