JSBridge：连接 Web 与 Native 的通信桥梁

为什么需要 JSBridge
JSBridge 的核心原理
JSBridge 的设计与实现
JSBridge 的优缺点与应对策略
最佳实践
未来趋势
总结

为什么需要 JSBridge

在移动应用开发中，Native App 与 Web App 各有千秋：

Native App：极致性能、完整硬件访问（如 Face ID、AR）、流畅动画，但迭代慢、需双平台维护、更新依赖应用商店审核。
Web App：跨平台、热更新、开发效率高，但受沙箱限制，无法直接访问硬件，复杂场景下性能不如 Native。

Hybrid App 结合两者优势：

核心功能用 Native 保障体验
动态内容用 Web 实现快速迭代

JSBridge 正是实现两者无缝协作的关键桥梁，JSBridge 的使命：

功能互补：Web 调用摄像头、蓝牙等 Native 硬件能力。
体验优化：Native 控制 Web 页面的加载、缓存和动画渲染。
动态化：通过 Web 页面快速迭代，绕过应用商店审核。

典型应用场景：

电商 App（如淘宝、京东）：商品详情、活动页用 Web 快速上线新营销活动，支付、登录用 Native 保证安全。
企业级 App（如钉钉、企业微信）：审批流程、报表用 Web 实现跨端统一，扫码、推送用 Native。

JSBridge 的核心原理

通信的基础：WebView

WebView 是 Native App 内嵌的浏览器引擎，负责渲染 Web 内容并提供 JS 与 Native 的交互通道。

iOS: 使用 WKWebView（高性能，支持现代 API）。
Android: 使用 WebView 或基于 Chromium 的 WebView。

双向通信机制

JSBridge 的核心是双向方法调用与数据传递：

