aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/IoT设备API.md

IoT设备API

**本文引用的文件** - [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java) - [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java) - [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java) - [IotDeviceServiceInvokeReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/IotDeviceServiceInvokeReqDTO.java) - [ResetTrafficCounterReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/ResetTrafficCounterReqDTO.java) - [DevicePropertyBatchQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyBatchQueryReqDTO.java) - [DevicePropertyHistoryQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryQueryReqDTO.java) - [DevicePropertyRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyRespDTO.java) - [DevicePropertyHistoryRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryRespDTO.java) - [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java) - [ApiConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ApiConstants.java) - [IotDeviceMessageTypeEnum.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/device/IotDeviceMessageTypeEnum.java)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论
10. 附录

简介

本文件为IoT设备管理模块的全面API接口文档，涵盖设备控制、属性查询、状态监控等核心功能。文档详细说明了设备连接认证机制、设备属性定义和数据格式规范，并提供了设备远程控制命令的接口规范、控制指令格式和响应处理方式。同时，文档还详细描述了设备属性查询接口（包括实时属性获取和历史数据查询）、设备状态监控接口（在线状态、运行状态和故障状态的查询方法），以及设备OTA升级接口和固件版本管理API。

项目结构

IoT模块采用分层架构设计，主要由以下部分组成：

• API接口层：定义对外暴露的Feign客户端接口
• DTO数据传输对象：定义请求和响应的数据结构
• 枚举类：定义设备消息类型、状态枚举等常量
• 核心业务逻辑：在IoT服务器中实现具体的业务处理

graph TB
subgraph "IoT模块"
API[API接口层]
DTO[DTO数据传输对象]
ENUM[枚举类]
CORE[核心业务逻辑]
end
subgraph "外部系统"
OPS[运维系统]
APP[移动端应用]
WEB[Web管理平台]
end
OPS --> API
APP --> API
WEB --> API
API --> DTO
API --> ENUM
API --> CORE
CORE --> DTO
CORE --> ENUM

图表来源

• IotDeviceControlApi.java
• IotDevicePropertyQueryApi.java
• IotDeviceStatusQueryApi.java

章节来源

• IotDeviceControlApi.java
• IotDevicePropertyQueryApi.java
• IotDeviceStatusQueryApi.java

核心组件

IoT设备管理模块的核心组件包括三个主要的Feign客户端接口：

设备控制API接口

提供设备远程控制能力，支持服务调用、批量服务调用和客流计数器重置功能。

设备属性查询API接口

提供设备属性的实时查询和历史数据查询功能，支持单个属性查询、批量属性查询和历史数据查询。

设备状态查询API接口

提供设备在线状态和设备状态信息的查询功能。

章节来源

• IotDeviceControlApi.java
• IotDevicePropertyQueryApi.java
• IotDeviceStatusQueryApi.java

架构概览

IoT设备管理模块采用微服务架构，通过Feign客户端进行服务间通信。整体架构分为三层：

graph TB
subgraph "表现层"
CLIENT[客户端应用]
end
subgraph "网关层"
GATEWAY[API网关]
end
subgraph "服务层"
IOT_SERVER[IoT服务器]
DEVICE_SERVICE[设备服务]
DATA_SERVICE[数据服务]
end
subgraph "基础设施层"
DATABASE[(数据库)]
REDIS[(Redis缓存)]
MQ[(消息队列)]
end
CLIENT --> GATEWAY
GATEWAY --> IOT_SERVER
IOT_SERVER --> DEVICE_SERVICE
IOT_SERVER --> DATA_SERVICE
DEVICE_SERVICE --> DATABASE
DEVICE_SERVICE --> REDIS
DEVICE_SERVICE --> MQ
DATA_SERVICE --> DATABASE
DATA_SERVICE --> REDIS

图表来源

• ApiConstants.java

详细组件分析

设备控制API组件

控制接口定义

设备控制API提供以下核心功能：

sequenceDiagram
participant Client as 客户端
participant API as 设备控制API
participant Server as IoT服务器
participant Device as 设备
Client->>API : 调用设备服务
API->>Server : RPC调用
Server->>Device : 发送控制指令
Device-->>Server : 返回执行结果
Server-->>API : 返回响应
API-->>Client : 返回控制结果

图表来源

• IotDeviceControlApi.java

服务调用请求DTO

服务调用请求包含以下关键字段：

• 设备ID：唯一标识目标设备
• 服务标识符：指定要调用的服务类型
• 服务参数：服务执行所需的参数
• 超时时间：服务执行的超时设置

批量服务调用

支持一次性对多个设备执行相同的服务调用，提高操作效率。

客流计数器重置

