WebSocket 类详细文档

概述

WebSocket 类是 SDK 中用于实现实时双向通信的核心组件。它提供了连接管理、消息发送接收、自动重连、缓存池等高级功能。

构造函数

constructor(option = {}, route = 'addons')

参数说明

参数	类型	默认值	说明
option	Object	{}	配置选项对象
route	String	'addons'	路由类型，决定使用哪个服务器地址

配置选项 (option)

属性	类型	默认值	说明
url	String	-	addons 服务器 WebSocket 地址
authUrl	String	-	认证服务器 WebSocket 地址
reconnection	Boolean	true	是否自动重连
buffer	Boolean	true	是否启用缓存池
heartRate	Number	60000	心跳间隔（毫秒）
heartRateType	String	'HEARTBEAT'	心跳消息类型
project_id	String	-	项目ID
app_id	String	-	应用ID
app_secret	String	-	应用密钥
device_id	String	-	设备ID
autoEmitBuffer	Boolean	false	是否自动发送缓存池数据

事件系统

WebSocket 类实现了完整的事件发布订阅模式，支持多种事件监听方式：

通配符监听

// 监听所有消息
websocket.on('*', (message) => {
  console.log('所有消息:', message)
})

// 监听所有事件（除了指定的）
websocket.on('**', (message) => {
  console.log('所有事件:', message)
})

特定事件监听

// 监接特定类型的消息
websocket.on('temp_secret_res', (message) => {
  console.log('临时密钥响应:', message)
})

// 监听命令响应
websocket.on('command_res', (message) => {
  console.log('命令响应:', message)
})

一次性监听

// 只处理一次的事件监听器
websocket.on('one_time_event', (message) => {
  console.log('仅处理一次:', message)
}, true) // single 参数设为 true

消息发送

emit 方法

async emit(event, param = {}, addons = '', controller = '', action = '')

发送消息到服务器。

参数说明

参数	类型	默认值	说明
event	String	-	消息类型
param	Object	{}	消息参数
addons	String	''	插件名称
controller	String	''	控制器名称
action	String	''	动作名称

使用示例

// 发送设备控制命令
websocket.emit("operation", {
  "device_id": 123,
  "id": 456,
  "imei": "device_mac"
}, 'yrddtu', 'dtu', 'command')

// 发送心跳
websocket.emit('HEARTBEAT')

// 发送认证请求
websocket.emit("temp-secret", {
  'app_id': 'your_app_id',
}, 'auth', 'addons', 'temp-secret')

连接管理

连接状态

// 获取当前连接状态
async getState() 
// 返回值：0-连接中，1-连接成功，2-重连中，3-失败

连接控制

// 初始化连接（在构造函数中自动调用）
await init()

// 手动连接
await connection()

// 关闭连接
await close()

// 重新连接
await reconnection()

缓存池机制

为了在网络不稳定的情况下保证消息不丢失，SDK 实现了缓存池机制：

缓存池操作

// 添加消息到缓存池
await addBuffer(data)

// 根据事件类型获取缓存
await getBuffer(event)

// 根据事件类型删除缓存
await removeBufferByEvent(event)

// 删除所有缓存
await removeBufferAll()

// 发送缓存池中的数据
await sendBufferRegister()

缓存池数据结构

{
  event: String,      // 事件类型
  param: Object,      // 消息参数
  addons: String,     // 插件名称
  controller: String, // 控制器名称
  action: String      // 动作名称
}

心跳机制

WebSocket 类内置了心跳机制来维持连接活跃：

// 开始发送心跳
await beginSendHeartBeat()

// 停止心跳
await killApp()

心跳间隔由 heartRate 配置项控制，默认为 60 秒。

事件监听器管理

注册事件监听器

// 注册监听器
await on(event, handler, single = false)

移除事件监听器

// 移除指定事件的所有监听器
await removeEventByName(name)

// 移除指定监听器
off(event, handler)

特殊事件类型

WebSocket 类预定义了一些特殊事件类型，用于处理特定场景：

temp_secret_res

临时密钥响应事件

websocket.on('temp_secret_res', (message) => {
  if (message.code === 200) {
    uni.setStorageSync('app_secret', message.data.temp_secret)
  }
})

app_secret_error

临时密钥过期事件

websocket.on('app_secret_error', (message) => {
  // 重新获取临时密钥
  websocket.emit("temp-secret", {
    'app_id': $ddiot.appId,
  }, 'auth', 'addons', 'temp-secret')
})

command_res

命令响应事件

websocket.on('command_res', (message) => {
  if (message.code === 200) {
    uni.showLoading({
      title: message.message
    })
    setTimeout(() => {
      uni.hideLoading()
    }, 1000)
  }
})

heart_res

心跳响应事件

websocket.on('heart_res', (message) => {
  console.log('收到心跳响应:', message)
})

operation_error 和 operation_success

操作错误和成功事件

websocket.on('operation_error', (message) => {
  console.log('操作错误:', message)
})

websocket.on('operation_success', (message) => {
  console.log('操作成功:', message)
  // 从缓存池中移除相关消息
  if (websocket.removeBufferByEvent) {
    websocket.removeBufferByEvent(message.event)
  }
})

错误处理

连接错误

websocket.on('error', (err) => {
  console.error('连接错误:', err)
})

websocket.on('reconnectionerror', (err) => {
  console.error('重连错误:', err)
})

消息发送错误

消息发送失败时，SDK 会自动将消息加入缓存池，待连接恢复后重新发送。

实际应用示例

设备控制场景

// 初始化 WebSocket
const websocket = new Socket({
  url: "wss://iot.ddicms.com:9502/addons",
  authUrl: 'wss://iot.ddicms.com:9502/auth',
  heartRate: 20000,
  app_id: 'your_app_id',
  app_secret: 'your_app_secret'
})

// 监听连接状态
websocket.on('connectioned', () => {
  console.log('WebSocket 连接成功')
})

// 发送设备控制命令
const controlDevice = (deviceId, instructionId, deviceMac) => {
  websocket.emit("operation", {
    "device_id": Number(deviceId),
    "id": instructionId,
    "imei": deviceMac,
  }, 'yrddtu', 'dtu', 'command')
}

// 监听命令执行结果
websocket.on('command_res', (message) => {
  if (message.code === 200) {
    console.log('命令执行成功:', message)
  } else {
    console.log('命令执行失败:', message)
  }
})

// 监听操作结果
websocket.on('operation_success', (message) => {
  uni.showToast({
    title: '操作成功',
    duration: 1500
  })
})

数据接收场景

// 监听设备数据更新
websocket.on('device_data_update', (message) => {
  console.log('设备数据更新:', message)
  // 更新界面显示
  updateDeviceData(message.data)
})

// 监听所有消息
websocket.on('*', (message) => {
  console.log('收到消息:', message)
})

性能优化建议

合理设置心跳间隔: 过短的心跳间隔会增加服务器负载，过长可能导致连接被服务器断开
及时清理监听器: 避免在组件销毁后仍保留事件监听器
批量发送消息: 在可能的情况下，合并多个小消息为一个大消息发送
缓存池大小控制: 监控缓存池大小，避免无限增长
连接复用: 在应用生命周期内复用同一个 WebSocket 连接

注意事项

确保在发送消息前检查连接状态
正确处理临时密钥过期情况
在页面切换或应用退到后台时考虑是否需要保持连接
错误处理应该包含用户友好的提示
考虑网络环境变化对 WebSocket 连接的影响