得物 API一站式協作平臺的一些思考
一、背景
Mooncake是得物API一站式協作平臺。從2022年3月份開始負責Mooncake，到現在已經一年了，回顧這一年，Mooncake大的階段上，總共經歷過兩個版本:
1、Mooncake 1.0: 面向前端和客戶端的mock平臺，主要解決接口調用者的數據mock問題
2、Mooncake 2.0: 面向前后端的，融合了yapi和mock的一站式文檔管理平臺，從供需兩端解決接口文檔的流通效率問題
升級后的Mooncake產品架構如下：
如上圖所示，我們希望Mooncake是得物研發生態系統中的重要一環，為了實現這個目標，Mooncake不斷推陳出新，發布了許多重要功能，例如支持染色環境調試、業務迭代信息報表、支持Dubbo協議的mock等；打通了RDC、EP、CMDB、網關等平臺。此外，Mooncake還提供了openAPI，向外生長，支持EP、DOP、APM等平臺，讓開發同學在研發的各個階段都能方便的通過文檔進行順暢的交流。
在這個過程當中，Mooncake具體做了什么，又為什么這么做，做了之后有什么用，針對這幾個問題我簡單的說一下我自己的思考。
二、一切過往 皆為序章
2002年貝索斯曾經給亞馬遜頒布了一份mandate，這份指令是這樣的：
從今天起，所有的團隊都要以服務接口的方式，提供數據和各種功能。
團隊之間必須通過接口來通信。
不允許任何其他形式的互操作：不允許直接鏈接，不允許直接讀其他團隊的數據，不允許共享內存，不允許任何形式的后門。
唯一許可的通信方式，就是通過網絡調用服務。
具體的實現技術不做規定，HTTP、Corba、PubSub、自定義協議皆可。
所有的服務接口，必須從一開始就以可以公開作為設計導向，沒有例外。這就是說，在設計接口的時候，就默認這個接口可以對外部人員開放，沒有討價還價的余地。
不遵守上面規定者，一律開除。
謝謝；祝你過得愉快！
這份指令的出發點是，貝索斯認為人際溝通往往會造成組織執行不力，而他解決這個問題的方式，就是通過API，系統性的規范組織間的對話。
這個其實在當下很普遍的微服務架構之下，已經不是什么新鮮事了，還有我們大量使用三方開放API，這些都是通過API來完成系統間的調用；
但是在當時，如何讓人們接受這個方案，積極的參與進來，同時也預防API泛濫，是個很大的問題。為此貝索斯建立了一套指標體系，通過激勵最終形成一套正向的持續演進和迭代循環。
這套指標體系，我們可以理解為是一種公司或者組織層面的基建。
1934年，美國經濟大蕭條時期，羅斯福解決經濟危機的兩大新政之一的以工代賑，通過大興基建的方式，刺激消費與生產均衡。
為什么羅斯福選擇通過基建的方式來提振經濟，其原因跟貝索斯這套指標體系是一樣的原因。在蘭小歡《置身事內：中國政府與經濟發展》一書中提到，基建有三個特點：
1、擴展公共服務的規模 產生規模效益
2、提高信息溝通效率 降低信息復雜性
3、增強各方對資源的競爭 產生激勵
由此可見，基建是可以降本增效，并且幫助組織形成一個正向的循環。
2022年3月份之前，得物通過Yapi平臺，沉淀的HTTP接口有數萬個，這是過去七年間得物自然增長的API數量，這已經是一個很龐大的數字，但是在這些http接口背后，還有數量更加龐大的rpc接口散落在語雀、飛書，更有大量的接口沒有文檔沉淀，在歷史中默默發揮著余熱。
那么如何讓文檔規范起來，如何讓更多的開發同學把接口統一起來，如何讓數量龐大的接口文檔發揮更大的價值，Mooncake從三個方面提供服務做了一次升級:
1、從單一mock服務升級為圍繞接口文檔的一站式協作平臺，用戶從前端和客戶端擴展到服務端、測試、前端、客戶端
2、圍繞接口研發生命周期，通過插件、飛書消息、一鍵mock、一鍵配置網關等一系列工具，提高信息溝通效率，降低前后端溝通復雜度
3、關聯rdc提供迭代和團隊兩個維度的數據看板，通過文檔質量分統計來刺激內部競爭，進而推動產出更高效的文檔
接下來我從設計和技術兩個層面簡單回顧一下Mooncake這次升級都是如何做的。
三、Mooncake的設計理念
Mooncake的升級，我們遵循了尼爾森的十大設計理念：
1、系統可?性原則
系統要在適當的時間內給予用戶恰當的反饋，始終讓用戶知道當前正在發生什么。
——尼爾森
可以理解為包括?戶在??上的任何操作，系統需要給出相應的反饋，來確保?戶在操作過程中的狀態可?、變化可?、內容可?，從?幫助?戶將交互引導到正確的?向，?不會浪費精?。
Mooncake通過按鈕、消息提示的即時反饋，來響應用戶的操作:
2、貼近場景原則
系統要使用用戶的語言，用戶熟悉的單詞、短語和概念，而不是系統術語。遵循現實世界的約定，使信息以自然和合乎邏輯的順序出現。 ——尼爾森
?戶會習慣?現實世界中已有認知來看待問題，這個已有認知是?戶根據??掌握的經驗、知識和想象所建?的?智模型。
Mooncake這次升級，融合了Yapi和Mock，除了技術底層在數據上的融合，交互上，也盡可能的保留了原有的交互習慣，比如通過idea上傳文檔的習慣，比如按照文檔、編輯、運行、類型聲明去組織頁面tab:
3、可控性原則
當用戶錯誤地選擇了的某個功能后，系統需要提供一個明確的「緊急出口」，來讓用戶離開其不想要的狀態，而且無需額外的對話框，支持撤銷和重做。
——尼爾森
Mooncake里，通過多tab的形式，方便用戶打開多個接口文檔，而無需頻繁的刷新頁面:
4、一致性原則
我們不應當讓用戶去懷疑不同的語句、狀態或操作是否在表達同一件事，設計需遵循平臺的慣例。
——尼爾森
?致性可以給?戶統?的認知，幫助?戶快速學習、記憶和熟悉產品的功能，從?建??戶穩定的?智模型。為了保障產品間的?戶體驗統?，通常都需要建?設計規范，來確保產品內部的?致性，這里的?致性包括視覺?致性、?為?致性和感知?致性。
Mooncake這次升級，字體、顏色、尺寸布局、組件庫都遵循了得物設計體系規范:
5、錯誤預防原則
比報錯提示更好的方法是，通過嚴謹的設計來防止錯誤的發生：要么消除容易出錯的情況，要么把這些容易出錯的情況找出來，并在用戶采取行動之前提供確認選項。
——尼爾森
當操作不可逆時，給予?戶?次確認的機會，避免?戶由于誤操作造成的后果:
6、系統識別勝過記憶
通過將對象、操作和選項進行可視化，最大限度地減輕用戶的記憶負擔，用戶不需要記住對話框中某一部分到另一部分的信息，系統操作的指示信息需要易于被用戶發現和獲取。
——尼爾森
?戶是不可能記住操作過程中的過多信息的，Mooncake提供了我的收藏和最近訪問幫助同學們快速找到自己常用的項目文檔:
7、使用的靈活性和效率
一些快捷操作的功能，雖然會被新手用戶忽略，但可能為專家用戶所使用并幫助提升其使用效率，因此，系統需要同時滿足新手用戶和專家用戶的需求，允許用戶頻繁地操作。
——尼爾森
這?點其實是在B端產品設計中?較容易忽視的?個原則，我們往往默認使?產品的是相對成熟的產品使?者。
Mooncake的菜單欄提供折疊和展開兩種模式，并且會記住用戶上次的選擇，對于新同學，默認展開菜單，方便了解平臺的功能；對于已經熟悉Mooncake 的同學可以收起菜單，文檔的可視區域最大化，方便閱讀:
8、美觀和簡約設計
對話框中不應包含無關或很少用到的信息，在對話框中每增加一個信息，就意味著降低了主要信息的相對可見性。
——尼爾森
Mooncake的對話框，都盡可能的降低復雜度，一次只做一件事情，一次只搜集最重要的數據，并且盡可能的提供下拉選框減少用戶輸入:
9、幫助?戶發現、判斷和修復錯誤
報錯信息應該用通俗易懂的語言表達，而不是用代碼，準確地反應問題，并且提出可行的解決方案。 ——尼爾森
10、人性化幫助原則
幫助文檔的信息應該易于被搜索，聚焦于用戶的任務，并列出具體的步驟，而且，不能太龐大。
——尼爾森
Mooncake提供全局搜索、一鍵進飛書答疑群、自助幫助文檔幫助同學快速的找到文檔，定位問題:
四、Mooncake的技術架構
在這次升級之前，我們調研了一些業界關于API管理的實踐，總的來說包含兩大塊內容：工具和平臺。
4.1 工具向左
工具是輪子，解決當下的問題，是生產力工具；
Mooncake 提供了一系列工具：
1、針對java開發的IDEA插件，針對golang開發的CLI工具，幫助開發同學快速的上傳文檔
2、覆蓋 webpack、vite以及瀏覽器的代理插件，幫助前端同學方便的實現數據mock
3、覆蓋iOS和android的客戶端代理工具，幫助客戶端同學mock數據
4、覆蓋前端和客戶端的抓包工具，用來快速的生成mock數據
4.2 平臺向右
平臺的作用就是，通過一系列的資源整合，讓平臺內的資源互相作用，不斷的磨合，創造出新的生產力工具。
在Mooncake平臺化的過程中，遵循了兩個原則：
第一是多元多維。這個概念來自窮查理寶典，Mooncake 融合打通了EP、CMDB、RDC、網關等平臺，最大限度的發揮文檔的價值，也最大限度的降低研發同學在API溝通上的成本。
第二分而治之，各個擊破。架構本身是解決問題的過程，問題太復雜了，只能采用分而治之的辦法。
怎么分？利用金字塔原理，同時在數據化上做思考，之后按照架構主題做拆分。Mooncake平臺分為文檔、用例、Mock三大塊，圍繞這三大塊進行升級和優化。同時按照組織架構和迭代，進行數據統計和分析，提供各種指標幫助研發同學衡量項目的文檔質量。
怎么擊破？Mooncake采用了分層架構，優先解決文檔的問題，圍繞文檔做深度；在解決了文檔問題之后，在文檔上下游和用例上持續迭代優化，通過openAPI的方式拓寬平臺廣度。
五、Mooncake的未來
如果說Mooncake 1.0是青銅時代，2.0是白銀時代，那么接下來一定是Mooncake的黃金時代。
5.1 青銅時代
1.0的Mooncake 覆蓋了得物前端平臺所有用戶，以及接近50%的客戶端用戶。
5.2 白銀時代
2.0時代的Mooncake融合了yapi+mock，同時打通rdc、EP、網關平臺等平臺，在研發流程的各個階段提供接口文檔服務，共沉淀了數萬接口，覆蓋了得物技術部90%的研發同學，平臺的NPS也一度達到57%。
5.3 黃金時代
目前的API建設、平臺研發都還有很多問題：
1、在進度壓力下，一些因為僥幸心理而遺留的技術債，比如網關環境和項目環境的切換，比如swagger定時掃描等等
2、一些屈從于短期目標的方案，比如簡單版本的diff功能，比如簡單版本的文檔遷移功能等等
3、一些因為路徑過長而放棄的遠大目標，比如dubbo的調試，比如文檔驅動開發等等
未來Mooncake還可以做很多，關于API體系建設、關于平臺化、關于開放，Mooncake將不斷推進產品和技術的創新和升級，為技術部的小伙伴提供更好的產品和服務。
