得物API一站式協作平臺探索與落地

1. 現狀

API文件作為公司研發重要的資料資產，承載了公司核心的業務邏輯，隨著公司業務的複雜化，軟體架構微服務化，公司數字化的發展，API的研發管理成為了公司研發的最重要的一個環節，而得物目前存在兩個介面文件相關的平臺：

• 文件管理平臺-YApi

基於開源的YApi平臺，提供基礎的API管理能力。

• 資料Mock平臺-Mooncake

Mooncake 平臺為前端和客戶端提供零侵入、場景化的Mock服務。

2. 面臨的問題

根據行業報告顯示，開發團隊大概有50%的工作時間是圍繞著API開展的，目前在得物的研發流程中，圍繞API文件的協同工作分散在不同的工具或者平臺，導致現有的API在研發協同工作中低效流轉。

• API 文件資源利用率低

YApi作為現有的文件管理平臺，過度的管控、複雜的互動和混亂的分類導致現有的文件利用率非常低。根據資料統計，大部分的使用場景為上傳文件、確認文件等。

• API 文件質量無法保障

由於YApi文件管理平臺缺乏文件的最終測試環節，導致介面在後期改動環節，並不能及時同步到文件平臺，最終無法保障文件的統一性和質量。

• 圍繞 API 研發 流程割裂

在介面的整個研發生命週期中（設計-開發/Mock-聯調-驗收），涉及到服務端、前端/客戶端、測試多個角色，跨越YApi、Mooncake、測試平臺等多個平臺。

3. 業務思考

優質的API能夠進一步的提升團隊的研發效率，進而達到降本提效的效果。那麼在這樣的背景下，解決團隊之間API的內部流轉，解決前後端基於文件的工作對接，提升文件的研發利用率和文件質量成為了平臺升級的核心問題。因此，文件和測試便成了核心環節，基於這樣的思考，我們提出了文件驅動和測試驅動兩個核心點，最終驅動整個研發流程的運轉。

• 文件驅動： 服務端完成介面文件、測試用例，前端、客戶端能夠通過介面文件瞭解介面定義以及應該如何跟介面進行互動，各職能團隊參照 API 文件獨立完成需求研發。

• 測試驅動 ：每個迭代，交付的介面文件都通過測試保證文件質量，對於測試不通過的文件，則要持續的改進，最終保證文件交付。

基於文件驅動和測試驅動，我們提出了 DTDD ( Document & Test Driven Development ) 研發模式，通過對DTDD模式的探索，打通了整個研發流程，實現了研發流程的閉環。

在DTDD模式下，平臺要做的事情也就很清楚了：

• 沉澱 API 資料資產 ：沉澱具備業務價值分類的API介面文件資產，產生規模化業務價值。

• 測試驅動 開發 ：同步自動化測試平臺針對API的測試用例，提高API交付的質量。

• 實現資料Mock ：基於API的資料Mock，提升前端、客戶端的研發效率。

• 豐富文件能力 ：圍繞 API 的使用場景，提供文件型別轉換，介面除錯能力。

• 降低溝通成本 ：基於訊息通知機制，降低溝通噪音和資訊複雜性，產品平臺價值。

4. 解決方案

明確了DTDD研發模式的目標之後，接下來就是要如何去做了，通過對業界主流的API文件管理方案的調研，結合得物目前的現有平臺YApi和Mooncake，我們最終決定打通兩個平臺，同時對功能進行了升級。平臺的架構如下圖所示：

Mooncake平臺的研發並不是一蹴而就的，下面我們從資料分類治理、提升文件利用率、提升介面交付質量、降低使用者溝通成本、降低平臺使用難度五個方面講述一下Mooncake研發過程中的一些思考。

4.1 資料分類治理

分類/分組從本質上，尋找事物的共同點和不同點，是我們認識和理解世界的基礎方法和能力，合理的分類/分組可以幫我們更好的理解事物的共同點，幫助我們判斷、推理，最終才能形式概念做出決策。

YApi原有專案分組和文件分類比較混亂，API文件作為業務資產不能很好的幫助研發理解業務，無法做到很好的提效，為了更好的輔助推動業務研發迭代效率，我們廢除了原來的專案分組和文件分類，如何進行合理的專案分組和文件分類成了面臨的問題。

• 專案分組：

