作者：Alan_beijing
來源：https://www.cnblogs.com/wangjiming/p/10256546.html


溫馨提示：文中代碼看不全可左右滑動

在設計接口時，有很多因素要考慮，如接口的業務定位，接口的安全性，接口的可擴展性、接口的穩定性、接口的跨域性、接口的協議規則、接口的路徑規則、接口單一原則、接口過濾和接口組合等諸多因素，本篇文章將簡要分析這些因素。

一 規範性建議

1.職責原則

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

2.單一性原則

在明確接口職責的條件下，儘量做到接口單一，即一個接口只做一件事，而非兩件以上。很多非資深接口設計者，在設計接口時，總認爲接口所做的事越多，越牛叉，這是非常嚴重的錯誤認識。

3.協議規範

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

  • FTP協議(File Transfer Protocol，簡稱FTP)，是一套標準的文件傳輸協議，用於傳輸文件，如.txt，.csv等，一般文件傳輸，採用FTP協議
  • HTTP協議，適用一般對安全性要求比較低或沒要求的業務情景
  • 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--賬號被鎖

二 反規範性建議

存在這樣一種業務場景：某個接口需要返回多個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示例

如何設計一個良好的接口

（四）用戶登錄

1.登錄接口概述


如何設計一個良好的接口


2.Request


如何設計一個良好的接口


3.Responce


如何設計一個良好的接口


4.Code

如何設計一個良好的接口

擴展閱讀

接口和抽象類

我的編碼習慣——接口定義

Java多線程編程-（18）-等待/通知模式接口Condition接口深入分析

某小公司 RESTful、共用接口、前後端分離、接口約定的實踐

對接「支付寶」支付接口

秒殺系統：設計高併發接口思路

相关文章