背景

作为后端云服务提供商，我们在底层通过 REST API 与 WebSocket 提供数据、文件存储、短信、推送、实时消息等服务。还为各个目标平台编写了 SDK 来封装这些 API，在 SDK 中实现客户端状态的持久化，为用户提供更加符合直觉的抽象。一个有趣的现象是越来越多的平台使用的都是 JavaScript：

• Web（浏览器/WebView/Windows Universal App/…）
• Node.js
• Electron/NW.js
• React Native
• Cocos2d-x（JavaScript binding）
• 微信小程序

为什么 SDK 要跨平台？降低成本是为重要的一大原因。对于用户，提供跨平台的 SDK 可以降低学习与切换成本。并且，随着同构应用以及服务端渲染的流行，对于采用这种方案的用户，跨平台 SDK 可以方便地作为「平台无关」代码进行共享。而对于公司而言，如果能够在多个平台中共享这部分代码，将会减少 SDK 的开发与维护成本。

基于以上前提，我们的目标具体表现为：

• 使用一套代码；
• 一致的 API；
• 各平台提供一致的安装加载方式。

接下来，我们分 API、编译打包、小程序、测试四个部分详细了解 SDK 在跨平台实践中遇到的常见问题及解决方案。

API

平台间的相同点

• JavaScript Engine

这些平台都会使用内置或者外部的 JavaScript Engine 来执行 JavaScript 代码。所有属于 ECMAScript 标准的 API 都是所有平台都支持的，比如 Math、Array、TypedArray、Promise、正则表达式。这倒不是指它们使用的是同一个 JavaScript Engine（事实上存在 V8、SpiderMonkey、JSC、Chakra 等各种实现），得益于 TC39 的存在以及 Babel 的出色表现，我们几乎不需要担心我们的 JavaScript 代码在不同平台上的一致性问题。这也意味着，如果一个第三方库只使用了 ECMAScript 的 API，那么它一定是跨平台的，我们可以放心使用，一个典型的例子就 lodash。

不同点

ECMAScript 的 API 是语言层面上的，除此之外，各个平台还会根据自己需要解决的问题提供平台特有的 API。比如，其中有委员会（W3C）来制定标准的平台——Web 平台——提供了下面这些 API。

• DOM API；
• 设备 API：地理位置，陀螺仪、电池、MediaCapture；
• 通讯 API：网络请求、WebSocket、WebRTC、推送；
• 数据管理 API：文件、本地存储、数据库。

其中 DOM API 在其他平台上都没有，而网络请求 API 在 Node.js 平台上则是完全不同的设计。对于 LeanCloud SDK，我们关心的是实现以下这些功能以及实现所需要用到的 API：

从上表中可以看到平台在设计这些基础能力 API 时，分为三大流派：

1. 客户端平台（Web、React Native、cocos2d-x）：（尽可能）内置 W3C 标准 API 的实现；
2. Node.js API：作为的服务端 Runtime，提供底层的能力，上层实现交给社区（上面说到的 W3C API，几乎都能找到基于 Node.js API 的实现）；
3. 微信小程序。

API 的本质是对实现的抽象，SDK 就像一个由 API 调用构成的金字塔，越往上抽象越贴近用户。要跨平台，用户就需要将不同的底层 API 抽象成一个。这里有两种思路，假设我们有两个平台的 API A 与 B：

1. 用 B 实现 A；
2. 分别用 A 与 B 实现 C；

具体到我们的实现：

打包

要想达成只使用一套 codebase 的目标，除了统一的 API 在各平台上的不同实现，还需要在不同的平台上运行对应的代码。我们先来看看有哪些工具能完成这个任务，这里以 WebSocket 为例。

运行时判断

开始，我们的 SDK 是没有编译打包环节的，在运行时进行平台检测来执行不同的代码。

// src/websocket.js let WebSocket; if (!utils.isNode) {
  WebSocket = window.WebSocket;
} else {
  WebSocket = require('ws').WebScoket;
}

• ☹️ 随着平台数量增加，文件体积大（这是一个例子，实际上 if else 的内容可能很长）；
• ☹️ 平台检测不可靠，随着平台数量增加难以维护。

条件编译

为了解决这个问题，我们引入了 webpack 来实现「条件编译」：

// src/websocket.js let WebSocket; if (process.env.PLATFORM === 'Browser') {
  WebSocket = window.WebSocket;
} else {
  WebSocket = require('ws').WebScoket;
}

// webpack/browser.js module.exports = { // ... plugins: [ new webpack.EnvironmentPlugin(["PLATFORM"])
    ]
};

// package.json:
{
  "scripts": {
    "build:browser": "PLATFORM=Browser webpack --config webpack/browser.js" } }

webpack 后：

var WebSocket; if ('Browser' === 'Browser') {
  WebSocket = window.WebSocket;
} else {
  WebSocket = require('ws').WebScoket;
}

uglify 后：

var WebSocket;WebSocket=window.WebSocket;

• ☹️ 现在有多个入口了，怎么告诉平台使用哪个呢？（需要提供一致的加载方式）
• ☹️ ws 怎么也打包进来了？（因为 bundler 不知道不需要 ws，换句话说，我们需要找到一种方式告知 bundler。）

package browser field spec

可见：https://github.com/defunctzombie/package-browser-field-spec

// package.json:
{
    "browser": {
    "ws": "./src/websocket.js" } }

// src/websocket-browser.js module.exports = window.WebSocket;

// src/websocket.js const WebSocket = require('ws');

