更适合 Spring Boot 的 MQTT 框架：mqtt-plus v1.0.0 发布了

更适合 Spring Boot 的 MQTT 框架：mqtt-plus v1.0.0 发布了

一个面向 Java / Spring Boot 的轻量级 MQTT 框架，支持注解驱动监听、多 broker、动态订阅、断线重连恢复，以及更友好的测试体验。

---

一、为什么会做 mqtt-plus

这两年在做设备接入、边缘通信、消息联动这类场景时，MQTT 基本是绕不过去的协议。

如果只是做一个简单 demo，直接用原生 Paho 当然没问题；但一旦项目进入实际开发阶段，问题很快就会冒出来：

• 业务代码里充满 callback 和连接细节
• 多 broker 场景下配置和路由容易混乱
• 动态订阅、取消订阅做起来不顺手
• 断线重连后怎么恢复订阅，往往需要自己补
• 测试时要么依赖真实 broker，要么只能手写很多 mock 代码
• Spring Boot 项目里缺少一个足够轻量、但又符合工程习惯的 MQTT 开发方式

于是我把这部分能力单独抽了出来，做成了一个独立的开源项目：mqtt-plus。

mqtt-plus 的目标不是替代所有底层 MQTT 客户端，而是在现有客户端之上，提供一层更适合 Java / Spring Boot 项目的开发体验。

---

二、mqtt-plus v1.0.0 解决了什么问题

mqtt-plus v1.0.0 是第一个公开版本，当前主要聚焦 MQTT 3.1.1 场景，核心能力包括：

• @MqttListener 注解驱动监听
• 多 broker 支持
• 运行时动态订阅 / 取消订阅
• 断线重连后的订阅恢复
• Spring Boot Starter 自动配置
• 发布侧 qos / retained 支持
• 同步 / 异步发布 API
• MqttTestTemplate 快速测试支持
• @EnableMqttPlusTest + embedded broker 测试支持
• 示例工程与 smoke test 验证

一句话理解：

原生客户端负责"能连上"，mqtt-plus 负责"在工程里更好用"。

---

三、和常见方案相比，有什么区别

下面这个表格比较能体现 mqtt-plus 的定位：

Feature	mqtt-plus	spring-integration-mqtt	Paho (raw)
Annotation-driven listeners	✅	❌	❌
Multi-broker	✅	⚠️	❌
Dynamic subscriptions	✅	⚠️	⚠️
MQTT 5.0	❌（planned）	❌	⚠️
Spring Boot Starter	✅	❌	❌
Non-Spring usage	✅	❌	✅
Interceptor chain	✅	❌	❌
Async publish	✅	⚠️	⚠️
Test helper module	✅	❌	❌

这里有两个点我想特别强调一下：

1. mqtt-plus 不是只为 Spring 写的

虽然它现在对 Spring Boot 的支持体验更完整，但核心层并不依赖 Spring，可以在普通 Java 场景下使用。

2. 它不是把底层客户端"藏起来"，而是把工程能力"补起来"

比如：

• adapter 抽象
• listener 路由
• 订阅协调
• 错误处理
• Starter 装配
• 测试支撑

这些才是业务项目里最容易反复造轮子的部分。

---

四、实际开发时，代码会变成什么样

1. 添加依赖

<dependency>
    <groupId>io.github.mqttplus</groupId>
    <artifactId>mqtt-plus-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>io.github.mqttplus</groupId>
    <artifactId>mqtt-plus-paho</artifactId>
    <version>1.0.0</version>
</dependency>

2. 配置 broker

mqtt-plus:
  brokers:
    primary:
      enabled: true
      mqtt-version: 3.1.1
      host: 127.0.0.1
      port: 1883
      client-id: sample-basic-client

3. 使用注解监听消息

@Component
public class DeviceMessageListener {

    @MqttListener(
            broker = "primary",
            topics = "devices/+/status",
            qos = 1,
            payloadType = String.class
    )
    public void onMessage(String payload, @MqttTopic String topic) {
        System.out.println("topic=" + topic + ", payload=" + payload);
    }
}

4. 使用模板发布消息

mqttTemplate.publish("primary", "devices/demo/status", "online", 1, false);

这套写法的好处是很直接：