Native 调用 JavaScript：直接执行 JavaScript 字符串（如 evaluateJavaScript 或 loadUrl("javascript:..."））。
JavaScript 调用 Native：通过特定协议触发 Native 逻辑。

通信需注意主线程安全、数据序列化、错误处理。

JavaScript 调用 Native 的三种方式

URL Scheme 拦截 (早期方案)

原理：Web 通过修改 location.href 或隐式 <iframe> 发送自定义协议 URL，如 jsbridge://methodName?params=xxx，Native 拦截并解析 URL，执行对应逻辑。
优点：兼容性广，实现简单。
缺点：URL 长度受限，性能较低（频繁修改 location 可能引起页面抖动）。
适用场景：简单、低频调用，兼容旧设备。

注入全局 API (经典方案)

原理：Native 向 Web 的全局对象 window 注入一个对象，Web 直接调用该对象的方法。

// Web call Native method
window.NativeBridge?.share({
  title: `Hey Lee`,
  url: `https://banli.co`,
})

优点：调用直观，性能较好。
缺点：Android 低版本存在安全漏洞（需添加 @JavascriptInterface 注解）。
适用场景：中高频调用，现代设备。

MessageChannel 通信 (现代推荐方案)

原理：利用 WebView 的消息通道（如 iOS WKScriptMessageHandler、Android addJavascriptInterface）传递 JSON，结合 Promise 实现异步通信。
优点：现代 WebView 推荐方式，无 URL 长度限制、性能最高、安全性好、支持 Promise。
缺点：兼容性依赖 WebView 版本（如 iOS 需 WKWebView）。
适用场景：大数据传输、异步密集交互（如实时聊天、地图标注）。

JSBridge 的设计与实现

协议设计

通信双方需约定统一的协议格式，常见格式如下：

// request example
{
  "jsonrpc": "2.0",
  "id": "req_1234567890",
  "method": "camera.takePhoto",
  "params": {
    "quality": "high",
    "allowEdit": true
  }
}

// response example
{
  "jsonrpc": "2.0",
  "id": "req_1234567890",
  "result": {
    "base64": "data:image/jpegbase64,..."
  },
  "error": null
}

数据序列化：使用 JSON 传递结构化数据。
异步支持：通过 callbackID 关联请求与响应。

Native 端的实现

iOS（Swift + WKWebView）：

注册消息处理器：通过 WKScriptMessageHandler 监听 Web 消息。
解析与路由：根据 method 字段分发到对应的 Native 方法。
回调 JavaScript：使用 evaluateJavaScript 执行 Web 端的回调函数。

Android（Kotlin + WebView）：

注入 JavaScript 接口：通过 addJavascriptInterface 暴露 Native 方法。
参数解析：从 JSON 字符串中解析参数。
线程切换：确保回调 JavaScript 时在主线程执行。

Web 端的实现

class JSBridge {
  private callbacks = new Map<string, { resolve: Function reject: Function }>()
  private seq = 0

  constructor() {
    // listen for messages from Native
    window.addEventListener('message', (event) => {
      const data = event.data
      if (data && data.id && this.callbacks.has(data.id)) {
        const cb = this.callbacks.get(data.id)!
        data.error ? cb.reject(data.error) : cb.resolve(data.result)
        this.callbacks.delete(data.id)
      }
    })
  }

  call<T = any>(method: string, params: any = {}): Promise<T> {
    return new Promise((resolve, reject) => {
      const id = `req_${Date.now()}_${this.seq++}`
      this.callbacks.set(id, { resolve, reject })

      const message = { jsonrpc: '2.0', id, method, params }

      // send message to Native
      if (window.NativeBridge?.postMessage) {
        window.NativeBridge.postMessage(JSON.stringify(message))
      } else if ((window as any).webkit?.messageHandlers?.JSBridge?.postMessage) {
        (window as any).webkit.messageHandlers.JSBridge.postMessage(message)
      } else {
        // fallback URL Scheme
        const iframe = document.createElement('iframe')
        iframe.style.display = 'none'
        iframe.src = `jsbridge://${encodeURIComponent(JSON.stringify(message))}`
        document.body.appendChild(iframe)
        setTimeout(() => iframe.remove(), 100)
      }

      // timeout handling
      setTimeout(() => {
        if (this.callbacks.has(id)) {
          reject(new Error('JSBridge call timeout'))
          this.callbacks.delete(id)
        }
      }, 10000)
    })
  }

  // register methods for Native to call
  register(method: string, handler: Function) {
    (window as any)[method] = handler
  }
}

// usage example
const bridge = new JSBridge()

bridge.call('user.getInfo').then(info => console.log(info))

bridge.register('web.showToast', (msg: string) => alert(msg))

方法注册：在全局对象（如 window）上挂载供 Native 调用的函数。

通信封装：封装 callNative 方法，统一处理消息发送与回调。

class JSBridge {  
  constructor() {  
    this.callbacks = new Map()
    // 监听 Native 消息  
    window.addEventListener(`message`, (e) => {  
      const { method, params, callbackID } = e.data
      if (callbackID && this.callbacks.has(callbackID)) {  
        this.callbacks.get(callbackID)(params)
        this.callbacks.delete(callbackID)
      }  
    })
  }  

  callNative(method, params) {  
    return new Promise((resolve, reject) => {  
      const callbackID = `cb_${Date.now()}`
      this.callbacks.set(callbackID, resolve)
      // 发送消息给 Native  
      window.NativeBridge?.postMessage(  
        JSON.stringify({ method, params, callbackID })  
      )
    })
  }  
}

JSBridge 的优缺点与应对策略

优点

动态化能力：快速更新 Web 页面，无需发版审核。
复用代码：同一套 Web 代码适配 iOS 和 Android。
功能扩展：Web 可间接调用所有 Native 能力。

缺点与解决方案

性能问题

场景：频繁通信或大数据传输可能引发卡顿。优化：

合并多次调用（如批量上传日志）。
使用二进制协议（如 Protocol Buffers）替代 JSON。

安全性风险

风险点：XSS 攻击、恶意调用 Native API。
防御：
- 限制可调用的 Native 方法白名单。
- 对参数进行严格校验（如类型、范围）。

兼容性问题

常见问题：不同 WebView 内核的 API 差异（如 iOS UIWebView 已废弃）。
方案：
- 使用现代 WebView（如 iOS 的 WKWebView）。
- 封装跨平台一致的通信库。

最佳实践

协议标准化

采用 JSON-RPC 规范，定义统一的状态码和错误信息格式。

错误处理

添加超时机制（例如 5 秒未响应自动触发超时）。
Native 捕获异常后返回错误详情给 Web。

安全保障

通信链路加密（HTTPS）。
Native 方法调用权限分级（如区分用户权限）。

性能监控

统计通信耗时、成功率等指标。
使用长连接（如 WebSocket）替代短轮询。

未来趋势

更高效的通信方案：如基于 WebAssembly 的跨语言调用。跨平台框架整合：如 Flutter 通过自渲染引擎减少对 WebView 的依赖。

总结

JSBridge 是 Hybrid 开发的核心技术，它通过 WebView 的通信能力，将 Web 的动态化与 Native 的高性能结合。尽管存在性能、安全等挑战，但通过合理的协议设计、错误处理和性能优化，可以构建出稳定高效的混合应用。