Bridge 通信プロトコル

Bridge は mini-sdk とホスト環境（シミュレータ / ネイティブアプリ）の間のメッセージ通信層です。すべての API 呼び出しは最終的に Bridge 経由で行われます。

アーキテクチャ概要

┌──────────────┐    Transport     ┌──────────────────┐
│   mini-sdk   │ ◄──────────────► │  ホスト (Host)    │
│              │   send/onMessage │  シミュレータ / ネイティブ │
│  bridge.call │ ──── req ──────► │                   │
│              │ ◄─── ack ─────── │  受信確認         │
│              │ ◄─── res ─────── │  結果返却         │
│  bridge.on   │ ◄─── evt ─────── │  イベント通知      │
└──────────────┘                  └──────────────────┘

メッセージ種別（BridgeKind）

Bridge は次の 5 種類のメッセージに対応します。

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 ブリッジ

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

ハンドシェイク

SDK 初期化時に woo.hello() によりホストとのハンドシェイクを完了します。

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

フローは次のとおりです。

1. SDK は SUPPORTED_PROTOCOL = 1 を付与して System.hello 要求を送る
2. Host は { role, protocol } を返し、プロトコルバージョンを確認する
3. プロトコルバージョンが一致しない場合、SDK は警告を出すが実行は止めない
4. あわせてデフォルトのエラーハンドラが登録される（未処理のエラーは Toast で表示）