RT-Thread RyanMqtt 2.0全面重构：更轻量、更安全、更可靠的物联网连接

RT-Thread社区精品软件包RyanMqtt正式发布2.0版本。本次更新是一次从底层协议栈到上层应用API的全面重构，旨在为物联网设备提供更轻量、更快、更安全、更可靠的连接能力。

核心亮点

维度	变更类型	核心价值
协议栈	Paho MQTT Embedded → coreMQTT	迁移至社区维护更活跃、测试覆盖更完善的coreMQTT，为未来支持MQTT 5.0奠定基础。
运行时安全	使用Sanitizer进行运行时安全分析验证	在调试阶段捕获内存越界、Use-after-free、数据竞争、未定义行为、内存泄漏等问题，显著提升代码健壮性与安全性。
代码质量	引入clang-tidy和Cppcheck进行静态分析	实现高质量代码保障，接近语法级“零缺陷”，大幅提升代码可维护性。
开发模式	使用AI工具辅助编码与代码审查	通过AI辅助开发与审查，持续提升代码质量，构筑安全防线。
内存管理	固定缓冲区 → 动态按需分配	采用按需动态分配策略，有效降低运行时的内存占用。
线程安全	实现更完善的线程安全机制	支撑更复杂的多线程应用场景，从根本上杜绝竞态风险。
测试体系	新增多项专项测试	覆盖更广泛的场景，并进行全链路内存泄漏检测，强化软件的稳定性与可靠性。

公共 API 变化

新增接口

本次更新增加了多个实用接口，进一步提升了开发的灵活性和效率。

// 批量订阅/取消订阅
extern RyanMqttError_e RyanMqttSubscribeMany(RyanMqttClient_t *client, int32_t count,
         RyanMqttSubscribeData_t subscribeManyData[]);
extern RyanMqttError_e RyanMqttUnSubscribeMany(RyanMqttClient_t *client, int32_t count,
           RyanMqttUnSubscribeData_t unSubscribeManyData[]);

// 带用户数据的发布
extern RyanMqttError_e RyanMqttPublishAndUserData(RyanMqttClient_t *client, char *topic, uint16_t topicLen,
        char *payload, uint32_t payloadLen, RyanMqttQos_e qos,
        RyanMqttBool_e retain, void *userData);

// 线程安全的订阅查询（资源需通过 RyanMqttSafeFreeSubscribeResources 安全释放）
extern RyanMqttError_e RyanMqttGetSubscribeSafe(RyanMqttClient_t *client, RyanMqttMsgHandler_t **msgHandles,
      int32_t *subscribeNum);
extern RyanMqttError_e RyanMqttSafeFreeSubscribeResources(RyanMqttMsgHandler_t *msgHandles, int32_t subscribeNum);

// 订阅数量查询
extern RyanMqttError_e RyanMqttGetSubscribeTotalCount(RyanMqttClient_t *client, int32_t *subscribeTotalCount);

// 获取 MQTT Config 信息（资源需通过 RyanMqttFreeConfigFromGet 安全释放）
extern RyanMqttError_e RyanMqttGetConfig(RyanMqttClient_t *client, RyanMqttClientConfig_t **pclientConfig);
extern RyanMqttError_e RyanMqttFreeConfigFromGet(RyanMqttClientConfig_t *clientConfig);

新增功能价值

接口	用途	优势
SubscribeMany/UnSubscribeMany	批量订阅/取消订阅多个主题	减少网络往返次数，有效提升吞吐效率。
PublishAndUserData	发布消息时可附带用户上下文数据	在消息回调中可直接读取关联的用户数据，简化了应用层的状态管理。
GetSubscribeSafe	安全地查询当前订阅状态	内部已进行同步处理，保证多线程环境下的安全访问。
GetSubscribeTotalCount	获取当前订阅的主题总数	便于进行系统监控与资源调度。

平台抽象层优化

1. 统一时间接口
   提供了 uint32_t platformUptimeMs(void); 接口，用于获取跨平台的毫秒级运行时间。内部已处理32位计时器回绕问题，确保长时间运行的稳定性。

2. 网络收发模型简化

   • 网络收、发接口的语义改为单次调用，减少了内部冗余的循环和分支判断。
   • 接口返回实际传输的字节数，更贴近底层网络行为。
   • 异常恢复路径更加明确清晰，这对构建稳定的物联网连接至关重要。

测试体系全面升级

为确保2.0版本的可靠性，我们新增了8大类专项测试用例，覆盖了从基础功能到极限压力场景的全流程验证：

测试类别	测试目标
1. 客户端销毁压力测试	验证资源释放的幂等性与完整性
2. 心跳与超时处理	Keep-Alive、PINGREQ/RESP 机制验证
3. 消息链路完整性（QoS 0/1/2）	QoS 0/1/2 消息端到端可靠性验证
4. 自动/手动重连机制	状态机正确性与连接恢复能力
5. 批量/重复订阅一致性	订阅表一致性、内存安全、去重逻辑
6. 多客户端高并发	20+ 客户端并发运行稳定性
7. 单客户端多线程共享	锁机制、数据一致性、竞态防护（20线程 × 各1000条QoS1/2消息）
8. 公共API参数校验	提升接口健壮性与可用性

