mica-mqtt 2.6.4：待发送队列默认关闭与 Solon 插件兼容升级

mica-mqtt 是国内开发者社区中活跃度较高的轻量 MQTT 客户端/服务端开源组件，面向物联网场景提供 Java 生态的 MQTT 接入能力。2.6.4 版本虽然改动条目不多，但两条变更都直接关系到运行时行为和框架兼容性——一条是客户端消息队列的默认策略回退，另一条是 Solon 插件初始化方式的接口迁移。如果你正在用 mica-mqtt 做设备接入或消息桥接，这两处改动值得在升级前逐项核对。

待发送消息队列：默认关闭意味着什么

2.6.4 之前，mica-mqtt-client 的 pendingPublishQueueEnabled 默认为 true——客户端在连接断开期间，会将待发送的 QoS 1/2 消息暂存到内部队列，重连后自动补发。这个行为对"不能丢消息"的场景很友好，但对"消息时效性优先、断连期间的数据宁可丢弃"的场景（比如实时遥测上报）反而是一种负担：队列堆积后重连瞬间批量补发，可能冲垮下游消费端。

2.6.4 将默认值改为 false，断连期间不再暂存，直接丢弃未发出的消息。这和老版本（更早于队列功能引入前的版本）的行为一致，也符合大多数物联网上报场景的实际需求——设备断网后重新上报最新采样值即可，旧数据没有补发价值。

如果你确实需要断连补发能力，升级后必须显式开启：

// MqttClient 配置示例 —— 显式开启待发送队列
MqttClient client = MqttClient.create()
        .ip("mqtt-broker.example.com")
        .port(1883)
        .username("device01")
        .password("s3cret")
        // 关键配置：开启断连期间的消息暂存队列
        .pendingPublishQueueEnabled(true)
        // 队列容量上限，防止内存溢出（默认 1024）
        .pendingPublishQueueMaxSize(2048)
        .connect();

// 发布消息 —— 如果当前断连且队列已开启，消息会暂存
client.publish("/sensor/temperature", "36.5".getBytes(), MqttQoS.AT_LEAST_ONCE);

升级检查点：如果你的业务依赖断连补发，升级 2.6.4 后务必在配置中加上 pendingPublishQueueEnabled(true)，否则断连期间的消息会被静默丢弃，日志里也不会有补发记录。

Solon 插件初始化：从注解驱动到 LifecycleBean 接口

第二条变更涉及 solon-plugin（Solon 框架的 mica-mqtt 集成插件）。旧版插件使用 Solon 的注解式初始化钩子来注册 MQTT 客户端/服务端 Bean，但在 Solon 2.8.0+ 中，编译后的注解元数据导出行为发生了变化，导致旧版插件在高版本 Solon 下初始化时机不可靠，可能出现 Bean 未就绪就被引用的问题。

2.6.4 将初始化逻辑迁移到 LifecycleBean 接口——这是 Solon 提供的生命周期回调接口，通过 start() 和 stop() 方法显式控制组件的启停顺序，不再依赖注解扫描，兼容性更稳定。

对使用者来说，配置方式不变，但如果你在 Solon 项目中手动注册或覆盖了 mica-mqtt 的 Bean，需要注意生命周期顺序：

// Solon 项目中自定义 MQTT 客户端配置示例
@Configuration
public class MqttConfig {

    @Bean
    public MqttClientCustomizer clientCustomizer() {
        // 返回一个定制器，在 LifecycleBean.start() 阶段被调用
        return client -> {
            client.ip("mqtt-broker.example.com")
                  .port(1883)
                  .pendingPublishQueueEnabled(true)  // 别忘了这条
                  .keepAliveSec(60);
        };
    }
}

# application.yml —— Solon + mica-mqtt 常用配置片段
mqtt:
  client:
    enabled: true
    ip: mqtt-broker.example.com
    port: 1883
    username: device01
    password: s3cret
    pendingPublishQueueEnabled: true   # 2.6.4 后必须显式写，否则默认 false
    pendingPublishQueueMaxSize: 2048
    keepAliveSec: 60
    reconnectIntervalSec: 5

实际改造建议

场景一：纯上报型设备（遥测、状态推送）

大多数物联网终端只上报最新值，断连后旧数据没有补发意义。这类项目升级 2.6.4 风险最低——默认行为（队列关闭）正好符合你的需求，不需要改任何配置。

场景二：指令下发型网关（控制指令、配置推送）

如果你的 MQTT 客户端用来向设备下发控制指令，QoS 1/2 消息丢了就意味着指令没送达，必须补发。升级步骤：

1. 在代码配置或 YAML 中显式设置 pendingPublishQueueEnabled: true。
2. 评估 pendingPublishQueueMaxSize——长时间断连可能导致队列撑满内存，建议根据最大容忍断连时长 × 消息频率来计算上限。
3. 升级后在测试环境模拟断连-重连场景，观察补发时序和下游消费压力。

场景三：Solon 项目升级

如果你同时升级 Solon 到 2.8.0+，mica-mqtt 插件也必须同步到 2.6.4，否则初始化顺序可能异常。升级后关注启动日志中 LifecycleBean 相关的初始化输出，确认 MQTT 客户端在业务 Bean 之前就绪。

升级清单

两条改动都不大，但默认值翻转是容易踩坑的隐性变更——升级前花十分钟确认你的消息可靠性需求，比上线后排查"消息怎么丢了"要划算得多。