【快樂摸魚】是一款基于Vue和Electron的開源接口管理工具。

傳送門

GitHub地址
Gitee地址
完整文檔
在線體驗(yàn)

前言

最初構(gòu)建這個(gè)項(xiàng)目的時(shí)候是為了學(xué)習(xí)Node.js和解決團(tuán)隊(duì)前后端協(xié)調(diào)問題。社區(qū)中有 YApi 、Rap2、Doclever、 Nei、Swagger、Apidoc等開源解決方案，同時(shí)也存在 Postman、Eolinker、ApiPost等商業(yè)解決方案。

在這之前團(tuán)隊(duì)嘗試了YApi和Rap2等社區(qū)方案，他們能夠滿足一些基本的需求，但是在深入使用以后，還是出現(xiàn)了一些影響效率的問題。當(dāng)時(shí)使用這兩個(gè)工具最大的問題就是接口無法支持多級嵌套，某些項(xiàng)目接口多了以后會導(dǎo)致檢索效率大大降低。于是嘗試從頭開始寫一款接口管理工具。

團(tuán)隊(duì)協(xié)作

非常核心的一個(gè)功能，在前后端分離情況下，一套簡潔的團(tuán)隊(duì)管理策略會大大提高分工效率。我們將權(quán)限分為 只讀、讀寫、管理員三類。

• 只讀：只允許用戶查看文檔(一般可以給前端開發(fā)人員賦予這個(gè)角色)
• 讀寫：允許對文檔進(jìn)行增刪改查等(一般可以給后端開發(fā)人員賦予這個(gè)角色)
• 管理員：除了讀寫以外還可以增加或者刪除用戶

上面的三種角色可以滿足大部分日常使用需求。在一些特殊情況下你可能需要更加細(xì)粒度的權(quán)限控制，比如：擁有讀寫權(quán)限的用戶你只希望他能編輯文檔，但不希望他能導(dǎo)出全部文檔。我們提供了自定義角色功能，可以精確到每一個(gè)接口和路由(一般情況下用不到)。

權(quán)限管理.gif

目錄導(dǎo)航

非常核心的一個(gè)功能，設(shè)計(jì)一個(gè)方便并且易使用的目錄導(dǎo)航能夠大大增強(qiáng)錄入體驗(yàn)。我們從其他開源項(xiàng)目issue中總結(jié)了一些常見需求。

• 支持無限級別嵌套
• 支持拖拽文件
• 支持拖拽目錄
• 支持單個(gè)或者批量拷貝文件
• 支持單個(gè)或者多個(gè)拷貝目錄
• 支持一些右鍵菜單
• 能夠批量刪除
• 導(dǎo)航欄接口要與目錄聯(lián)動展開

工具實(shí)現(xiàn)了上面的全部功能，同時(shí)也擴(kuò)展了一些實(shí)用的功能。

• 單個(gè)目錄下面擁有超過10個(gè)文檔會降低文檔檢索效率，默認(rèn)情況下工具限制單個(gè)目錄只允許8個(gè)文檔存在，當(dāng)然也允許你自定義限制個(gè)數(shù)。
• 由于目錄導(dǎo)航空間有限，工具允許你使用Ctrl + 鼠標(biāo)左鍵來查看節(jié)點(diǎn)的額外信息

批量刪除.gif

批量刪除操作.gif

標(biāo)簽導(dǎo)航

標(biāo)簽導(dǎo)航是為了方便開發(fā)人員在多個(gè)接口之間快速切換，開源的產(chǎn)品這塊做的并不是很完善，我們在實(shí)踐中總結(jié)了這些需求。

• 頂部導(dǎo)航標(biāo)簽要與左側(cè)目錄導(dǎo)航一起聯(lián)動
• 導(dǎo)航標(biāo)簽要允許拖拽
• 導(dǎo)航標(biāo)簽需要鼠標(biāo)右鍵操作
• 在文檔發(fā)生變動的時(shí)候?qū)Ш綐?biāo)簽需要有小圓點(diǎn)提示
• 導(dǎo)航標(biāo)簽需要標(biāo)注請求類型

大部分商用的接口工具都具備導(dǎo)航標(biāo)簽功能，但是開源產(chǎn)品這塊大都不具備標(biāo)簽導(dǎo)航功能或者功能完成度不高

導(dǎo)航標(biāo)簽.gif

接口調(diào)試(模擬請求)

大部分的接口工具都會內(nèi)置接口調(diào)試功能，這樣開發(fā)人員只需要使用一個(gè)工具就能完成接口調(diào)試和接口錄入。不過由于瀏覽器本身的限制(同源策略)，直接在web端發(fā)起HTTP請求大概率會失敗。這里列舉了一些常見的解決方案。

