闲鱼的统一跨端 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/