重试与结果确认

理解默认重试、结果未知、请求 ID 和重复消息处理。

SDK 的默认策略是优先避免重复下发。查询和下载在特定网络失败时最多尝试两次；会修改数据或控制设备的调用只尝试一次。

默认尝试次数

下表次数包含第一次调用：

调用类型	默认最多尝试	说明
查询、列表、分页、状态	2	仅连接失败或超时时再次尝试
文件下载	2	失败尝试不会作为完整文件返回
任务下发、控制和取消	1	可能已经被平台接收
任务模板创建和删除	1	可能已经修改平台数据
设备、充电和摄像机控制	1	重复命令可能影响现场设备

HTTP 错误、平台明确返回的业务失败、参数错误和响应解析错误不会自动重试。

RequestOptions.RetryPolicy.NEVER 可以关闭查询或下载的默认重试，但不能强制重试写入和控制操作。

resultUnknown

写入或控制调用发生连接中断、读取超时等情况时，请求可能已经到达平台，但调用方没有收到最终响应。此时 SDK 异常会返回：

resultUnknown=true

它不表示成功或失败，而是表示当前结果尚未确认。处理顺序是：

1. 不要立即重复调用；
2. 保存异常中的 requestId、operation、code 和发生时间；
3. 通过查询 API、RocketMQ 消息或现场状态确认原操作是否生效；
4. 只有确认原操作没有生效，并且业务允许时，才重新执行。

常见确认方式：

原操作	建议确认方式
任务下发、控制、取消	查询任务执行记录或等待任务状态消息
任务模板创建、删除	查询模板详情或模板分页
四足狗控制	查询设备状态和实时坐标
摄像机或云台控制	结合设备状态或现场确认

requestId

requestId 用于关联一次 HTTP 调用的日志和异常。未设置时 SDK 会自动生成。

它不是业务幂等键，不能依靠重复使用相同 requestId 阻止重复操作。客户应用需要根据自己的业务标识判断任务、结果或消息是否已经处理。

RocketMQ 消息重复

RocketMQ 消息可能重复投递。业务 Handler 应能够重复处理同一条消息：

• 任务结果可使用 taskExecuteCode + devicePointCode 作为业务键；
• 文件列表可按 fileType + filePath 合并；
• 处理失败时抛出异常，让 RocketMQ 稍后重新投递；
• 不要把单个 JVM 内存中的 Set 当作长期去重方案；
• 日志只记录 Tag 和业务标识，不记录原始消息体。

四类消息和配置方式见RocketMQ 消息接入。