閱讀本文大概需要 3 分鐘。
在設計接口時，有很多因素要考慮：
接口的業務定位
接口的安全性
接口的可擴展性
接口的穩定性
接口的跨域性
接口的協議規則
接口的路徑規則
接口單一原則
接口過濾及接口組合
本篇文章將簡要分析這些因素。
一 規範性建議
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}作者：Alan
來源：https://www.cnblogs.com/wangjiming/p/10256546.html
·END·
程序員的成長之路
路雖遠，行則必至
本文原發於 同名微信公衆號「程序員的成長之路」，回覆「1024」你懂得，給個讚唄。
回覆 [ 520 ] 領取程序員最佳學習方式
回覆 [ 256 ] 查看 Java 程序員成長規劃