实战：软件架构网络系列之【 MQTT V5工具类：MqttClientV5Util】

概叙

科普文：软件架构网络系列之【应用层协议：MQTT(消息队列遥测传输)详解】-CSDN博客

科普文：软件架构网络系列之【在线公共 MQTT 服务器梳理】-CSDN博客

实战：软件架构网络系列之【 MQTT V3工具类：MqttClientV3Util】-CSDN博客

实战：软件架构网络系列之【 MQTT基层功能：发布/订阅】-CSDN博客

实战：软件架构网络系列之【 MQTT基层功能：MQTT遗嘱消息（可靠传输保障）】-CSDN博客

实战：软件架构网络系列之【 MQTT基层功能：带遗嘱消息的智能家居温度传感器（可靠传输保障）】-CSDN博客

实战：软件架构网络系列之【 MQTT基础功能：MQTT over SSL/TLS 安全通信（安全传输）】-CSDN博客

实战：软件架构网络系列之【 MQTT基础功能：MQTT 重连（可靠传输保障）】-CSDN博客

实战：软件架构网络系列之【MQTT基础功能：MQTT多主题订阅】-CSDN博客

【摘要】本系列文章全面解析MQTT协议及其应用实践。

基础篇详细介绍了MQTT作为轻量级发布/订阅协议的特性，并整理了6个主流公共MQTT服务器（如Mosquitto、HiveMQ等）的地址端口信息。

实战篇包含：1）开发MqttClientV3/V5工具类简化客户端操作；2）实现多主题订阅与发布功能；3）通过遗嘱消息保障可靠传输；4）构建智能家居传感器案例；5）配置SSL/TLS安全通信。

特别提供了MQTT5.0工具类实现，支持用户属性等新特性，包含连接管理、异常处理等完整功能，适用于物联网开发场景。文中还对比了各公共Broker的协议支持情况，为开发者提供实用参考。

免费公共 MQTT Broker

MQTT V5工具类：MqttClientV5Util

MqttClientV5Util封装了MQTT 5.0客户端的创建、连接和关闭操作，支持默认与自定义配置。

主要功能包括：获取客户端实例、设置连接参数（如clean start、keep alive等）、建立连接及安全断开连接。工具类简化了MQTT客户端的使用流程。

package com.zxx.study.rjava.mqtt;

import com.zxx.study.common.util.ZhouxxTool;
import org.eclipse.paho.mqttv5.client.MqttClient;
import org.eclipse.paho.mqttv5.client.MqttConnectionOptions;
import org.eclipse.paho.mqttv5.client.persist.MemoryPersistence;
import org.eclipse.paho.mqttv5.common.MqttException;
import org.eclipse.paho.mqttv5.common.packet.UserProperty;

import java.util.ArrayList;
import java.util.List;

/**
 * MQTT 5.0 客户端工具类
 *
 * @author zhouxx
 * @create 2024-10-10 13:16
 */
public class MqttClientV5Util {
    private static final String BROKER_URL = "tcp://test.mosquitto.org:1883";
    private static final String DEFAULT_CLIENT_ID = "JavaMqtt5Client";
    private static final String DEFAULT_TOPIC = "mqtt5/topic";

    /**
     * 获取默认配置的MQTT 5.0客户端
     *
     * @return MqttClient实例
     * @throws MqttException 创建客户端时发生错误
     */
    public static MqttClient getMqttClient() throws MqttException {
        return new MqttClient(BROKER_URL, DEFAULT_CLIENT_ID, new MemoryPersistence());
    }

    /**
     * 获取自定义配置的MQTT 5.0客户端
     *
     * @param broker    MQTT broker地址
     * @param clientId  客户端ID
     * @return MqttClient实例
     * @throws MqttException 创建客户端时发生错误
     */
    public static MqttClient getMqttClient(String broker, String clientId) throws MqttException {
        return new MqttClient(broker, clientId, new MemoryPersistence());
    }

    /**
     * 使用默认配置连接MQTT 5.0客户端
     *
     * @param mqttClient MQTT客户端实例
     * @throws MqttException 连接时发生错误
     */
    public static void connect(MqttClient mqttClient) throws MqttException {
        MqttConnectionOptions options = new MqttConnectionOptions();
        options.setCleanStart(true);
        options.setKeepAliveInterval(20);
        options.setConnectionTimeout(10);

        mqttClient.connect(options);
    }

    /**
     * 使用默认配置连接MQTT 5.0客户端
     *
     * @param mqttClient MQTT客户端实例
     * @throws MqttException 连接时发生错误
     */
    public static void setMqttConnectionOptions(MqttClient mqttClient) throws MqttException {
        MqttConnectionOptions subOpts = new MqttConnectionOptions();
        subOpts.setCleanStart(false);
        // MQTT 5.0用户属性示例
        List<UserProperty> userProperties = subOpts.getUserProperties()==null?new ArrayList<UserProperty>():subOpts.getUserProperties();
        userProperties.add(new UserProperty("priority", "high"));
        userProperties.add(new UserProperty("version", "5.0"));
        userProperties.add(new UserProperty("client", "Java"));
        subOpts.setUserProperties(userProperties);
        subOpts.setKeepAliveInterval(60);
        subOpts.setConnectionTimeout(10);
        mqttClient.connect(subOpts);
    }

