摘要: mica-mqtt 2.5.4 版本正式發佈！本次更新帶來了備受期待的 Topic 變量解析功能，同時對註解處理、內部實現和依賴項進行了多項優化和重構。本文將帶您深入瞭解此次更新的亮點，助您輕鬆掌握新版本特性。
各位 mica-mqtt 的使用者和關注者們，大家好！
我們非常激動地宣佈，mica-mqtt 2.5.4 版本現已正式發佈！這個版本在持續提升性能和穩定性的基礎上，重點增強了註解處理能力，為開發者帶來了更加便捷和強大的 Topic 處理方式。同時，我們對項目的代碼結構和部分實現進行了重構，為未來的功能迭代打下了堅實的基礎。
以下是本次更新的主要內容：
✨ 核心亮點：註解原生支持 Topic 變量解析
在 2.5.4 版本中，我們為客户端的 @MqttClientSubscribe 和服務端的 @MqttServerFunction 註解增加了 Topic 變量解析功能。現在，您可以更加靈活地處理動態 Topic，輕鬆提取 Topic 中的變量，讓代碼更加簡潔優雅。
客户端 @MqttClientSubscribe
通過在 Topic 字符串中使用 ${variable} 的形式定義模板變量，mica-mqtt 客户端現在可以自動解析出這些變量，並通過 Map<String, String> 類型的參數注入到您的訂閲處理方法中。
/**
* 訂閲，參數為可選，但是參數數量必須大於 2，
*
* @param topic topic 參數，可選參數
* @param topicVars 訂閲 topic 模板 ${productKey} 中的變量解析（v2.5.4支持），可選參數，注意：類型必須為 Map<String, String>
* @param payload 消息內容，以字節數組形式提供，可選參數，也可支持對象形式，默認 json 序列化
*/
@MqttClientSubscribe("/sys/${productKey}/${deviceName}/thing/sub/register")
public void thingSubRegister(String topic, Map<String, String> topicVars, byte[] payload) {
// 1.3.8 開始支持，@MqttClientSubscribe 註解支持 ${} 變量替換，會默認替換成 +
// 注意：mica-mqtt 會先從 Spring boot 配置中替換參數 ${}，如果存在配置會優先被替換。
// 2.4.5 開始支持，支持 2 到 3 個參數，字段類型映射規則（順序）如下：
// String 字符串會默認映射到 topic，
// Map<String, String> topicVars 會默認映射到 topic 中的變量解析（v2.5.4支持），注意：別跟消息序列化的衝突，消息反序列化不要用 Map<String, String>
// MqttPublishMessage 會默認映射到 原始的消息，可以拿到 mqtt5 的 props 參數
// byte[] 會映射到 mqtt 消息內容 payload
// ByteBuffer 會映射到 mqtt 消息內容 payload
// 其他類型會走序列化，確保消息能夠序列化，默認為 json 序列化
log.info("topic:{} payload:{}", topic, new String(payload, StandardCharsets.UTF_8));
}服務端 @MqttServerFunction
同樣地，服務端的消息處理函數也獲得了 Topic 變量解析的能力。您可以輕鬆地從 Topic 中提取設備標識、產品密鑰等動態信息，簡化業務邏輯。
/**
* MQTT消息處理函數，匹配 mqtt Topic /test/+
*
* @param context ChannelContext，可選參數
* @param topic 實際接收到消息的主題名稱，可選參數
* @param topicVars topic 中的 ${xxxx} 變量解析（v2.5.4支持），可選參數，注意：類型必須為 Map<String, String>
* @param publishMessage 完整的MQTT發佈消息對象，包含消息頭和負載，可選參數
* @param message 消息負載內容，以字節數組形式提供，可選參數，也可支持對象形式，默認 json 序列化
*/
@MqttServerFunction("/test/${xxxx}")
public void func3(ChannelContext context, String topic, Map<String, String> topicVars, MqttPublishMessage publishMessage, byte[] message) {
// 獲取客户端節點信息
Node clientNode = context.getClientNode();
// 記錄接收到的MQTT消息信息
log.info("clientNode:{} topic:{} topicVars:{} publishMessage:{} message:{}", clientNode, topic, topicVars, publishMessage, new String(message));
}🚀 性能與體驗優化
除了核心功能的增強，2.5.4 版本還包含了多項性能和開發者體驗的優化：
- 服務端訂閲管理升級：mica-mqtt-server 現已採用前綴樹（Trie）來管理 MQTT 訂閲，大幅提升了大規模訂閲場景下的匹配效率和性能。
- 心跳檢測更靈活：當心跳超時時間小於等於0時，服務端將不再開啓心跳檢測，為特定場景提供了更大的靈活性（但不建議常規使用，推薦 mqtt 客户端自定義心跳時長）。
- Topic 空白字符校驗調整：為了更好地兼容 EMQX 等主流 MQTT Broker，我們移除了對 Topic 中空白字符的校驗，並增加了相應的日誌提示，幫助開發者快速定位潛在問題。
🛠️ 重構與不兼容變更
為了提升代碼質量和可維護性，併為未來的功能擴展奠定堅實基礎，我們在 2.5.4 版本中進行了一系列重要的內部重構。這些調整旨在減少重複代碼，併為 mica-mqtt 將來更好地支持 MQTT 5.0 屬性消息構建打下基礎。
部分變更為不兼容更新，請開發者在升級時注意：
- 註解包路徑變更：
@MqttServerFunction和@MqttClientSubscribe註解被統一移動到了mica-mqtt-common包中，您需要更新代碼中的 import 路徑。 - Codec 包調整：對
mica-mqtt-codec包進行了一系列調整，包括類名和方法名的重命名，以及對 MQTT 消息構建器的重構。 - 工具類方法移除：移除了
MqttCodecUtil中的isValidPublishTopicName方法，現在統一使用isTopicFilter進行校驗。
雖然這些變更可能需要您在升級時進行少量代碼調整，但我們堅信，一個更清晰、更健壯的底層架構將為 mica-mqtt 的長遠發展帶來巨大的價值。
🙏 特別感謝
本次版本的發佈離不開社區開發者的積極反饋和貢獻。特別感謝 @劉業興 和 @長草顏糰子 在 gitee 上提出的寶貴建議。
我們鼓勵所有用户升級到 mica-mqtt 2.5.4 版本，以體驗最新的功能和優化。如果您在升級過程中遇到任何問題，或對新版本有任何建議，歡迎通過我們的官方渠道進行反饋。
立即體驗 mica-mqtt 2.5.4，開啓更高效、更便捷的物聯網開發之旅！
