Android / iOS Webview 容器下 JSBridge SDK 原理浅析 —— 前端视角

雨点打透心脏的1/2处 2022-09-02 11:43 367阅读 0赞

在 Hybrid 开发的过程中，由于前端和客户端同学存在认知差异，导致在解决一些 bridge 问题时存在一定的沟通成本和信息不对称。本文从前端视角切入，讲述 bridge 方法如何和客户端进行交互，以及在此过程中进行的各种中间处理。

# Native 与 Webview 的通信方式 #

*  ## JavaScript 调用 Native 方法 ##

在 Webview 内，JavaScript 调用 Native 方法主要存在 3 种方式：

1.  Native 向 Webview 的 Context ( 即 Webview 中的 `window` ) 注入一个**暴露指定 Native 方法 ( Android )** 或**接受 JavaScript 消息 ( iOS )** 的对象。
2.  拦截 Webview 内的某类特定的 URL Scheme，并根据 URL 来执行对应的 Native 方法。
3.  拦截 JavaScript 的 `console.log` 、`alert` 、`prompt` 或 `confirm`，并执行对应的 Native 方法。

在目前主流的 JSSDK 实现中，主要采用了前两种通信方式，并以注入式为主、拦截式为兜底策略进行通信，本文也会主要介绍基于这两种方式的实现原理和应用场景。

注入式（ 即第一种方式 ）有更好的性能和更优的开发体验，但**并非兼容所有系统版本**。

Android 的 `JavascriptInterface` 在 **Android 4.2** 版本前因没有注解导致暴露了包括系统类 ( `java.lang.Runtime` ) 方法在内的其他不应暴露的接口，存在较大的安全隐患；而 iOS 的 `WKScriptMessageHandler` 仅支持 **iOS 8.0+** 的版本。

因此、在较低的系统版本中，会采用拦截式（ 即第二种方式 ）作为与 Native 通信的方法。

*  ## Native 调用 JavaScript 方法 ##

Native 调用特定 Webview 内的 JavaScript 方法主要存在 2 种方式：

1.  直接**通过 URL 执行 JavaScript 语句**，例如 `javascript:alert('calling...');` 。
2.  通过 Android 和 iOS 同名的方法 `evaluateJavascript()` 来执行 JavaScript 语句。

第二种方式仅兼容 Android 4.4+ 和 iOS 8.0+，而相比第一种，它的优势在于可以获取到 JavaScript 的返回值，是官方提供的推荐通信方式。

# 调用 NATIVE 方法 #

结合目前各类主流的 JSSDK 实现，调用 NATIVE 方法的流程大致如下：![format_png][]

## 调用兼容方法 ##

我们把 JavaScript 调用**原生方法**或**监听原生事件**的入口称为**兼容方法**，通常**兼容方法**会根据**宿主环境**映射到一个特定的**原生方法**或**原生事件**监听器。

以 `toast()` 举例，该方法是一个通知客户端弹出有指定文字的的**兼容方法**，它在 JSSDK 中的实现可以是这样的：

import core from "./core"
    import rules from "./toast.rule"
    
    interface JSBridgeRequest {
      content: string
    }
    interface JSBridgeResponse {
      code: number
    }
    
    function toast(
      params?: JSBridgeRequest,
      callback?: (_: JSBridgeResponse) => void,
      options?: { namespace?: string; sdkVersion?: string | number }
    ) {
      return core.pipeCall(
        {
          method: "toast",
          params,
          callback,
          rules,
        }
      ) as Promise<JSBridgeResponse>
    }
    
    toast.rules = rules
    export default toast

此处，`core.pipeCall()` 为 JSSDK 中调用**原生方法**的核心入口，其中主要涉及到以下几个参数：

*  `method`: **兼容方法**的方法名称
 *  `params`: **兼容方法**的入参
 *  `callback`: 获取到 Native 返回后的回调函数，在业务代码中调用**兼容方法**时定义
 *  `rules`: **兼容方法**的规则，包括**映射的原生方法名、入参/出参预处理函数、宿主 ID**、**版本兼容信息**，可能存在复数个，后续会匹配出适用的一条**规则**，若没有的话则会报错并采用**兜底规则**

