# MQTT Spring Boot Starter

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

## 特性

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

## 快速开始

### 1. 添加依赖

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

### 2. 配置属性

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

```yaml
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 发送消息

```java
@Autowired
private MqttTemplate mqttTemplate;

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

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

#### 3.2 订阅消息

```java
@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 自定义消息拦截器

```java
@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 连接状态监听

```java
@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 通配符主题订阅：

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

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

### 2. 消息转换

支持自动的 JSON 消息转换：

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

### 3. 异步消息发送

支持异步消息发送：

```java
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 许可证。