SpringBoot + MQTT实战：从零搭建物联网消息收发系统（附完整代码）

SpringBoot + MQTT实战：从零搭建物联网消息收发系统（附完整代码）

如果你正在开发一个物联网项目，比如智能家居、工业传感器监控或者车联网应用，大概率会遇到设备与服务器之间如何高效、稳定通信的问题。传统的HTTP轮询在实时性和资源消耗上往往力不从心，而WebSocket又可能过于“重”且对移动网络下的连接保持不够友好。这时，MQTT（Message Queuing Telemetry Transport）协议就成了一个绝佳的选择。它专为低带宽、高延迟或不稳定的网络环境设计，采用发布/订阅模式，非常适合物联网场景。

然而，仅仅知道MQTT协议的优势还不够，如何将其快速、优雅地集成到你的SpringBoot后端服务中，构建一个具备生产级可靠性的消息收发系统，才是真正的挑战。网上零散的代码片段可能解决了连接问题，但面对断线重连、消息质量保证（QoS）、遗嘱消息（Will Message） 等实际生产中的复杂需求时，往往捉襟见肘。本文将带你从零开始，基于SpringBoot和Spring Integration框架，搭建一个功能完整、可直接用于生产环境的MQTT消息系统。我们会从EMQX服务器的快速部署讲起，深入到客户端的每一个配置细节，并提供一套经过实战检验的代码模板，让你能快速上手，避开我踩过的那些“坑”。

1. 环境准备与核心概念梳理

在动手写代码之前，我们需要把“战场”布置好，并理解清楚即将使用的“武器”。一个完整的MQTT系统通常包含三个核心角色：消息代理（Broker）、发布者（Publisher） 和订阅者（Subscriber）。我们的SpringBoot应用将同时扮演发布者和订阅者的角色，而Broker我们选择业界流行的开源方案——EMQX。

1.1 快速部署EMQX消息代理

EMQX是一个高性能、可扩展的MQTT Broker。对于本地开发和测试，使用Docker部署是最快捷的方式。确保你的机器上已经安装了Docker和Docker Compose。

首先，创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  emqx:
    image: emqx:5.6
    container_name: emqx-broker
    restart: unless-stopped
    ports:
      - "1883:1883"   # MQTT协议端口
      - "8083:8083"   # MQTT over WebSocket端口
      - "8084:8084"   # MQTT over SSL端口
      - "18083:18083" # 管理控制台HTTP端口
    environment:
      - EMQX_NODE_NAME=emqx@node
      - EMQX_CLUSTER__DISCOVERY_STRATEGY=static
    volumes:
      - ./emqx_data:/opt/emqx/data

然后，在终端中执行以下命令启动EMQX：

docker-compose up -d

启动成功后，打开浏览器访问 http://localhost:18083，使用默认用户名 admin 和密码 public 登录，你将看到EMQX的管理控制台。这里可以监控连接状态、主题流量、管理客户端等，是后续调试的得力工具。

1.2 MQTT核心概念与Spring Integration角色映射

理解以下概念对后续配置至关重要：

• 主题（Topic）：一个分层结构的字符串，如 sensor/room1/temperature。发布者向特定主题发布消息，订阅者订阅感兴趣的主题来接收消息。它就像是消息的“地址”或“频道”。
• 服务质量（QoS）：定义消息传递的保证级别。这是MQTT可靠性的核心。
  • QoS 0（最多一次）：消息发出即忘，不保证送达。适用于可容忍丢失的非关键数据（如周期性传感器读数）。
  • QoS 1（至少一次）：确保消息至少送达一次，但可能重复。接收方需要具备幂等处理能力。
  • QoS 2（恰好一次）：通过四次握手确保消息恰好送达一次。这是最可靠但开销最大的级别，适用于支付、关键指令等场景。
• 遗嘱消息（Last Will）：客户端在连接时预先设定。如果客户端异常断开（如网络故障），Broker会自动向指定主题发布这条消息，通知其他客户端该设备已离线。
• Spring Integration的角色：在Spring生态中，我们使用 spring-integration-mqtt 模块。它抽象了底层的Paho客户端，通过 MessageChannel（消息通道）、MessageHandler（消息处理器）和适配器（Adapter） 来收发消息，让我们的业务代码更专注于处理消息内容本身，而非通信细节。

