REST API 和 WebSocket 如何选择

WLTE 同时提供 REST API 和 WebSocket。两者不是互相替代的关系，而是面向不同接入场景的两种通道。

基本原理

REST API 是标准请求-响应模型。你的服务端发起一次 HTTPS 请求，WLTE 返回一次明确结果。它适合获取列表、查询资源、提交操作和查询操作结果。

WebSocket 是长连接模型。你的服务端先通过 REST 创建一次性 wsTicket，再建立 wss 连接。连接建立后，可以在同一条连接上发送请求，也可以接收设备事件。

核心差别

维度	REST API	WebSocket
连接方式	每次请求独立建立 HTTP 调用	建立长连接后持续复用
使用方式	请求一次，返回一次	发送 request，接收 reply，也可接收 event
适合场景	列表、分页、配置、命令提交、结果查询	实时状态查询、低延迟交互、事件通知
可靠性模型	请求结果明确，失败后可按 HTTP 规则重试	长连接可能断开，断线期间事件不保证补发
权限处理	每个受保护端点都会校验当前权限	建连需要 ticket；主动请求仍按操作校验权限
请求保护	查询和设备操作均有频率保护	连接、消息和设备操作均有频率保护
接入复杂度	更简单，适合大多数服务端集成	更复杂，需要处理心跳、重连和事件幂等

何时使用 REST API

优先使用 REST API，如果你的需求是：

展示账号下的设备列表
分页加载设备
查询设备类型定义
创建继电器、RS485 或配置类操作
查询命令结果
服务端定时同步状态
需要清晰的 HTTP 状态码和业务错误码

典型流程：

text

获取 access token
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

何时使用 WebSocket

考虑使用 WebSocket，如果你的服务端需要：

长时间在线接收设备事件
对单台设备发起低延迟实时状态查询
在一个服务进程中维护实时设备状态
减少频繁建立 HTTP 请求带来的延迟

典型流程：

text

获取 access token
-> POST /wlte/v1/ws/ticket
-> 建立 wss://.../wlte/v1/ws?ticket=...
-> 发送 session.ping 保持应用层心跳
-> 发送 device.state.get 查询单台设备实时状态
-> 发送 device.operation.execute 执行设备操作
-> 接收设备事件

常见误区

用 WebSocket 刷新账号下所有设备

不建议。device.state.get 面向单台设备实时状态查询，会触发实时刷新和设备级限流。账号设备列表应使用查询设备列表。

认为 WebSocket 永远不会断

不成立。网络、部署、代理、服务重启和客户端进程重启都可能导致断线。客户端必须实现重连、心跳和幂等处理。

认为 WebSocket 事件可以替代全部状态查询

不建议。WebSocket 用于实时通知变化，但不是唯一永久状态来源。发现状态缺口、页面重新加载或服务重启后，应使用 REST API 或 device.state.get 重新确认状态。

简单决策表

需求	推荐
首次接入、验证 API 是否可用	REST API
展示设备列表	REST API
用户打开单个设备详情页并点击刷新	REST API `GET /devices/{deviceId}` 或 WS `device.state.get`
服务端需要持续接收设备变化	WebSocket
执行设备控制	REST API；已维护 WebSocket 连接时也可使用 `device.operation.execute`
查询命令最终结果	REST API
WebSocket 断线后恢复状态	REST API 重新同步，再继续 WebSocket

REST API 和 WebSocket 如何选择 ​

基本原理 ​

核心差别 ​

何时使用 REST API ​

何时使用 WebSocket ​

推荐组合方式 ​

常见误区 ​

用 WebSocket 刷新账号下所有设备 ​

认为 WebSocket 永远不会断 ​

认为 WebSocket 事件可以替代全部状态查询 ​

简单决策表 ​