當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

如何设计一个良好的接口？

發布時間：2025/3/21 编程问答 19 豆豆

生活随笔收集整理的這篇文章主要介紹了如何设计一个良好的接口？小編覺得挺不錯的,現在分享給大家,幫大家做個參考.

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

一規范性建議

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/vze8trgl8bvbq/，如，其中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.Response

4.code示例

Request: {"mobile":13636595499,"verify_code":"987654","pwd":"123456" }Response: (1)error {"status":0,"error_code":1001，"error_desc":"手機驗證碼已失效" } (2)succed {"sid":"sh201901141529","uid":1,"status":1 }

（四）用戶登錄

1.登錄接口概述