设备信息API

引用文件

本文档引用的文件

简介

本文件详细说明了设备信息管理API的设计与实现，涵盖设备信息查询接口、设备信息修改接口、设备状态监控接口等核心功能。文档重点阐述了设备数据结构、信息字段定义、修改权限控制、状态同步机制，并提供了设备信息更新示例、数据验证规则和性能优化建议。

项目结构

设备相关模块采用分层架构设计，主要分为API接口层、业务实现层、数据访问层和数据对象层：

Mermaid Diagram Code:

graph TB
subgraph "API接口层"
DeviceApi["DeviceApi 接口"]
DeviceModifyRespDTO["DeviceModifyRespDTO"]
DeviceRespDTO["DeviceRespDTO"]
end
subgraph "业务实现层"
DeviceApiImpl["DeviceApiImpl 实现"]
DeviceServiceImpl["DeviceServiceImpl 实现"]
AppDeviceHeartBeatController["AppDeviceHeartBeatController 控制器"]
end
subgraph "数据访问层"
DeviceMapper["DeviceMapper 接口"]
DeviceRedisDAO["DeviceRedisDAO"]
end
subgraph "数据对象层"
DeviceDO["DeviceDO 实体"]
end
DeviceApi --> DeviceApiImpl
DeviceApiImpl --> DeviceServiceImpl
DeviceServiceImpl --> DeviceMapper
DeviceServiceImpl --> DeviceRedisDAO
DeviceApiImpl --> DeviceRespDTO
DeviceServiceImpl --> DeviceDO
AppDeviceHeartBeatController --> DeviceServiceImpl

图表来源

章节来源

核心组件

本节详细介绍设备信息API的核心组件及其职责分工。

设备查询接口

设备查询接口提供多种查询方式，支持基于MAC地址、CPU标识符以及组合条件的查询：

基础查询：getDeviceByMac() - 根据MAC地址查询设备信息
数据库直连查询：getDeviceByMacOnDataBase() - 强制从数据库查询
组合查询：getDeviceByMacByCpu() - 结合MAC和CPU查询
批量查询：支持按渠道ID、型号ID批量查询设备数量

设备修改接口

设备修改接口提供灵活的更新能力：

标准更新：updateDevice() - 更新设备基本信息
推送更新：updateOnDevicePush() - 设备推送场景下的更新
异步更新：updateUiByIdAsync() - 异步UI更新

设备状态监控接口

设备状态监控通过心跳机制实现：

心跳接口：deviceHeartBeat() - 基础心跳检测
增强心跳：deviceHeartBeatV2() - 支持CPU参数的心跳检测
状态同步：自动更新设备在线状态和活动记录

章节来源

架构概览

设备信息API采用微服务架构，通过Feign客户端实现服务间通信：

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "DeviceApi 接口"
participant Impl as "DeviceApiImpl 实现"
participant Service as "DeviceServiceImpl"
participant Redis as "Redis 缓存"
participant DB as "MySQL 数据库"
Client->>API : GET /device/get-by-mac
API->>Impl : 调用实现方法
Impl->>Service : getDeviceByMac(mac)
Service->>Redis : 查询缓存
alt 缓存命中
Redis-->>Service : 返回设备信息
Service-->>Impl : 设备信息
Impl-->>API : CommonResult
API-->>Client : 设备响应
else 缓存未命中
Service->>DB : 查询数据库
DB-->>Service : 设备信息
Service->>Redis : 写入缓存
Service-->>Impl : 设备信息
Impl-->>API : CommonResult
API-->>Client : 设备响应
end

图表来源

详细组件分析

设备数据模型

设备数据模型采用统一的数据传输对象，包含完整的设备信息字段：

Mermaid Diagram Code:

classDiagram
class DeviceDO {
+Long id
+String mac
+Integer status
+String certification
+Long userId
+Integer companyId
+Long channelId
+String deviceModel
+Integer modelId
+String orderNumber
+String sdkVersionName
+String remarks
+LocalDateTime activationTime
+String name
+String brand
+String systemVersion
+String build
+String ddr
+String cpu
+String deviceIp
+Long regionId
+String ipAddress
+String ui
+String serialNumber
+String realDdr
+String realFlash
+String productionOrder
+String masterModel
+String pcbModel
+Long tenantId
+String beginTime
+String endTime
+String channelName
}
class DeviceRespDTO {
+Long id
+String mac
+Integer status
+String certification
+Long userId
+Integer companyId
+Long channelId
+String channelName
+String deviceModel
+Integer modelId
+String orderNumber
+String sdkVersionName
+String remarks
+LocalDateTime activationTime
+String name
+String brand
+String systemVersion
+String build
+String ddr
+String cpu
+String deviceIp
+Long regionId
+String ipAddress
+String ui
+String serialNumber
+String realDdr
+String realFlash
+String productionOrder
+String masterModel
+String pcbModel
+LocalDateTime createTime
+LocalDateTime updateTime
}
DeviceRespDTO --> DeviceDO : "数据转换"

图表来源

设备字段定义

设备信息包含以下关键字段类别：

基础信息字段

id: 主键自增ID
mac: MAC地址（必填）
status: 设备状态（已激活1，未激活0）
certification: 入网认证码
userId: 所属用户ID
companyId: 所属公司ID

渠道信息字段

channelId: 所属渠道ID（必填）
channelName: 渠道名称
deviceModel: 设备型号
modelId: 设备型号主键

业务信息字段

orderNumber: 订单号
sdkVersionName: SDK版本名称
remarks: 备注信息
activationTime: 设备激活时间

硬件配置字段

name: 设备名称
brand: 品牌
systemVersion: 系统版本
build: 构件信息
ddr: DDR内存
cpu: CPU类型
deviceIp: 设备IP地址
regionId: 地区关联ID
ipAddress: IP地址

UI配置字段

ui: Launcher包名（多个用英文逗号分隔）
serialNumber: 序列号
realDdr: 真实DDR
realFlash: 真实Flash
productionOrder: 生产订单
masterModel: 主控型号
pcbModel: PCB主板型号

时间戳字段

createTime: 创建时间
updateTime: 最后更新时间

章节来源

设备查询流程

设备查询采用多级缓存策略，提升查询性能：

Mermaid Diagram Code:

flowchart TD
Start([查询开始]) --> CheckCache["检查Redis缓存"]
CheckCache --> CacheHit{"缓存命中？"}
CacheHit --> |是| ReturnCache["返回缓存数据"]
CacheHit --> |否| CheckDB["查询数据库"]
CheckDB --> DBResult{"数据库存在？"}
DBResult --> |是| SaveCache["写入Redis缓存"]
DBResult --> |否| ReturnNull["返回空数据"]
SaveCache --> ReturnData["返回设备数据"]
ReturnCache --> End([查询结束])
ReturnData --> End
ReturnNull --> End

图表来源

查询接口详解

单设备查询

getDeviceByMac(): 支持缓存优先策略
getDeviceByMacOnDataBase(): 强制数据库查询
getDeviceByMacByCpu(): 组合MAC和CPU查询

批量查询

getCountByChannelIds(): 按渠道ID查询设备数量
getCountByModelIds(): 按型号ID查询设备数量
batchGetCountByModelIds(): 批量型号查询
batchGetCountByChannelIds(): 批量渠道查询

章节来源

设备修改流程

设备修改接口提供多种更新场景：

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "DeviceApi 接口"
participant Service as "DeviceServiceImpl"
participant Redis as "Redis 缓存"
participant DB as "MySQL 数据库"
Client->>API : PUT /device/update
API->>Service : updateDevice(respDTO)
Service->>Service : 校验设备存在性
Service->>DB : 更新数据库记录
DB-->>Service : 更新结果
Service->>Redis : 清除相关缓存
Service->>Redis : 更新设备缓存
Service-->>API : 更新结果
API-->>Client : 更新响应

