如何寫(xiě)出完美的接口：接口規(guī)范定義、接口管理工具推薦

作者：xcbeyond
瘋狂源自夢(mèng)想，技術(shù)成就輝煌！微信公眾號(hào)：《程序猿技術(shù)大咖》號(hào)主，專注后端開(kāi)發(fā)多年，擁有豐富的研發(fā)經(jīng)驗(yàn)，樂(lè)于技術(shù)輸出、分享，現(xiàn)階段從事微服務(wù)架構(gòu)項(xiàng)目的研發(fā)工作，涉及架構(gòu)設(shè)計(jì)、技術(shù)選型、業(yè)務(wù)研發(fā)等工作。對(duì)于Java、微服務(wù)、數(shù)據(jù)庫(kù)、Docker有深入了解，并有大量的調(diào)優(yōu)經(jīng)驗(yàn)。 









 

無(wú)規(guī)矩不成方圓，為了開(kāi)發(fā)人員間更好的配合，我特意整理了這么一篇文檔供大家參考學(xué)習(xí)，如有意見(jiàn)、見(jiàn)解，請(qǐng)?jiān)谠u(píng)論區(qū)留言探討。

 接口規(guī)范說(shuō)起來(lái)大，其實(shí)也就那么幾個(gè)部分，接口規(guī)范、接口管理工具、接口文檔編寫(xiě)、開(kāi)發(fā)文檔編寫(xiě)。

接口規(guī)范定義

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

為了確保不同系統(tǒng)/模塊間的數(shù)據(jù)交互，需要事先約定好通訊協(xié)議，如：TCP、HTTP、HTTPS協(xié)議。為了確保數(shù)據(jù)交互安全，建議使用HTTPS協(xié)議。

二、接口路徑規(guī)范

作為接口路徑，為了方便清晰的區(qū)分來(lái)自不同的系統(tǒng)，可以采用不同系統(tǒng)/模塊名作為接口路徑前綴。

格式規(guī)范如下：

支付模塊   /pay/xx

訂單模塊  /order/xx

三、版本控制規(guī)范

為了便于后期接口的升級(jí)和維護(hù)，建議在接口路徑中加入版本號(hào)，便于管理，實(shí)現(xiàn)接口多版本的可維護(hù)性。如果你細(xì)心留意過(guò)的話，你會(huì)發(fā)現(xiàn)好多框架對(duì)外提供的API接口中(如：Eureka)，都帶有版本號(hào)的。如：接口路徑中添加類似"v1"、"v2"等版本號(hào)。

格式規(guī)范如下：

  /xx/v1/xx

更新版本后可以使用v2、v3等、依次遞加。

四、接口命名規(guī)范

和Java命名規(guī)范一樣，好的、統(tǒng)一的接口命名規(guī)范，不僅可以增強(qiáng)其可讀性，而且還會(huì)減少很多不必要的口頭/書(shū)面上的解釋。

可結(jié)合【接口路徑規(guī)范】、【版本控制規(guī)范】，外加具體接口命名(路徑中可包含請(qǐng)求數(shù)據(jù)，如：id等)，建議具體接口命名也要規(guī)范些，可使用"駝峰命名法"按照實(shí)現(xiàn)接口的業(yè)務(wù)類型、業(yè)務(wù)場(chǎng)景等命名，有必要時(shí)可采取多級(jí)目錄命名，但目錄不宜過(guò)長(zhǎng)，兩級(jí)目錄較為適宜。

格式規(guī)范如下：

/user/v1/sys/login     用戶服務(wù)/模塊的系統(tǒng)登錄接口

/zoo/v1/zoos/{ID} 動(dòng)物園服務(wù)/模塊中，獲取id為ID的動(dòng)物

具體接口命名，通常有以下兩種方式：

接口名稱動(dòng)詞前/后綴化

接口名稱以接口數(shù)據(jù)操作的動(dòng)詞為前/后綴，常見(jiàn)動(dòng)詞有：add、delete、update、query、get、send、save、detail、list等，如：新建用戶addUser、查詢訂單詳情queryOrderDetail。

接口名稱動(dòng)詞+請(qǐng)求方式

 接口路徑中包含具體接口名稱的名詞，接口數(shù)據(jù)操作動(dòng)作以HTTP請(qǐng)求方式來(lái)區(qū)分。常用的HTTP請(qǐng)求方式有：

GET：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。

POST：在服務(wù)器新建一個(gè)資源。

PUT：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。

PATCH：在服務(wù)器更新資源（客戶端提供改變的屬性）。

DELETE：從服務(wù)器刪除資源。

如：

GET /zoo/v1/zoos：列出所有動(dòng)物園

POST /zoo/v1/zoos：新建一個(gè)動(dòng)物園

GET /zoo/v1/zoos/{ID}：獲取某個(gè)指定動(dòng)物園的信息

PUT /zoo/v1/zoos/{ID}：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）

PATCH /zoo/v1/zoos/{ID}：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）

