開源位址
https://github.com/XiaoMi/mone/tree/master/miapi-all/mi-api
背景
目前軟體技術領域生态豐富，各類産品與技術蓬勃發展。網際網路行業目前主流技術架構普遍基于微服務的協作式研發。在微服務研發的協作體系中，微服務接口文檔、測試、Mock等相關協作環節的自動化、智能化能力是決定研發傳遞效率的關鍵一環，MiApi 則用于改善，填補該環節的空缺與不足。
什麼是MiApi
市面上第一款內建了多類型 RPC 接口自動化管理、自動化文檔生成、接口測試、mock、團隊文檔等功能子產品的一站式平台。重新定義了微服務接口的開發傳遞流程，緻力于提供最好的接口治理服務，更大程度提高開發效率。并已取得相關軟體著作權《Mi-Api一站式微服務接口維護平台》與相關技術專利《一種基于注解的RPC接口文檔自動生成技術》。
- 我們面臨的問題
- 之是以決定立項做這件事兒是因為我們的業務研發在服務接口傳遞時切實的存在幾個痛點：
- 極高的接口對接成本
對多種協定（如Dubbo、Grpc）微服務接口開發文檔生成能力缺失，人工撰寫文檔極度耗費開發人員人力、時間、精力，版本難以控制、修改難以追溯，接口改動/協同成本極高。
- 互相阻塞的調試過程
微服務接口開發過程中缺乏測試/調試工具，提供方與使用方之間無法提前 mock 資料，互相阻塞開發進度。
- 持續傳遞能力的缺失
接口/項目文檔管理混亂，缺乏較好的聚合、持續傳遞以及長期維護能力。
而市面上目前主流的幾款接口管理軟體如 YApi、Swagger、Postman等等...幾乎都無法兼顧我們面臨的這幾項痛點，對于多協定，自動化生成的支援都較為薄弱。
基于以上痛點，我們決定自主設計、研發一套完整的、更加自動化、流程化、智能化的解決方案，以下本文将對項目進行詳細介紹，以及對于一些痛點問題我們是如何解決、如何設計的。
核心流程與能力
- 核心流程
- 為了做到整個服務接口傳遞過程 90% 以上的自動化，我們設計了一套基于注解的線上接口定義傳遞流程，即研發人員将在服務接口的定義階段，根據自身需求為需要對外提供能力的接口添加基礎注解說明，完成接口定義後，運作服務，在平台中即可直接搜尋選取自身服務，加載儲存。由于目前主流微服務項目大多基于Java下的 Spring/Springboot 架構，是以本項目方案主要針對 spring 架構項目。當然，我們同樣支援以手動方式來添加維護接口。
- 儲存過程中平台将基于自動解析擷取的接口的基本資訊以及研發人員自定義的選項說明等生成該接口的基本示例、mock資料等等。同時，在加載儲存後即可直接使用生成的請求用例來調試相應接口，或者進行接口mock。
- 主要流程如圖：
核心流程圖
- 核心能力
- 對于整個平台而言我們重點提供了以下幾項較為核心的能力：
- 多協定服務接口支援
- 平台提供了對 Http/Https、Dubbo、Grpc 等 RPC 協定類型接口的配置維護的支援。 包括但不限于對各種協定類型接口文檔的自動化生成、接口 mock 資料的自動化生成與自定義、接口的遠端調試等。
- 對于在項目中已添加依賴，注解的服務，皆可在平台中直接搜尋選取加載（加載過程将進行自動化的文檔資料生成）。
平台使用示例
一鍵測試與mock
對于以上支援的協定類型下的服務接口，在平台中都支援使用平台生成的用例資料直接進行調用、調試。同時，平台也将對維護的接口生成相應的 mock 資料與調用mock的位址。
快速分享
項目中維護的接口可以通過自定義聚合集合的方式生成接口集合連結分享給調用方，同時也支援直接生成 pdf格式檔案進行轉發。
技術與架構
上述介紹了接入平台的核心流程與平台提供的核心功能，以下将對平台的整體設計以及一些核心能力的技術方案做詳細說明。
整體架構
技術架構圖
- 服務接口資訊的加載生成
- 對于不同協定類型的接口，我們關心的接口資訊可能不完全一緻。對Http來說，我們可能需要關注該接口的url路徑、請求方式、出入參數等。而對于Dubbo接口來說，我們可能更關注該接口的服務名、方法名、出入參類型、服務版本、分組等。總體而言，對于大多數服務接口，接口的入口、出入參這些資訊都是我們需要關心的，而這些資料的擷取則需要對業務項目從接口層、方法層、參數層進行解析。
- 是以，我們針對不同的協定類型的服務項目提供了相應的解析包，在服務運作後，通過可選的開關選項，決定是否對項目進行掃描解析，若啟用，則在業務項目 spring 容器整體初始化完成之後，觸發掃描器（掃描器的具體設計實作将在後續進行介紹），對項目服務、接口、參數等進行掃描解析，并緩存解析資料。
- 項目資料掃描解析完成後，元件将把緩存的資料推送至主體平台，平台根據一定規則存儲這些接口資料，進而業務研發人員即可在平台中搜尋相應服務資料，根據自身需要選擇、加載、生成指定的服務、接口文檔。
接口加載流程圖
- 維護接口的調試與Mock
- 除了生成服務的接口文檔之外，在開發過程中，研發人員還需要對指定的接口進行 mock 或調用測試。
- 關于調試，在接口文檔的生成過程中，平台将根據解析到的接口基本資料生成一些請求示例、請求參數用例等，這些資料在文檔中都會展現。研發人員可以在不進行任何額外配置與參數編寫的情況下，通過平台的測試引擎，對不同協定類型接口直接進行調用，對于不同協定類型的接口調用底層實作方式有所差別，具體如下圖所示：
- 測試的流程圖
- 對于 mock 來說，不同協定接口的mock也有所差別。例如 http/https 協定的接口，平台将直接生成該接口的 mockUrl，調用方直接調用該 url 即可擷取該接口的 mock 資料。而對于 dubbo 服務接口來說，調用方一般基于服務方提供的 api 包進行調用，是以需要進行特殊處理攔截轉發 dubbo 調用請求，擷取平台生成的 mock 資料，整體如下圖所示：
- 接口mock流程圖
- 是以，為了實作上述描述的功能，平台整體将由提供給業務項目引用的依賴包、互動平台、Mock伺服器幾個元件構成。
核心元件
- 業務依賴包
- 為了擷取上述我們所需的業務項目接口的基本資料，我們需要業務方引入我們提供的一套依賴包，針對不同協定接口的服務我們提供了針對性的依賴包，例如對提供 Http 接口、Dubbo接口的項目，我們分别設計提供了适配 Http、适配 Dubbo 的依賴包。這些包将用于不同協定接口資料的解析、資料推送、服務注冊等等。
- 适配不同協定的依賴包在具體解析等實作上有所差別，但整體結構基本一緻，所有包都由注解子產品（annos）、核心子產品（core）、緩存子產品（cache）構成。
- 其中，注解子產品（annos）提供了包括啟用文檔生成的開關注解、服務接口層級的定位注解、方法層級的定位描述注解以及字段層級的描述注解以上4個核心注解。具體注解的作用在技術方案的注解定義中将詳細介紹。
- 核心子產品（core）主要提供了掃描器（scanner）以及相關實作工具類。該子產品是整個MiApi的核心，它用于掃描解析業務項目接口，擷取、解析服務、接口的基本資訊如方法名、出入參等資料。具體實作同樣在技術方案中的掃描器子產品加以說明。
- 緩存子產品（cache）則用于暫存掃描器（scanner）掃描解析到的基本資料，用于後期的資料推送等。
- 主體平台
- 主體平台是使用者互動的入口平台項目，它提供了一些基本的包括團隊管理、接口管理、文檔管理、接口資料生成、多協定接口測試等子產品功能。當然，平台最重要的能力是承接來自各地、各方業務項目的資料推送，包括業務的心跳注冊（用于實時線上資料，技術方案中将做介紹）、接口基本資料推送，并基于接收到的這些基本資料生成例如請求用例、mock資料等等，并将生成好的資料以一定規範組織聚合成對使用者友好的文檔頁面内容。
- Mock伺服器
- Mock伺服器是較為獨立的一個子產品，它的主要功能是接收存儲平台基于接口資料生成的、或者研發人員自定義的mock資料，以及承接來自各方的mock請求，根據請求的路徑、參數、以及一定的規則進行比對最終傳回指定接口的mock資料。對于不同協定接口的 mock 調用邏輯不完全一緻，具體将在技術方案中的Mock資料生成與調用攔截中進行介紹。
總結
本文介紹了關于 MiApi 項目的研發背景、平台提供的主要流程與能力以及一些核心能力的設計思考，關于本項目更多的技術細節與實作我們将在後續文章中陸續進行分享。