构建设备监控看板
适用场景
适用于展示账号下设备连接状态和外设数据的看板，同时让 HTTP 请求量保持可控。
- 使用 REST 设备列表完成首次展示、分页和后台同步。
- 用户主动刷新详情页或操作前后需要确认时，查询单台设备。
- 使用 WebSocket 持续接收连接状态以及继电器、数字输入的状态变化。
不要通过 HTTP 持续轮询账号下的每一台设备。
推荐架构
按 deviceId 维护一份设备状态。合并运行状态时比较 stateUpdatedAt，避免旧数据覆盖新数据。连接事件用于更新连接状态；device.state.changed 的 changes 标识发生变化的继电器或数字输入，peripherals 是完整状态块，不是增量字段。模拟量和传感器读数需要在用户主动刷新或业务需要时查询，不要对所有设备高频轮询。
分步骤实现
- 使用具有
device:read权限的 API Client 获取 access token。 - 调用查询设备列表，按分页读取并保存设备的
deviceType、status、外设数据和stateUpdatedAt。 - 获取设备类型定义列表，把每个
deviceType映射到能力定义。缓存定义，不要每次渲染都重新请求。 - 创建一次性 WebSocket Ticket，建立连接并启动文档规定的心跳。
- 根据
deviceId应用device.connection.online、device.connection.offline和device.state.changed事件。 - 用户明确要求刷新单台设备时，调用查询设备详情，或发送
device.state.get。 - WebSocket 断开或服务重启后，使用新 ticket 重连，并先通过 REST 重建状态基线。只对业务关键设备逐台确认。
关键接口与事件
| 用途 | 文档 |
|---|---|
| 首次设备列表和分页 | 查询设备列表 |
| 按能力渲染 UI | 查询设备类型定义列表 |
| 用户主动刷新单台设备 | 查询设备详情 |
| WebSocket 鉴权 | 创建 WebSocket Ticket |
| 在线和离线变化 | 设备连接事件 |
| 外设状态变化 | 设备状态变化事件 |
失败与恢复策略
- WebSocket 断开后，将实时通道标记为不可用，使用带随机抖动的指数退避重连，并为每次连接创建新的
wsTicket。 - 断线期间的事件不会补发。重连后通过 REST 重建状态基线。
- 事件与查询并发到达时，保留
stateUpdatedAt更新的数据。 - 收到
429 RATE_LIMITED后等待Retry-After。不要在 WebSocket 断开时改为逐台高频轮询。 OFFLINE设备可能仍带有最后一次同步的外设状态。连接状态和状态数据的新鲜度应分别展示。
生产环境注意事项
- 按
deviceId保存规范化状态；传感器读数使用index + type标识。 - 事件处理必须可重复执行。连接事件提供
occurredAt，状态事件提供stateUpdatedAt；已经应用的旧更新应被忽略。 - 需要长期保留的业务事件应及时落库，因为 WebSocket 不提供历史补发。
- 监控重连次数、事件延迟、REST 同步失败和
requestId，但不要记录凭证或 token。