mica-mqtt 2.5.4 发布：动态 Topic 处理从未如此简单！
在物联网（IoT）和实时消息传递领域，MQTT Topic 的设计至关重要。一个常见的模式是使用动态 Topic 来区分不同的设备、产品或业务场景，例如 /devices/${productId}/${deviceId}/events。以往，处理这类 Topic 往往需要在业务代码中进行手动的字符串分割和解析，不仅繁琐且容易出错。
在 mica-mqtt 2.5.4 版本中，我们聚焦于解决这一核心痛点。通过对注解功能的革命性增强，我们引入了原生的 Topic 变量解析能力，让您以一种前所未有的优雅和简洁的方式处理动态 Topic。
一、✨ 本次更新亮点：注解驱动的 Topic 变量解析
新版本最大的亮点在于，@MqttClientSubscribe（客户端）和 @MqttServerFunction（服务端）注解现在可以直接从 Topic 字符串中提取变量，并将其注入到您的处理方法中。
1.1 使用方式：客户端订阅
假设您需要订阅符合 /sys/${productKey}/${deviceName}/thing/sub/register 格式的所有主题。现在，您只需定义一个带有 Map<String, String> 类型参数的方法即可。
当客户端收到一条消息，例如主题为 /sys/prod-123/dev-007/thing/sub/register，mica-mqtt 会自动解析该主题，并将解析结果注入到 topicVars 参数中。
代码示例：
import java.util.Map; @MqttClientSubscribe("/sys/${productKey}/${deviceName}/thing/sub/register") public void onDeviceRegister(String topic, Map<String, String> topicVars, byte[] payload) { // 对于主题 "/sys/prod-123/dev-007/thing/sub/register" // topicVars 的值将会是: {"productKey": "prod-123", "deviceName": "dev-007"} String productKey = topicVars.get("productKey"); String deviceName = topicVars.get("deviceName"); log.info("接收到新设备注册消息 -> 产品: {}, 设备: {}", productKey, deviceName); log.info("完整主题: {}", topic); log.info("消息内容: {}", new String(payload)); }
优势：
-
零手动解析：告别
topic.split("/")的陈旧方式。 -
代码更清晰：业务逻辑与 Topic 解析逻辑解耦，意图一目了然。
-
不易出错：避免了因 Topic 层级变化或数组越界导致的运行时错误。
1.2 使用方式：服务端消息处理
同样的能力也赋予了服务端。您可以轻松地在消息处理函数中获取任意层级的 Topic 变量，极大地简化了后端业务逻辑的实现。
代码示例：
import java.util.Map; @MqttServerFunction("/devices/${productType}/+/data") public void handleDeviceData(String topic, Map<String, String> topicVars, byte[] message) { // 假设收到主题 "/devices/sensor/SN-9527/data" // topicVars 的值将会是: {"productType": "sensor"} String type = topicVars.get("productType"); log.info("处理来自主题 {} 的数据，产品类型: {}", topic, type); // ... 进一步的业务处理 }
二、🚀 性能与内部优化
除了核心功能增强，此版本还包含多项重要的内部改进：
-
引入前缀树（Trie）管理订阅：在服务端，我们使用前缀树数据结构来重构订阅管理器。相比传统的列表遍历，这极大地提升了在海量订阅场景下的消息匹配和路由效率。
-
灵活的心跳检测：为满足特殊应用场景，现在可以将心跳超时设置为小于等于0，此时服务端将不启用对该客户端的心跳检测。
-
兼容性提升：调整了 Topic 校验逻辑，放宽了对空白字符的限制，以更好地兼容 EMQX 等主流 Broker。同时，增加了相关日志提示，帮助开发者提前发现潜在问题。
三、🛠️ 重要：升级须知（重构与不兼容变更）
为了提升代码质量和可维护性，并为未来的功能扩展奠定坚实基础，我们在 2.5.4 版本中进行了一系列重要的内部重构。这些调整旨在减少重复代码，并为 mica-mqtt 将来更好地支持 MQTT 5.0 属性消息构建打下基础。
请正在使用旧版本的开发者注意以下不兼容变更：
-
注解包路径变更：
@MqttServerFunction和@MqttClientSubscribe注解已统一移动到mica-mqtt-common包中。升级后，请修改您代码中的import语句。 -
mica-mqtt-codec包结构调整：对该模块进行了大规模的重构，包括重命名部分类和方法。如果您有直接依赖此包的底层实现，请仔细核对。 -
API 变更：移除了
MqttCodecUtil中的isValidPublishTopicName方法，请统一使用isTopicFilter方法进行校验。
虽然这些变更可能需要您在升级时进行少量代码调整，但我们坚信，一个更清晰、更健壮的底层架构将为 mica-mqtt 的长远发展带来巨大的价值。
四、❤️ 结语
mica-mqtt 2.5.4 是一个里程碑式的版本，它将开发者的体验提升到了一个新的高度。我们相信，原生、易用的 Topic 变量解析功能将使您的物联网和消息应用开发变得更加高效和愉悦。
我们鼓励所有用户升级到最新版本，体验这些激动人心的变化。
感谢社区的每一位贡献者和反馈者，是你们让 mica-mqtt 变得更好！
