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

一、規(guī)范性建議

1、職責原則

在設計接口時，必須明確接口的職責，即接口類型，接口應解決什么業(yè)務問題等。

2、單一性原則

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

3、協(xié)議規(guī)范

在設計接口時，應明確接口協(xié)議，是采用HTTP協(xié)議,HTTPS協(xié)議還是FTP協(xié)議，要根據(jù)具體情況來定。

(1) FTP協(xié)議(File Transfer Protocol，簡稱FTP)，是一套標準的文件傳輸協(xié)議，用于傳輸文件，如.txt，.csv等，一般文件傳輸，采用FTP協(xié)議。

(2) HTTP協(xié)議，適用一般對安全性要求比較低或沒要求的業(yè)務情景。

(3) HTTPS=HTTP+SSL，適用于對安全性要求較高的業(yè)務情景。

4、路徑規(guī)則

由于api獲取的是一種資源，所以網(wǎng)址中盡量為名詞，而非動詞

/api/v1.0/Pruduct/2019

/api/v1.0/Users/2019

5、http請求方式

接口基本訪問協(xié)議：get(獲取)，post(新增)，put(修改)和delete(刪除)

get? ? ? /users：列出所有用戶

get? ? ? /users/id：根據(jù)id獲取用戶

post? ? ?/user：新增用戶

put? ? ? ?/user/id：根據(jù)用戶id更新用戶

delete? ?/user/id：根據(jù)用戶id刪除用戶

6、域名

一般地，域名分為主域名和專有域名，主域名適合api長期不變或變化較少的業(yè)務，專有域名是解決具體的專有業(yè)務的

以百度舉例：

(1) 主域名:www.baidu.com

(2) 產(chǎn)品服務類

?百度文庫：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/vozvdkddzhkzd/，如?，其中d表示版本號,如v1.0,v2.0

例子：獲取產(chǎn)品號為2019,版本號為v1.0的版本號的產(chǎn)品信息

/api/v1.0/Pruducts/2019

9、適度過濾信息

當記錄數(shù)比較多時(如 SELECT * FROM TBName)，因適當添加一些條件對數(shù)據(jù)進行過濾，如TOP,分頁,分組，排序和WHERE條件等

下面是一些常見的參數(shù)。

?limit=100：返回100條數(shù)據(jù)

?offset=101：從第101條數(shù)據(jù)開始返回

?page=10：指第10頁

per_page=100：每頁100條數(shù)據(jù)

?sortby=name：排序字段

?order=desc：降序

？group=groupName:分組

?producy_type=1：篩選條件

10、返回數(shù)據(jù)格式

返回數(shù)據(jù)格式，一般包括三個字段：

(1) 失敗情況（狀態(tài)碼、錯誤碼和錯誤描述）

(2) 成功情況（標識id,數(shù)據(jù)對象,狀態(tài)碼）

11、安全性原則

接口暴露的考慮，接口并發(fā)量的考慮，接口防攻擊的考慮，接口跨域的考慮等。

12、可擴展性原則

在設計接口時，充分考慮接口的可擴展性。

13、定義api界限

任何api，從權限上，可歸結為匿名api和非匿名api，前者不需要驗證，后者需要驗證。

14、定義api返回碼

在api設計時，要定好api返回碼，如：

1 --授權過期

404--未找到資源

500--內部服務器錯誤

600--賬號被鎖

二、反規(guī)范性建議

存在這樣一種業(yè)務場景：某個接口需要返回多個api接口組合的結果 ，在類似的業(yè)務場景下，所設計的接口，具有一定的反規(guī)范性。

1、Request

2、Response

三、實例

假設存在這樣一個一個業(yè)務：一個ERP系統(tǒng)，需要提供兩個接口，一個是用戶訪問接口(需要驗證)，另一個是用戶注冊接口(不需要驗證)。

根據(jù)本篇文章一，二部分的建議，我們來設計滿足該業(yè)務需求的接口

（一）定義統(tǒng)一參數(shù)

1、定義統(tǒng)一輸入?yún)?shù)

2、定義統(tǒng)一輸出參數(shù)

3、定義統(tǒng)一錯誤碼

（二）定義接口授權類別

如下為定義接口授權類別

（三）用戶接口

1、用戶注冊

2、Request

3、Response

4、code示例

（四）用戶登錄

1、登錄接口概述

2、Request

3、Response

4、Code

總結

以上是生活随笔為你收集整理的API设计原则的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內容還不錯，歡迎將生活随笔推薦給好友。