開源地址

https://github.com/XiaoMi/mone/tree/master/miapi-all/mi-api

背景

目前軟件技術(shù)領(lǐng)域生態(tài)豐富，各類產(chǎn)品與技術(shù)蓬勃發(fā)展。互聯(lián)網(wǎng)行業(yè)目前主流技術(shù)架構(gòu)普遍基于微服務(wù)的協(xié)作式研發(fā)。在微服務(wù)研發(fā)的協(xié)作體系中，微服務(wù)接口文檔、測試、Mock等相關(guān)協(xié)作環(huán)節(jié)的自動化、智能化能力是決定研發(fā)交付效率的關(guān)鍵一環(huán)，MiApi 則用于改善，填補(bǔ)該環(huán)節(jié)的空缺與不足。

什么是MiApi

市面上第一款集成了多類型 RPC 接口自動化管理、自動化文檔生成、接口測試、mock、團(tuán)隊文檔等功能模塊的一站式平臺。重新定義了微服務(wù)接口的開發(fā)交付流程，致力于提供最好的接口治理服務(wù)，更大程度提高開發(fā)效率。并已取得相關(guān)軟件著作權(quán)《Mi-Api一站式微服務(wù)接口維護(hù)平臺》與相關(guān)技術(shù)專利《一種基于注解的RPC接口文檔自動生成技術(shù)》。

我們面臨的問題

??之所以決定立項(xiàng)做這件事兒是因?yàn)槲覀兊臉I(yè)務(wù)研發(fā)在服務(wù)接口交付時切實(shí)的存在幾個痛點(diǎn)：

• 極高的接口對接成本

對多種協(xié)議（如Dubbo、Grpc）微服務(wù)接口開發(fā)文檔生成能力缺失，人工撰寫文檔極度耗費(fèi)開發(fā)人員人力、時間、精力，版本難以控制、修改難以追溯，接口改動/協(xié)同成本極高。

• 互相阻塞的調(diào)試過程

微服務(wù)接口開發(fā)過程中缺乏測試/調(diào)試工具，提供方與使用方之間無法提前 mock 數(shù)據(jù)，互相阻塞開發(fā)進(jìn)度。

• 持續(xù)交付能力的缺失

接口/項(xiàng)目文檔管理混亂，缺乏較好的聚合、持續(xù)交付以及長期維護(hù)能力。

而市面上目前主流的幾款接口管理軟件如 YApi、Swagger、Postman等等...幾乎都無法兼顧我們面臨的這幾項(xiàng)痛點(diǎn)，對于多協(xié)議，自動化生成的支持都較為薄弱。

基于以上痛點(diǎn)，我們決定自主設(shè)計、研發(fā)一套完整的、更加自動化、流程化、智能化的解決方案，以下本文將對項(xiàng)目進(jìn)行詳細(xì)介紹，以及對于一些痛點(diǎn)問題我們是如何解決、如何設(shè)計的。

核心流程與能力

核心流程

??為了做到整個服務(wù)接口交付過程 90% 以上的自動化，我們設(shè)計了一套基于注解的在線接口定義交付流程，即研發(fā)人員將在服務(wù)接口的定義階段，根據(jù)自身需求為需要對外提供能力的接口添加基礎(chǔ)注解說明，完成接口定義后，運(yùn)行服務(wù)，在平臺中即可直接搜索選取自身服務(wù)，加載保存。由于目前主流微服務(wù)項(xiàng)目大多基于Java下的 Spring/Springboot 框架，因此本項(xiàng)目方案主要針對 spring 框架項(xiàng)目。當(dāng)然，我們同樣支持以手動方式來添加維護(hù)接口。

??保存過程中平臺將基于自動解析獲取的接口的基本信息以及研發(fā)人員自定義的選項(xiàng)說明等生成該接口的基本示例、mock數(shù)據(jù)等等。同時，在加載保存后即可直接使用生成的請求用例來調(diào)試相應(yīng)接口，或者進(jìn)行接口mock。

??主要流程如圖：

核心流程圖

核心能力

??對于整個平臺而言我們重點(diǎn)提供了以下幾項(xiàng)較為核心的能力：

多協(xié)議服務(wù)接口支持

