一、背景

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

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

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

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

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

在這個過程當中，Mooncake具體做了什么，又為什么這么做，做了之后有什么用，針對這幾個問題我簡單的說一下我自己的思考。

二、一切過往 皆為序章

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

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

團隊之間必須通過接口來通信。 

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

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

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

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

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

謝謝；祝你過得愉快！

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

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

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

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

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

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

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

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

3、增強各方對資源的競爭 產(chǎn)生激勵

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

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

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

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

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

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

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

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

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

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

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

——尼爾森

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

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

2、貼近場景原則

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

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

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

3、可控性原則

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

——尼爾森

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

4、一致性原則

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

——尼爾森

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

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

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

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

   ——尼爾森

當操作不可逆時，給予?戶?次確認的機會，避免?戶由于誤操作造成的后果:

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

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

 ——尼爾森

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

7、使用的靈活性和效率

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

 ——尼爾森

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

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

8、美觀和簡約設(shè)計

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

——尼爾森

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

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

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

10、人性化幫助原則

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

 ——尼爾森

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

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

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

4.1   工具向左

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

Mooncake 提供了一系列工具：

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

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

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

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

4.2   平臺向右

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

在Mooncake平臺化的過程中，遵循了兩個原則：

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

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

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

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

五、Mooncake的未來

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

5.1   青銅時代

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

5.2   白銀時代

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

5.3   黃金時代

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

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

2、一些屈從于短期目標的方案，比如簡單版本的diff功能，比如簡單版本的文檔遷移功能等等

3、一些因為路徑過長而放棄的遠大目標，比如dubbo的調(diào)試，比如文檔驅(qū)動開發(fā)等等

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