• 监听侧是声明式的
• 发布侧是模板式的
• broker 维度是显式的
• 不需要业务代码直接处理底层 callback 细节

---

五、动态订阅是怎么做的

动态订阅是我这次比较想补齐的一块能力。

很多项目在启动时订阅 topic 没问题，但运行中如果要：

• 新增 topic
• 取消某个 topic
• 让变更立刻作用到当前连接

往往会发现没有一个很顺手的统一入口。

在 mqtt-plus 里，这部分能力被拆成了两层：

1. 静态监听定义

@MqttListener 定义"这个 listener 能处理哪些 topic"。

2. 实际订阅状态

运行中的 subscribe / unsubscribe 控制"当前 broker 连接上真正订阅了哪些 topic"。

这样一来：

• 静态定义负责声明能力范围
• 动态操作负责改变当前有效订阅

更重要的是，当前版本里动态订阅和取消订阅已经是立即生效的，不是"等下次重连再生效"。

---

六、测试这件事，为什么我也单独做了支持

如果你写过 MQTT 相关代码，应该能体会一个痛点：

功能不复杂，但测试经常很麻烦。

要么：

• 起一个真实 broker
• 配一堆连接参数
• 测试很重

要么：

• 只能 mock 很多中间层
• 结果测试和真实运行链路差得太远

所以 mqtt-plus 在 v1.0.0 里专门做了两类测试支持：

1. MqttTestTemplate

这是一个更轻量的快速测试工具，适合做 router / listener 级别的测试。

2. @EnableMqttPlusTest

这条路线会启一个 embedded broker，让 Spring Boot 集成测试更接近真实 MQTT 场景。

这样一来，开发时可以在"快"和"真"之间做选择，而不是只有一种重型测试方式。

---

七、当前版本做到了什么程度

为了避免"能跑 demo 但不能稳定交付"的情况，这个版本在发布前做了几层验证：

• core 单元测试
• starter 配置与上下文测试
• Paho 集成测试
• sample smoke test
• 根工程级别：

mvn -B test
mvn -B -Pintegration-test verify

目前仓库里已经包含 3 个 sample：

• sample-basic
• sample-multi-broker
• sample-dynamic-subscription

这些示例不只是"放在那里"，而是已经进入了自动化验证链路。

---

八、当前版本的边界

虽然 v1.0.0 已经能覆盖大部分 MQTT 3.1.1 的工程接入场景，但还是有一些明确边界：

• 当前主要支持 MQTT 3.1.1
• MQTT 5.0 还没有在 v1.0.0 中提供
• 动态修改 broker 连接信息（如 host、用户名、密码）暂未纳入当前版本

另外，JSON 对象绑定是可选能力：

• String 和 byte[] 默认就能用
• 如果项目类路径里有 jackson-databind，会自动启用 Jackson converter
• 如果你想接别的 JSON 框架，也可以通过自定义 PayloadConverter 来接入

这个设计是有意为之：我不想把一个基础框架强耦合到唯一 JSON 实现上。

---

九、后面还会继续做什么

v1.0.0 更像是一个稳定起点，后续我比较明确会继续推进的方向包括：

• 支持 spring-integration

• MQTT 5.0 支持
• 更丰富的 adapter 体系
• 连接配置动态更新能力
• 指标与可观测性增强
• 更完善的文档和示例

也就是说，mqtt-plus 现在不是一个停在 demo 层的想法，而是已经进入了可持续迭代状态。

---

十、项目地址

GitHub:

https://github.com/mqttplus/mqtt-plus

如果你对下面这些场景感兴趣：

• Spring Boot 中怎么优雅接入 MQTT
• 多 broker 怎么统一管理
• 动态订阅怎么做
• MQTT 项目怎么把测试体验补齐

欢迎关注这个项目，也欢迎直接提 issue / PR。

---

十一、结语

做这个项目的初衷其实很简单：

希望 MQTT 在 Java / Spring Boot 项目里，不只是"能用"，而是"好用、稳、可测试、可维护"。

mqtt-plus v1.0.0 现在刚刚迈出第一步。

如果你正好也在做类似的场景，欢迎试用、交流，也欢迎给项目一个 Star。

如果这个项目对你有帮助，欢迎 ⭐ Star。