點選「 IT碼徒 」， 關註，置頂 公眾號
每日技術幹貨，第一時間送達！
在設計介面時，有很多因素要考慮，如介面的業務定位，介面的安全性，介面的可延伸性、介面的穩定性、介面的跨域性、介面的協定規則、介面的路徑規則、介面單一原則、介面過濾和介面組合等諸多因素，本篇文章將簡要分析這些因素。
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) 市場活動類
百度公益：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) 失敗情況（狀態碼、錯誤碼和錯誤描述）
(2) 成功情況（標識id,數據物件,狀態碼）
11、安全性原則
介面暴露的考慮，介面並行量的考慮，介面防攻擊的考慮，介面跨域的考慮等。
12、可延伸性原則
在設計介面時，充分考慮介面的可延伸性。
13、定義api界限
任何api，從許可權上，可歸結為匿名api和非匿名api，前者不需要驗證，後者需要驗證。
14、定義api返回碼
在api設計時，要定好api返回碼，如：
1 --授權過期
404--未找到資源
500--內部伺服器錯誤
600--帳號被鎖
2
反規範性建議
存在這樣一種業務場景：某個介面需要返回多個api介面組合的結果 ，在類似的業務場景下，所設計的介面，具有一定的反規範性。
1、Request
2、Response
3
例項
假設存在這樣一個一個業務：一個ERP系統，需要提供兩個介面，一個是使用者存取介面(需要驗證)，另一個是使用者註冊介面(不需要驗證)。
根據本篇文章一，二部份的建議，我們來設計滿足該業務需求的介面
（一）定義統一參數
1、定義統一輸入參數
2、定義統一輸出參數
3、定義統一錯誤碼
（二）定義介面授權類別
如下為定義介面授權類別
（三）使用者介面
1、使用者註冊
2、Request
3、Response
4、code範例
（四）使用者登入
1、登入介面概述
2、Request
3、Response
4、Code
作者：Alan_beijing
來源：www.cnblogs.com/wangjiming
— END —
PS：防止找不到本篇文章，可以收藏點贊，方便翻閱尋找哦。
往期推薦
