闲鱼的统一跨端 API 方案 —— Uni API

本文将介绍跨端 API 解决方案应该解决什么问题，提供什么能力。

背景

随着 C 端流量红利的逐渐消失，端外投放已成为业务寻求增长的重要抓手之一。而不同 App 上存在不同应用场景、不同时期诞生的前端容器：

• 基于浏览器的 Webview 容器（h5

• 基于客户端渲染衍生的 React Native、Weex 容器

• 基于自绘渲染的 flutter 容器

• 平台开放能力的小程序容器

业务在端外进行跨端时，就需要前端同学对投放目标环境逐一评估和适配。在初期阶段，前端侧通常通过同一业务针对不同目标环境维护多套实现的方式进行支持，这使得工作量成倍增加。效率提升空间下，催生了跨端方案。

问题定义

在跨端业务的前端代码中，通常存在大量的跨端 JS API 调用的重复逻辑：

if (isH5) {
  if (isXianyu) {   // 闲鱼
    webXianyuToast();
  }else if (isTaobao) { // 淘宝
    webTaobaoToast();
  } else if(isAlipay){ // 支付宝
    webAlipayToast()
  }
  // ...
} else if(isWeex)
// ...

这些调用从开发到上线通常需要经历的路径：

• 和业务同学确定需要投放的目标环境。如 H5（支付宝、淘宝、天猫等）

• 向目标容器维护者询问 API 调用方式

• 在不同环境下调试、开发

• 测试同学使用不同机型在不同 App 上适配

每一步都是比较耗时的体力活。假想，能够满足可用性、易用性、丰富性、可扩展性，使得业务直接开发如下代码，正常测试后即可上线。跨端 API 解决方案应该解决什么问题，提供什么能力呢？

import toast from 'uni-toast'


toast()

1. 可用性：适配业务常投放的 Webview、小程序、Wap 等前端容器和 App。并最大化保障 API 能力使用，调用 APP 定制能力 -> 调用容器通用能力 -> Wap 环境模拟能力 -> 返回支持度信息，避免调用异常

2. 易用性：让不同环境的 API 调用有可靠、可快速调试支持度的统一入口

3. 丰富性：所支持的目标环境、 API 集合足够多，满足绝大部分业务诉求

4. 可扩展性：随着业务的发展，能够支持更多 App 、API；随着前端技术的发展，能够支持更多形态的容器

方案设计&实现

▐  整体设计

在项目起步阶段，了解到不止是闲鱼，整个阿里经济体前端支撑跨端业务也有相同的问题。于是，跨端 API 项目站在经济体的的视角，以共建的方式进行推进。针对上述问题的方案设计：

我们将跨端 API 整体方案定义为规范、SDK 和配套设施三个部分：

• 规范作为跨端 API 抹平标准，使得对上层业务只感知一套成为可能。

• SDK 遵循规范，对不同环境调用底层 API 进行抹平。通过自定义构建、分端构建等工程能力，透出可定制、可扩展的跨端 API 产物；

• 配套设施通过 API 文档、CANIUSE 工具提供快速检索能力，一码多端调用示例提供快速试用能力；

▐  促成规范

跨端 API 规范的意义是：

• 向上为 SDK 层 API 设计提供参考标准，提高业务侧使用时的确定性、合理性；

• 向下为 Native 层 JSAPI 设计提供参考标准，减缓底层分化趋势；

规范能否普遍推广和保持生命力取决于 自身合理性 **和 **上下游认可度，为保障以上两点，邀请了经济体各现有跨端方案作者成立了跨端 API 规范小组，从以下四个方面制定了跨端 API 规范：

• 确定范围

什么样的 API 应该算作跨端 API。

跨端 API 应该具备 跨端属性和高频属性：跨端属性可通过各容器支持度客观反映，高频属性一方面通过各方案的调用统计作为依据，一方面通过跨端规范小组成员逐个投票判断

• 环境探针

跨端 API 核心在于根据不同环境调用相应实现，精确的环境感知尤为重要。

环境判断涉及到经济体内、外的标准容器、特殊容器，在环境探针规范中通过 容器识别协议、端识别协议、系统识别协议、识别次序约定 的组合机制覆盖了全场景；

• 标准 API 定义

标准 API 模型是真实 API 的 interface，也是所有 API 的骨骼。

通过标准 API 合集进行分析，API 之间的差异主要体现在：方法命名、调用方式、出入参结构、返回错误码 四个部分，这四部分加上 出入参扩展机制 就定义了标准 API 模型；

• 扩展机制

标准 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. 2.统一多端适配 API 的 SDK，使得开发同学不再逐个环境拼凑、调试、开发 API，而是像标准 API 一样直接使用

3. 3.统一维护 SDK，免去测试同学针对不同机型、不同环境下容器能力使用的工作量

从 SDK 1.0 release 开始，闲鱼会玩社区、端外分享承接页等业务就开始陆续进行试点和落地。此外，方案 SDK Uni API 已在阿里经济体内 10+ BU 应用，逐渐成为经济体前端开发的基础设施。

展望

抹平不是终点，上层适配应对分化永远是中间态方案，一套底层标准 API 才是最优解。「跨端 API 调用规范」为「容器 API 标准」提供来自上层使用侧的输入，使得新容器 API 在设计时能够有所参考，避免不必要的分化

开源社区版本（https://universal-api.js.org[1]）建设（由跨端 API 小组、Rax 等团队共同建设）。目前 Uni API 开源版本已支持阿里系、微信、字节系、百度等小程序和 h5 容器，预期后续持续扩展 API 和支持容器等丰富度

所以在端技术仍在日益发展的背景下，下一代的跨端方案，是由底层的 Fuchsia OS、HarmonyOS 等多端操作系统统一，还是依旧通过上层适配实现呢，你怎么认为呢？

✿  拓展阅读

作者|叶遥

编辑|橙子君

出品|阿里巴巴新零售淘系技术