一、背景

Mooncake是得物API一站式協(xié)作平臺(tái)。從2022年3月份開始負(fù)責(zé)Mooncake，到現(xiàn)在已經(jīng)一年了，回顧這一年，Mooncake大的階段上，總共經(jīng)歷過兩個(gè)版本:

1、Mooncake 1.0: 面向前端和客戶端的mock平臺(tái)，主要解決接口調(diào)用者的數(shù)據(jù)mock問題

2、Mooncake 2.0: 面向前后端的，融合了yapi和mock的一站式文檔管理平臺(tái)，從供需兩端解決接口文檔的流通效率問題

升級(jí)后的Mooncake產(chǎn)品架構(gòu)如下：

如上圖所示，我們希望Mooncake是得物研發(fā)生態(tài)系統(tǒng)中的重要一環(huán)，為了實(shí)現(xiàn)這個(gè)目標(biāo)，Mooncake不斷推陳出新，發(fā)布了許多重要功能，例如支持染色環(huán)境調(diào)試、業(yè)務(wù)迭代信息報(bào)表、支持Dubbo協(xié)議的mock等；打通了RDC、EP、CMDB、網(wǎng)關(guān)等平臺(tái)。此外，Mooncake還提供了openAPI，向外生長(zhǎng)，支持EP、DOP、APM等平臺(tái)，讓開發(fā)同學(xué)在研發(fā)的各個(gè)階段都能方便的通過文檔進(jìn)行順暢的交流。

在這個(gè)過程當(dāng)中，Mooncake具體做了什么，又為什么這么做，做了之后有什么用，針對(duì)這幾個(gè)問題我簡(jiǎn)單的說一下我自己的思考。

二、一切過往 皆為序章

2002年貝索斯曾經(jīng)給亞馬遜頒布了一份mandate，這份指令是這樣的：

從今天起，所有的團(tuán)隊(duì)都要以服務(wù)接口的方式，提供數(shù)據(jù)和各種功能。

團(tuán)隊(duì)之間必須通過接口來通信。 

不允許任何其他形式的互操作：不允許直接鏈接，不允許直接讀其他團(tuán)隊(duì)的數(shù)據(jù)，不允許共享內(nèi)存，不允許任何形式的后門。

唯一許可的通信方式，就是通過網(wǎng)絡(luò)調(diào)用服務(wù)。 

具體的實(shí)現(xiàn)技術(shù)不做規(guī)定，HTTP、Corba、PubSub、自定義協(xié)議皆可。 

所有的服務(wù)接口，必須從一開始就以可以公開作為設(shè)計(jì)導(dǎo)向，沒有例外。這就是說，在設(shè)計(jì)接口的時(shí)候，就默認(rèn)這個(gè)接口可以對(duì)外部人員開放，沒有討價(jià)還價(jià)的余地。

不遵守上面規(guī)定者，一律開除。

謝謝；祝你過得愉快！

這份指令的出發(fā)點(diǎn)是，貝索斯認(rèn)為人際溝通往往會(huì)造成組織執(zhí)行不力，而他解決這個(gè)問題的方式，就是通過API，系統(tǒng)性的規(guī)范組織間的對(duì)話。

這個(gè)其實(shí)在當(dāng)下很普遍的微服務(wù)架構(gòu)之下，已經(jīng)不是什么新鮮事了，還有我們大量使用三方開放API，這些都是通過API來完成系統(tǒng)間的調(diào)用；

但是在當(dāng)時(shí)，如何讓人們接受這個(gè)方案，積極的參與進(jìn)來，同時(shí)也預(yù)防API泛濫，是個(gè)很大的問題。為此貝索斯建立了一套指標(biāo)體系，通過激勵(lì)最終形成一套正向的持續(xù)演進(jìn)和迭代循環(huán)。

這套指標(biāo)體系，我們可以理解為是一種公司或者組織層面的基建。

1934年，美國(guó)經(jīng)濟(jì)大蕭條時(shí)期，羅斯福解決經(jīng)濟(jì)危機(jī)的兩大新政之一的以工代賑，通過大興基建的方式，刺激消費(fèi)與生產(chǎn)均衡。

為什么羅斯福選擇通過基建的方式來提振經(jīng)濟(jì)，其原因跟貝索斯這套指標(biāo)體系是一樣的原因。在蘭小歡《置身事內(nèi)：中國(guó)政府與經(jīng)濟(jì)發(fā)展》一書中提到，基建有三個(gè)特點(diǎn)：