测试覆盖范围

• 基础连接：100次循环连接/断开，混合QoS消息发布与订阅。
• 消息流控：连续发送QoS0/1/2等级共1000条消息，进行混合QoS压力测试。
• 订阅管理：批量、大量、重复、混合QoS的订阅与取消操作。
• 并发压测:
  • 单客户端20线程，各发送1000条QoS1/2消息。
  • 多客户端20个并发实例，进行双向发布/订阅。
• 可靠性：长连接、弱网模拟、Keep-Alive、重连机制验证。
• 资源安全：全链路内存泄漏、句柄泄漏检测。

代码质量与规范

工具链全面集成

工具	用途
Sanitizer	运行时捕获内存与线程安全问题
clang-tidy	静态分析潜在缺陷（空指针、资源泄漏等）
Cppcheck	深度扫描内存与资源管理问题
ClangFormat	统一代码风格
编译器警告	-Wall -Wextra（默认启用），CI环境强化开启-Weffc++/-Weverything

检查重点覆盖

• 内存安全：杜绝内存泄漏、越界访问、悬空指针。
• 性能优化：减少冗余数据拷贝与低效算法。
• 可读性：确保命名规范、注释完整、逻辑清晰。

通过以上措施，RyanMqtt 2.0实现了接近语法级的“零缺陷”目标，从而大幅降低了长期的代码维护成本。

安全性与可靠性全面提升

• 全面的API审查：对所有公共API进行了安全复审。
• 强化的同步机制：核心数据结构的访问均受同步机制保护。
• 健壮的内存管理：动态内存分配策略更健壮，确保异常路径下的资源也能安全释放。
• 严格的输入验证：增强了输入验证与边界检查，采用防御性编程。
• 完善的网络异常处理：优化了弱网环境下的网络收发模型和连接恢复速度。
• 精准的错误恢复：错误恢复路径更稳健，超时与重试策略更精准。

总结

RyanMqtt 2.0是一次里程碑式的升级，主要体现在以下五个方面：

1. 技术栈现代化：迁移至coreMQTT，拥抱更活跃的开源生态，为未来功能扩展铺平道路。
2. 架构更清晰：模块高度解耦，抽象设计更为合理。
3. 质量更可信：专项测试、静态分析与AI审查共同构筑了强大的质量防线。
4. 性能再优化：实现了更低的资源占用和更高的网络吞吐效率。
5. 维护更轻松：统一的代码规范和清晰的平台抽象层，显著降低了长期开发和维护成本。

从 1.x 迁移至 2.x

RyanMqtt 2.0在设计上充分考虑了向后兼容性，升级过程极为简单。

从V1.x升级到V2.x时，您只需在RyanMqttClientConfig_t结构体中移除以下四个已废弃的字段：

char *recvBuffer;        // MQTT 接收缓冲区（已废弃）
char *sendBuffer;        // MQTT 发送缓冲区（已废弃）
uint32_t recvBufferSize; // 接收缓冲区大小（已废弃）
uint32_t sendBufferSize; // 发送缓冲区大小（已废弃）

受影响的主要接口如下（其余接口原则上保持兼容，具体差异请以头文件为准）：

• RyanMqttError_e RyanMqttSetConfig(RyanMqttClient_t *client, RyanMqttClientConfig_t *clientConfig);
• RyanMqttError_e RyanMqttDiscardAckHandler(...); 函数中的packetType参数类型已更新，请参考RyanMqttPublic.h中的新宏定义。

完成上述修改后，其余API与配置均可保持兼容，无需额外调整即可完成迁移。若编译时遇到不兼容问题，请以mqttclient/include/*.h头文件中的最新函数签名为准。

我们强烈建议所有用户升级到2.0版本（软件包中心的latest标签即为2.0版，该版本已在生产环境稳定运行数月）。对于暂时不希望升级的用户，可以选择1.2.1版本，这是V1系列的最终维护版。

---

20250916 更新
RyanMqtt核心库进行了细节优化，测试套件新增3个专项测试例程：

• 随机网络故障弱网丢包测试：验证在弱网及高丢包率环境下，QoS 0/1/2全等级消息的完整性与内存回收。
• 随机网络故障内存回收检测：验证异常网络情况下的内存释放，提升接口健壮性。
• 随机内存故障内存回收测试：验证内存分配异常情况下的资源释放能力。

20251013 更新

• 修复：客户端在初始化(init)后未启动(start)便直接销毁(destroy)时，资源无法释放的问题。
• 优化：现支持clientId、userName、password字段为零长度字符串。
• 优化：降低了Config结构体的内存占用。
• 增强：补充了对应的单元测试代码。

---

相关资源

• RyanMqtt GitHub仓库：https://github.com/Ryan-CW-Code/RyanMqtt
• RT-Thread软件包中心：https://packages.rt-thread.org/detail.html?package=RyanMqtt