错误处理

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 有两级超时保护：

阶段	默认时长	说明
请求超时	10s	等待 Host 响应的超时时间
ACK 后超时	5min	Host 发送 ack 后的超时，用于用户交互操作

交互式操作（如 showDialog、showActionSheet）使用 timeout = 0，即不自动超时：

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

ACK 流程

SDK                         Host
 │ ── req ──────────────────► │
 │                            │ 收到请求，需要用户操作
 │ ◄─── ack ─────────────────│ "我收到了，正在处理"
 │                            │  ← 此时重置超时为 5min
 │   ... 用户操作中 ...       │
 │ ◄─── res ─────────────────│ 返回结果

getErrorMessage 工具函数

import { getErrorMessage } from 'mini-sdk'

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