最初我們想到的是按照公司組織架構對現有的專案文件進行分組，但是由於組織架構存在頻繁調整的問題，通過調研我們發現與專案緊密關聯的RDC 業務域相對穩定，最終我們將專案文件和業務域關聯，將現有的專案文件按照業務域進行劃分。

我們獲取專案最新上傳的十個介面，獲取介面的維護人員，查詢維護人員的歸屬業務域，通過計算不同業務域的權重，將專案按照計最大的業務域權重劃分業務域分組。

示例：

記人員為A， 下面所獲取的業務線為{[a, 80],[b,60], [c,10], [d, 5]}

記人員為B，下面所獲取的業務線為{[a, 60],[b,30], [e,10]}

// 業務線a
weight_a = (80+60)/2 = 70
// 業務線b
weight_b = (60+30)/2 = 45
// 業務線c
weight_c = (10+0)/2 = 5
// 業務線d
weight_d = (5+0)/2 = 2.5
// 業務線e
weight_e = (10+0)/2 = 5


weight_a > weight_b > weight_c = weight_e > weight_d

通過對專案資料的清洗，對YApi原有的專案進行了業務域的劃分歸屬，也達到了一下目的：

• 通過對專案進行業務域的分組，可以更清晰的獲取專案的相關業務屬性。

• 預設選中使用者歸屬業務域，降低使用者獲取資訊成本。

• 介面 分類：

YApi 平臺介面分類管理能力較弱，隨著文件和分類的增多，文件的可維護性逐漸變差，文件和業務的關係也逐漸削弱。例如在大型專案中，上千的介面，數百的分類目錄，文件的分類管理已經失去了原有的能力。

最初介面的分類治理方案：

1. 手動建立分類，並維護一個類目對映關係，外掛依然使用原來的上傳邏輯。

缺點：需要頻繁維護類目之間的關係，後期維護成本高。

b. 使用貝葉斯演算法，根據服務、介面名稱、介面路徑等構建分類關係。

缺點：分類效果不明確，需要不定期篩選、維護不準確分類的介面。

通過對後端團隊的調研，對現有的介面分類能力進行了以下的優化升級：

• 廢棄原來的分類，提供多級分類的能力。

• 支援原有資料的批量分類能力。

通過為使用者提供靈活的多級分類能力，使得介面分類具備更深層次的業務能力，對於專案文件資產的沉澱，起到了很好了幫助。例如在門店專案中，我們能很清晰的理解介面的業務能力，如圖所示：

4.2 提升文件利用率

• 基於文件的資料Mock

圍繞API文件前後端的對接，自然離不開資料Mock。根據文件欄位，平臺提供了一鍵Mock功能，依據文件欄位，可以生成更精準的Mock資料，例如image、time、name、city等生成相關的資料。除此之外，我們提供更強大的Mock功能：

• Mock空間的資料隔離 ： 通過提供更靈活的私有場景集，和更穩定的公有場景集，保證了Mock資料的安全性和資料隔離。

• Mock 介面 的多場景： 同個介面提供不同的資料Mock場景，使用者可以自己定義Mock場景資料，例如404場景，支付成功場景等，一鍵啟用場景或者切換場景。

• Mock外掛的零侵入： 目前市面上常見的Mock服務，要麼自己在業務程式碼中編寫Mock資料，要麼提供的外掛侵入工程的業務程式碼，Mooncake平臺基於Chrome外掛提供零程式碼侵入Mock功能。

• 基於文件的 除錯 能力

目前對於介面的除錯，大家還是常用Postman進行除錯，配置URL和引數的過程還是比較麻煩的，文件變更之後，還不能及時的進行改變。Mooncake基於現有的文件資料，提供了除錯功能，免去了配置出入參的麻煩，主要特性如下：

• 支援多環境配置： 使用者可以提前配置多套執行除錯環境，例如開發，測試，生產等多種環境，一鍵切換除錯環境。

• 免登陸配置： 通過賬號的配置，可以自動獲取token，解決除錯獲取token的問題。

• 公共引數配置： 配置公有header引數，減少介面配置次數，節約配置時間成本。

• 除錯 場景 ： 支援遠端除錯和本地除錯。

• 基於文件的轉換能力