图表来源

修改权限控制

设备修改权限通过以下机制控制：

接口权限

心跳接口：@PermitAll 注解允许匿名访问
设备查询：基于Feign客户端的安全控制
设备修改：通过业务逻辑验证设备归属

数据权限

租户隔离：通过租户上下文控制数据访问
渠道权限：按渠道ID限制设备操作范围
用户权限：基于用户ID的设备管理权限

章节来源

设备状态监控机制

设备状态监控通过心跳机制实现实时状态同步：

Mermaid Diagram Code:

sequenceDiagram
participant Device as "设备客户端"
participant Controller as "AppDeviceHeartBeatController"
participant Service as "DeviceServiceImpl"
participant Redis as "Redis 缓存"
participant Activity as "设备活动服务"
Device->>Controller : GET /deviceHeartBeat/v2/{mac}/{cpu}
Controller->>Service : checkDeviceCertification(mac, cpu)
Service->>Service : 验证设备认证状态
alt 设备已激活
Service-->>Controller : 设备信息
Controller->>Redis : 更新在线时间
Controller->>Activity : 保存活动记录
Controller-->>Device : 心跳响应
else 设备未激活
Service-->>Controller : 设备不存在
Controller-->>Device : 错误响应
end

图表来源

心跳配置管理

设备心跳配置通过字典数据管理：

配置项

心跳间隔：设备心跳发送频率
超时时间：心跳超时阈值
重试次数：心跳失败重试次数
状态检查：设备状态验证周期

配置存储

Redis缓存：高性能配置读取
动态更新：支持运行时配置调整
版本控制：配置版本管理和回滚

章节来源

DeviceServiceImpl.java

设备信息修改DTO

设备信息修改采用专门的数据传输对象：

Mermaid Diagram Code:

classDiagram
class DeviceModifyRespDTO {
+String mac
+String cpu
+String[] macs
}
note for DeviceModifyRespDTO "设备修改响应DTO\n- mac : MAC地址验证\n- cpu : CPU标识符\n- macs : 批量MAC数组"

图表来源

DeviceModifyRespDTO.java

数据验证规则

设备修改DTO包含以下验证规则：

MAC地址验证