## SDK Bridge 入口 ##

进入 `pipeCall()` 后，接下来依次执行容器环境校验和 `onInvokeStart()` 生命周期函数。然后，会通过入参中的 `rules` 解析出 Native 可读的 `realMethod` 和`realParams`，以及回调中可能会用到的**出参预处理**和**环境信息：**

async pipeCall({ method, params, callback, rules }) {
        if (!isBrowser && this.container === 'web') {
          return Promise.resolve()
        }
        let config = {
          method,
          params,
        }
        if (this.onInvokeStart) {
          config = this.onInvokeStart(hookConfig)
        }
        const { realMethod, realParams, rule, env } = await this.transformConfig(method, params, rules)
        ...
    }

在 `transformConfig()` 中，会匹配适用**规则**、映射**原生方法**的名字、完成**入参预处理**：

async transformConfig(method, params, rules) {
        const env = this.env || (await this.getEnv)
        const rule = this.getRuleForMethod(env, rules) || {}
    
        let realMethod = (rule.map && rule.map.method) || method
    
        const realParams = rule.preprocess ? rule.preprocess(params, { env, bridge: this.bridge }) : params
        return { realMethod, realParams, rule, env }
      }

最后调用 SDK 注入的 `window.JSBridge.call()`。

在传入的回调中，依次做了**全局出参预处理**、**方法出参预处理**（ 从之前解析出的 `rule` 中获取）、执行业务代码中之前传入的**回调函数**，最后**执行环境变量的** `onInvokeEnd()` **生命周期函数**：

return new Promise((resolve, reject) => {
            this.bridge.call(
              realMethod,
              realParams,
              (realRes) => {
                let res = realRes
                try {
                  if (globalPostprocess && typeof globalPostprocess === 'function') {
                    res = globalPostprocess(res, { params, env })
                  }
                  if (rule.postprocess && typeof rule.postprocess === 'function') {
                    res = rule.postprocess(res, { params, env })
                  }
                } catch (error) {
                  if (this.onInvokeEnd) {
                    this.onInvokeEnd({ error: error, config: hookConfig })
                  }
                  reject(error)
                }
                if (typeof callback === 'function') {
                  callback(res)
                }
                resolve(res)
                if (this.onInvokeEnd) {
                  this.onInvokeEnd({ response: res, config: hookConfig })
                }
              },
              Object.assign(this.options, options),
            )
          })

## 调用 Bridge 方法 ##

`window.JSBridge.call()` 方法会根据入参拼出一条 `Message` 用于与 Native 通信，并会把传入的 `callback` 参数添加到全局的 `callbackMap` 属性中，用一个 `callbackId` 来标识。`Message` 的结构设计如下：

export interface JavaScriptMessage {
        func: string;    // 此处的 func 是原生方法名
        params: object;
        __msg_type: JavaScriptMessageType;
        __callback_id?: string;
        __iframe_url?: string;
    }

接着，会把拼好的 `Message` 通过 `window.JSBridge.sendMessageToNative()` 发给 Native，这里会出现两种情况：

private sendMessageToNative(message: JavaScriptMessage): void {
        if (String(message.JSSDK) !== "1" && this.nativeMethodInvoker) {
            const nativeMessageJSON = this.nativeMethodInvoker(message);
            /**
             * 如果该方法有返回，说明客户端采用了同步调用方式
             */
            if (nativeMessageJSON) {
                const nativeMessage = JSON.parse(nativeMessageJSON);
                this.handleMessageFromNative(nativeMessage);
            }
        } else {
            // 如果没有检测到注入的全局API，则fallback到iframe发起调用的方式
            this.javascriptMessageQueue.push(message);
            if (!this.dispatchMessageIFrame) {
                this.tryCreateIFrames();
                return;
            }
            this.dispatchMessageIFrame.src = `${this.scheme}${this.dispatchMessagePath}`;
        }
    }

### 注入式调用 ###

