Uni API -- 统一跨端 API 方案

发表于 3年以前 | 总阅读数：315 次

背景

随着 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()

可用性：适配业务常投放的 Webview、小程序、Wap 等前端容器和 App。并最大化保障 API 能力使用，调用 APP 定制能力 -> 调用容器通用能力 -> Wap 环境模拟能力 -> 返回支持度信息，避免调用异常
易用性：让不同环境的 API 调用有可靠、可快速调试支持度的统一入口
丰富性：所支持的目标环境、 API 集合足够多，满足绝大部分业务诉求
可扩展性：随着业务的发展，能够支持更多 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 完成了。