更适合 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支持同步 / 异步发布 APIMqttTestTemplate快速测试支持EnableMqttPlusTest embedded broker 测试支持示例工程与 smoke test 验证一句话理解原生客户端负责“能连上”mqtt-plus负责“在工程里更好用”。三、和常见方案相比有什么区别下面这个表格比较能体现mqtt-plus的定位Featuremqtt-plusspring-integration-mqttPaho (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. 添加依赖dependencygroupIdio.github.mqttplus/groupIdartifactIdmqtt-plus-spring-boot-starter/artifactIdversion1.0.0/version/dependencydependencygroupIdio.github.mqttplus/groupIdartifactIdmqtt-plus-paho/artifactIdversion1.0.0/version/dependency2. 配置 brokermqtt-plus:brokers:primary:enabled:truemqtt-version:3.1.1host:127.0.0.1port:1883client-id:sample-basic-client3. 使用注解监听消息ComponentpublicclassDeviceMessageListener{MqttListener(brokerprimary,topicsdevices//status,qos1,payloadTypeString.class)publicvoidonMessage(Stringpayload,MqttTopicStringtopic){System.out.println(topictopic, payloadpayload);}}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-Btestmvn-B-Pintegration-test verify目前仓库里已经包含 3 个 samplesample-basicsample-multi-brokersample-dynamic-subscription这些示例不只是“放在那里”而是已经进入了自动化验证链路。八、当前版本的边界虽然v1.0.0已经能覆盖大部分 MQTT 3.1.1 的工程接入场景但还是有一些明确边界当前主要支持 MQTT 3.1.1MQTT 5.0 还没有在 v1.0.0 中提供动态修改 broker 连接信息如 host、用户名、密码暂未纳入当前版本另外JSON 对象绑定是可选能力String和byte[]默认就能用如果项目类路径里有jackson-databind会自动启用 Jackson converter如果你想接别的 JSON 框架也可以通过自定义PayloadConverter来接入这个设计是有意为之我不想把一个基础框架强耦合到唯一 JSON 实现上。九、后面还会继续做什么v1.0.0更像是一个稳定起点后续我比较明确会继续推进的方向包括支持 spring-integrationMQTT 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。