下表清晰地对比了三种QoS级别的特性和适用场景：

提示：在实际项目中，不要盲目使用QoS 2。评估你的业务对消息丢失和重复的容忍度，在可靠性和性能之间做出权衡。大多数物联网场景，QoS 1已经足够。

2. 项目搭建与基础配置

现在，让我们开始构建SpringBoot项目。我将使用Maven进行依赖管理，你也可以使用Gradle。

2.1 创建项目与引入依赖

使用Spring Initializr或IDE创建一个新的SpringBoot项目，主要依赖选择 Spring Web 和 Lombok。然后，手动在 pom.xml 中添加以下关键依赖：

<dependencies>
    <!-- Spring Boot 基础依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!-- Spring Integration 核心 & MQTT 支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-integration</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.integration</groupId>
        <artifactId>spring-integration-mqtt</artifactId>
    </dependency>

    <!-- 用于JSON序列化/反序列化 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

spring-integration-mqtt 是我们实现MQTT功能的核心，它内部封装了Eclipse Paho客户端。

2.2 配置文件详解

接下来，在 application.yml 中配置MQTT连接参数。我习惯将配置分层，并加入一些生产环境中常用的选项：

spring:
  application:
    name: iot-mqtt-demo

mqtt:
  broker:
    # Broker地址，支持多个备用地址，用逗号分隔
    urls: tcp://localhost:1883
    # 连接超时时间（秒）
    connection-timeout: 30
    # 心跳间隔（秒），用于保活
    keep-alive-interval: 60
    # 是否自动重连
    automatic-reconnect: true
    # 重连间隔最大值（毫秒）
    max-reconnect-delay: 10000

  client:
    # 客户端ID前缀，后面会加上随机数确保唯一性
    id-prefix: springboot-client-
    # 是否清除会话（Clean Session）。false表示Broker会保存订阅和未确认消息，重连后可恢复。
    clean-session: false

  security:
    username: admin # 如果Broker启用了认证
    password: public

  default:
    # 默认订阅的主题，多个用逗号分隔
    inbound-topics: device/status/+, sensor/data/#
    # 默认发布主题
    outbound-topic: server/command
    # 默认QoS等级
    qos: 1
    # 默认是否保留消息（Retained）。Broker会为Topic保存最后一条保留消息，新订阅者能立即收到。
    retained: false

  will:
    # 遗嘱消息配置
    enabled: true
    topic: device/offline
    payload: "{\"clientId\":\"${spring.mqtt.client.id-prefix}\",\"status\":\"abnormal_disconnect\"}"
    qos: 1
    retained: true

这里有几个关键点：

• clean-session: false：对于需要保持会话状态（如离线消息、持久化订阅）的设备端非常重要。设为true则每次连接都是全新会话。
• automatic-reconnect: true：开启客户端自动重连，这是生产环境必备的韧性能力。
• 通配符订阅：device/status/+ 订阅单层通配符，sensor/data/# 订阅多层通配符。这极大地增加了订阅的灵活性。
• 遗嘱消息：我们配置了当客户端异常断开时，向 device/offline 主题发送一个JSON格式的离线通知。

3. 核心配置类：构建消息收发骨架

这是整个系统最核心的部分，我们将创建配置类来定义Spring Integration的消息通道（Channel）、出站/入站适配器（Adapter） 以及连接工厂。

3.1 连接工厂与客户端配置

首先，创建一个 MqttConfiguration 类来读取配置并构建连接工厂。

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.mqtt.core.DefaultMqttPahoClientFactory;
import org.springframework.integration.mqtt.core.MqttPahoClientFactory;

@Slf4j
@Configuration
@RequiredArgsConstructor
@EnableConfigurationProperties(MqttProperties.class) // 绑定配置属性类
public class MqttConfiguration {

    private final MqttProperties mqttProperties;

