leancloud：SDK 跨平台支持常见问题及解决方案实践

发布：2018-02-07 11:00浏览：次来源：网络作者：cola

背景

作为后端云服务提供商，我们在底层通过 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：

leancloud：SDK 跨平台支持常见问题及解决方案实践(图1)

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

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

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

用 B 实现 A；
分别用 A 与 B 实现 C；

具体到我们的实现：

leancloud：SDK 跨平台支持常见问题及解决方案实践(图2)

打包

要想达成只使用一套 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。

直到出现了一位新玩家。

小程序带来的新挑战

先来看下小程序的架构。

leancloud：SDK 跨平台支持常见问题及解决方案实践(图3)

在第一部分说到，由于 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 的需求，这个库应该能节省你一些时间。