從技術(shù)上來說，使用客戶端來規(guī)避同源策略是一種比較好的實(shí)踐，同時(shí)依托客戶端強(qiáng)大的api還能完成很多web端無法完成的事情，當(dāng)然安裝客戶端也會給用戶帶來一些不方便。目前主流的商業(yè)項(xiàng)目大都采用客戶端的形式來為用戶提供接口調(diào)試功能，部分工具甚至不提供web端的使用。我們采用了客戶端的方式來實(shí)現(xiàn)接口調(diào)試，同時(shí)也保留了web端的使用功能，除了接口調(diào)試和Mock功能無法使用外，web端和客戶端在功能上沒有其他區(qū)別。我們也會在未來提供瀏覽器插件功能，這樣用戶就可以在web端使用接口調(diào)試功能了

我們總結(jié)一些常見的接口調(diào)試需求

• 支持常見的GET、POST、PUT、DELETE、OPTIONS、PATCH
• 支持RESTFUL類型查詢參數(shù)
• 支持 x-www-form-urlencoded、multipart/form-data、json、xml、binary等常見MIME類型
• multipart/form-data支持傳遞文件
• 支持自定義Header
• 支持發(fā)送Cookie
• 支持自定義變量
• 支持格式化的預(yù)覽返回值，json，text/html，image等類型
• 前置操作，后置操作
• websocket

非JSON格式數(shù)據(jù)展示.png

JSON格式數(shù)據(jù).png

接口錄入

對接口的增刪改查是整個(gè)接口工具最核心的部分，常見的開源產(chǎn)品對 請求參數(shù)(Body)，多個(gè)返回參數(shù)方面支持比較弱。我們總結(jié)了在典型業(yè)務(wù)場景下，接口錄入應(yīng)該包含以下核心模塊。

• 請求方法和請求URL錄入
• 接口標(biāo)簽錄入
• 請求參數(shù)(Params) /api/demo?id=3&name=lee
• 請求參數(shù)(Path) /api/demo/{id}
• 請求參數(shù)(Body)
  • none
  • form-data(可以傳文件)
  • x-www-form-urlencoded(表單提交方式)
  • application/json
  • text/plain、text/plain、application/javascript、application/xml等 MIME類型
  • binary
• 請求頭
• 返回參數(shù)(通常來說可以添加多個(gè)返回參數(shù))
• 備注信息(富文本格式)
• 草稿狀態(tài)
• 變量支持
• 支持豐富的參數(shù)類型 Number、Integer、String、Array、Object、File、Binary、Boolean、Null、Enum

接口工具區(qū)分body錄入方式，目的是對某些特定類型數(shù)據(jù)進(jìn)行格式化處理，這些數(shù)據(jù)都通過HTTP body傳輸，程序通過header里面的Content-Type區(qū)分?jǐn)?shù)據(jù)格式。

接口錄入.png

【接口錄入工作區(qū)】

除了完善必要的接口模塊，工具還在錄入效率方面想了很多辦法。我們從Yapi、Rap2等開源項(xiàng)目issue中整理用戶常見的錄入需求。

• 每個(gè)字段的錄入都希望存在補(bǔ)全功能
• 參數(shù)模板功能
• json類型數(shù)據(jù)導(dǎo)入功能，并且能自動補(bǔ)全備注
• 發(fā)送模擬請求時(shí)，希望能將真實(shí)返回值應(yīng)用于文檔

字段快捷補(bǔ)全.gif

參數(shù)模板.gif

json數(shù)據(jù)導(dǎo)入.gif

返回參數(shù)應(yīng)用為文檔.gif

導(dǎo)入功能

目前市面上接口工具總類繁多，在處理導(dǎo)入的時(shí)候會有以下幾個(gè)主要問題。

• 大部分接口工具并沒有嚴(yán)格的數(shù)據(jù)格式定義
• 當(dāng)前系統(tǒng)數(shù)據(jù)接口并不能很好的和第三方接口兼容
• 部分工具不提供可處理格式數(shù)據(jù)(JSON，YAML等)導(dǎo)出功能
• openapi/swagger這類規(guī)范細(xì)節(jié)非常豐富，需要處理大量邏輯
• openapi/swagger這類規(guī)范，用戶未能嚴(yán)格按照規(guī)范書寫導(dǎo)致導(dǎo)入出錯
• 導(dǎo)入數(shù)據(jù)會有一些額外的配置需求(eg: 指定導(dǎo)出位置，指定導(dǎo)出數(shù)據(jù)量等)

