閒魚的統一跨端 API 方案 —— Uni API

做者：閒魚技術——葉遙

背景

隨着 C 端流量紅利的逐漸消失，端外投放已成爲業務尋求增加的重要抓手之一。而不一樣 App 上存在不一樣應用場景、不一樣時期誕生的前端容器：前端

1.基於瀏覽器的 Webview 容器（h52.基於客戶端渲染衍生的 React Native、Weex 容器3.基於自繪渲染的 flutter 容器，4.平臺開放能力的小程序容器web

業務在端外進行跨端時，就須要前端同窗對投放目標環境逐一評估和適配。在初期階段，前端側一般經過同一業務針對不一樣目標環境維護多套實現的方式進行支持，這使得工做量成倍增長。效率提高空間下，催生了跨端方案小程序

問題定義

在跨端業務的前端代碼中，一般存在大量的跨端 JS API 調用的重複邏輯：api

if (isH5) {
  if (isXianyu) {   // 閒魚
    webXianyuToast();
  }else if (isTaobao) { // 淘寶
    webTaobaoToast();
  } else if(isAlipay){ // 支付寶
    webAlipayToast()
  }
  // ...
} else if(isWeex)
// ...
複製代碼

這些調用從開發到上線一般須要經歷的路徑：瀏覽器

1.和業務同窗肯定須要投放的目標環境。如 H5（支付寶、淘寶、天貓等）2.向目標容器維護者詢問 API 調用方式3.在不一樣環境下調試、開發4.測試同窗使用不一樣機型在不一樣 App 上適配微信

每一步都是比較耗時的體力活。假想，可以知足可用性、易用性、豐富性、可擴展性，使得業務直接開發以下代碼，正常測試後便可上線。跨端 API 解決方案應該解決什麼問題，提供什麼能力呢？markdown

import toast from 'uni-toast'

toast()
複製代碼

1.**可用性：**適配業務常投放的 Webview、小程序、Wap 等前端容器和 App。並最大化保障 API 能力使用，調用 APP 定製能力 -> 調用容器通用能力 -> Wap 環境模擬能力 -> 返回支持度信息，避免調用異常2.**易用性：**讓不一樣環境的 API 調用有可靠、可快速調試支持度的統一入口3.**豐富性：**所支持的目標環境、 API 集合足夠多，知足絕大部分業務訴求4.**可擴展性：**隨着業務的發展，可以支持更多 App 、API；隨着前端技術的發展，可以支持更多形態的容器工具

方案設計 & 實現

總體設計

在項目起步階段，瞭解到不止是閒魚，整個阿里經濟體前端支撐跨端業務也有相同的問題。因而，跨端 API 項目站在經濟體的的視角，以共建的方式進行推動。針對上述問題的方案設計：咱們將跨端 API 總體方案定義爲規範、SDK 和配套設施三個部分：oop

•規範做爲跨端 API 抹平標準，使得對上層業務只感知一套成爲可能。•SDK 遵循規範，對不一樣環境調用底層 API 進行抹平。經過自定義構建、分端構建等工程能力，透出可定製、可擴展的跨端 API 產物；•配套設施經過 API 文檔、CANIUSE 工具提供快速檢索能力，一碼多端調用示例提供快速試用能力；測試

促成規範

跨端 API 規範的意義是：

1.向上爲 SDK 層 API 設計提供參考標準，提升業務側使用時的肯定性、合理性；2.向下爲 Native 層 JSAPI 設計提供參考標準，減緩底層分化趨勢；

規範可否廣泛推廣和保持生命力取決於 自身合理性 **和 **上下游承認度，爲保障以上兩點，邀請了經濟體各現有跨端方案做者成立了跨端 API 規範小組，從如下四個方面制定了跨端 API 規範：

1.肯定範圍：什麼樣的 API 應該算做跨端 API。

跨端 API 應該具有 跨端屬性 **和 **高頻屬性：跨端屬性可經過各容器支持度客觀反映，高頻屬性一方面經過各方案的調用統計做爲依據，一方面經過跨端規範小組成員逐個投票判斷

1.環境探針：跨端 API 核心在於根據不一樣環境調用相應實現，精確的環境感知尤其重要。

環境判斷涉及到經濟體內、外的標準容器、特殊容器，在環境探針規範中經過容器識別協議、端識別協議、系統識別協議、識別次序約定的組合機制覆蓋了全場景；