提供客流计数器的基准值重置功能，支持工单创建后的计数器调整。

章节来源

• IotDeviceControlApi.java
• IotDeviceServiceInvokeReqDTO.java
• ResetTrafficCounterReqDTO.java

设备属性查询API组件

实时属性查询

提供设备属性的实时查询能力，支持单个属性查询和批量属性查询：

flowchart TD
Start([开始查询]) --> CheckType{查询类型}
CheckType --> |单个属性| SingleQuery[单个属性查询]
CheckType --> |批量属性| BatchQuery[批量属性查询]
CheckType --> |最新属性| LatestQuery[最新属性查询]
SingleQuery --> GetDevice[获取设备信息]
BatchQuery --> GetDevices[获取设备列表]
LatestQuery --> GetCache[获取缓存数据]
GetDevice --> QueryDB[查询数据库]
GetDevices --> QueryDB
QueryDB --> ProcessData[处理查询结果]
GetCache --> ProcessData
ProcessData --> ReturnResult[返回查询结果]
ReturnResult --> End([结束])

图表来源

• IotDevicePropertyQueryApi.java

历史数据查询

支持按时间范围查询设备属性的历史数据，包含以下查询条件：

• 设备ID：指定查询的目标设备
• 属性标识符：指定查询的属性类型
• 开始时间和结束时间：限定查询的时间范围
• 限制条数：控制返回数据的最大数量

属性数据格式

属性查询返回的数据包含以下字段：

• 属性标识符：属性的唯一标识
• 属性值：当前或历史的属性数值
• 更新时间：数据的更新时间戳

章节来源

• IotDevicePropertyQueryApi.java
• DevicePropertyBatchQueryReqDTO.java
• DevicePropertyHistoryQueryReqDTO.java
• DevicePropertyRespDTO.java
• DevicePropertyHistoryRespDTO.java

设备状态查询API组件

在线状态检测

提供设备在线状态的实时检测功能，通过以下方式判断设备状态：

• 心跳检测：基于设备的心跳包判断在线状态
• 缓存查询：从Redis缓存中获取最新的设备状态
• 最近活动时间：根据设备最近的消息活动时间判断状态

设备状态信息

状态查询返回的设备状态信息包含：

• 设备ID：唯一标识设备
• 设备编码：设备的业务编码
• 设备状态：设备的当前状态（激活、在线、离线）
• 状态变更时间：状态最后一次变更的时间

stateDiagram-v2
[*] --> INACTIVE
INACTIVE --> ONLINE : 设备上线
INACTIVE --> OFFLINE : 设备离线
ONLINE --> OFFLINE : 设备下线
OFFLINE --> ONLINE : 设备重新上线
ONLINE --> INACTIVE : 设备注销
OFFLINE --> INACTIVE : 设备注销

图表来源

• DeviceStatusRespDTO.java

章节来源

• IotDeviceStatusQueryApi.java
• DeviceStatusRespDTO.java

设备消息类型定义

消息类型枚举

IoT设备支持多种消息类型，每种类型对应不同的业务场景：

消息类型	描述	用途
STATE	设备状态	设备运行状态的上报和查询
PROPERTY	设备属性	设备属性值的上报和查询
EVENT	设备事件	设备事件的上报和订阅
SERVICE	设备服务	设备服务的调用和执行
CONFIG	设备配置	设备配置的远程下发
OTA	设备OTA	设备固件的远程升级
REGISTER	设备注册	设备的身份注册和认证
TOPOLOGY	设备拓扑	设备间的拓扑关系管理

章节来源

• IotDeviceMessageTypeEnum.java

依赖关系分析

组件依赖图

IoT设备管理模块的组件间依赖关系如下：

graph TB
subgraph "API层"
CONTROL_API[IotDeviceControlApi]
PROPERTY_API[IotDevicePropertyQueryApi]
STATUS_API[IotDeviceStatusQueryApi]
end
subgraph "DTO层"
SERVICE_REQ[IotDeviceServiceInvokeReqDTO]
RESET_REQ[ResetTrafficCounterReqDTO]
BATCH_REQ[DevicePropertyBatchQueryReqDTO]
HISTORY_REQ[DevicePropertyHistoryQueryReqDTO]
PROPERTY_RESP[DevicePropertyRespDTO]
HISTORY_RESP[DevicePropertyHistoryRespDTO]
STATUS_RESP[DeviceStatusRespDTO]
end
subgraph "枚举层"
API_CONST[ApiConstants]
MSG_TYPE[IotDeviceMessageTypeEnum]
end
CONTROL_API --> SERVICE_REQ
CONTROL_API --> RESET_REQ
PROPERTY_API --> BATCH_REQ
PROPERTY_API --> HISTORY_REQ
PROPERTY_API --> PROPERTY_RESP
PROPERTY_API --> HISTORY_RESP
STATUS_API --> STATUS_RESP
CONTROL_API --> API_CONST
PROPERTY_API --> API_CONST
STATUS_API --> API_CONST
CONTROL_API --> MSG_TYPE
PROPERTY_API --> MSG_TYPE
STATUS_API --> MSG_TYPE