格式：`^([0-9A-Fa-f]2[:-])5([0-9A-Fa-f]2)- 格式：
必填：修改操作必需
校验：支持批量MAC验证

CPU标识验证

可选：部分场景下可为空
格式：十六进制字符串
长度：固定长度验证

批量操作支持

数组：支持多个MAC地址同时处理
去重：自动去除重复的MAC地址
分批：支持大数据量的分批处理

章节来源

DeviceModifyRespDTO.java

依赖关系分析

设备信息API的依赖关系呈现清晰的分层结构：

Mermaid Diagram Code:

graph TB
subgraph "外部依赖"
Feign["Feign 客户端"]
Redis["Redis 缓存"]
MySQL["MySQL 数据库"]
Dict["字典数据服务"]
end
subgraph "内部模块"
DeviceApi["DeviceApi 接口"]
DeviceApiImpl["DeviceApiImpl 实现"]
DeviceServiceImpl["DeviceServiceImpl 实现"]
DeviceDO["DeviceDO 实体"]
end
Feign --> DeviceApi
Redis --> DeviceServiceImpl
MySQL --> DeviceServiceImpl
Dict --> DeviceServiceImpl
DeviceApi --> DeviceApiImpl
DeviceApiImpl --> DeviceServiceImpl
DeviceServiceImpl --> DeviceDO

图表来源

错误码管理

设备模块采用统一的错误码管理体系：

错误码分类

设备明细错误：DEVICE_NOT_EXISTS (1_600__001_000)
导入失败：DEVICE_IMPORT_FAIL (1_600__001_001)
条件验证：DEVICE_CONDITION_NOT_EXISTS (1_600__001_002)
信息修改：INFO_MODIFY_NOT_EXISTS (1_600__002_000)

错误码使用

统一异常处理：通过ErrorCodeConstants集中管理
国际化支持：错误消息支持多语言
调试友好：详细的错误上下文信息

章节来源

ErrorCodeConstants.java

性能考虑

设备信息API在设计时充分考虑了性能优化：

缓存策略

多级缓存架构

Redis缓存：热点数据缓存，降低数据库压力
空值缓存：防止缓存穿透，提升系统稳定性
缓存失效：智能过期策略，保证数据一致性

缓存更新机制

写操作：先更新数据库，再清除缓存
读操作：优先读取缓存，缓存未命中再查询数据库
批量操作：支持批量缓存更新，提升批量处理效率

数据库优化

查询优化

索引设计：MAC地址、CPU、渠道ID建立复合索引
分页查询：支持大数据量的分页查询
批量操作：支持批量插入和更新

连接池管理

连接复用：减少数据库连接开销
连接池配置：根据业务量动态调整
连接监控：实时监控数据库连接状态

并发控制

乐观锁机制

版本号控制：防止并发更新冲突
冲突处理：自动重试机制
事务管理：保证数据一致性

限流策略

QPS限制：防止系统过载
并发控制：线程池大小限制
资源监控：实时监控系统资源使用

故障排除指南

设备信息API提供完善的错误处理和故障排除机制：

常见错误及解决方案

设备不存在

错误码：DEVICE_NOT_EXISTS (1_600__001_000)
可能原因：设备未注册或数据损坏
解决方案：检查设备注册状态，重新注册设备

导入失败

错误码：DEVICE_IMPORT_FAIL (1_600__001_001)
可能原因：Excel格式错误或数据格式不匹配
解决方案：检查Excel文件格式，确保数据格式正确

条件验证失败

错误码：DEVICE_CONDITION_NOT_EXISTS (1_600__001_002)
可能原因：查询条件为空或格式不正确
解决方案：提供有效的查询条件，确保条件格式正确

监控指标

关键指标

请求成功率：监控API调用成功率
响应时间：监控接口响应时间
错误率：监控错误发生频率
缓存命中率：监控缓存使用效率

告警机制

自动告警：异常情况自动触发告警
告警级别：根据严重程度分级告警
处理流程：标准化的告警处理流程

章节来源

ErrorCodeConstants.java

结论

设备信息API采用现代化的微服务架构设计，通过合理的分层结构、完善的缓存策略和严格的错误处理机制，实现了高性能、高可用的设备管理服务。系统支持多种查询模式、灵活的修改接口和实时的状态监控，能够满足复杂的设备管理需求。

通过本文档的详细说明，开发者可以快速理解和使用设备信息API的各项功能，包括设备查询、修改和状态监控等核心能力。同时，文档提供的性能优化建议和故障排除指南，有助于在实际部署和运维过程中获得更好的系统表现。

目录​

简介​

项目结构​

核心组件​

设备查询接口​

设备修改接口​

设备状态监控接口​

架构概览​

详细组件分析​

设备数据模型​

设备字段定义​

设备查询流程​

查询接口详解​

设备修改流程​

修改权限控制​

设备状态监控机制​

心跳配置管理​

设备信息修改DTO​

数据验证规则​

依赖关系分析​

错误码管理​

性能考虑​

缓存策略​

数据库优化​

并发控制​

故障排除指南​

常见错误及解决方案​

监控指标​

结论​

目录

简介

项目结构

核心组件

设备查询接口

设备修改接口

设备状态监控接口

架构概览

详细组件分析

设备数据模型

设备字段定义

设备查询流程

查询接口详解

设备修改流程

修改权限控制

设备状态监控机制

心跳配置管理

设备信息修改DTO

数据验证规则

依赖关系分析

错误码管理

性能考虑

缓存策略

数据库优化

并发控制

故障排除指南

常见错误及解决方案

监控指标

结论