    /**
     * 配置MQTT连接选项，这是连接行为的核心定义。
     */
    @Bean
    public MqttConnectOptions mqttConnectOptions() {
        MqttConnectOptions options = new MqttConnectOptions();
        // 设置Broker地址数组，支持故障转移
        options.setServerURIs(mqttProperties.getBroker().getUrls().split(","));
        options.setUserName(mqttProperties.getSecurity().getUsername());
        options.setPassword(mqttProperties.getSecurity().getPassword().toCharArray());

        // 关键连接参数
        options.setConnectionTimeout(mqttProperties.getBroker().getConnectionTimeout());
        options.setKeepAliveInterval(mqttProperties.getBroker().getKeepAliveInterval());
        options.setAutomaticReconnect(mqttProperties.getBroker().isAutomaticReconnect());
        options.setMaxReconnectDelay(mqttProperties.getBroker().getMaxReconnectDelay());
        options.setCleanSession(mqttProperties.getClient().isCleanSession());

        // 配置遗嘱消息
        if (mqttProperties.getWill().isEnabled()) {
            options.setWill(mqttProperties.getWill().getTopic(),
                           mqttProperties.getWill().getPayload().getBytes(),
                           mqttProperties.getWill().getQos(),
                           mqttProperties.getWill().isRetained());
            log.info("遗嘱消息已启用，主题: {}", mqttProperties.getWill().getTopic());
        }

        // 设置MQTT协议版本，默认为3.1.1，兼容性最好
        // options.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1);
        return options;
    }

    /**
     * 创建MQTT客户端工厂，供出站和入站适配器共用。
     */
    @Bean
    public MqttPahoClientFactory mqttClientFactory() {
        DefaultMqttPahoClientFactory factory = new DefaultMqttPahoClientFactory();
        factory.setConnectionOptions(mqttConnectOptions());
        return factory;
    }
}

注意：MqttProperties 是一个使用了 @ConfigurationProperties(prefix = "mqtt") 注解的类，用于映射 application.yml 中的所有 mqtt.* 配置。这里为了简洁没有列出其完整代码，你可以使用Lombok的 @Data 注解和嵌套的静态类来轻松定义它。

3.2 出站配置（消息发送）

出站配置负责将Spring Integration消息通道中的消息发送到MQTT Broker。

@Configuration
@RequiredArgsConstructor
public class MqttOutboundConfig {

    private final MqttPahoClientFactory mqttClientFactory;
    private final MqttProperties mqttProperties;

    /**
     * 定义出站消息通道。
     */
    @Bean
    public MessageChannel mqttOutboundChannel() {
        return new DirectChannel();
    }

    /**
     * 配置出站消息处理器（适配器）。
     * @ServiceActivator 表明该方法处理来自 `mqttOutboundChannel` 的消息。
     */
    @Bean
    @ServiceActivator(inputChannel = "mqttOutboundChannel")
    public MessageHandler mqttOutboundHandler() {
        // 使用一个唯一的客户端ID，避免与入站客户端冲突
        String clientId = mqttProperties.getClient().getIdPrefix() + "outbound-" + UUID.randomUUID().toString().substring(0, 8);
        MqttPahoMessageHandler handler = new MqttPahoMessageHandler(clientId, mqttClientFactory);

        // 设置为异步模式，避免阻塞发送线程，提升性能
        handler.setAsync(true);
        handler.setDefaultTopic(mqttProperties.getDefault().getOutboundTopic());
        handler.setDefaultQos(mqttProperties.getDefault().getQos());
        handler.setDefaultRetained(mqttProperties.getDefault().isRetained());

        // 可以设置消息转换器，例如将对象自动转为JSON字节
        // handler.setConverter(new MyJsonMessageConverter());

        return handler;
    }
}

3.3 入站配置（消息接收）

入站配置负责订阅Broker上的主题，并将收到的消息投递到Spring Integration的消息通道中，供我们的业务逻辑消费。

@Configuration
@RequiredArgsConstructor
public class MqttInboundConfig {

    private final MqttPahoClientFactory mqttClientFactory;
    private final MqttProperties mqttProperties;

    /**
     * 定义入站消息通道，用于传递从MQTT接收到的消息。
     */
    @Bean
    public MessageChannel mqttInboundChannel() {
        return new DirectChannel();
    }

