JSBridge SDK

生产级 JSBridge SDK - 通过原生 log 能力实现监控和日志上报

✨ 核心特性

• 🎯 职责单一 - 只封装原生 API，不包含适配层
• 📱 双平台支持 - 兼容 Android 和 iOS
• 📊 统一日志管理 - 监控和业务日志都通过原生 log 上报
• 📝 提供 log API - 子应用可以上传业务日志
• 🔍 Debug 模式 - 支持开启调试模式和调用追踪
• 💪 类型安全 - 完整的 TypeScript 类型定义
• ⚡ 高性能 - 毫秒级初始化，内置竞态处理机制
• 📦 体积小 - 20KB（gzip: 7KB）

🎯 两个目的

1. ✅ 监控 SDK 稳定性 - SDK 自动记录性能和错误，通过原生 log 上报
2. ✅ 提供子应用日志能力 - 子应用调用 JSBridge.log.* 上传业务日志

🚀 快速开始

安装

npm install @hd-front-end/jsbridge-sdk

基础使用

import { init, JSBridge } from '@hd-front-end/jsbridge-sdk'

// 初始化
await init({
  monitor: {
    enabled: true,
    autoReport: true,        // 通过 log 自动上报
    logTag: 'JSBridge-Monitor'
  }
})

// 使用 bridge API
// SDK 会自动处理初始化等待，无需手动 check
const result = await JSBridge.scan()

// 上传业务日志
await JSBridge.log.info('用户点击了购买按钮', 'UserBehavior')
await JSBridge.log.error('支付失败', 'Payment')

调试模式

SDK 不再内置 vConsole，以减少包体积和避免依赖冲突。如果需要 vConsole，请在业务项目中自行安装。

// 业务代码中
import VConsole from 'vconsole'

if (process.env.NODE_ENV === 'development') {
  new VConsole()
  
  // 开启 SDK 调试模式
  init({
    debug: {
      enabled: true, // 开启后会在控制台输出详细的调用日志
      logLevel: 'debug'
    }
  })
}

📚 文档

快速入口

• docs/README.md - 📖 文档索引（从这里开始）
• docs/05-迁移指南.md - 🔄 Vue2/Vue3 集成指南
• docs/生产级-架构设计-v2.md - 🏗️ 完整架构
• docs/设计理念说明.md - 💡 设计理念（⭐ 必读）

详细文档

• 平台兼容性说明.md - Android/iOS 兼容
• 监控指南.md - 监控使用指南
• 新增桥接能力扩展说明.md - 新集成的业务级桥接能力及 UniApp 适配方法说明
• 更新日志.md - 版本演进历史
• 关键问题解答.md - 核心问题解答

工作总结

• 最终工作报告-v2.md - 完整工作总结
• 阶段3-总结.md - 集成测试与性能攻坚总结

🏗️ 架构设计

┌─────────────────────────────────────┐
│  子应用                              │
│  - 调用 JSBridge.log.info(...)      │
│  - 上传业务日志                      │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  @hd-front-end/jsbridge-sdk                   │
│  ├── 核心通信（Android/iOS）         │
│  ├── API 层（device/media/log...）  │
│  ├── 监控层（通过 log 上报）         │
│  └── Debug 层（调用追踪）           │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  原生 WebView                        │
│  ├── log handler                    │
│  ├── LogUtil 写入日志文件            │
│  └── 统一上传到服务器                │
└─────────────────────────────────────┘

💻 核心 API

Bridge API

// 扫码
const result = await JSBridge.scan()

// 拨打电话
await JSBridge.makePhoneCall({ phoneNumber: '10086' })

// 震动
await JSBridge.vibrate()

// 获取设备信息
const info = await JSBridge.getDeviceInfo()

Log API

// 记录日志
await JSBridge.log.info('操作成功', 'Business')
await JSBridge.log.error('接口异常', 'Network', { status: 500 })