安全控制继电器
适用场景
适用于继电器操作会影响真实设备，并且调用方需要处理重试、结果不确定和多路继电器控制，避免产生重复副作用的场景。
推荐流程
同一台设备的一次控制应把继电器变化放入一个 relays 数组。一个批次只产生一条设备命令，可避免连续传输超过设备处理能力。
分步骤实现
- 通过设备类型定义列表确认支持
device.relay.set，并读取继电器数量和允许的 action。 - 构造目标继电器数组。单路控制传一个元素，多路控制传多个不重复的 index。
- 为本次操作意图生成新的
Idempotency-Key。 - 使用
device:control权限调用执行继电器命令。 - 保存
data.command.id并读取data.command.status。状态为SENT时，在有上限的轮询时间内调用查询命令结果。 - 设备确认中包含
data.state时直接使用。不要只为补齐这个可选字段再次刷新设备。 - 返回
TIMEOUT时，先读取设备当前状态，再决定是否适合执行新操作。
命令生命周期
| 结果 | 含义 | 客户端处理 |
|---|---|---|
HTTP 202 + COMMAND_ACCEPTED | 平台已接受请求；它不是独立的命令状态 | 读取 data.command.status 并保存命令 ID |
SENT | 命令仍在等待确认 | 有上限地查询命令结果 |
SUCCESS | 设备已确认执行 | 有返回状态时应用该状态 |
FAILED | 平台已确认命令未完成 | 停止自动重试并处理失败 |
TIMEOUT | 等待窗口内没有最终确认 | 不能认定设备已执行或未执行；先查询当前状态 |
关键接口
失败与恢复策略
- HTTP 网络中断导致是否受理未知时，使用相同
Idempotency-Key重试完全相同的请求。 - 收到
429 RATE_LIMITED后等待Retry-After，再使用原 key 重试同一操作。 - 不要把 key 用于不同设备、不同继电器数组或不同 action，否则会返回
IDEMPOTENCY_CONFLICT。 TIMEOUT后先刷新状态。如果状态仍无法确认，应先由业务判断是否允许再次执行物理操作。- 重复
JOG或其他设备动作可能产生真实副作用，即使上一条响应在网络中丢失。应设计确认流程和操作保护。
生产环境注意事项
- 将幂等键、命令 ID、请求的继电器数组、状态和
requestId一起保存，便于审计和恢复。 - 在应用层协调同一设备上的并发操作。
- 命令结果轮询必须有上限，并遵守限流响应。
- UI 或自动化规则允许控制前，应校验目标通道和设备操作安全性。