1、擴(kuò)展公共服務(wù)的規(guī)模 產(chǎn)生規(guī)模效益

2、提高信息溝通效率 降低信息復(fù)雜性

3、增強(qiáng)各方對(duì)資源的競(jìng)爭(zhēng) 產(chǎn)生激勵(lì)

由此可見，基建是可以降本增效，并且?guī)椭M織形成一個(gè)正向的循環(huán)。

2022年3月份之前，得物通過Yapi平臺(tái)，沉淀的HTTP接口有數(shù)萬個(gè)，這是過去七年間得物自然增長(zhǎng)的API數(shù)量，這已經(jīng)是一個(gè)很龐大的數(shù)字，但是在這些http接口背后，還有數(shù)量更加龐大的rpc接口散落在語雀、飛書，更有大量的接口沒有文檔沉淀，在歷史中默默發(fā)揮著余熱。

那么如何讓文檔規(guī)范起來，如何讓更多的開發(fā)同學(xué)把接口統(tǒng)一起來，如何讓數(shù)量龐大的接口文檔發(fā)揮更大的價(jià)值，Mooncake從三個(gè)方面提供服務(wù)做了一次升級(jí):

1、從單一mock服務(wù)升級(jí)為圍繞接口文檔的一站式協(xié)作平臺(tái)，用戶從前端和客戶端擴(kuò)展到服務(wù)端、測(cè)試、前端、客戶端

2、圍繞接口研發(fā)生命周期，通過插件、飛書消息、一鍵mock、一鍵配置網(wǎng)關(guān)等一系列工具，提高信息溝通效率，降低前后端溝通復(fù)雜度

3、關(guān)聯(lián)rdc提供迭代和團(tuán)隊(duì)兩個(gè)維度的數(shù)據(jù)看板，通過文檔質(zhì)量分統(tǒng)計(jì)來刺激內(nèi)部競(jìng)爭(zhēng)，進(jìn)而推動(dòng)產(chǎn)出更高效的文檔

接下來我從設(shè)計(jì)和技術(shù)兩個(gè)層面簡(jiǎn)單回顧一下Mooncake這次升級(jí)都是如何做的。

三、Mooncake的設(shè)計(jì)理念

Mooncake的升級(jí)，我們遵循了尼爾森的十大設(shè)計(jì)理念：

1、系統(tǒng)可?性原則

系統(tǒng)要在適當(dāng)?shù)臅r(shí)間內(nèi)給予用戶恰當(dāng)?shù)姆答仯冀K讓用戶知道當(dāng)前正在發(fā)生什么。                                        

——尼爾森

可以理解為包括?戶在??上的任何操作，系統(tǒng)需要給出相應(yīng)的反饋，來確保?戶在操作過程中的狀態(tài)可?、變化可?、內(nèi)容可?，從?幫助?戶將交互引導(dǎo)到正確的?向，?不會(huì)浪費(fèi)精?。

Mooncake通過按鈕、消息提示的即時(shí)反饋，來響應(yīng)用戶的操作:

2、貼近場(chǎng)景原則

系統(tǒng)要使用用戶的語言，用戶熟悉的單詞、短語和概念，而不是系統(tǒng)術(shù)語。遵循現(xiàn)實(shí)世界的約定，使信息以自然和合乎邏輯的順序出現(xiàn)。                                ——尼爾森

?戶會(huì)習(xí)慣?現(xiàn)實(shí)世界中已有認(rèn)知來看待問題，這個(gè)已有認(rèn)知是?戶根據(jù)??掌握的經(jīng)驗(yàn)、知識(shí)和想象所建?的?智模型。

Mooncake這次升級(jí)，融合了Yapi和Mock，除了技術(shù)底層在數(shù)據(jù)上的融合，交互上，也盡可能的保留了原有的交互習(xí)慣，比如通過idea上傳文檔的習(xí)慣，比如按照文檔、編輯、運(yùn)行、類型聲明去組織頁面tab:

3、可控性原則

當(dāng)用戶錯(cuò)誤地選擇了的某個(gè)功能后，系統(tǒng)需要提供一個(gè)明確的「緊急出口」，來讓用戶離開其不想要的狀態(tài)，而且無需額外的對(duì)話框，支持撤銷和重做。                                 

——尼爾森

Mooncake里，通過多tab的形式，方便用戶打開多個(gè)接口文檔，而無需頻繁的刷新頁面:

4、一致性原則

我們不應(yīng)當(dāng)讓用戶去懷疑不同的語句、狀態(tài)或操作是否在表達(dá)同一件事，設(shè)計(jì)需遵循平臺(tái)的慣例。                                       

——尼爾森

?致性可以給?戶統(tǒng)?的認(rèn)知，幫助?戶快速學(xué)習(xí)、記憶和熟悉產(chǎn)品的功能，從?建??戶穩(wěn)定的?智模型。為了保障產(chǎn)品間的?戶體驗(yàn)統(tǒng)?，通常都需要建?設(shè)計(jì)規(guī)范，來確保產(chǎn)品內(nèi)部的?致性，這里的?致性包括視覺?致性、?為?致性和感知?致性。

Mooncake這次升級(jí)，字體、顏色、尺寸布局、組件庫都遵循了得物設(shè)計(jì)體系規(guī)范:

5、錯(cuò)誤預(yù)防原則

比報(bào)錯(cuò)提示更好的方法是，通過嚴(yán)謹(jǐn)?shù)脑O(shè)計(jì)來防止錯(cuò)誤的發(fā)生：要么消除容易出錯(cuò)的情況，要么把這些容易出錯(cuò)的情況找出來，并在用戶采取行動(dòng)之前提供確認(rèn)選項(xiàng)。                                           

   ——尼爾森

當(dāng)操作不可逆時(shí)，給予?戶?次確認(rèn)的機(jī)會(huì)，避免?戶由于誤操作造成的后果:

6、系統(tǒng)識(shí)別勝過記憶

通過將對(duì)象、操作和選項(xiàng)進(jìn)行可視化，最大限度地減輕用戶的記憶負(fù)擔(dān)，用戶不需要記住對(duì)話框中某一部分到另一部分的信息，系統(tǒng)操作的指示信息需要易于被用戶發(fā)現(xiàn)和獲取。                                               

 ——尼爾森

?戶是不可能記住操作過程中的過多信息的，Mooncake提供了我的收藏和最近訪問幫助同學(xué)們快速找到自己常用的項(xiàng)目文檔:

7、使用的靈活性和效率

一些快捷操作的功能，雖然會(huì)被新手用戶忽略，但可能為專家用戶所使用并幫助提升其使用效率，因此，系統(tǒng)需要同時(shí)滿足新手用戶和專家用戶的需求，允許用戶頻繁地操作。                                              

 ——尼爾森

這?點(diǎn)其實(shí)是在B端產(chǎn)品設(shè)計(jì)中?較容易忽視的?個(gè)原則，我們往往默認(rèn)使?產(chǎn)品的是相對(duì)成熟的產(chǎn)品使?者。

Mooncake的菜單欄提供折疊和展開兩種模式，并且會(huì)記住用戶上次的選擇，對(duì)于新同學(xué)，默認(rèn)展開菜單，方便了解平臺(tái)的功能；對(duì)于已經(jīng)熟悉Mooncake 的同學(xué)可以收起菜單，文檔的可視區(qū)域最大化，方便閱讀:

8、美觀和簡(jiǎn)約設(shè)計(jì)

對(duì)話框中不應(yīng)包含無關(guān)或很少用到的信息，在對(duì)話框中每增加一個(gè)信息，就意味著降低了主要信息的相對(duì)可見性。                       

——尼爾森

Mooncake的對(duì)話框，都盡可能的降低復(fù)雜度，一次只做一件事情，一次只搜集最重要的數(shù)據(jù)，并且盡可能的提供下拉選框減少用戶輸入:

9、幫助?戶發(fā)現(xiàn)、判斷和修復(fù)錯(cuò)誤

報(bào)錯(cuò)信息應(yīng)該用通俗易懂的語言表達(dá)，而不是用代碼，準(zhǔn)確地反應(yīng)問題，并且提出可行的解決方案。                                            ——尼爾森

10、人性化幫助原則

幫助文檔的信息應(yīng)該易于被搜索，聚焦于用戶的任務(wù)，并列出具體的步驟，而且，不能太龐大。                                      

 ——尼爾森

Mooncake提供全局搜索、一鍵進(jìn)飛書答疑群、自助幫助文檔幫助同學(xué)快速的找到文檔，定位問題:

四、Mooncake的技術(shù)架構(gòu)

