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

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









 

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

 接口規(guī)范說起來大，其實也就那么幾個部分，接口規(guī)范、接口管理工具、接口文檔編寫、開發(fā)文檔編寫。

接口規(guī)范定義

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

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

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

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

格式規(guī)范如下：

支付模塊   /pay/xx

訂單模塊  /order/xx

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

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

格式規(guī)范如下：

  /xx/v1/xx

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

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

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

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

格式規(guī)范如下：

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

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

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

接口名稱動詞前/后綴化

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

接口名稱動詞+請求方式

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

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

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

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

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

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

如：

GET /zoo/v1/zoos：列出所有動物園

POST /zoo/v1/zoos：新建一個動物園

GET /zoo/v1/zoos/{ID}：獲取某個指定動物園的信息

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

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

DELETE /zoo/v1/zoos/{ID}：刪除某個動物園

GET /zoo/v1/zoos/{ID}/animals：列出某個指定動物園的所有動物

DELETE /zoo/v1/zoos/ID/animals/ID：刪除某個指定動物園的指定動物

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

請求方式：

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

請求頭：





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

請求參數(shù)/請求體：

    請求參數(shù)字段，盡可能與數(shù)據(jù)庫表字段、對象屬性名等保持一致，因為保持一致最省事，最舒服的一件事。

六、返回數(shù)據(jù)規(guī)范

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

格式規(guī)范如下：

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

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

接口管理工具推薦

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

接口管理的痛點

接口的管理常常面臨很多的痛苦，這里就列舉幾個常見的，看看你是否也遇到過。

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

接口管理工具推薦

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

word

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

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

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

wiki

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

RAP

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

swagger
在這里插入圖片描述

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

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

Easy Mock
在這里插入圖片描述

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

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



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