一、背景与问题缘起

在基于 Eclipse Paho MQTT 客户端（org.eclipse.paho.client.mqttv3）开发 MQTT 通信功能时，不少开发者会遇到以下核心问题：

1. 使用 1.2.0 版本时，开启自动重连后断开重连，无法恢复断开前的订阅关系，消息接收异常；
2. 对 MqttCallback 回调中的 deliveryComplete 方法理解模糊，不清楚其触发时机与实际价值；
3. 升级版本时担心兼容性问题，不敢贸然从 1.2.0 切换到最新稳定版 1.2.5。

本文将结合实际代码场景，详细解析从 1.2.0 升级到 1.2.5 的兼容性、核心问题修复，以及关键 API 的正确使用方式。

二、Paho MQTT 1.2.0→1.2.5 版本核心修复内容

1.2.x 系列是 Paho MQTT v3 客户端的最终维护分支，从 1.2.0 到 1.2.5 的迭代主要聚焦稳定性、可靠性修复，无破坏性更新，核心修复点如下：

表格

版本	发布时间	核心修复（解决 1.2.0 关键问题）
1.2.1	2018.02	修复重连时客户端 ID 被错误重置（cleanSession=false 场景）；修复 messageArrived 抛异常导致线程卡死
1.2.2	2018.07	修复 MQTT 3.1.1 CONNACK 报文解析失败；修复多线程 publish 线程安全问题
1.2.3	2019.11	修复 QoS 1/2 消息重发时重复接收；修复连接超时参数不生效
1.2.4	2020.12	修复通配符主题匹配错误；修复日志敏感信息（密码）泄露
1.2.5	2022.02	修复 SSLSocket 关闭时内存泄漏；修复 JDK 11+ TLS 1.3 握手失败；优化 KeepAlive 心跳逻辑

核心收益：1.2.0 中 “重连后订阅丢失” 的核心问题在 1.2.1 已修复，1.2.5 整合所有关键修复，是 1.2.x 系列最稳定版本。

三、1.2.0 升级到 1.2.5 的兼容性分析

以下是典型的 MQTT 客户端连接代码，升级到 1.2.5 完全兼容，无需修改核心逻辑：

// 初始化MQTT客户端
MqttClient mqttClient = new MqttClient(host, clientId, new MqttDefaultFilePersistence());
MqttConnectOptions mqttConnectOptions = new MqttConnectOptions();
// 断开重连后不保留会话（需重新订阅）
mqttConnectOptions.setCleanSession(true);
// 连接超时时间
mqttConnectOptions.setConnectionTimeout(4);
// 心跳间隔
mqttConnectOptions.setKeepAliveInterval(10);
// 开启自动重连
mqttConnectOptions.setAutomaticReconnect(true);

// SSL配置（按需）
if ("two".equals(sslType)) {
    mqttConnectOptions.setSocketFactory(SslUtil.getSocketFactory(rootCrtPath, clientCrtPath, clientKeyPath, clientPassword, sslProtocol));
}

// 用户名密码配置
if (StringUtils.isNotBlank(userName)) {
    mqttConnectOptions.setUserName(userName);
}
if (StringUtils.isNotBlank(password)) {
    mqttConnectOptions.setPassword(password.toCharArray());
}

// 连接服务端
mqttClient.setTimeToWait(Integer.parseInt(waitTime));
mqttClient.connect(mqttConnectOptions);

3.1 完全兼容的核心 API

• MqttClient 构造方法、connect 连接方法无变更；
• MqttConnectOptions 的 setCleanSession、setAutomaticReconnect 等核心配置方法签名、逻辑不变；
• SSL 相关的 setSocketFactory 方法入参要求（SSLSocketFactory）无变化。

3.2 重连订阅丢失问题的完整解决方案

因 setCleanSession (true) 时服务端不持久化订阅关系，需补充重连后订阅恢复逻辑：

