Skip to main content

​
WebSocket服务概述

WebSocket服务类型

提供三种类型的WebSocket连接：
  • 用户WebSocket（/v3/wss）
  • 应用WebSocket（/v3/wss/:appId）
  • 硬件WebSocket（/v3/wss/:hdId）

​
消息格式

所有WebSocket通信采用JSON-RPC 2.0协议格式：

​
请求格式

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {
    // 参数对象
  },
  "id": "请求ID"
}

​
响应格式

{
  "jsonrpc": "2.0",
  "result": {
    // 结果对象
  },
  "id": "请求ID"
}

​
通知格式

{
  "jsonrpc": "2.0",
  "method": "通知方法名",
  "params": {
    // 通知参数
  }
}

​
错误格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": 错误码,
    "message": "错误信息",
    "data": {
      // 错误详情
    }
  },
  "id": "请求ID"
}

​
连接生命周期

  1. 建立连接
    • 客户端发起WebSocket连接
    • 服务器验证认证信息
    • 连接成功后进入就绪状态
  2. 保持连接
    • 客户端定期发送心跳包
    • 服务器响应心跳确认
    • 超时未收到心跳则断开连接
  3. 断开连接
    • 正常断开：客户端发送关闭帧
    • 异常断开：网络故障或超时
    • 服务器清理相关资源
建议实现自动重连机制，在连接断开后尝试重新建立连接。

​
错误处理

错误码说明

错误码说明
-32700解析错误
-32600无效请求
-32601方法不存在
-32602无效参数
-32603内部错误
-32000服务器错误
-32001认证失败
-32002权限不足

​
最佳实践

  1. 连接管理
    • 实现指数退避的重连策略
    • 保持合理的心跳间隔（推荐30秒）
    • 优雅处理断开连接
  2. 消息处理
    • 实现消息队列和重试机制
    • 处理消息顺序和幂等性
    • 合理设置超时时间
  3. 错误处理
    • 实现错误重试策略
    • 记录详细的错误日志
    • 向用户提供友好的错误提示