??平臺提供了對 Http/Https、Dubbo、Grpc 等 RPC 協(xié)議類型接口的配置維護(hù)的支持。 包括但不限于對各種協(xié)議類型接口文檔的自動化生成、接口 mock 數(shù)據(jù)的自動化生成與自定義、接口的遠(yuǎn)程調(diào)試等。

??對于在項(xiàng)目中已添加依賴，注解的服務(wù)，皆可在平臺中直接搜索選取加載（加載過程將進(jìn)行自動化的文檔數(shù)據(jù)生成）。

平臺使用示例

一鍵測試與mock

對于以上支持的協(xié)議類型下的服務(wù)接口，在平臺中都支持使用平臺生成的用例數(shù)據(jù)直接進(jìn)行調(diào)用、調(diào)試。同時，平臺也將對維護(hù)的接口生成相應(yīng)的 mock 數(shù)據(jù)與調(diào)用mock的地址。

快速分享

項(xiàng)目中維護(hù)的接口可以通過自定義聚合集合的方式生成接口集合鏈接分享給調(diào)用方，同時也支持直接生成 pdf格式文件進(jìn)行轉(zhuǎn)發(fā)。

技術(shù)與架構(gòu)

上述介紹了接入平臺的核心流程與平臺提供的核心功能，以下將對平臺的整體設(shè)計以及一些核心能力的技術(shù)方案做詳細(xì)說明。

整體架構(gòu)

技術(shù)架構(gòu)圖

服務(wù)接口信息的加載生成

??對于不同協(xié)議類型的接口，我們關(guān)心的接口信息可能不完全一致。對Http來說，我們可能需要關(guān)注該接口的url路徑、請求方式、出入?yún)?shù)等。而對于Dubbo接口來說，我們可能更關(guān)注該接口的服務(wù)名、方法名、出入?yún)㈩愋?、服?wù)版本、分組等。總體而言，對于大多數(shù)服務(wù)接口，接口的入口、出入?yún)⑦@些信息都是我們需要關(guān)心的，而這些數(shù)據(jù)的獲取則需要對業(yè)務(wù)項(xiàng)目從接口層、方法層、參數(shù)層進(jìn)行解析。

??因此，我們針對不同的協(xié)議類型的服務(wù)項(xiàng)目提供了相應(yīng)的解析包，在服務(wù)運(yùn)行后，通過可選的開關(guān)選項(xiàng)，決定是否對項(xiàng)目進(jìn)行掃描解析，若啟用，則在業(yè)務(wù)項(xiàng)目 spring 容器整體初始化完成之后，觸發(fā)掃描器（掃描器的具體設(shè)計實(shí)現(xiàn)將在后續(xù)進(jìn)行介紹），對項(xiàng)目服務(wù)、接口、參數(shù)等進(jìn)行掃描解析，并緩存解析數(shù)據(jù)。

??項(xiàng)目數(shù)據(jù)掃描解析完成后，組件將把緩存的數(shù)據(jù)推送至主體平臺，平臺根據(jù)一定規(guī)則存儲這些接口數(shù)據(jù)，從而業(yè)務(wù)研發(fā)人員即可在平臺中搜索相應(yīng)服務(wù)數(shù)據(jù)，根據(jù)自身需要選擇、加載、生成指定的服務(wù)、接口文檔。

接口加載流程圖

維護(hù)接口的調(diào)試與Mock

??除了生成服務(wù)的接口文檔之外，在開發(fā)過程中，研發(fā)人員還需要對指定的接口進(jìn)行 mock 或調(diào)用測試。

??關(guān)于調(diào)試，在接口文檔的生成過程中，平臺將根據(jù)解析到的接口基本數(shù)據(jù)生成一些請求示例、請求參數(shù)用例等，這些數(shù)據(jù)在文檔中都會體現(xiàn)。研發(fā)人員可以在不進(jìn)行任何額外配置與參數(shù)編寫的情況下，通過平臺的測試引擎，對不同協(xié)議類型接口直接進(jìn)行調(diào)用，對于不同協(xié)議類型的接口調(diào)用底層實(shí)現(xiàn)方式有所區(qū)別，具體如下圖所示：

測試的流程圖

