1. 現(xiàn)狀
API文檔作為公司研發(fā)重要的數(shù)據(jù)資產(chǎn)，承載了公司核心的業(yè)務(wù)邏輯，隨著公司業(yè)務(wù)的復(fù)雜化，軟件架構(gòu)微服務(wù)化，公司數(shù)字化的發(fā)展，API的研發(fā)管理成為了公司研發(fā)的最重要的一個(gè)環(huán)節(jié)，而得物目前存在兩個(gè)接口文檔相關(guān)的平臺(tái)：
- 文檔管理平臺(tái)-YApi
基于開源的YApi平臺(tái)，提供基礎(chǔ)的API管理能力。
- 數(shù)據(jù)Mock平臺(tái)-Mooncake
Mooncake 平臺(tái)為前端和客戶端提供零侵入、場(chǎng)景化的Mock服務(wù)。
2. 面臨的問題
根據(jù)行業(yè)報(bào)告顯示，開發(fā)團(tuán)隊(duì)大概有50%的工作時(shí)間是圍繞著API開展的，目前在得物的研發(fā)流程中，圍繞API文檔的協(xié)同工作分散在不同的工具或者平臺(tái)，導(dǎo)致現(xiàn)有的API在研發(fā)協(xié)同工作中低效流轉(zhuǎn)。
- API文檔資源利用率低
YApi作為現(xiàn)有的文檔管理平臺(tái)，過度的管控、復(fù)雜的交互和混亂的分類導(dǎo)致現(xiàn)有的文檔利用率非常低。根據(jù)數(shù)據(jù)統(tǒng)計(jì)，大部分的使用場(chǎng)景為上傳文檔、確認(rèn)文檔等。
- API文檔質(zhì)量無法保障
由于YApi文檔管理平臺(tái)缺乏文檔的最終測(cè)試環(huán)節(jié)，導(dǎo)致接口在后期改動(dòng)環(huán)節(jié)，并不能及時(shí)同步到文檔平臺(tái)，最終無法保障文檔的統(tǒng)一性和質(zhì)量。
- 圍繞API研發(fā)流程割裂
在接口的整個(gè)研發(fā)生命周期中（設(shè)計(jì)-開發(fā)/Mock-聯(lián)調(diào)-驗(yàn)收），涉及到服務(wù)端、前端/客戶端、測(cè)試多個(gè)角色，跨越Y(jié)Api、Mooncake、測(cè)試平臺(tái)等多個(gè)平臺(tái)。
3. 業(yè)務(wù)思考
優(yōu)質(zhì)的API能夠進(jìn)一步的提升團(tuán)隊(duì)的研發(fā)效率，進(jìn)而達(dá)到降本提效的效果。那么在這樣的背景下，解決團(tuán)隊(duì)之間API的內(nèi)部流轉(zhuǎn)，解決前后端基于文檔的工作對(duì)接，提升文檔的研發(fā)利用率和文檔質(zhì)量成為了平臺(tái)升級(jí)的核心問題。因此，文檔和測(cè)試便成了核心環(huán)節(jié)，基于這樣的思考，我們提出了文檔驅(qū)動(dòng)和測(cè)試驅(qū)動(dòng)兩個(gè)核心點(diǎn)，最終驅(qū)動(dòng)整個(gè)研發(fā)流程的運(yùn)轉(zhuǎn)。
- 文檔驅(qū)動(dòng)： 服務(wù)端完成接口文檔、測(cè)試用例，前端、客戶端能夠通過接口文檔了解接口定義以及應(yīng)該如何跟接口進(jìn)行交互，各職能團(tuán)隊(duì)參照API文檔獨(dú)立完成需求研發(fā)。
- 測(cè)試驅(qū)動(dòng)：每個(gè)迭代，交付的接口文檔都通過測(cè)試保證文檔質(zhì)量，對(duì)于測(cè)試不通過的文檔，則要持續(xù)的改進(jìn)，最終保證文檔交付。
基于文檔驅(qū)動(dòng)和測(cè)試驅(qū)動(dòng)，我們提出了DTDD ( Document & Test Driven Development ) 研發(fā)模式，通過對(duì)DTDD模式的探索，打通了整個(gè)研發(fā)流程，實(shí)現(xiàn)了研發(fā)流程的閉環(huán)。
在DTDD模式下，平臺(tái)要做的事情也就很清楚了：
- 沉淀API數(shù)據(jù)資產(chǎn)：沉淀具備業(yè)務(wù)價(jià)值分類的API接口文檔資產(chǎn)，產(chǎn)生規(guī)?；瘶I(yè)務(wù)價(jià)值。
- 測(cè)試驅(qū)動(dòng)開發(fā)：同步自動(dòng)化測(cè)試平臺(tái)針對(duì)API的測(cè)試用例，提高API交付的質(zhì)量。
- 實(shí)現(xiàn)數(shù)據(jù)Mock：基于API的數(shù)據(jù)Mock，提升前端、客戶端的研發(fā)效率。
- 豐富文檔能力：圍繞API的使用場(chǎng)景，提供文檔類型轉(zhuǎn)換，接口調(diào)試能力。
- 降低溝通成本：基于消息通知機(jī)制，降低溝通噪音和信息復(fù)雜性，產(chǎn)品平臺(tái)價(jià)值。
4. 解決方案
明確了DTDD研發(fā)模式的目標(biāo)之后，接下來就是要如何去做了，通過對(duì)業(yè)界主流的API文檔管理方案的調(diào)研，結(jié)合得物目前的現(xiàn)有平臺(tái)YApi和Mooncake，我們最終決定打通兩個(gè)平臺(tái)，同時(shí)對(duì)功能進(jìn)行了升級(jí)。平臺(tái)的架構(gòu)如下圖所示：
Mooncake平臺(tái)的研發(fā)并不是一蹴而就的，下面我們從數(shù)據(jù)分類治理、提升文檔利用率、提升接口交付質(zhì)量、降低用戶溝通成本、降低平臺(tái)使用難度五個(gè)方面講述一下Mooncake研發(fā)過程中的一些思考。
4.1 數(shù)據(jù)分類治理
分類/分組從本質(zhì)上，尋找事物的共同點(diǎn)和不同點(diǎn)，是我們認(rèn)識(shí)和理解世界的基礎(chǔ)方法和能力，合理的分類/分組可以幫我們更好的理解事物的共同點(diǎn)，幫助我們判斷、推理，最終才能形式概念做出決策。
YApi原有項(xiàng)目分組和文檔分類比較混亂，API文檔作為業(yè)務(wù)資產(chǎn)不能很好的幫助研發(fā)理解業(yè)務(wù)，無法做到很好的提效，為了更好的輔助推動(dòng)業(yè)務(wù)研發(fā)迭代效率，我們廢除了原來的項(xiàng)目分組和文檔分類，如何進(jìn)行合理的項(xiàng)目分組和文檔分類成了面臨的問題。
- 項(xiàng)目分組：
最初我們想到的是按照公司組織架構(gòu)對(duì)現(xiàn)有的項(xiàng)目文檔進(jìn)行分組，但是由于組織架構(gòu)存在頻繁調(diào)整的問題，通過調(diào)研我們發(fā)現(xiàn)與項(xiàng)目緊密關(guān)聯(lián)的RDC 業(yè)務(wù)域相對(duì)穩(wěn)定，最終我們將項(xiàng)目文檔和業(yè)務(wù)域關(guān)聯(lián)，將現(xiàn)有的項(xiàng)目文檔按照業(yè)務(wù)域進(jìn)行劃分。
我們獲取項(xiàng)目最新上傳的十個(gè)接口，獲取接口的維護(hù)人員，查詢維護(hù)人員的歸屬業(yè)務(wù)域，通過計(jì)算不同業(yè)務(wù)域的權(quán)重，將項(xiàng)目按照計(jì)最大的業(yè)務(wù)域權(quán)重劃分業(yè)務(wù)域分組。
示例：
記人員為A， 下面所獲取的業(yè)務(wù)線為{[a, 80],[b,60], [c,10], [d, 5]}
記人員為B，下面所獲取的業(yè)務(wù)線為{[a, 60],[b,30], [e,10]}
// 業(yè)務(wù)線a
weight_a = (80+60)/2 = 70
// 業(yè)務(wù)線b
weight_b = (60+30)/2 = 45
// 業(yè)務(wù)線c
weight_c = (10+0)/2 = 5
// 業(yè)務(wù)線d
weight_d = (5+0)/2 = 2.5
// 業(yè)務(wù)線e
weight_e = (10+0)/2 = 5
weight_a > weight_b > weight_c = weight_e > weight_d
通過對(duì)項(xiàng)目數(shù)據(jù)的清洗，對(duì)YApi原有的項(xiàng)目進(jìn)行了業(yè)務(wù)域的劃分歸屬，也達(dá)到了以下目的：
- 通過對(duì)項(xiàng)目進(jìn)行業(yè)務(wù)域的分組，可以更清晰的獲取項(xiàng)目的相關(guān)業(yè)務(wù)屬性。
- 默認(rèn)選中用戶歸屬業(yè)務(wù)域，降低用戶獲取信息成本。
-
接口分類：
YApi 平臺(tái)接口分類管理能力較弱，隨著文檔和分類的增多，文檔的可維護(hù)性逐漸變差，文檔和業(yè)務(wù)的關(guān)系也逐漸削弱。例如在大型項(xiàng)目中，上千的接口，數(shù)百的分類目錄，文檔的分類管理已經(jīng)失去了原有的能力。
最初接口的分類治理方案：
a. 手動(dòng)創(chuàng)建分類，并維護(hù)一個(gè)類目映射關(guān)系，插件依然使用原來的上傳邏輯。
缺點(diǎn)：需要頻繁維護(hù)類目之間的關(guān)系，后期維護(hù)成本高。
b. 使用貝葉斯算法，根據(jù)服務(wù)、接口名稱、接口路徑等構(gòu)建分類關(guān)系。
缺點(diǎn)：分類效果不明確，需要不定期篩選、維護(hù)不準(zhǔn)確分類的接口。
通過對(duì)后端團(tuán)隊(duì)的調(diào)研，對(duì)現(xiàn)有的接口分類能力進(jìn)行了以下的優(yōu)化升級(jí)：
- 廢棄原來的分類，提供多級(jí)分類的能力。
- 支持原有數(shù)據(jù)的批量分類能力。
通過為用戶提供靈活的多級(jí)分類能力，使得接口分類具備更深層次的業(yè)務(wù)能力，對(duì)于項(xiàng)目文檔資產(chǎn)的沉淀，起到了很好了幫助。例如在門店項(xiàng)目中，我們能很清晰的理解接口的業(yè)務(wù)能力，如圖所示：
4.2 提升文檔利用率
- 基于文檔的數(shù)據(jù)Mock
圍繞API文檔前后端的對(duì)接，自然離不開數(shù)據(jù)Mock。根據(jù)文檔字段，平臺(tái)提供了一鍵Mock功能，依據(jù)文檔字段，可以生成更精準(zhǔn)的Mock數(shù)據(jù)，例如image、time、name、city等生成相關(guān)的數(shù)據(jù)。除此之外，我們提供更強(qiáng)大的Mock功能：
- Mock空間的數(shù)據(jù)隔離：通過提供更靈活的私有場(chǎng)景集，和更穩(wěn)定的公有場(chǎng)景集，保證了Mock數(shù)據(jù)的安全性和數(shù)據(jù)隔離。
- Mock接口的多場(chǎng)景： 同個(gè)接口提供不同的數(shù)據(jù)Mock場(chǎng)景，用戶可以自己定義Mock場(chǎng)景數(shù)據(jù)，例如404場(chǎng)景，支付成功場(chǎng)景等，一鍵激活場(chǎng)景或者切換場(chǎng)景。
- Mock插件的零侵入： 目前市面上常見的Mock服務(wù)，要么自己在業(yè)務(wù)代碼中編寫Mock數(shù)據(jù)，要么提供的插件侵入工程的業(yè)務(wù)代碼，Mooncake平臺(tái)基于Chrome插件提供零代碼侵入Mock功能。
- 基于文檔的調(diào)試能力
目前對(duì)于接口的調(diào)試，大家還是常用Postman進(jìn)行調(diào)試，配置URL和參數(shù)的過程還是比較麻煩的，文檔變更之后，還不能及時(shí)的進(jìn)行改變。Mooncake基于現(xiàn)有的文檔數(shù)據(jù)，提供了調(diào)試功能，免去了配置出入?yún)⒌穆闊?，主要特性如下?/p>
- 支持多環(huán)境配置： 用戶可以提前配置多套運(yùn)行調(diào)試環(huán)境，例如開發(fā)，測(cè)試，生產(chǎn)等多種環(huán)境，一鍵切換調(diào)試環(huán)境。
- 免登陸配置： 通過賬號(hào)的配置，可以自動(dòng)獲取token，解決調(diào)試獲取token的問題。
- 公共參數(shù)配置： 配置公有header參數(shù)，減少接口配置次數(shù)，節(jié)約配置時(shí)間成本。
- 調(diào)試場(chǎng)景：支持遠(yuǎn)程調(diào)試和本地調(diào)試。
- 基于文檔的轉(zhuǎn)換能力
YApi提供的文檔轉(zhuǎn)換能力較弱，無法判斷字段的是否必填，在對(duì)前端的調(diào)研中，發(fā)現(xiàn)大家現(xiàn)有的轉(zhuǎn)換能力不滿意，導(dǎo)致功能的使用率較低，然而文檔的轉(zhuǎn)換能力在前端的使用過程中是個(gè)高頻功能，手動(dòng)轉(zhuǎn)換比較浪費(fèi)時(shí)間，因此我們豐富了文檔的轉(zhuǎn)換能力。
- 多文檔類型支持： 支持多種文檔類型的數(shù)據(jù)轉(zhuǎn)換，包括Schema 、JSON、Raw 類型等。
- 更精準(zhǔn)的字段定義：根據(jù)字段的是否必填，在 TypeScript 中直接轉(zhuǎn)換字段是否可選。
- 更多語言的支持： 目前支持類型聲明轉(zhuǎn)換為TypeScript 、Java 、Swift 、Go 、Kotlin 、Dart 等。
通過豐富基于文檔的內(nèi)容和功能，Mooncake平臺(tái)提升了文檔的利用率。 在Mooncake平臺(tái)推進(jìn)的最近三個(gè)迭代，同比原有的YApi，人均PV提升2倍，使用時(shí)長(zhǎng)提升23倍。
4.3 提升接口交付質(zhì)量
DTDD最重要的一個(gè)核心測(cè)試驅(qū)動(dòng)，通過接口文檔的測(cè)試，保證文檔的交付質(zhì)量。在Mooncake平臺(tái)，將接口文檔的數(shù)據(jù)同步到自動(dòng)化測(cè)試平臺(tái)，測(cè)試編寫接口的測(cè)試用例，Mooncake平臺(tái)將測(cè)試用例同步過來，開發(fā)在交付文檔前，可以通過跑測(cè)試用例，確保接口的交付質(zhì)量。
開發(fā)可以在Mooncake查看當(dāng)前用例的參數(shù)設(shè)置，同時(shí)也可以運(yùn)行用例查看用例執(zhí)行結(jié)果，如下圖所示：
4.4 降低用戶溝通成本
整個(gè)研發(fā)流程圍繞API文檔的生命周期進(jìn)行，因?yàn)闋可娴讲煌穆毮芙巧?前端，后端，測(cè)試，客戶端)等，所以接口的變更會(huì)影響到整個(gè)研發(fā)鏈路。圍繞接口變更的頻繁溝通，或者由于接口變更沒有及時(shí)通知到其他角色，影響整個(gè)研發(fā)進(jìn)展的事情時(shí)常發(fā)生，基于這樣的考慮，我們?cè)黾恿艘韵绿匦裕?/p>
- 接口訂閱： 通過訂閱關(guān)心的接口，可以實(shí)時(shí)收到接口的變化通知，一鍵查看接口變更。
- 歷史版本： 平臺(tái)記錄了接口變更的歷史版本，可以很方便的查看當(dāng)前版本與歷史版本的區(qū)別。
- 群消息通知： 平臺(tái)增加了基于webhook的群消息通知功能，項(xiàng)目接口文檔的增刪改變化都能收到機(jī)器人的通知。
4.5 降低平臺(tái)使用難度
子曰：工欲善其事，必先利其器。工具的重要性不言而喻。為了使得平臺(tái)使用起來更方便，提升工作效率，我們配套Mooncake平臺(tái)，提供了如下的工具鏈：
- 前端工具： 抽離前端代理SDK，服務(wù)與不同項(xiàng)目配置的代理插件，包含Webpack插件 、Vite插件、Umi插件、Chrome插件等。如圖所示：
-
后端工具：
- IDEA插件：提供交互式IDEA插件，降低代碼侵入，增強(qiáng)對(duì)文檔分類的約束。
- Go命令行工具：基于社區(qū)的Go文檔生成工具，將Yaml文件一鍵上傳到指定項(xiàng)目。
- 本地調(diào)試工具：提供本地調(diào)試工具Chrome插件，解決本地調(diào)試跨域問題。
通過對(duì)DTDD模式的探索和思考，最終完成了得物一站式文檔協(xié)作平臺(tái)的自主研發(fā)，Mooncake一站式文檔協(xié)作平臺(tái)的上線只是起點(diǎn)，絕不是終點(diǎn)，對(duì)于文檔平臺(tái)的展望如下圖所示，通過文檔協(xié)作平臺(tái)的建設(shè)，推動(dòng)業(yè)務(wù)發(fā)展，進(jìn)而實(shí)現(xiàn)產(chǎn)生經(jīng)濟(jì)價(jià)值的目的。
- 基本功能: 圍繞API提供基本的功能，例如接口文檔、接口測(cè)試、數(shù)據(jù)Mock等
- 解決方案: 圍繞API的一些功能，為研發(fā)提供解決方案，如研發(fā)流程的管理、API的快速生成、接口編排、依賴信息變更等
- 降本提效: 基于API的擴(kuò)展性方案，體驗(yàn)研發(fā)流程效率，降低生產(chǎn)成本，推動(dòng)業(yè)務(wù)發(fā)展
5. 總結(jié)&思考
本文簡(jiǎn)要給大家介紹了Mooncake作為得物一站式研發(fā)協(xié)作平臺(tái)的演進(jìn)過程。平臺(tái)的整合需要深度思考整合前的現(xiàn)狀以及最終要解決的問題，對(duì)于最終想要的產(chǎn)品，首先要進(jìn)行充足的調(diào)研，充分了解用戶目前的痛點(diǎn)，做到調(diào)研先行，明確目的，本著提出問題、解決問題的核心，打磨好每個(gè)細(xì)節(jié)、每個(gè)功能。
目前Mooncake平臺(tái)已經(jīng)實(shí)現(xiàn)文檔的管理功能，后續(xù)平臺(tái)的方向我們也在規(guī)劃：完善Dubbo協(xié)議的支持和調(diào)試；定時(shí)掃描代碼，實(shí)現(xiàn)文檔的自動(dòng)化更新；豐富文檔依賴的上游信息，做到變更通知；接口編排實(shí)現(xiàn)業(yè)務(wù)數(shù)據(jù)的組裝等。
*文 /migor