图表来源

• IotDeviceControlApi.java
• IotDevicePropertyQueryApi.java
• IotDeviceStatusQueryApi.java

服务间通信流程

设备控制、属性查询、状态查询三类API通过统一的RPC前缀进行通信：

sequenceDiagram
participant Client as 客户端
participant ControlAPI as 设备控制API
participant PropertyAPI as 属性查询API
participant StatusAPI as 状态查询API
participant Server as IoT服务器
Client->>ControlAPI : 设备控制请求
ControlAPI->>Server : RPC调用
Server-->>ControlAPI : 控制结果
Client->>PropertyAPI : 属性查询请求
PropertyAPI->>Server : RPC调用
Server-->>PropertyAPI : 查询结果
Client->>StatusAPI : 状态查询请求
StatusAPI->>Server : RPC调用
Server-->>StatusAPI : 状态信息

图表来源

• ApiConstants.java

章节来源

• ApiConstants.java

性能考虑

IoT设备管理模块在设计时充分考虑了性能优化：

缓存策略

• 实时属性查询优先从Redis缓存获取，减少数据库访问压力
• 设备状态信息使用缓存机制，提高查询响应速度
• 历史数据查询支持分页和时间范围限制，避免大数据量查询

批量操作优化

• 批量属性查询支持多设备、多属性的并行处理
• 批量服务调用减少网络往返次数
• 批量重置客流计数器支持事务性操作

连接池管理

• 使用连接池管理数据库连接，提高连接复用率
• 消息队列采用异步处理机制，提升系统吞吐量
• 缓存操作使用连接池，减少连接建立开销

故障排除指南

常见问题及解决方案

设备不在线

问题现象：调用设备服务时返回失败 可能原因：

• 设备未正确注册到平台
• 设备网络连接异常
• 设备心跳包丢失

解决步骤：

1. 检查设备状态查询接口返回的状态
2. 验证设备的网络连接情况
3. 确认设备是否正常发送心跳包

属性查询超时

问题现象：属性查询请求超时 可能原因：

• 设备离线或无响应
• 数据库查询性能问题
• 缓存未命中导致的延迟

解决步骤：

1. 检查设备在线状态
2. 优化数据库查询索引
3. 调整缓存策略和超时时间

批量操作失败

问题现象：批量操作中部分设备执行失败 可能原因：

• 某些设备网络异常
• 设备服务调用超时
• 数据格式不匹配

解决步骤：

1. 分析批量操作的错误日志
2. 对失败的设备单独重试
3. 验证设备服务的可用性

章节来源

• DeviceStatusRespDTO.java
• IotDevicePropertyQueryApi.java

结论

IoT设备管理模块提供了完整的设备生命周期管理能力，包括设备控制、属性查询、状态监控等功能。通过标准化的API接口和数据传输对象，实现了设备与系统的解耦，提高了系统的可扩展性和可维护性。模块采用微服务架构设计，支持高并发场景下的稳定运行，为IoT应用场景提供了可靠的技术支撑。

附录

API接口规范汇总

设备控制接口

• 服务调用：POST /rpc/iot/device/control/invoke-service
• 批量服务调用：POST /rpc/iot/device/control/invoke-service-batch
• 重置客流计数器：POST /rpc/iot/device/control/reset-traffic-counter

设备属性查询接口

• 单个属性查询：GET /rpc/iot/device/property/get
• 最新属性查询：GET /rpc/iot/device/property/get-latest
• 批量属性查询：POST /rpc/iot/device/property/batch-get
• 属性历史查询：POST /rpc/iot/device/property/history

设备状态查询接口

• 在线状态检测：GET /rpc/iot/device/status/is-online
• 设备状态查询：GET /rpc/iot/device/status/get-status

数据模型定义

设备状态枚举

• INACTIVE：设备未激活
• ONLINE：设备在线
• OFFLINE：设备离线

设备消息类型

• STATE：设备状态消息
• PROPERTY：设备属性消息
• EVENT：设备事件消息
• SERVICE：设备服务消息
• CONFIG：设备配置消息
• OTA：设备OTA消息
• REGISTER：设备注册消息
• TOPOLOGY：设备拓扑消息

章节来源

• IotDeviceMessageTypeEnum.java
• DeviceStatusRespDTO.java