    /**
     * 配置入站消息生产者（适配器），负责订阅主题并接收消息。
     */
    @Bean
    public MessageProducer inbound() {
        String clientId = mqttProperties.getClient().getIdPrefix() + "inbound-" + UUID.randomUUID().toString().substring(0, 8);
        // 订阅配置中定义的默认主题
        String[] topics = mqttProperties.getDefault().getInboundTopics().split(",");

        MqttPahoMessageDrivenChannelAdapter adapter =
                new MqttPahoMessageDrivenChannelAdapter(clientId, mqttClientFactory, topics);

        // 为每个主题设置QoS，这里简单都设为默认值
        int[] qosArray = new int[topics.length];
        Arrays.fill(qosArray, mqttProperties.getDefault().getQos());
        adapter.setQos(qosArray);

        adapter.setCompletionTimeout(mqttProperties.getBroker().getConnectionTimeout() * 1000); // 转为毫秒
        adapter.setOutputChannel(mqttInboundChannel()); // 设置输出通道

        // 使用默认转换器，将payload转为String。如果需要字节，可设置 setPayloadAsBytes(true)
        DefaultPahoMessageConverter converter = new DefaultPahoMessageConverter();
        // converter.setPayloadAsBytes(true);
        adapter.setConverter(converter);

        return adapter;
    }

    /**
     * 配置入站消息的消费者（业务处理器）。
     * 这里只是一个示例，实际业务处理应放在独立的Service中。
     */
    @Bean
    @ServiceActivator(inputChannel = "mqttInboundChannel")
    public MessageHandler inboundMessageHandler() {
        return message -> {
            String topic = (String) message.getHeaders().get(MqttHeaders.RECEIVED_TOPIC);
            Object payload = message.getPayload(); // 根据转换器，可能是String或byte[]

            log.info("收到MQTT消息 - 主题: [{}], 载荷: {}", topic, payload);

            // 根据不同的主题，路由到不同的业务处理方法
            if (topic.startsWith("sensor/data/")) {
                handleSensorData(topic, (String) payload);
            } else if (topic.startsWith("device/status/")) {
                handleDeviceStatus(topic, (String) payload);
            }
            // ... 其他主题处理逻辑
        };
    }

    private void handleSensorData(String topic, String payload) {
        // 解析payload，例如JSON，然后进行业务处理（存入数据库、触发告警等）
        log.debug("处理传感器数据: {}", payload);
    }

    private void handleDeviceStatus(String topic, String payload) {
        log.debug("处理设备状态: {}", payload);
    }
}

至此，一个具备基础收发能力的MQTT集成框架就搭建完成了。应用启动后，它会自动连接到EMQX，订阅配置的主题，并准备好发送消息的通道。

4. 高级特性与生产级优化

基础功能跑通只是第一步。要让系统真正健壮，我们需要处理更多边界情况和提升易用性。

4.1 实现优雅的消息发送网关

直接操作 MessageChannel 来发送消息不够直观。我们可以定义一个消息网关（Messaging Gateway），这是一个接口，Spring Integration会为其自动生成实现，让发送消息像调用普通方法一样简单。

import org.springframework.integration.annotation.MessagingGateway;
import org.springframework.integration.mqtt.support.MqttHeaders;
import org.springframework.messaging.handler.annotation.Header;

/**
 * MQTT消息发送网关。
 * defaultRequestChannel 指向我们配置的出站通道。
 */
@MessagingGateway(defaultRequestChannel = "mqttOutboundChannel")
public interface MqttGateway {

    /**
     * 发送消息到默认主题（配置中的 outbound-topic）。
     * @param payload 消息内容
     */
    void sendToMqtt(String payload);