在 Native 注入 `JS2NativeBridge` 对象的情况下，SDK 初始化时会在 `window.JSBridge` 下添加 `nativeMethodInvoker` 方法，用于直接调用 Native 暴露的 Bridge API，入参为 JSON 格式的 `Message`：

const nativeMessageJSON = this.nativeMethodInvoker(message);
    /**
     * 如果该方法有返回，说明客户端采用了同步调用方式
     */
    if (nativeMessageJSON) {
        const nativeMessage = JSON.parse(nativeMessageJSON);
        this.handleMessageFromNative(nativeMessage);
    }

这里还会有两个分支，如果 Native 的实现是同步调用，那可以直接获取到结果，并由前端执行回调函数；如果实现是异步调用，那则会由客户端执行回调函数。

### 拦截式调用 ###

在 Native 没有注入 `JS2NativeBridge` 对象的情况下，会降级采用通过 `iframe` 命中 URL Scheme 的拦截策略。SDK 初始化时，会生成一个消息队列，用于临时存储待执行的 `Message` ，并在 Native 拦截到 URL 时进行消费：

// 如果没有检测到注入的全局API，则fallback到iframe发起调用的方式
    this.javascriptMessageQueue.push(message);
    if (!this.dispatchMessageIFrame) {
        this.tryCreateIFrames();
        return;
    }
    this.dispatchMessageIFrame.src = `${this.scheme}${this.dispatchMessagePath}`;

## SDK 初始化时的 Native 对象注入 ##

SDK 在初始化时，会根据 Native 的对象注入来创建对应的 `nativeMethodInvoker`：

/**
     * 探测客户端注入的调用API
     */
    export function detectNativeMethodInvoker(): NativeMethodInvoker|undefined {
      let nativeMethodInvoker;
    
      if (global.JS2NativeBridge && global.JS2NativeBridge._invokeMethod) { // 标准实现
          nativeMethodInvoker = (message: JavaScriptMessage) => {
              return global.JS2NativeBridge._invokeMethod(JSON.stringify(message));
          };
      }
    
      return nativeMethodInvoker;
    }

# 监听 NATIVE 事件 #

结合目前各类主流的 JSSDK 实现，监听 NATIVE 事件的流程大致如下：![format_png 1][]

## 调用兼容方法 ##

为了实现反向让 Native 调用 JavaScript 能力的，需要监听 Native 的原生事件来进行回调处理。以 `onAppShow()` 举例，该方法是 Native 通知 JavaScript 容器（ Activity 或 ViewController ）回到了前台，可以执行相应的回调函数：

import core from "./core"
    import rules from "./onAppShow.rule"
    
    interface JSBridgeRequest {}
    interface JSBridgeResponse {}
    
    interface Subscription {
      remove: () => void
      listener: (_: JSBridgeResponse) => void
    }
    
    function onAppShow(
      callback: (_: JSBridgeResponse) => void,
      once?: boolean
    ): Subscription {
      return core.pipeEvent({
        event: "onAppShow",
        callback,
        rules,
        once,
      })
    }
    
    onAppShow.rules = rules
    export default onAppShow

此处，`core.pipeEvent()` 为 JSSDK 中监听**原生事件**的核心入口，其中主要涉及到以下几个参数：

*  `event`: **兼容方法**的监听方法名称
 *  `callback`: 获取到**原生事件**后的回调函数，在业务代码中调用**兼容方法**时定义
 *  `rules`: **兼容方法**的规则，包括**映射的原生方法名、入参/出参预处理函数、宿主 ID**、**版本兼容信息**，可能存在复数个，后续会匹配出适用的一条**规则**，若没有的话则会报错并采用**兜底规则**
 *  `once`: 用于决定是否只调用 1 次

## SDK Bridge 入口 ##

进入 `pipeEvent()` 后，执行容器环境校验，然后通过入参中的 `rules` 完成**入参预处理、解析出 Native 可读的 `realMethod`，以及回调中可能会用到的出参预处理**（ 同调用 Native 方法 ），最后调用 SDK 注入的 `window.JSBridge.on()`。

在传入的回调中，依次做了**全局出参预处理**、**方法出参预处理**（ 从之前解析出的 `rule` 中获取 ），然后执行业务代码中之前传入的**回调函数**。