1.標準 API 定義：標準 API 模型是真實 API 的 interface，也是全部 API 的骨骼。

經過標準 API 合集進行分析，API 之間的差別主要體如今：方法命名、調用方式、出入參結構、返回錯誤碼四個部分，這四部分加上出入參擴展機制就定義了標準 API 模型；

1.**擴展機制：**標準 API 合集未覆蓋的場景，經過定製、擴展能力支持。

基於標準 API 擴展新的端容器實現，或者擴展一個全新的 API；

SDK 實現

有了規範做爲實現依據和指導以後，咱們開始進行進行 SDK 實現。在整個過程當中，主要面臨瞭如下挑戰：

【實現】**巨大的維護工做量：**55+ API 在 8 容器、30+ APP 上的適配和長期維護，且 API 和環境數量均無收斂趨勢 **【工程】多場景產物輸出：多場景使用 -> 多形態產物。**如平常業務開發指望的使用方式是window.uni.toast()；跨端基礎物料開發指望的是 import toast from 'uni-toast' 。多場景的使用使得產物須要多形態輸出【工程】**方案的可定製性：**站在經濟體視角，場景不僅是面向閒魚自身業務。業務側場景一般只須要投放方案所支持容器環境中的一部分，使用整個方案會引入沒必要要的冗餘。因此方案須要支持從全集中定義構建出子集的能力

應對上述挑戰的關鍵解法是： 分層按端適配 API。API 差別分佈在容器層、APP 層，SDK 設計時，也按照分層進行抹平。容器層抹平了通用 API 差別，APP 層基於容器層進行定製。按端適配的設計帶來了自然的擴展性，在支持一個新端時，只需實現對應的 API 適配集合，其他環境判斷、掛載 API、多維度輸出包的部分就交給工程和 uniapi-core 完成了。開放方案擴展能力，下降中心化維護工做量。官方優先保障高頻 APP、容器的 API 維護，當業務跨端投放目標環境未適配時，可經過共建的方式按照規範進行適配；另外，創建 APP 適配維護認領機制，使得維護多端適配具有長效性。

**自定義構建能力。**原子化 API 的設計 + 組合機制可使整個方案具有了自定義構建能力。原子化 API：將指定容器、APP 上的 API 適配做爲最小單元，進行無反作用的實現；組合機制：經過配置提取所需 API 及目標投放環境，以代碼模板的方式自動組合 API 進行構建、發佈；

擁有全環境的 API 原子化實現，便能構建出任意支持度的跨端 API 方案。目前已輸數個 BU 級定製包。

配套設施建設

規範和 SDK 知足了可用性、豐富性、可擴展性訴求。在易用性，跨端 API 提供複雜 API 的查詢、調試能力，建設了內部、開源站點：文檔（支持度信息細緻到參數、APP 粒度）、CAN I USE 工具、一碼多端調用示例等

業務接入後

在接入跨端 API 方案後，跨端業務的工做流有了如下優化：

1.中心化的容器能力信息維護，使得產品、開發同窗再也不逐個環境詢問能力，而是經過統一入口快速查詢評估2.統一多端適配 API 的 SDK，使得開發同窗再也不逐個環境拼湊、調試、開發 API，而是像標準 API 同樣直接使用3.統一維護 SDK，免去測試同窗針對不一樣機型、不一樣環境下容器能力使用的工做量

從 SDK 1.0 release 開始，閒魚會玩社區、端外分享承接頁等業務就開始陸續進行試點和落地。此外，方案 SDK Uni API 已在阿里經濟體內 10+ BU 應用，逐漸成爲經濟體前端開發的基礎設施。

展望

•抹平不是終點，上層適配應對分化永遠是中間態方案，一套底層標準 API 纔是最優解。「跨端 API 調用規範」爲「容器 API 標準」提供來自上層使用側的輸入，使得新容器 API 在設計時可以有所參考，避免沒必要要的分化•開源社區版本（universal-api.js.org\[1\]）建設（由跨端 API 小組、Rax 等團隊共同建設）。目前 Uni API 開源版本已支持阿里系、微信、字節系、百度等小程序和 h5 容器，預期後續持續擴展 API 和支持容器等豐富度

因此在端技術仍在日益發展的背景下，下一代的跨端方案，是由底層的 Fuchsia OS、HarmonyOS 等多端操做系通通一，仍是依舊經過上層適配實現呢，你怎麼認爲呢？

References

[1] universal-api.js.org: universal-api.js.org/