    /**
     * 发送消息到指定主题，使用默认QoS和Retained设置。
     * @param topic 目标主题
     * @param payload 消息内容
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic, String payload);

    /**
     * 发送消息到指定主题，并自定义QoS和Retained标志。
     * @param topic 目标主题
     * @param qos 服务质量 (0,1,2)
     * @param retained 是否保留
     * @param payload 消息内容
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic,
                    @Header(MqttHeaders.QOS) int qos,
                    @Header(MqttHeaders.RETAINED) boolean retained,
                    String payload);

    /**
     * 发送字节数组载荷，适用于传输二进制数据（如图片、自定义协议包）。
     * @param topic 目标主题
     * @param qos 服务质量
     * @param payload 字节数组载荷
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic,
                    @Header(MqttHeaders.QOS) int qos,
                    byte[] payload);
}

在业务代码中，你只需注入 MqttGateway 即可轻松发送消息：

@Service
@RequiredArgsConstructor
public class DeviceControlService {

    private final MqttGateway mqttGateway;

    public void sendRebootCommand(String deviceId) {
        String topic = "server/command/" + deviceId + "/reboot";
        String command = "{\"action\":\"reboot\",\"timestamp\":" + System.currentTimeMillis() + "}";
        // 发送一条QoS为1的指令，确保设备至少收到一次
        mqttGateway.sendToMqtt(topic, 1, false, command);
        log.info("已向设备 {} 发送重启指令", deviceId);
    }
}

4.2 监听连接事件与实现自定义重连逻辑

虽然我们配置了 automaticReconnect，但有时我们需要在连接状态变化时执行特定操作，比如记录日志、更新设备在线状态等。Spring Integration提供了事件机制。

import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener;
import org.springframework.integration.mqtt.event.*;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class MqttEventListener {

    /**
     * 连接建立成功
     */
    @EventListener
    public void handleConnected(MqttConnectionOpenEvent event) {
        log.info("MQTT连接已建立，客户端ID: {}", event.getClientId());
        // 可以在这里触发一些连接恢复后的初始化操作，比如重新订阅动态主题
    }

    /**
     * 连接丢失或失败
     */
    @EventListener
    public void handleConnectionLost(MqttConnectionFailedEvent event) {
        log.warn("MQTT连接丢失或失败，原因: {}", event.getCause().getMessage());
        // 更新系统内该客户端对应的设备状态为“离线”
    }

    /**
     * 消息已送达（针对QoS 1和2的确认）
     */
    @EventListener
    public void handleMessageDelivered(MqttMessageDeliveredEvent event) {
        log.debug("消息已确认送达，消息ID: {}", event.getMessageId());
    }

    /**
     * 订阅成功
     */
    @EventListener
    public void handleSubscribed(MqttSubscribedEvent event) {
        log.info("成功订阅主题: {}", String.join(", ", event.getTopics()));
    }
}

对于更复杂的重连策略（如指数退避），可以自定义一个 MqttClientFactory，在 MqttConnectOptions 中设置 automaticReconnect 为 false，然后自己实现一个 MqttCallbackExtended 并在 connectionLost 方法中编写重试逻辑。不过，对于大多数场景，Paho客户端内置的自动重连已经足够可靠。

4.3 动态主题订阅与管理

我们的入站配置订阅了固定的主题。但在实际应用中，可能需要根据运行时条件（如新设备注册）动态订阅或取消订阅主题。这需要直接操作底层的Paho客户端。

首先，需要暴露一个能获取到入站适配器或底层客户端的方法。我们可以通过创建一个管理类来实现：

@Service
@Slf4j
public class MqttSubscriptionManager {

    @Autowired
    private MqttPahoMessageDrivenChannelAdapter mqttInboundAdapter;

    /**
     * 动态订阅一个新主题。
     * @param topic 要订阅的主题
     * @param qos 服务质量
     * @return 是否成功
     */
    public boolean subscribeTopic(String topic, int qos) {
        try {
            mqttInboundAdapter.addTopic(topic, qos);
            log.info("已动态订阅主题: {} (QoS: {})", topic, qos);
            return true;
        } catch (Exception e) {
            log.error("动态订阅主题失败: {}", topic, e);
            return false;
        }
    }

    /**
     * 取消订阅一个主题。
     * @param topic 要取消的主题
     * @return 是否成功
     */
    public boolean unsubscribeTopic(String topic) {
        try {
            mqttInboundAdapter.removeTopic(topic);
            log.info("已取消订阅主题: {}", topic);
            return true;
        } catch (Exception e) {
            log.error("取消订阅主题失败: {}", topic, e);
            return false;
        }
    }

    /**
     * 获取当前所有订阅的主题。
     */
    public String[] getSubscribedTopics() {
        return mqttInboundAdapter.getTopic();
    }
}

注意：要注入 MqttPahoMessageDrivenChannelAdapter，你需要确保它在Spring容器中有唯一的Bean名称。可以在 MqttInboundConfig 的 inbound() 方法上添加 @Bean(name = "mqttInboundAdapter") 来指定。

5. 实战测试与问题排查

理论配置完成，我们需要验证系统是否正常工作。

5.1 编写测试Controller

创建一个简单的REST接口，用于触发消息发送和查看状态。