    /**
     * 使用自定义配置连接MQTT 5.0客户端
     *
     * @param mqttClient MQTT客户端实例
     * @param options    连接选项
     * @throws MqttException 连接时发生错误
     */
    public static void connect(MqttClient mqttClient, MqttConnectionOptions options) throws MqttException {
        mqttClient.connect(options);
    }

    /**
     * 安全关闭MQTT 5.0客户端
     *
     * @param mqttClient MQTT客户端实例
     */
    public static void close(MqttClient mqttClient) {
        if (mqttClient != null && mqttClient.isConnected()) {
            try {
                mqttClient.disconnect();
                ZhouxxTool.printTimeAndThread("已断开连接");
            } catch (MqttException e) {
                e.printStackTrace(); // 或使用日志框架记录
            } finally {
                try {
                    mqttClient.close();
                    ZhouxxTool.printTimeAndThread("客户端已关闭");
                } catch (MqttException e) {
                    e.printStackTrace(); // 或使用日志框架记录
                }
            }
        }
    }
}

MQTT 5.0 客户端工具类，封装了 MQTT 5.0 客户端的创建、连接配置、以及安全关闭等常用操作，旨在简化 MQTT 5.0 客户端的使用流程，提供默认配置和自定义配置的灵活支持。

该工具类是 MQTT 5.0 客户端的轻量级封装，提供了客户端创建、连接配置（含 MQTT 5.0 用户属性）、安全关闭等核心功能的标准化实现，适合用于快速集成 MQTT 5.0 通信功能的项目，尤其适合需要兼容 MQTT 5.0 特性的物联网或消息推送场景。

以下是详细解析：

核心功能

1. 客户端实例化：提供默认配置和自定义配置两种方式创建 MQTT 5.0 客户端（基于 Eclipse Paho MQTT 5.0 客户端库）。

2. 连接配置：支持默认连接参数（如清理会话、心跳间隔等）和高级配置（如 MQTT 5.0 用户属性、自定义超时时间）。

3. 安全关闭：确保客户端在断开连接和释放资源时处理异常，避免资源泄漏。

4. MQTT 5.0 特性支持：演示了 MQTT 5.0 特有的用户属性（User Properties）功能，用于传递附加元数据（如优先级、版本号等）。

设计亮点

1. MQTT 5.0 特性支持：通过 UserProperty 演示了 MQTT 5.0 的用户属性功能，便于扩展业务元数据（如消息优先级、客户端类型等）。

2. 灵活配置：提供默认配置和自定义配置两种方式，适应不同场景需求（如测试环境快速初始化或生产环境精细控制）。

3. 资源安全：close 方法确保客户端在断开连接和释放资源时处理异常，避免因未关闭连接导致的内存或网络泄漏。

4. 工具类封装：将客户端创建、连接、关闭等高频操作封装为静态方法，简化调用方的代码复杂度。

注意事项

1. 依赖库：需引入 Eclipse Paho MQTT 5.0 客户端库（如 org.eclipse.paho:org.eclipse.paho.mqttv5.client）。

2. 测试环境限制：使用 tcp://test.mosquitto.org:1883（非加密端口），适用于测试；生产环境需替换为加密代理（如 ssl:// 协议）并配置安全参数（如证书、用户名/密码）。

3. 硬编码风险：默认的代理地址、客户端 ID 等建议通过配置文件管理（如 application.properties），提升灵活性。

4. 日志优化：当前使用 printStackTrace() 打印异常，实际项目建议集成日志框架（如 Log4j2 或 SLF4J）进行统一管理。

高级连接配置（MQTT 5.0 用户属性）

public static void setMqttConnectionOptions(MqttClient mqttClient) throws MqttException {
    MqttConnectionOptions subOpts = new MqttConnectionOptions();
    subOpts.setCleanStart(false); // 不清理会话（恢复历史会话状态）
    
    // 设置 MQTT 5.0 用户属性（附加元数据）
    List<UserProperty> userProperties = subOpts.getUserProperties() == null 
        ? new ArrayList<UserProperty>() 
        : subOpts.getUserProperties();
    userProperties.add(new UserProperty("priority", "high")); // 优先级：高
    userProperties.add(new UserProperty("version", "5.0"));  // 协议版本：5.0
    userProperties.add(new UserProperty("client", "Java"));  // 客户端类型：Java
    subOpts.setUserProperties(userProperties);
    
    subOpts.setKeepAliveInterval(60); // 心跳间隔 60 秒
    subOpts.setConnectionTimeout(10); // 连接超时 10 秒
    mqttClient.connect(subOpts);      // 执行连接
}

• CleanStart=false：表示尝试恢复之前的会话状态（适用于需要持久化订阅或未确认消息的场景）。
• UserProperties：MQTT 5.0 特有功能，允许在连接时附加自定义键值对（如优先级、版本号、客户端类型等），代理或服务端可据此实现差异化处理。
• 其他参数：心跳间隔延长至 60 秒，连接超时保持 10 秒。