開源地址

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 則用于改善蛤售，填補該環(huán)節(jié)的空缺與不足。

什么是MiApi

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

我們面臨的問題

??之所以決定立項做這件事兒是因為我們的業(yè)務(wù)研發(fā)在服務(wù)接口交付時切實的存在幾個痛點：

極高的接口對接成本

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

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

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

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

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

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

基于以上痛點东囚，我們決定自主設(shè)計、研發(fā)一套完整的战授、更加自動化页藻、流程化桨嫁、智能化的解決方案，以下本文將對項目進行詳細(xì)介紹份帐，以及對于一些痛點問題我們是如何解決璃吧、如何設(shè)計的。

核心流程與能力

核心流程

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

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

??主要流程如圖：

? ???????????????????????????????????????????????????????????????????核心流程圖

核心能力

??對于整個平臺而言我們重點提供了以下幾項較為核心的能力：

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

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

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

? ??????????????????????????????????????????????????????????????????平臺使用示例

一鍵測試與mock

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

快速分享

項目中維護的接口可以通過自定義聚合集合的方式生成接口集合鏈接分享給調(diào)用方，同時也支持直接生成 pdf格式文件進行轉(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ù)項目從接口層屯掖、方法層、參數(shù)層進行解析襟衰。

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

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

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?接口加載流程圖

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

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

??關(guān)于調(diào)試，在接口文檔的生成過程中双吆，平臺將根據(jù)解析到的接口基本數(shù)據(jù)生成一些請求示例眨唬、請求參數(shù)用例等，這些數(shù)據(jù)在文檔中都會體現(xiàn)好乐。研發(fā)人員可以在不進行任何額外配置與參數(shù)編寫的情況下匾竿，通過平臺的測試引擎，對不同協(xié)議類型接口直接進行調(diào)用蔚万，對于不同協(xié)議類型的接口調(diào)用底層實現(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 包進行調(diào)用，因此需要進行特殊處理攔截轉(zhuǎn)發(fā) dubbo 調(diào)用請求梧田，獲取平臺生成的 mock 數(shù)據(jù)淳蔼，整體如下圖所示：

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?接口mock流程圖

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

核心組件

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

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

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

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

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

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

主體平臺

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

Mock服務(wù)器

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

總結(jié)

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