在設計介面時,有很多因素要考慮,如介面的業務定位,介面的安全性,介面的可擴展性、介面的穩定性、介面的跨域性、介面的協議規則、介面的路徑規則、介面單一原則、 介面過濾和介面組合等諸多因素,本篇文章將簡要分析這些因素。 一 規範性建議 1.職責原則 在設計介面時,必須明確介面的職責,即介面類型,介面應解 ...
在設計介面時,有很多因素要考慮,如介面的業務定位,介面的安全性,介面的可擴展性、介面的穩定性、介面的跨域性、介面的協議規則、介面的路徑規則、介面單一原則、
介面過濾和介面組合等諸多因素,本篇文章將簡要分析這些因素。
一 規範性建議
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/Pruduct/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)市場活動類
百度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.Responce
{ 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.Responce
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 }
四 WebApi相關文章
五 版權區
- 感謝您的閱讀,若有不足之處,歡迎指教,共同學習、共同進步。
- 博主網址:http://www.cnblogs.com/wangjiming/。
- 極少部分文章利用讀書、參考、引用、抄襲、複製和粘貼等多種方式整合而成的,大部分為原創。
- 如您喜歡,麻煩推薦一下;如您有新想法,歡迎提出,郵箱:[email protected]。
- 可以轉載該博客,但必須著名博客來源。