在這次升級(jí)之前，我們調(diào)研了一些業(yè)界關(guān)于API管理的實(shí)踐，總的來說包含兩大塊內(nèi)容：工具和平臺(tái)。

4.1   工具向左

工具是輪子，解決當(dāng)下的問題，是生產(chǎn)力工具；

Mooncake 提供了一系列工具：

1、針對(duì)java開發(fā)的IDEA插件，針對(duì)golang開發(fā)的CLI工具，幫助開發(fā)同學(xué)快速的上傳文檔

2、覆蓋 webpack、vite以及瀏覽器的代理插件，幫助前端同學(xué)方便的實(shí)現(xiàn)數(shù)據(jù)mock

3、覆蓋iOS和android的客戶端代理工具，幫助客戶端同學(xué)mock數(shù)據(jù)

4、覆蓋前端和客戶端的抓包工具，用來快速的生成mock數(shù)據(jù)

4.2   平臺(tái)向右

平臺(tái)的作用就是，通過一系列的資源整合，讓平臺(tái)內(nèi)的資源互相作用，不斷的磨合，創(chuàng)造出新的生產(chǎn)力工具。

在Mooncake平臺(tái)化的過程中，遵循了兩個(gè)原則：

第一是多元多維。這個(gè)概念來自窮查理寶典，Mooncake 融合打通了EP、CMDB、RDC、網(wǎng)關(guān)等平臺(tái)，最大限度的發(fā)揮文檔的價(jià)值，也最大限度的降低研發(fā)同學(xué)在API溝通上的成本。

第二分而治之，各個(gè)擊破。架構(gòu)本身是解決問題的過程，問題太復(fù)雜了，只能采用分而治之的辦法。

怎么分？利用金字塔原理，同時(shí)在數(shù)據(jù)化上做思考，之后按照架構(gòu)主題做拆分。Mooncake平臺(tái)分為文檔、用例、Mock三大塊，圍繞這三大塊進(jìn)行升級(jí)和優(yōu)化。同時(shí)按照組織架構(gòu)和迭代，進(jìn)行數(shù)據(jù)統(tǒng)計(jì)和分析，提供各種指標(biāo)幫助研發(fā)同學(xué)衡量項(xiàng)目的文檔質(zhì)量。

怎么擊破？Mooncake采用了分層架構(gòu)，優(yōu)先解決文檔的問題，圍繞文檔做深度；在解決了文檔問題之后，在文檔上下游和用例上持續(xù)迭代優(yōu)化，通過openAPI的方式拓寬平臺(tái)廣度。

五、Mooncake的未來

如果說Mooncake 1.0是青銅時(shí)代，2.0是白銀時(shí)代，那么接下來一定是Mooncake的黃金時(shí)代。

5.1   青銅時(shí)代

1.0的Mooncake 覆蓋了得物前端平臺(tái)所有用戶，以及接近50%的客戶端用戶。

5.2   白銀時(shí)代

2.0時(shí)代的Mooncake融合了yapi+mock，同時(shí)打通rdc、EP、網(wǎng)關(guān)平臺(tái)等平臺(tái)，在研發(fā)流程的各個(gè)階段提供接口文檔服務(wù)，共沉淀了數(shù)萬接口，覆蓋了得物技術(shù)部90%的研發(fā)同學(xué)，平臺(tái)的NPS也一度達(dá)到57%。

5.3   黃金時(shí)代

目前的API建設(shè)、平臺(tái)研發(fā)都還有很多問題：

1、在進(jìn)度壓力下，一些因?yàn)閮e幸心理而遺留的技術(shù)債，比如網(wǎng)關(guān)環(huán)境和項(xiàng)目環(huán)境的切換，比如swagger定時(shí)掃描等等

2、一些屈從于短期目標(biāo)的方案，比如簡(jiǎn)單版本的diff功能，比如簡(jiǎn)單版本的文檔遷移功能等等

3、一些因?yàn)槁窂竭^長(zhǎng)而放棄的遠(yuǎn)大目標(biāo)，比如dubbo的調(diào)試，比如文檔驅(qū)動(dòng)開發(fā)等等

未來Mooncake還可以做很多，關(guān)于API體系建設(shè)、關(guān)于平臺(tái)化、關(guān)于開放，Mooncake將不斷推進(jìn)產(chǎn)品和技術(shù)的創(chuàng)新和升級(jí)，為技術(shù)部的小伙伴提供更好的產(chǎn)品和服務(wù)。