DELETE /zoo/v1/zoos/{ID}：刪除某個(gè)動(dòng)物園

GET /zoo/v1/zoos/{ID}/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物

DELETE /zoo/v1/zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物

五、請(qǐng)求參數(shù)規(guī)范

請(qǐng)求方式：

按照GET、POST、PUT等含義定義，避免出現(xiàn)不一致現(xiàn)象，對(duì)人造成誤解、歧義。

請(qǐng)求頭：





請(qǐng)求頭根據(jù)項(xiàng)目需求添加配置參數(shù)。如：請(qǐng)求數(shù)據(jù)格式，accept=‘a(chǎn)pplication/json’等。如有需要，請(qǐng)求頭可根據(jù)項(xiàng)目需求要求傳入用戶token、唯一驗(yàn)簽碼等加密數(shù)據(jù)。

請(qǐng)求參數(shù)/請(qǐng)求體：

    請(qǐng)求參數(shù)字段，盡可能與數(shù)據(jù)庫(kù)表字段、對(duì)象屬性名等保持一致，因?yàn)楸３忠恢伦钍∈?，最舒服的一件事?

六、返回?cái)?shù)據(jù)規(guī)范

統(tǒng)一規(guī)范返回?cái)?shù)據(jù)的格式，對(duì)己對(duì)彼都有好處，此處以json格式為例。返回?cái)?shù)據(jù)應(yīng)包含：返回狀態(tài)碼、返回狀態(tài)信息、具體數(shù)據(jù)。

格式規(guī)范如下：

{
 
    "status":"000000",
 
    "msg":"success",
 
    "data": {
 
        //json格式的具體數(shù)據(jù)
 
    }
 
}

    返回?cái)?shù)據(jù)中的狀態(tài)碼、狀態(tài)信息，常指具體的業(yè)務(wù)狀態(tài)，不建議和HTTP狀態(tài)碼混在一起。HTTP狀態(tài)，是用來(lái)體現(xiàn) HTTP鏈路狀態(tài)情況，如：404-Not Found。HTTP狀態(tài)碼和json結(jié)果中的狀態(tài)碼，并存尚可，用于體現(xiàn)不同維度的狀態(tài)。

接口管理工具推薦

接口開(kāi)發(fā)完后，最終的目的是提供給其他系統(tǒng)/模塊來(lái)使用的，因此，接口的管理是必不可少的。

接口管理的痛點(diǎn)

接口的管理常常面臨很多的痛苦，這里就列舉幾個(gè)常見(jiàn)的，看看你是否也遇到過(guò)。

系統(tǒng)/模塊太多、接口太多，沒(méi)有系統(tǒng)統(tǒng)一管理所有接口。
代碼修改后，接口文檔沒(méi)有及時(shí)更新，造成接口文檔和實(shí)際接口不一致的現(xiàn)象。
接口管理系統(tǒng)自主研開(kāi)發(fā)成本高。
接口管理缺少接口mock功能。

接口管理工具推薦

   在日常工作過(guò)程中用過(guò)、接觸過(guò)的接口管理工具也是不盡其數(shù)，下面介紹你可能使用過(guò)、沒(méi)有使用過(guò)的接口管理工具，同時(shí)也介紹這些接口管理工具的優(yōu)缺點(diǎn)。

word

  相信大家之前用來(lái)管理接口比較多的應(yīng)該是word吧，開(kāi)發(fā)人員將系統(tǒng)的接口維護(hù)在word文檔里，不管是組內(nèi)溝通還是和其他團(tuán)隊(duì)的接口溝通都離不開(kāi)這些接口文檔，每次修改文檔和代碼都要同步修改。相信使用word的缺點(diǎn)大家應(yīng)該也很清楚，就是維護(hù)和管理很麻煩，我們經(jīng)常會(huì)遇到文檔和代碼不一致的情況，大部分不一致都是因?yàn)榻涌谝驗(yàn)榉N種原因修改了，開(kāi)發(fā)人員大部分都是只改了代碼里的接口實(shí)現(xiàn)，而沒(méi)有去修改接口文檔。而且word文檔搜索接口也很麻煩，沒(méi)辦法建全局索引，只能一個(gè)個(gè)文檔點(diǎn)開(kāi)查看，想想就很痛苦。但不可否認(rèn)的是，word對(duì)于一些小團(tuán)隊(duì)用起來(lái)還是挺方便的，不用搭建系統(tǒng)，給誰(shuí)一看就明白。

自建接口管理系統(tǒng)

   對(duì)于一些有一定規(guī)模的企業(yè)，在各項(xiàng)工程管理活動(dòng)上都非常正規(guī)，各種ISO標(biāo)準(zhǔn)要遵守，自然對(duì)接口管理的要求也非常高，之前在國(guó)有銀行，我們就是自建了接口管理系統(tǒng)，自建還是很消耗人力成本的，從開(kāi)發(fā)到后續(xù)運(yùn)維，都要消耗人力，但是自建的好處就是，可以根據(jù)公司的要求進(jìn)行各種花樣的定制，我們之前在接口管理系統(tǒng)中加入了很多好用的定制功能，例如接口被哪些系統(tǒng)調(diào)用、接口是在哪個(gè)批次投產(chǎn)又在哪個(gè)批次做過(guò)變更等等，這對(duì)于架構(gòu)師來(lái)說(shuō)非常好用，用于分析接口影響范圍非常方便。目前開(kāi)源的接口管理系統(tǒng)還沒(méi)有能做到這些定制化功能的。

