evo-BMS/README_INTEGRATION.md

EvoBMS MyBatis-Plus 和 MQTT 集成说明

概述

本项目已成功集成了 MyBatis-Plus 和 MQTT 功能，为 EVO 电池管理系统提供了强大的数据持久化和实时通信能力。

MyBatis-Plus 集成

1. 依赖配置

已在 pom.xml 中添加以下依赖：

• mybatis-plus-boot-starter: MyBatis-Plus 核心依赖
• mybatis-plus-generator: 代码生成器
• freemarker: 模板引擎

2. 配置文件

在 application.yml 中添加了 MyBatis-Plus 配置：

mybatis-plus:
  mapper-locations: classpath*:mybatis/**/*Mapper.xml
  type-aliases-package: com.evobms.project.**.domain
  global-config:
    db-config:
      id-type: AUTO
      field-strategy: NOT_NULL
      logic-delete-field: delFlag
      logic-delete-value: 2
      logic-not-delete-value: 0

3. 核心功能

3.1 实体类注解

• @TableName: 指定表名
• @TableId: 主键配置
• @TableLogic: 逻辑删除
• @Version: 乐观锁

3.2 Mapper 接口

继承 BaseMapper<T> 获得基础 CRUD 操作：

@Mapper
public interface BmsDeviceMapper extends BaseMapper<BmsDevice> {
    // 自定义方法
}

3.3 Service 层

继承 IService<T> 和 ServiceImpl<M, T>：

public interface IBmsDeviceService extends IService<BmsDevice> {}

@Service
public class BmsDeviceServiceImpl extends ServiceImpl<BmsDeviceMapper, BmsDevice> 
    implements IBmsDeviceService {}

4. 示例代码

BmsDevice 实体类

位置：src/main/java/com/evobms/project/bms/domain/BmsDevice.java

包含完整的 BMS 设备属性，使用了 MyBatis-Plus 注解。

数据库表

执行 sql/bms_device.sql 创建示例表和数据。

MQTT 集成

1. 依赖配置

已添加 MQTT 相关依赖：

• spring-integration-mqtt: Spring Integration MQTT 支持
• org.eclipse.paho.client.mqttv3: Eclipse Paho MQTT 客户端

2. 配置文件

在 application.yml 中添加了 MQTT 配置：

mqtt:
  host: tcp://localhost:1883
  clientId: evobms-client
  username: 
  password: 
  connectionTimeout: 30
  keepAliveInterval: 60
  subscribeTopic: evobms/+/data
  publishTopic: evobms/command

3. 核心组件

3.1 MqttConfig 配置类

位置：src/main/java/com/evobms/framework/config/MqttConfig.java

提供了：

• MQTT 客户端工厂配置
• 消息接收通道
• 消息发送通道
• 消息处理器

3.2 MqttService 服务类

位置：src/main/java/com/evobms/project/bms/service/MqttService.java

提供了：

• 发送 MQTT 消息
• 处理设备数据
• 设备控制命令
• 设备状态查询

4. 使用示例

发送消息

@Autowired
private MqttService mqttService;

// 发送设备控制命令
mqttService.sendDeviceCommand("BMS001", "STATUS_QUERY");

// 发送自定义消息
mqttService.sendMessage("evobms/test", "Hello MQTT");

接收消息

消息会自动通过配置的消息处理器处理，支持设备数据自动更新。

API 接口

BmsDeviceController

位置：src/main/java/com/evobms/project/bms/controller/BmsDeviceController.java

提供了完整的 RESTful API：

• GET /bms/device/list - 查询设备列表
• GET /bms/device/{deviceId} - 获取设备详情
• POST /bms/device - 新增设备
• PUT /bms/device - 修改设备
• DELETE /bms/device/{deviceIds} - 删除设备
• PUT /bms/device/status - 批量更新状态
• POST /bms/device/queryStatus/{deviceCode} - 查询设备状态
• POST /bms/device/restart/{deviceCode} - 重启设备
• POST /bms/device/config/{deviceCode} - 配置设备
• POST /bms/device/mqtt/send - 发送 MQTT 消息
• GET /bms/device/statistics - 获取统计信息

使用建议

1. MyBatis-Plus 最佳实践

1. 实体类设计：

   • 使用合适的注解标注字段
   • 继承 BaseEntity 获得公共字段
   • 合理使用逻辑删除和乐观锁

2. 查询优化：

   • 使用 QueryWrapper 构建复杂查询
   • 合理使用分页插件
   • 避免 N+1 查询问题

3. 代码生成：

   • 使用 MyBatis-Plus 代码生成器快速生成基础代码
   • 自定义模板适应项目需求

2. MQTT 最佳实践

1. 主题设计：

   • 使用层次化主题结构：evobms/{deviceCode}/{dataType}
   • 合理使用通配符订阅

2. 消息格式：

   • 使用 JSON 格式传输数据
   • 包含时间戳和设备标识

3. 错误处理：

   • 实现消息重试机制
   • 记录通信日志
   • 处理连接断开重连

3. 安全考虑

1. 数据库安全：

   • 使用参数化查询防止 SQL 注入
   • 合理设置数据库权限

2. MQTT 安全：

   • 配置用户名密码认证
   • 使用 TLS 加密传输
   • 限制主题访问权限

扩展功能

1. 数据监控

• 实时设备状态监控
• 历史数据分析
• 告警机制

2. 设备管理

• 设备注册和注销
• 固件升级
• 参数配置

3. 数据分析

• 电池性能分析
• 故障预测
• 能耗统计

故障排除

常见问题

1. MyBatis-Plus 相关：

   • 检查实体类注解配置
   • 确认 Mapper 扫描路径
   • 验证数据库连接配置

2. MQTT 相关：

   • 检查 MQTT 服务器连接
   • 确认主题订阅配置
   • 验证消息格式

日志配置

在 application.yml 中调整日志级别：

logging:
  level:
    com.evobms: debug
    com.baomidou.mybatisplus: debug
    org.springframework.integration.mqtt: debug

总结

通过集成 MyBatis-Plus 和 MQTT，EvoBMS 系统具备了：

• 强大的数据持久化能力
• 实时的设备通信功能
• 完整的 RESTful API
• 灵活的扩展机制

这为构建现代化的电池管理系统提供了坚实的技术基础。