Bridge 通信协议

Bridge 是 mini-sdk 与宿主环境（模拟器 / Native App）之间的消息通信层。所有 API 调用最终都通过 Bridge 传递。

架构概览

┌──────────────┐    Transport     ┌──────────────────┐
│   mini-sdk   │ ◄──────────────► │  宿主 (Host)      │
│              │   send/onMessage │  模拟器 / Native   │
│  bridge.call │ ──── req ──────► │                    │
│              │ ◄─── ack ─────── │  确认接收          │
│              │ ◄─── res ─────── │  返回结果          │
│  bridge.on   │ ◄─── evt ─────── │  推送事件          │
└──────────────┘                  └──────────────────┘

消息类型（BridgeKind）

Bridge 支持五种消息类型：

Kind	方向	说明
req	SDK → Host	请求调用，携带 type + name + payload
res	Host → SDK	响应结果，携带 result 或 error
ack	Host → SDK	确认接收，用于长时间交互操作（SSO、生物识别等）
evt	Host → SDK	事件推送（生命周期、路由变化等）
chunk	Host → SDK	流式数据块（大文件传输等）

BridgeEnvelope 消息格式

每条消息都封装在统一的信封格式中：

interface BridgeEnvelope<P = unknown, R = unknown> {
  v: number          // 协议版本（当前为 1）
  id?: number        // 请求序列号（req/res/ack/chunk 共享）
  kind: BridgeKind   // 消息类型
  type: BridgeType   // API 分类（Router / UI / Network 等）
  name: string       // 完整方法名，格式 "Type.methodName"
  ts?: number        // 时间戳
  payload?: P        // 请求参数
  result?: R         // 响应结果
  error?: BridgeError // 错误信息
}

Bridge 类

Bridge 是通信核心类，SDK 默认导出一个单例 bridge：

import { bridge, Bridge } from 'mini-sdk'

构造参数

const customBridge = new Bridge({
  defaultTimeout: 10000,    // 默认超时 10s
  defaultAckTimeout: 300000, // ACK 后超时 5min（用于交互操作）
  debug: false,              // 是否打印调试日志
})

bridge.call() — 发起请求

bridge.call<P, R>(
  type: BridgeType,   // API 分类
  name: string,       // 方法名
  payload?: P,        // 参数
  timeout?: number,   // 超时时间（ms），0 = 不超时
  onChunk?: (chunk: unknown) => void  // 流式回调
): Promise<R>

示例：

// 简单调用
const result = await bridge.call('Storage', 'get', { key: 'token' })

// 不超时（交互类操作）
const dialogResult = await bridge.call('UI', 'showDialog', {
  title: '提示',
  content: '确认删除？',
}, 0) // timeout = 0，等待用户操作

bridge.on() — 监听事件

const unsubscribe = bridge.on<P>(
  type: BridgeType,
  name: string,
  handler: (payload: P, envelope: BridgeEnvelope<P>) => void
): () => void  // 返回取消订阅函数

示例：

// 监听生命周期事件
const unsub = bridge.on('Lifecycle', 'show', (payload) => {
  console.log('页面显示')
})

// 取消监听
unsub()

bridge.destroy() — 销毁

bridge.destroy()

销毁时会：

1. 清除所有超时定时器
2. 以 BridgeDestroyed 错误拒绝所有挂起请求
3. 清除所有事件监听器
4. 释放 Transport 连接

BridgeType 分类

type BridgeType =
  | 'System'      // 系统握手
  | 'Router'      // 路由导航
  | 'UI'          // 界面交互
  | 'Network'     // 网络请求
  | 'Lifecycle'   // 页面生命周期
  | 'Storage'     // 数据存储
  | 'Clipboard'   // 剪贴板
  | 'Device'      // 设备能力
  | 'Auth'        // 认证鉴权
  | 'Analytics'   // 数据分析
  | 'Wallet'      // 钱包支付
  | 'Notification' // 通知推送
  | 'Vehicle'     // 车辆信息
  | 'Component'   // 组件操控
  | (string & {}) // 可扩展

Transport 层

Transport 负责实际的消息传输，根据运行环境自动选择：

环境	Transport 实现	传输方式
模拟器	SimulatorTransport	window.__MINIDEV__ IPC
iOS	NativeTransport	webkit.messageHandlers.MiniAppBridge
Android	NativeTransport	MiniAppBridge Java Bridge

import { createTransport } from 'mini-sdk'
const transport = createTransport() // 自动检测环境

握手协议

SDK 初始化时通过 woo.hello() 完成与宿主的握手：

// 自动调用，一般无需手动触发
await woo.hello()

握手流程：

1. SDK 发送 System.hello 请求，携带 SUPPORTED_PROTOCOL = 1
2. Host 返回 { role, protocol } 确认协议版本
3. 如果协议版本不匹配，SDK 打印警告但不阻断
4. 同时注册默认错误处理器（通过 Toast 显示未处理错误）