目前比較穩(wěn)定和被普遍認(rèn)可的規(guī)范是OpenAPI規(guī)范，很多商業(yè)化的工具都是支持這種規(guī)范的。postman這類工具擁有非常大的市場占有率，大部分工具也都支持這種類型數(shù)據(jù)導(dǎo)入。我們收集了一些常用的接口工具，并且列出了工具對導(dǎo)入的支持情況。

在常規(guī)導(dǎo)入需求上面，我們擴(kuò)展了一些功能，提高了部分項(xiàng)目內(nèi)遷移效率。

• 允許多個(gè)項(xiàng)目之間互相導(dǎo)出數(shù)據(jù)
• 允許用戶指定導(dǎo)入時(shí)候掛載目錄

項(xiàng)目互相導(dǎo)出.gif

額外導(dǎo)入數(shù)據(jù)配置.png

導(dǎo)出功能

導(dǎo)出功能一方面是方便用戶分享文檔給第三方用戶，另一方面也提供了一定的遷移和備份能力。下面是一些常見的導(dǎo)出場景

由于HTML擁有非常不錯的UI表現(xiàn)能力，我們花費(fèi)了相當(dāng)多的精力在靜態(tài)HTML上。我們推薦使用HTML作為首選的離線文檔。

按需導(dǎo)出.gif

回收站和日志功能

日志功能是團(tuán)隊(duì)管理和安全操作中非常重要的一環(huán)，工具對接口的每一步操作都做詳細(xì)記錄。

• 刪除單個(gè)文檔
• 刪除單個(gè)目錄
• 批量刪除節(jié)點(diǎn)
• 編輯文檔
• 新建文檔
• 新建文件夾
• 復(fù)制文檔
• 生成文檔副本
• 改變文檔位置
• 重命名
• 導(dǎo)入導(dǎo)出
• 權(quán)限改變

除了基本的記錄以外，工具也提供非常豐富的檢索。在某些操作上面用戶可能希望獲取更加詳細(xì)的日志信息，例如：對于編輯文檔，用戶可能更希望知道具體改變了哪些內(nèi)容。工具目前在這方面的支持度有限，未來會繼續(xù)完善這塊內(nèi)容。

日志功能.png

回收站功能.png

接口預(yù)覽

工具區(qū)分接口錄入和接口預(yù)覽兩個(gè)狀態(tài)，接口錄入的目的是達(dá)到高效錄入，接口預(yù)覽的目的是達(dá)到高效檢索。和其他工具導(dǎo)出數(shù)據(jù)不同，工具在檢索和預(yù)覽方面做了一些優(yōu)化。

在實(shí)際項(xiàng)目開發(fā)的時(shí)候，聯(lián)調(diào)人員更關(guān)心某某人修改的最近幾條數(shù)據(jù)，通過過濾條件能夠非常高效的進(jìn)行數(shù)據(jù)檢索。

支持豐富的過濾條件.png

相對于表格形式的json展示，下面這種呈現(xiàn)形式對開發(fā)人員來說是非常友好的。

帶備注信息的json展示.png

Mock功能

可以使用Mock功能來進(jìn)行快速開發(fā)，和大部分接口工具一樣我們支持Mock.js語法，同時(shí)我們簡化了整個(gè)mock過程你無需做任何額外的配置。工具會在本地啟動一個(gè)Mock服務(wù)器，你可以簡單的把這個(gè)服務(wù)器當(dāng)作后端的服務(wù)器。

mock.gif

受瀏覽器限制，僅客戶端可以啟動Mock服務(wù)器

自動化測試

非常遺憾，目前還不支持這個(gè)功能，不過我們已經(jīng)開始開發(fā)這個(gè)非常重要的功能了。

二次開發(fā)&部署

客戶端技術(shù)棧

• Vue
• ElementUI
• Electron

服務(wù)端技術(shù)棧

• Egg.js
• MongoDB

目前開源類的接口工具大都只提供使用以及部署文檔，二次開發(fā)對于用戶來說會比較困難。為了延長項(xiàng)目壽命，同時(shí)也為了吸引更多開發(fā)者參與，我們把完善開發(fā)文檔和產(chǎn)品設(shè)計(jì)思路作為了最重要的開發(fā)任務(wù)之一。由于項(xiàng)目本身的復(fù)雜性，完善的開發(fā)文檔將會占據(jù)大量的開放時(shí)間，文檔會有一定的滯后性。

產(chǎn)品設(shè)計(jì)思路
開發(fā)文檔
部署文檔

總結(jié)

我們希望給正在尋找接口管理工具的用戶多提供一種選擇，同時(shí)也不斷完善產(chǎn)品設(shè)計(jì)和開發(fā)文檔，希望吸引更多的人參與到項(xiàng)目中來。