??對于 mock 來說，不同協(xié)議接口的mock也有所區(qū)別。例如 http/https 協(xié)議的接口，平臺將直接生成該接口的 mockUrl，調(diào)用方直接調(diào)用該 url 即可獲取該接口的 mock 數(shù)據(jù)。而對于 dubbo 服務(wù)接口來說，調(diào)用方一般基于服務(wù)方提供的 api 包進(jìn)行調(diào)用，因此需要進(jìn)行特殊處理攔截轉(zhuǎn)發(fā) dubbo 調(diào)用請求，獲取平臺生成的 mock 數(shù)據(jù)，整體如下圖所示：

接口mock流程圖

??因此，為了實(shí)現(xiàn)上述描述的功能，平臺整體將由提供給業(yè)務(wù)項(xiàng)目引用的依賴包、交互平臺、Mock服務(wù)器幾個組件構(gòu)成。

核心組件

業(yè)務(wù)依賴包

??為了獲取上述我們所需的業(yè)務(wù)項(xiàng)目接口的基本數(shù)據(jù)，我們需要業(yè)務(wù)方引入我們提供的一套依賴包，針對不同協(xié)議接口的服務(wù)我們提供了針對性的依賴包，例如對提供 Http 接口、Dubbo接口的項(xiàng)目，我們分別設(shè)計提供了適配 Http、適配 Dubbo 的依賴包。這些包將用于不同協(xié)議接口數(shù)據(jù)的解析、數(shù)據(jù)推送、服務(wù)注冊等等。

??適配不同協(xié)議的依賴包在具體解析等實(shí)現(xiàn)上有所區(qū)別，但整體結(jié)構(gòu)基本一致，所有包都由注解模塊（annos）、核心模塊（core）、緩存模塊（cache）構(gòu)成。

??其中，注解模塊（annos）提供了包括啟用文檔生成的開關(guān)注解、服務(wù)接口層級的定位注解、方法層級的定位描述注解以及字段層級的描述注解以上4個核心注解。具體注解的作用在技術(shù)方案的注解定義中將詳細(xì)介紹。

??核心模塊（core）主要提供了掃描器（scanner）以及相關(guān)實(shí)現(xiàn)工具類。該模塊是整個MiApi的核心，它用于掃描解析業(yè)務(wù)項(xiàng)目接口，獲取、解析服務(wù)、接口的基本信息如方法名、出入?yún)⒌葦?shù)據(jù)。具體實(shí)現(xiàn)同樣在技術(shù)方案中的掃描器模塊加以說明。

??緩存模塊（cache）則用于暫存掃描器（scanner）掃描解析到的基本數(shù)據(jù)，用于后期的數(shù)據(jù)推送等。

主體平臺

??主體平臺是用戶交互的入口平臺項(xiàng)目，它提供了一些基本的包括團(tuán)隊管理、接口管理、文檔管理、接口數(shù)據(jù)生成、多協(xié)議接口測試等模塊功能。當(dāng)然，平臺最重要的能力是承接來自各地、各方業(yè)務(wù)項(xiàng)目的數(shù)據(jù)推送，包括業(yè)務(wù)的心跳注冊（用于實(shí)時在線數(shù)據(jù)，技術(shù)方案中將做介紹）、接口基本數(shù)據(jù)推送，并基于接收到的這些基本數(shù)據(jù)生成例如請求用例、mock數(shù)據(jù)等等，并將生成好的數(shù)據(jù)以一定規(guī)范組織聚合成對用戶友好的文檔頁面內(nèi)容。

Mock服務(wù)器

??Mock服務(wù)器是較為獨(dú)立的一個模塊，它的主要功能是接收存儲平臺基于接口數(shù)據(jù)生成的、或者研發(fā)人員自定義的mock數(shù)據(jù)，以及承接來自各方的mock請求，根據(jù)請求的路徑、參數(shù)、以及一定的規(guī)則進(jìn)行匹配最終返回指定接口的mock數(shù)據(jù)。對于不同協(xié)議接口的 mock 調(diào)用邏輯不完全一致，具體將在技術(shù)方案中的Mock數(shù)據(jù)生成與調(diào)用攔截中進(jìn)行介紹。

總結(jié)

本文介紹了關(guān)于 MiApi 項(xiàng)目的研發(fā)背景、平臺提供的主要流程與能力以及一些核心能力的設(shè)計思考，關(guān)于本項(xiàng)目更多的技術(shù)細(xì)節(jié)與實(shí)現(xiàn)我們將在后續(xù)文章中陸續(xù)進(jìn)行分享。