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

{"type":"doc","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"隨着 C 端流量紅利的逐漸消失，端外投放已成爲業務尋求增長的重要抓手之一。而不同 App 上存在不同應用場景、不同時期誕生的前端容器："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"numberedlist","attrs":{"start":null,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"基於瀏覽器的 Webview 容器（h5"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"基於客戶端渲染衍生的 React Native、Weex 容器"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"基於自繪渲染的 flutter 容器"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"平臺開放能力的小程序容器"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"業務在端外進行跨端時，就需要前端同學對投放目標環境逐一評估和適配。在初期階段，前端側通常通過同一業務針對不同目標環境維護多套實現的方式進行支持，這使得工作量成倍增加。效率提升空間下，催生了跨端方案"}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"問題定義"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在跨端業務的前端代碼中，通常存在大量的跨端 JS API 調用的重複邏輯："}]},{"type":"codeblock","attrs":{"lang":null},"content":[{"type":"text","text":"if (isH5) {\n if (isXianyu) { \/\/ 閒魚\n webXianyuToast();\n }else if (isTaobao) { \/\/ 淘寶\n webTaobaoToast();\n } else if(isAlipay){ \/\/ 支付寶\n webAlipayToast()\n }\n \/\/ ...\n} else if(isWeex)\n\/\/ ...\n"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"這些調用從開發到上線通常需要經歷的路徑："}]},{"type":"numberedlist","attrs":{"start":null,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"和業務同學確定需要投放的目標環境。如 H5（支付寶、淘寶、天貓等）"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"向目標容器維護者詢問 API 調用方式"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"在不同環境下調試、開發"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"測試同學使用不同機型在不同 App 上適配"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"每一步都是比較耗時的體力活。假想，能夠滿足可用性、易用性、豐富性、可擴展性，使得業務直接開發如下代碼，正常測試後即可上線。跨端 API 解決方案應該解決什麼問題，提供什麼能力呢？"}]},{"type":"codeblock","attrs":{"lang":null},"content":[{"type":"text","text":"import toast from 'uni-toast'\n\ntoast()"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"numberedlist","attrs":{"start":1,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"可用性：適配業務常投放的 Webview、小程序、Wap 等前端容器和 App。並最大化保障 API 能力使用，調用 APP 定製能力 -> 調用容器通用能力 -> Wap 環境模擬能力 -> 返回支持度信息，避免調用異常"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"易用性：讓不同環境的 API 調用有可靠、可快速調試支持度的統一入口"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"豐富性：所支持的目標環境、 API 集合足夠多，滿足絕大部分業務訴求"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"可擴展性：隨着業務的發展，能夠支持更多 App 、API；隨着前端技術的發展，能夠支持更多形態的容器"}]}]}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"方案設計 & 實現"}]},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"整體設計"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在項目起步階段，瞭解到不止是閒魚，整個阿里經濟體前端支撐跨端業務也有相同的問題。於是，跨端 API 項目站在經濟體的的視角，以共建的方式進行推進。針對上述問題的方案設計："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/6d\/6ddf24e37685c4964e490b0f715e6e88.png","alt":"圖片","title":"null","style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"我們將跨端 API 整體方案定義爲規範、SDK 和配套設施三個部分："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"• 規範作爲跨端 API 抹平標準，使得對上層業務只感知一套成爲可能。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"• SDK 遵循規範，對不同環境調用底層 API 進行抹平。通過自定義構建、分端構建等工程能力，透出可定製、可擴展的跨端 API 產物；"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"• 配套設施通過 API 文檔、CANIUSE 工具提供快速檢索能力，一碼多端調用示例提供快速試用能力；"}]},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"促成規範"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"跨端 API 規範的意義是："}]},{"type":"numberedlist","attrs":{"start":null,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"向上爲 SDK 層 API 設計提供參考標準，提高業務側使用時的確定性、合理性；"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"向下爲 Native 層 JSAPI 設計提供參考標準，減緩底層分化趨勢；"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"規範能否普遍推廣和保持生命力取決於 "},{"type":"text","marks":[{"type":"strong"}],"text":"自身合理性 **和 **上下游認可度"},{"type":"text","text":"，爲保障以上兩點，邀請了經濟體各現有跨端方案作者成立了跨端 API 規範小組，從以下四個方面制定了跨端 API 規範："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/e1\/e14f99d6ba2fc2cbf1ac4102b8c4bb66.png","alt":"圖片","title":"null","style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"確定範圍"},{"type":"text","text":"：什麼樣的 API 應該算作跨端 API。"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"跨端 API 應該具備 "},{"type":"text","marks":[{"type":"strong"}],"text":"跨端屬性和高頻屬性"},{"type":"text","text":"：跨端屬性可通過各容器支持度客觀反映，高頻屬性一方面通過各方案的調用統計作爲依據，一方面通過跨端規範小組成員逐個投票判斷"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"環境探針"},{"type":"text","text":"：跨端 API 核心在於根據不同環境調用相應實現，精確的環境感知尤爲重要。"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"環境判斷涉及到經濟體內、外的標準容器、特殊容器，在環境探針規範中通過 容器識別協議、端識別協議、系統識別協議、識別次序約定 的組合機制覆蓋了全場景；"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"標準 API 定義"},{"type":"text","text":"：標準 API 模型是真實 API 的 interface，也是所有 API 的骨骼。"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"通過標準 API 合集進行分析，API 之間的差異主要體現在：方法命名、調用方式、出入參結構、返回錯誤碼 四個部分，這四部分加上 出入參擴展機制 就定義了標準 API 模型；"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"擴展機制："},{"type":"text","text":"標準 API 合集未覆蓋的場景，通過定製、擴展能力支持。"}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"基於標準 API 擴展新的端容器實現，或者擴展一個全新的 API；"}]},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"SDK 實現"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"有了規範作爲實現依據和指導之後，我們開始進行進行 SDK 實現。在整個過程中，主要面臨了以下挑戰："}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"【"},{"type":"text","marks":[{"type":"strong"}],"text":"實現"},{"type":"text","text":"】"},{"type":"text","marks":[{"type":"strong"}],"text":"巨大的維護工作量："},{"type":"text","text":"55+ API 在 8 容器、30+ APP 上的適配和長期維護，且 API 和環境數量均無收斂趨勢 "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"【工程】多場景產物輸出："},{"type":"text","text":"多場景使用 -> 多形態產物"},{"type":"text","marks":[{"type":"strong"}],"text":"。"},{"type":"text","text":"如日常業務開發期望的使用方式是"},{"type":"codeinline","content":[{"type":"text","text":"window.uni.toast()"}]},{"type":"text","text":"；跨端基礎物料開發期望的是 "},{"type":"codeinline","content":[{"type":"text","text":"import toast from 'uni-toast'"}]},{"type":"text","text":" 。多場景的使用使得產物需要多形態輸出 "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"【"},{"type":"text","marks":[{"type":"strong"}],"text":"工程"},{"type":"text","text":"】"},{"type":"text","marks":[{"type":"strong"}],"text":"方案的可定製性："},{"type":"text","text":"站在經濟體視角，場景不只是面向閒魚自身業務。業務側場景通常只需要投放方案所支持容器環境中的一部分，使用整個方案會引入不必要的冗餘。所以方案需要支持從全集中定義構建出子集的能力"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"應對上述挑戰的關鍵解法是： "},{"type":"text","marks":[{"type":"strong"}],"text":"分層按端適配 API"},{"type":"text","text":"。API 差異分佈在容器層、APP 層，SDK 設計時，也按照分層進行抹平。容器層抹平了通用 API 差異，APP 層基於容器層進行定製。按端適配的設計帶來了天然的"},{"type":"text","marks":[{"type":"strong"}],"text":"擴展性"},{"type":"text","text":"，在支持一個新端時，只需實現對應的 API 適配集合，其餘環境判斷、掛載 API、多維度輸出包的部分就交給工程和 uniapi-core 完成了。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/24\/24ac4a75a2fd6a04bd0b1ec788783464.png","alt":"圖片","title":"null","style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"開放方案擴展能力，降低中心化維護工作量"},{"type":"text","text":"。官方優先保障高頻 APP、容器的 API 維護，當業務跨端投放目標環境未適配時，可通過共建的方式按照規範進行適配；另外，建立 APP 適配維護認領機制，使得維護多端適配具備長效性。"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"自定義構建能力。"},{"type":"text","text":"原子化 API 的設計 + 組合機制可以使整個方案具備了自定義構建能力。原子化 API：將指定容器、APP 上的 API 適配作爲最小單元，進行無副作用的實現；組合機制：通過配置提取所需 API 及目標投放環境，以代碼模板的方式自動組合 API 進行構建、發佈；"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/49\/4955fe29e52fd8e557b7560745da40ce.png","alt":"圖片","title":"null","style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"擁有全環境的 API 原子化實現，便能構建出任意支持度的跨端 API 方案。目前已輸數個 BU 級定製包。"}]},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"配套設施建設"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"規範和 SDK 滿足了可用性、豐富性、可擴展性訴求。在易用性，跨端 API 提供複雜 API 的查詢、調試能力，建設了內部、開源站點：文檔（支持度信息細緻到參數、APP 粒度）、CAN I USE 工具、一碼多端調用示例等"}]},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/ad\/ad82e601520f4b8b531947337912d1da.png","alt":"圖片","title":"null","style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"業務接入後"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在接入跨端 API 方案後，跨端業務的工作流有了以下優化："}]},{"type":"numberedlist","attrs":{"start":null,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"中心化的容器能力信息維護，使得產品、開發同學不再逐個環境詢問能力，而是通過統一入口快速查詢評估"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"統一多端適配 API 的 SDK，使得開發同學不再逐個環境拼湊、調試、開發 API，而是像標準 API 一樣直接使用"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"統一維護 SDK，免去測試同學針對不同機型、不同環境下容器能力使用的工作量"}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"從 SDK 1.0 release 開始，閒魚會玩社區、端外分享承接頁等業務就開始陸續進行試點和落地。此外，方案 SDK Uni API 已在阿里經濟體內 10+ BU 應用，逐漸成爲經濟體前端開發的基礎設施。"}]}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"展望"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"• 抹平不是終點，上層適配應對分化永遠是中間態方案，一套底層標準 API 纔是最優解。「跨端 API 調用規範」爲「容器 API 標準」提供來自上層使用側的輸入，使得新容器 API 在設計時能夠有所參考，避免不必要的分化"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"• 開源社區版本（https:\/\/universal-api.js.org[1]）建設（由跨端 API 小組、Rax 等團隊共同建設）。目前 Uni API 開源版本已支持阿里系、微信、字節系、百度等小程序和 h5 容器，預期後續持續擴展 API 和支持容器等豐富度"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"所以在端技術仍在日益發展的背景下，下一代的跨端方案，是由底層的 Fuchsia OS、HarmonyOS 等多端操作系統統一，還是依舊通過上層適配實現呢，你怎麼認爲呢？"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":"References"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"codeinline","content":[{"type":"text","text":"[1]"}]},{"type":"text","text":"https:\/\/universal-api.js.org: "},{"type":"text","marks":[{"type":"italic"}],"text":"https:\/\/universal-api.js.org\/"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"本文轉載自：閒魚技術（ID：XYtech_Alibaba）"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"原文鏈接："},{"type":"link","attrs":{"href":"https:\/\/mp.weixin.qq.com\/s\/KJNb3HRqSIS80_yy0BlH7w","title":"xxx","type":null},"content":[{"type":"text","text":"閒魚的統一跨端 API 方案 —— Uni API"}]}]}]}