YApi提供的文件轉換能力較弱，無法判斷欄位的是否必填，在對前端的調研中，發現大家現有的轉換能力不滿意，導致功能的使用率較低，然而文件的轉換能力在前端的使用過程中是個高頻功能，手動轉換比較浪費時間，因此我們豐富了文件的轉換能力。

• 多文件型別支援： 支援多種文件型別的資料轉換，包括Schema 、JSON、Raw 型別等。

• 更精準的欄位定義 ： 根據欄位的是否必填，在 TypeScript 中直接轉換欄位是否可選。

• 更多語言的支援： 目前支援型別宣告轉換為TypeScript 、Java 、Swift 、Go 、Kotlin 、Dart 等。

通過豐富基於文件的內容和功能， Mooncake 平臺提升了文件的利用率。 在Mooncake平臺推進的最近三個迭代，同比原有的YApi， 人均 PV 提升2倍，使用時長提升23倍。

4.3 提升介面交付質量

DTDD最重要的一個核心測試驅動，通過介面文件的測試，保證文件的交付質量。在Mooncake平臺，將介面文件的資料同步到自動化測試平臺，測試編寫介面的測試用例，Mooncake平臺將測試用例同步過來，開發在交付文件前，可以通過跑測試用例，確保介面的交付質量。

開發可以在Mooncake檢視當前用例的引數設定，同時也可以執行用例檢視用例執行結果，如下圖所示：

4.4 降低使用者溝通成本

整個研發流程圍繞API文件的生命週期進行，因為牽涉到不同的職能角色(前端，後端，測試，客戶端)等，所以介面的變更會影響到整個研發鏈路。圍繞介面變更的頻繁溝通，或者由於介面變更沒有及時通知到其他角色，影響整個研發進展的事情時常發生，基於這樣的考慮，我們增加了以下特性：

• 介面 訂閱： 通過訂閱關心的介面，可以實時收到介面的變化通知，一鍵檢視介面變更。

• 歷史版本： 平臺記錄了介面變更的歷史版本，可以很方便的檢視當前版本與歷史版本的區別。

• 群訊息通知： 平臺增加了基於webhook的群訊息通知功能，專案介面文件的增刪改變化都能收到機器人的通知。

4.5 降低平臺使用難度

子曰：工欲善其事，必先利其器。工具的重要性不言而喻。為了使得平臺使用起來更方便，提升工作效率，我們配套Mooncake平臺，提供瞭如下的工具鏈：

• 前端工具：抽離前端代理SDK，服務與不同專案配置的代理外掛，包含Webpack外掛 、Vite外掛、Umi外掛、Chrome外掛等。如圖所示：

• 後端工具：

• IDEA外掛：提供互動式IDEA外掛，降低程式碼侵入，增強對文件分類的約束。

• Go命令列工具：基於社群的Go文件生成工具，將Yaml檔案一鍵上傳到指定專案。

• 本地除錯工具：提供本地除錯工具Chrome外掛，解決本地除錯跨域問題。

通過對DTDD模式的探索和思考，最終完成了得物一站式文件協作平臺的自主研發，Mooncake一站式文件協作平臺的上線只是起點，絕不是終點，對於文件平臺的展望如下圖所示，通過文件協作平臺的建設，推動業務發展，進而實現產生經濟價值的目的。

• API Tools: 圍繞API提供基本的功能，例如介面文件、介面測試、資料Mock等。

• API Solution: 圍繞API的一些功能，為研發提供解決方案，如研發流程的管理、API的快速生成等。

• API Economy:   基於API的擴充套件性方案，產生規模化的效益。

5. 總結&思考

本文簡要給大家介紹了Mooncake作為得物一站式研發協作平臺的演進過程。平臺的整合需要深度思考整合前的現狀以及最終要解決的問題，對於最終想要的產品，首先要進行充足的調研，充分了解使用者目前的痛點，做到調研先行，明確目的，本著提出問題、解決問題的核心，打磨好每個細節、每個功能。

目前Mooncake平臺已經實現文件的管理功能，後續平臺的方向我們也在規劃：完善Dubbo協議的支援和除錯；定時掃描程式碼，實現文件的自動化更新；豐富文件依賴的上游資訊，做到變更通知；介面編排實現業務資料的組裝等。

*文 /migor

關注得物技術，每週一三五晚18:30更新技術乾貨

要是覺得文章對你有幫助的話，歡迎評論轉發點贊～