@RestController
@RequestMapping("/api/mqtt")
@RequiredArgsConstructor
public class MqttTestController {

    private final MqttGateway mqttGateway;
    private final MqttSubscriptionManager subscriptionManager;

    @PostMapping("/publish")
    public ResponseEntity<String> publishMessage(@RequestParam String topic,
                                                 @RequestParam(defaultValue = "1") int qos,
                                                 @RequestParam String message) {
        try {
            mqttGateway.sendToMqtt(topic, qos, false, message);
            return ResponseEntity.ok("消息已发送到主题: " + topic);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                                 .body("发送失败: " + e.getMessage());
        }
    }

    @PostMapping("/subscribe")
    public ResponseEntity<String> subscribeTopic(@RequestParam String topic,
                                                 @RequestParam(defaultValue = "1") int qos) {
        boolean success = subscriptionManager.subscribeTopic(topic, qos);
        if (success) {
            return ResponseEntity.ok("订阅成功: " + topic);
        } else {
            return ResponseEntity.badRequest().body("订阅失败");
        }
    }

    @GetMapping("/subscriptions")
    public ResponseEntity<List<String>> listSubscriptions() {
        return ResponseEntity.ok(Arrays.asList(subscriptionManager.getSubscribedTopics()));
    }
}

5.2 使用MQTTX客户端进行集成测试

MQTTX 是一个出色的跨平台MQTT客户端工具，非常适合测试。

1. 启动你的SpringBoot应用。
2. 启动MQTTX，新建一个连接，连接到 localhost:1883。
3. 测试接收：在MQTTX中订阅 device/status/+ 和 sensor/data/#。然后调用你的SpringBoot应用的 /api/mqtt/publish 接口发送消息，观察MQTTX是否能收到。
4. 测试发送：在MQTTX中向 sensor/data/room1 发布一条消息。查看你的SpringBoot应用的控制台日志，是否打印出了接收到的消息。
5. 测试遗嘱消息：在MQTTX中连接时也设置一个遗嘱消息。然后突然关闭MQTTX（模拟异常断开），观察你的SpringBoot应用（或其他订阅了遗嘱主题的客户端）是否收到了离线通知。
6. 测试动态订阅：通过 /api/mqtt/subscribe 接口让SpringBoot应用订阅一个新主题 test/dynamic，然后在MQTTX中向该主题发布消息，看应用是否能收到。

5.3 常见问题排查指南

在开发和部署过程中，你可能会遇到以下问题：

• 连接被拒绝：
  • 检查EMQX容器是否正常运行 (docker ps)。
  • 检查 application.yml 中的 urls 端口是否正确。
  • 检查防火墙设置。
• 订阅了但收不到消息：
  • 检查主题名是否完全匹配（包括大小写）。MQTT主题默认是大小写敏感的。
  • 检查通配符使用是否正确。+ 是单层，# 是多层且必须是主题的最后一个字符。
  • 在EMQX控制台的 “WebSocket” 页面或 “监控” -> “主题统计” 中，查看消息是否真的被Broker接收和转发。
• 消息重复消费：
  • 这通常是QoS 1级别的正常现象。确保你的消息处理逻辑是幂等的（即重复处理同一消息结果不变）。
• 客户端ID冲突：
  • 确保你的 client.id-prefix 加上随机后缀后是唯一的，尤其是在多个应用实例或频繁重启时。冲突会导致前一个客户端被踢下线。
• 内存泄漏：
  • 在高频消息场景下，如果消息处理过慢，可能导致内存通道堆积。考虑使用 QueueChannel 并设置合适的容量，或者增加消费者线程。

# 一个有用的调试命令：查看EMQX容器日志
docker logs -f emqx-broker

# 在应用日志中开启Spring Integration的DEBUG日志，查看消息流
logging:
  level:
    org.springframework.integration: DEBUG

经过以上步骤，你应该已经拥有了一个功能全面、配置灵活、具备生产级韧性的SpringBoot MQTT消息收发系统。这套代码模板可以直接用于你的物联网项目，并根据具体业务需求进行扩展，例如集成消息持久化、与规则引擎联动、实现集群化部署等。记住，在分布式系统中，网络是不可靠的，设计时永远要为“失败”做准备，而MQTT协议及其客户端库提供的各种机制，正是帮助我们构建稳定系统的有力工具。