wiki

  之前在小團(tuán)隊(duì)的時(shí)候還用過(guò)一段時(shí)間的私有wiki，wiki特別適合于小團(tuán)隊(duì)高速線性迭代開(kāi)發(fā)，在wiki上看到的就是最新的接口，團(tuán)隊(duì)內(nèi)所有成員看到的都是一樣的，如果接口有變化，相關(guān)開(kāi)發(fā)人員修改后立即生效，保證了順暢的接口溝通。但是wiki的缺點(diǎn)也很多，接口文檔只是靜態(tài)頁(yè)面，無(wú)法實(shí)現(xiàn)一些動(dòng)態(tài)效果，無(wú)法實(shí)現(xiàn)追溯等等缺點(diǎn)。

RAP

   相信很多互聯(lián)網(wǎng)公司都在使用RAP，RAP是阿里開(kāi)源的一套接口管理系統(tǒng)，RAP可以比較方便的管理公司所有系統(tǒng)的接口，同時(shí)還有比較完善的權(quán)限管理，還可以做接口mock，方便開(kāi)發(fā)人員在接口功能還沒(méi)有完成的時(shí)候能夠及時(shí)發(fā)布出去，給調(diào)用方去使用。但是RAP的缺點(diǎn)就是每個(gè)接口都需要維護(hù)進(jìn)去，接口修改后也需要及時(shí)維護(hù)，當(dāng)時(shí)我們?cè)谑褂玫臅r(shí)候遇到的最大的問(wèn)題也是經(jīng)常碰到接口沒(méi)有及時(shí)維護(hù)的問(wèn)題。

swagger
在這里插入圖片描述

  上面說(shuō)的那些接口管理工具，其實(shí)都有一個(gè)很大的問(wèn)題就是修改代碼后需要同步維護(hù)接口文檔，但是讓程序員去修改文檔是很難的，大部分程序員都比較討厭維護(hù)各類文檔。當(dāng)我第一次了解到swagger的時(shí)候，發(fā)現(xiàn)這簡(jiǎn)直就是為程序員定制的接口管理工具，swagger定義了很多注解，在對(duì)接口加上swagger相關(guān)的注解，當(dāng)接口代碼修改后，swagger在工程啟動(dòng)后會(huì)根據(jù)代碼自動(dòng)生成最新的接口html文檔，同時(shí)swagger提供了mock接口模擬的功能，也能夠更加方便的模擬接口，并且還能夠在swagger界面上直接發(fā)起接口調(diào)用，可以方便調(diào)用方在還沒(méi)寫(xiě)代碼的時(shí)候就能夠嘗試下接口調(diào)用后的結(jié)果。

  看了那么多swagger的優(yōu)點(diǎn)，下面也說(shuō)說(shuō)swagger的缺點(diǎn)，那就是swagger是跟隨著每個(gè)工程一起啟動(dòng)的，這就導(dǎo)致每個(gè)工程都有一個(gè)swagger的訪問(wèn)地址，如果公司系統(tǒng)很多的話，那就會(huì)導(dǎo)致查看不同系統(tǒng)的接口都要到不同的地址去查看，每個(gè)開(kāi)發(fā)都要自己收藏好各個(gè)系統(tǒng)的swagger地址。有些公司也自己開(kāi)發(fā)了統(tǒng)一網(wǎng)關(guān)，將所有swagger的接口地址聚合起來(lái)，但是多少還是涉及到一些開(kāi)發(fā)工作的，而且做的還不一定很完善。

Easy Mock
在這里插入圖片描述

    官網(wǎng)的這張圖基本上介紹清楚了easymock的核心功能，這其中我最看重的功能有兩塊，一個(gè)是能夠集成swagger接口并集中管理所有接口，另一個(gè)就是響應(yīng)式數(shù)據(jù)。

   EasyMock能夠根據(jù)swagger接口的地址自動(dòng)導(dǎo)入所有swagger接口，非常方便，對(duì)于非swagger的接口也可以手工維護(hù)進(jìn)去，這樣可以很方便的做到全公司接口統(tǒng)一維護(hù)，而且也有比較完善的接口權(quán)限管理，方便分組管理。但缺點(diǎn)就是過(guò)于龐大，可能太適合小一點(diǎn)項(xiàng)目或團(tuán)隊(duì)。



  上面提及到接口管理工具，大家可根據(jù)自己項(xiàng)目的規(guī)模、需求，進(jìn)行實(shí)際選擇，切記生搬硬套。