最后，`pipeEvent()` 会返回一个用于移除监听器的方法，以及传入的回调函数：

pipeEvent({ event, callback, rules, once }) {
        if (!isBrowser && this.container === 'web') {
          return {
            remove: () => {},
            listener: callback,
          }
        }
        const promise = this.transformConfig(event, null, rules)
    
        const excutor = promise.then(({ realMethod, rule, env }) => {
          function realCallback(realRes) {
            let res = realRes
            if (globalPostprocess && typeof globalPostprocess === 'function') {
              res = globalPostprocess(res, { env })
            }
            if (rule.postprocess && typeof rule.postprocess === 'function') {
              res = rule.postprocess(res, { env })
            }
            if (rule.postprocess) {
              if (realRes !== null) {
                // 约定如果返回除null以外的任何数据才调用callback
                callback(res)
              }
            } else {
              callback(res)
            }
          }
          const callbackId = this.bridge.on(realMethod, realCallback, once)
          return [realMethod, callbackId]
        })
        return {
          remove: () => {
            excutor.then(([realMethod, callbackId]) => {
              this.bridge.off(realMethod, callbackId)
            })
          },
          listener: callback,
        }
      }

## 调用 Bridge 监听方法 ##

`window.JSBridge.event()` 方法会把传入的 `callback` 参数添加到全局的 `callbackMap` 属性中，用一个 `callbackId` 来标识；接着，再将这一**原生事件**添加到全局的 `eventMap` 属性中，并把刚刚生成的 `callbackId` 绑定到 `eventMap` 中对应的**原生事件**上：

public on(
        event: string,
        callback: Callback,
        once: boolean = false
    ): string {
        if (
            !event ||
            typeof event !== 'string' ||
            typeof callback !== 'function'
        ) {
            return;
        }
        const callbackId = this.registerCallback(event, callback);
        this.eventMap[event] = this.eventMap[event] || {};
        this.eventMap[event][callbackId] = {
            once
        };
    }

## 移除 Bridge 监听方法 ##

public off(event: string, callbackId: string): boolean {
        if (!event || typeof event !== 'string') {
            return true;
        }
    
        const callbackMetaMap = this.eventMap[event];
        if (
            !callbackMetaMap ||
            typeof callbackMetaMap !== 'object' ||
            !callbackMetaMap.hasOwnProperty(callbackId)
        ) {
            return true;
        }
        this.deregisterCallback(callbackId);
        delete callbackMetaMap[callbackId];
        return true;
    }

\- END -

[![8b1462fc9729ab96beb5da827841a4dd.png][]][8b1462fc9729ab96beb5da827841a4dd.png 1]

## 关于奇舞团 ##

奇舞团是 360 集团最大的大前端团队，代表集团参与 W3C 和 ECMA 会员（TC39）工作。奇舞团非常重视人才培养，有工程师、讲师、翻译官、业务接口人、团队 Leader 等多种发展方向供员工选择，并辅以提供相应的技术力、专业力、通用力、领导力等培训课程。奇舞团以开放和求贤的心态欢迎各种优秀人才关注和加入奇舞团。

![2800251e341dc9f0b0d29a855cc961bf.png][]

[format_png]: /images/20220829/b247d62eea114950842bdd8722a4c324.png
[format_png 1]: /images/20220829/7af8a339481a4c09951a5ee6096bdb28.png
[8b1462fc9729ab96beb5da827841a4dd.png]: /images/20220829/c9265bee8d304953a00f2a27db240601.png
[8b1462fc9729ab96beb5da827841a4dd.png 1]: http://mp.weixin.qq.com/s?__biz=Mzg4MTYwMzY1Mw%3D%3D&chksm=cf61d698f8165f8e2b7f6cf4a638347c3b55b035e6c2095e477b217723cce34acbbe943ad537&idx=1&mid=2247496626&scene=21&sn=699dc2b117d43674b9e80a616199d5b6#wechat_redirect
[2800251e341dc9f0b0d29a855cc961bf.png]: /images/20220829/b9f9e8c9f33843788e966896ce82b95f.png