如何設計一個良好的接口

時間 2019-11-09

標籤如何設計一個良好接口简体版

原文原文鏈接

在設計接口時，有不少因素要考慮，如接口的業務定位，接口的安全性，接口的可擴展性、接口的穩定性、接口的跨域性、接口的協議規則、接口的路徑規則、接口單一原則、html

接口過濾和接口組合等諸多因素，本篇文章將簡要分析這些因素。api

一規範性建議跨域

1.職責原則安全

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

2.單一性原則架構

在明確接口職責的條件下，儘可能作到接口單一，即一個接口只作一件事，而非兩件以上。不少非資深接口設計者，在設計接口時，併發

總認爲接口所作的事越多，越牛叉，這是很是嚴重的錯誤認識。post

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)失敗狀況(狀態碼、錯誤碼和錯誤描述)

{

「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相關文章

【01】淺談HTTP在WebApi開發中的運用

【02】聊聊WebApi體系結構

【03】詳解WebApi參數的傳遞

【04】詳解WebApi測試和PostMan

【05】淺談WebApi Cores

【06】詳解WebApi 異常處理

【07】用WebAPI寫個基於EF的CURD

【08】淺談WebAPI身份認證

【09】詳解系列化和模型綁定

【10】淺談WebApi如何配合Mvc有效工做

【11】淺談API Reference