hfln-framework-parent/hfln-framework-design-starter/mqtt-spring-boot-starter

MQTT Spring Boot Starter

一个基于 Spring Boot 的 MQTT 客户端启动器，提供了简单易用的 MQTT 消息发布订阅功能。

特性

• 支持 MQTT 消息的发布和订阅
• 支持通配符主题订阅（+ 和 #）
• 支持 JSON 消息的自动转换
• 支持消息拦截器
• 支持连接状态监听
• 支持消息监听器
• 支持 SSL/TLS 加密连接
• 支持自动重连
• 支持消息持久化

快速开始

1. 添加依赖

<dependency>
    <groupId>cn.hfln.framework</groupId>
    <artifactId>mqtt-spring-boot-starter</artifactId>
    <version>${latest.version}</version>
</dependency>

2. 配置属性

在 application.yml 中添加以下配置：

mqtt:
  enabled: true
  broker: tcp://localhost:1883
  client-id: ${spring.application.name}
  username: your-username
  password: your-password
  timeout: 30
  keepalive: 60
  clean-session: true
  automatic-reconnect: true
  max-reconnect-delay: 10000
  connection-timeout: 30
  max-message-size: 1048576
  ssl: false
  # SSL 配置（如果需要）
  ssl-ca-path: /path/to/ca.crt
  ssl-client-cert-path: /path/to/client.crt
  ssl-client-key-path: /path/to/client.key
  ssl-client-key-password: your-key-password

3. 使用示例

3.1 发送消息

@Autowired
private MqttTemplate mqttTemplate;

// 发送字符串消息
mqttTemplate.send("test/topic", "Hello MQTT!");

// 发送 JSON 消息
TestMessage message = new TestMessage("test", 123);
mqttTemplate.sendJson("test/json", message);

3.2 订阅消息

@Component
public class MqttMessageHandler {
    
    @MqttSubscribe(topic = "test/+/topic")
    public void handleStringMessage(String message) {
        System.out.println("Received message: " + message);
    }
    
    @MqttSubscribe(topic = "test/json")
    public void handleJsonMessage(TestMessage message) {
        System.out.println("Received JSON message: " + message);
    }
}

3.3 自定义消息拦截器

@Component
public class CustomMqttMessageInterceptor implements MqttMessageInterceptor {
    
    @Override
    public boolean preSend(String topic, MqttMessage message) {
        // 发送消息前的处理
        return true;
    }
    
    @Override
    public void postSend(String topic, MqttMessage message) {
        // 发送消息后的处理
    }
    
    @Override
    public boolean preReceive(String topic, MqttMessage message) {
        // 接收消息前的处理
        return true;
    }
    
    @Override
    public void postReceive(String topic, MqttMessage message) {
        // 接收消息后的处理
    }
}

3.4 连接状态监听

@Component
public class CustomMqttConnectionListener implements MqttConnectionListener {
    
    @Override
    public void onConnected() {
        System.out.println("MQTT client connected");
    }
    
    @Override
    public void onDisconnected() {
        System.out.println("MQTT client disconnected");
    }
    
    @Override
    public void onConnectionLost(Throwable cause) {
        System.out.println("MQTT connection lost: " + cause.getMessage());
    }
}

高级特性

1. 通配符主题

支持 MQTT 通配符主题订阅：

• +：匹配单层任意字符
• #：匹配多层任意字符

示例：

@MqttSubscribe(topic = "test/+/topic")  // 匹配 test/1/topic, test/2/topic 等
@MqttSubscribe(topic = "test/#")        // 匹配 test/ 下的所有主题

2. 消息转换

支持自动的 JSON 消息转换：

@MqttSubscribe(topic = "test/json")
public void handleJsonMessage(TestMessage message) {
    // message 会自动从 JSON 转换为 TestMessage 对象
}

3. 异步消息发送

支持异步消息发送：

mqttTemplate.send("test/topic", "Hello MQTT!")
    .thenRun(() -> System.out.println("Message sent successfully"))
    .exceptionally(throwable -> {
        System.out.println("Failed to send message: " + throwable.getMessage());
        return null;
    });

配置说明

配置项	说明	默认值
mqtt.enabled	是否启用 MQTT	true
mqtt.broker	MQTT 服务器地址	-
mqtt.client-id	客户端 ID	${spring.application.name}
mqtt.username	用户名	-
mqtt.password	密码	-
mqtt.timeout	超时时间（秒）	30
mqtt.keepalive	保活时间（秒）	60
mqtt.clean-session	是否清除会话	true
mqtt.automatic-reconnect	是否自动重连	true
mqtt.max-reconnect-delay	最大重连延迟（毫秒）	10000
mqtt.connection-timeout	连接超时时间（秒）	30
mqtt.max-message-size	最大消息大小（字节）	1048576
mqtt.ssl	是否启用 SSL	false
mqtt.ssl-ca-path	CA 证书路径	-
mqtt.ssl-client-cert-path	客户端证书路径	-
mqtt.ssl-client-key-path	客户端密钥路径	-
mqtt.ssl-client-key-password	客户端密钥密码	-

注意事项

1. 确保 MQTT 服务器地址配置正确
2. 如果使用 SSL/TLS，确保证书配置正确
3. 建议在生产环境中启用自动重连功能
4. 注意设置合适的消息大小限制
5. 建议使用唯一的客户端 ID，避免冲突

常见问题

1. 连接失败

   • 检查服务器地址是否正确
   • 检查用户名密码是否正确
   • 检查网络连接是否正常

2. 消息发送失败

   • 检查客户端是否已连接
   • 检查主题格式是否正确
   • 检查消息大小是否超限

3. 消息接收失败

   • 检查订阅主题是否正确
   • 检查消息格式是否匹配
   • 检查处理方法参数类型是否正确

贡献指南

欢迎提交 Issue 和 Pull Request。

许可证

本项目采用 MIT 许可证。