如何設計乙個良好的介面

在設計介面時，有很多因素要考慮，如介面的業務定位，介面的安全性，介面的可擴充套件性、介面的穩定性、介面的跨域性、介面的協議規則、介面的路徑規則、介面單一原則、

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

一 規範性建議

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/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)產品服務類

(3)市場活動類

7.跨域考慮

在明確網域名稱的情況下，一定要考慮介面是否跨域，以及跨域應採用的技術手段等

8.api版本

對於介面的url，應加版本號如 ，其中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」:1//
狀態碼 0-表示失敗，1-表示成功
}

12.可擴充套件性原則

在設計介面時，充分考慮介面的可擴充套件性。

13.定義api界限

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

14.定義api返回碼

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

1 --授權過期

404--未找到資源

500--內部伺服器錯誤

600--賬號被鎖

二 反規範性建議

存在這樣一種業務場景：某個介面需要返回多個api介面組合的結果 ，在類似的業務場景下，所設計的介面，具有一定的反規範性。

1.request

data:[

},},
]

,}]

}

假設存在這樣乙個乙個業務：乙個erp系統，需要提供兩個介面，乙個是使用者訪問介面(需要驗證)，另乙個是使用者註冊介面(不需要驗證)。

根據本篇文章一，二部分的建議，我們來設計滿足該業務需求的介面

（一）定義統一引數

1.定義統一輸入引數

2.定義統一輸出引數

3.定義統一錯誤碼

（二）定義介面授權類別

如下為定義介面授權類別

（三）使用者介面

1.使用者註冊

4.code示例

request:

responce:(1
)error(2
)succed

**http在webapi開發中的運用

聊聊webapi體系結構

詳解webapi引數的傳遞

詳解webapi測試和postman

**webapi cores

詳解webapi 異常處理

用webapi寫個基於ef的curd

**webapi身份認證

詳解系列化和模型繫結

**webapi如何配合mvc有效工作

**api reference

**介面在軟體架構中的作用

**webapi和webservice的比較

如何設計乙個良好的介面

五  版權區

博主**：

乙個良好的團隊

乙個良好的團隊，是需要相互包含的，相互理解的！想要營造乙個良好的氛圍就必然需要幾個願意無償付出，奉獻的人，負責的人！畢竟人都是自私的，自利的，只在乎自己！所以適當的付出，無償的奉獻，一定程度上會使你占領先機，有一定的人緣優勢！構造乙個良好的團隊，就需要你無償的付出，所以說吃虧是福，提高情商，做乙個有...

如何設計乙個優雅的RESTFUL的介面

設計介面是我們開發人員的日常操作。當我們把接 給前端人員時，是否有種拔劍出鞘的錯覺。畢竟交付介面，我們的開發工作就階段性完成了。不過，如果我們沒有乙個介面設計規範的時候，結果會怎樣呢？我們來張圖感受一下。2000年，乙個年輕小夥子 roy thomas fielding 在他的博士 提出了 rest...

如何正確合理的設計乙個介面專案

首先，我這裡說明介面，不是 裡的介面，而是介面專案，如果想錯了就不用往下看了。在手機廣泛流行的今天，手機應用也隨之越來越多，而且成長的速度也非常快。手機應用軟體開發實現方式同普通pc軟體一樣，也分為bs和cs方式。而採用cs方式，在伺服器端大多採用介面的形式提供資料互動 主流資料互動方式有 json...