除了对内告诉 bundler 要如何打包模块，browser field 也用来对外申明浏览器版本的入口：

// package.json:
{
    "main": "./dist/node/index.js",
    "browser": {
      "./dist/node/index.js": "./dist/av.js",
    "ws": "./src/websocket-browser.js" } }

作为事实标准，browser 字段得到了市面上几乎所有 bundler 的支持（包括 React Native 内置的 Packager、cocos creator 使用的 browserify，以及 webpack 与 rollup），npm 上众多跨平台的 package 也都是采用了这种申明方式。

同样的，我们还有一些 React Native 特有的代码需要在打包时替换。webpack 使用了一种更通用的方式支持了这个特性。

// package.json:
{
    "main": "./dist/node/index.js",
    "browser": {
      "./dist/node/index.js": "./dist/av.js",
    "ws": "./src/websocket.js" },
    "react-native": {
      "./dist/node/index.js": "./dist/av-rn.js",
    "./src/utils/localstorage.js": "./src/utils/localstorage-rn.js" } }

// webpack/react-native.js module.exports = { // ... resolve: {
      aliasFields: ['react-native', 'browser']
  }
};

预编译？

刚才说到，市面上几乎所有的 bundler 都支持这个标准，bundler 会按照我们的配置正确的使用对应的模块，所以为目标平台编译出一个文件并不是必须的。事实上这样做是有缺点的

• 无法与其他模块共享代码
• 无法自动得到依赖模块的 patch

与此同时，预编译的版本也不会自动得到依赖模块的新 bug，并且考虑到很多 bundler 在具体的实现上总有各种各样的问题，所以我们目前依然在每次一发布时都提供了各个平台的预编译版本。

至此，我们几乎完成了前面所设定的目标：

• 我们使用一个 codebase，共享了大部分的代码；
• 统一使用 npm 安装，使用 require 加载，为不同的平台指定不同的入口；
• 提供了统一的 API。

直到出现了一位新玩家。

小程序带来的新挑战

先来看下小程序的架构。

在部分说到，由于 Web API 抽象层级高、后台硬、现有轮子多，各个平台都倾向于实现 Web API。SDK 大部分时候都是直接调用的 Web API。另一方面，我们也使用了 superagent/axios 等第三方库提供更加易用的 API，并不希望去修改这些第三方库。

很自然地，为了适配小程序，便捷的方案是用小程序的 API 来 polyfill Web API。很快我们就遇到了两个问题：

unpolyfillable runtime

小程序的 JavaScript 代码在真机上是运行在 JSC / JSCore 上的，但是在开发者工具中，这部分代码是直接运行在浏览器环境中的，是能够使用包括 window、document、XMLHttpRequest 在内的所有 Web API 的。为了保证 IDE 与真机运行环境的一致性，IDE 在编译阶段会在每个文件的 CommonJS wapper 中申明这些变量：

define("app", function(require, module, exports, window,document,frames,self,location,navigator,localStorage,history,Caches,screen,alert,confirm,prompt,XMLHttpRequest,WebSocket,webkit,WeixinJSCore,WeixinJSBridge,Reporter){  'use strict'; // SDK code new XMLHttpRequest(); // throw new window.XMLHttpRequest(); // throw });

这意味着即使能够为 global object 增加 Web API，也无法在其他文件中访问到。

define("app", function(require, module, exports, window,XMLHttpRequest/* ... */){  'use strict'; // polyfill code window = window || {};
  window.XMLHttpRequest = require('./xmlhttprequest.js'); try {
    XMLHttpRequest = XMLHttpRequest || require('./xmlhttprequest.js');
    } catch (e) {} // SDK code new XMLHttpRequest(); new window.XMLHttpRequest();
});

小程序的 API 的抽象层级在 Web API 之上

还是以 HTTP 请求为例，小程序的 wx.request API 在开发者工具中是用浏览器中的 XMLHttpRequest 实现的。因此小程序的 API 缺少了很多实现 Web API 需要的特性：

• Response Headers 无法获得；
• 不支持上传进度；
• 不支持 abort；
• 拿不到 HEADERS_RECEIVED 与 LOADING 等中间状态。

一方面，我们只能在微信小程序中禁用掉 SDK 的一些功能，比如文件上传进度功能。另一方面尽可能去 mock 一些特性或数据来保证现有的基于 Web API 的代码逻辑不会抛异常，比如 getResponseHeade('content-type') 始终返回'application/json'，其他 key 始终返回 ‘’。

这些 polyfill 开源在 GitHub - leancloud/weapp-polyfill: Polyfills for w3c API on top of Weapp API 。目前我们 polyfill 了以下 API，如果有在小程序中使这些 API 的需求，这个库应该能节省你一些时间。

• XMLHttpRequest
• FormData
• WebSocket
• localStorage

测试

测试是保证 SDK 质量的重要手段，我们使用了 Mocha 作为测试框架，Sinon.js 作为 spy 与 mock 工具，它们都同时支持浏览器与 Node.js。再加上 SDK 提供的 API 是平台无关的，使得我们能够使用一份测试代码分别在浏览器与 Node.js 中运行测试。

对于跨平台 SDK，测试流程的自动化是必不可少的。我们使用 travis-ci 来运行 Node.js 的测试，使用 Saucelabs（Selenium）来运行浏览器测试，保证每次提交在我们支持的所有 Node.js 版本与我们支持的所有浏览器中都能通过测试。

遗憾的是，对于其他平台，由于工具的缺失，目前并没有良好的测试方案，我们现在也只是在发布之前手动进行冒烟测试。