// 设置回调，监听重连成功事件
mqttClient.setCallback(new MqttCallback() {
    @Override
    public void connectionLost(Throwable cause) {
        logger.warn("MQTT连接断开：{}", cause.getMessage());
    }

    @Override
    public void messageArrived(String topic, MqttMessage message) throws Exception {
        // 处理接收的消息
    }

    @Override
    public void deliveryComplete(IMqttDeliveryToken token) {
        // 消息投递完成回调（下文详细解析）
        try {
            logger.info("消息投递完成：主题={}, 消息ID={}", token.getTopics()[0], token.getMessageId());
        } catch (MqttException e) {
            logger.error("获取投递信息失败", e);
        }
    }

    // 重连成功回调
    @Override
    public void connectComplete(boolean reconnect, String serverURI) {
        if (reconnect) {
            logger.info("MQTT重连成功，重新订阅主题");
            // 重连后重新订阅（替换为实际业务主题）
            try {
                mqttClient.subscribe("your/business/topic", 1);
            } catch (MqttException e) {
                logger.error("重连后订阅失败", e);
            }
        }
    }
});

四、核心回调方法：deliveryComplete 深度解析

4.1 方法核心作用

deliveryComplete 是 MQTT 客户端的 “消息投递回执”，当客户端确认消息被服务端成功接收并处理后触发，仅通知 “服务端已收到”，不代表订阅者已接收。

4.2 触发时机（与 QoS 强相关）

表格

QoS 级别	触发时机	可靠性说明
0（最多一次）	消息发送后立即触发	仅代表 “消息已发出”，不保证服务端接收
1（至少一次）	收到服务端 PUBACK 确认后触发	保证服务端已收到，至少送达一次
2（恰好一次）	完成三次握手（PUBREC/PUBREL/PUBCOMP）后触发	最高可靠性，保证消息唯一处理

4.3 典型使用场景

1. 消息发送状态监控：记录消息投递结果，便于问题排查；
2. 异步发布失败重试：异步发布时无异常抛出，可通过 “是否触发该回调” 判断投递是否成功；
3. 业务流程闭环：触发回调后更新 “消息已提交” 状态，完成业务逻辑。

4.4 常见误区

• 误区 1：触发回调 = 订阅者已收到消息→错误，订阅者接收消息在 messageArrived 回调中体现；
• 误区 2：该方法必须实现→错误，可留空，但生产环境建议打印日志；
• 误区 3：同步发布无需关注→同步发布失败会抛异常，异步发布需依赖该回调确认结果。

五、升级操作与注意事项

5.1 升级步骤

1. 修改 Maven 依赖版本：

<dependency>
    <groupId>org.eclipse.paho</groupId>
    <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
    <version>1.2.5</version>
</dependency>

1. 执行 mvn clean 清理旧依赖，重新编译项目；
2. 测试核心场景：网络断开重连、SSL 连接、消息收发。

5.2 注意事项

1. JDK 11 + 环境：1.2.5 修复了 TLS 1.3 握手失败问题，无需额外配置；
2. SSL 连接：1.2.5 修复了握手超时设置不生效问题，setConnectionTimeout 配置可正常生效；
3. 生产环境：建议保留 deliveryComplete 日志，便于排查消息投递问题。

六、总结

1. 从 1.2.0 升级到 1.2.5 完全兼容，核心 API 无变更，且修复了重连客户端 ID 异常、内存泄漏、SSL 兼容性等关键问题；
2. 重连订阅丢失问题需结合 connectComplete 回调补充订阅恢复逻辑（适配 cleanSession=true 的协议规范）；
3. deliveryComplete 回调是消息投递到服务端的确认机制，触发时机与 QoS 强相关，生产环境建议完善该回调的日志或业务逻辑。

升级到 1.2.5 不仅能解决 1.2.0 的核心问题，还能提升客户端在长连接、高并发、复杂网络环境下的稳定性，是 1.2.x 系列的最优选择。