エラーハンドリング

BridgeError 構造

すべての API エラーは次の形式に従います。

interface BridgeError {
  code: number      // 错误码
  message: string   // 错误描述
  data?: unknown    // 附加数据（可选）
}

エラーコードの分類

エラーコードは 5 桁の規則に従います。

範囲	区分	説明
1xxxx	プロトコル/ルーティング	Bridge プロトコル上のエラー
2xxxx	権限/認証	ユーザー承認や認証に関する事項
4xxxx	クライアント	引数の不正、非対応など
5xxxx	内部	システム内部の例外

エラーコード一覧

enum BridgeErrorCode {
  // ── 协议错误 ──
  UnhandledApi     = 10001,  // API 未注册
  InvalidRequest   = 10002,  // 请求 ID 缺失或格式错误
  ProtocolMismatch = 10003,  // 协议版本不匹配

  // ── 超时 ──
  Timeout          = 40800,  // 请求超时（等待响应）
  TimeoutAfterAck  = 40801,  // ACK 后超时（用户交互超时）

  // ── 权限/认证 ──
  PermissionDenied = 20001,  // 用户拒绝权限
  AuthFailed       = 20002,  // 认证失败（凭证无效/过期）
  BiometricCancelled = 20003, // 用户取消生物识别

  // ── 客户端错误 ──
  InvalidParam     = 40001,  // 参数缺失或无效
  NotSupported     = 40002,  // 当前环境不支持该功能
  UserCancelled    = 40003,  // 用户取消操作
  NetworkUnavailable = 40004, // 网络不可用

  // ── 内部错误 ──
  InternalError    = 50000,  // 未知内部错误
  BridgeDestroyed  = 50900,  // Bridge 已销毁
}

エラーの捕捉

try/catch 方式

import woo from 'mini-sdk'
import { BridgeErrorCode } from 'mini-sdk'

try {
  const result = await woo.getLocation()
  console.log('位置：', result)
} catch (err) {
  switch (err.code) {
    case BridgeErrorCode.PermissionDenied:
      woo.showToast({ title: '请授权位置权限', icon: 'none' })
      break
    case BridgeErrorCode.Timeout:
      woo.showToast({ title: '请求超时，请重试', icon: 'none' })
      break
    case BridgeErrorCode.NotSupported:
      woo.showToast({ title: '当前环境不支持此功能', icon: 'none' })
      break
    default:
      woo.showToast({ title: err.message, icon: 'none' })
  }
}

Callback 方式

woo.getLocation({
  success(result) {
    console.log('位置：', result)
  },
  fail(err) {
    console.error(`错误 [${err.code}]: ${err.message}`)
  },
  complete() {
    console.log('调用完成')
  },
})

グローバルなエラーハンドリング

setErrorHandler で最終的なハンドラを登録します。

import { setErrorHandler } from 'mini-sdk'

setErrorHandler((message) => {
  // 所有未被业务代码 catch 的错误都会进入这里
  console.error('[全局错误]', message)
  woo.showToast({ title: message, icon: 'none', duration: 3000 })
})

デフォルトの挙動

SDK 初期化時（woo.hello()）に、未捕捉のエラーを Toast で表示するデフォルトのエラーハンドラが自動登録されます。setErrorHandler で上書きできます。

タイムアウト

Bridge には 2 段階のタイムアウト保護があります。

段階	既定値	説明
リクエスト	10 秒	Host の応答待ち
ACK 後	5 分	Host が ack を送ったあとの、ユーザー操作を伴うフロー向け

対話型操作（showDialog、showActionSheet など）では timeout = 0 とし、自動タイムアウトしません。

// showDialog 内部实现
bridge.call('UI', 'showDialog', payload, 0)
//                                       ^ timeout = 0，等待用户点击

ACK フロー

SDK                         Host
 │ ── req ──────────────────► │
 │                            │ 要求を受信。ユーザー操作が必要
 │ ◄─── ack ─────────────────│ 「受信済み、処理中」
 │                            │  ← この時点でタイムアウトを 5 分に再設定
 │   ... ユーザー操作中 ...   │
 │ ◄─── res ─────────────────│ 結果を返す

getErrorMessage ユーティリティ

import { getErrorMessage } from 'mini-sdk'

try {
  await woo.someApi()
} catch (err) {
  const message = getErrorMessage(err)
  // 统一转换为可读字符串
}