得物 API 一站式協作平臺的一些思考

　　 1 背景

　　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具體做了什麼，又為什麼這麼做，做了之後有什麼用，針對這幾個問題我簡單的說一下我自己的思考。

　　 2 一切過往 皆為序章

　　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這次升級都是如何做的。

　　 3 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提供全域性搜尋、一鍵進飛書答疑群、自助幫助文件幫助同學快速的找到文件，定位問題:　　

　　 4 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的方式拓寬平臺廣度。

　　 5 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將不斷推進產品和技術的創新和升級，為技術部的小夥伴提供更好的產品和服務。