Spring Boot 整合 MQTT 全流程详解（Windows 环境）—— 从 Mosquitto 安装到消息收发实战

松莫莫2025-12-11 11:20

目录

前言

[第一步：下载并安装 Mosquitto（MQTT Broker）](#第一步：下载并安装 Mosquitto（MQTT Broker）)

[1.1 什么是 Mosquitto？](#1.1 什么是 Mosquitto？)

[1.2 下载安装包](#1.2 下载安装包)

[1.3 安装 Mosquitto](#1.3 安装 Mosquitto)

[第二步：验证 Mosquitto 是否安装成功](#第二步：验证 Mosquitto 是否安装成功)

[2.1 检查 Windows 服务](#2.1 检查 Windows 服务)

[2.2 使用命令行测试](#2.2 使用命令行测试)

[2.3 发布/订阅测试（关键步骤！）](#2.3 发布/订阅测试（关键步骤！）)

[窗口 A：订阅主题](#窗口 A：订阅主题)

[窗口 B：发布消息](#窗口 B：发布消息)

[第三步：创建 Spring Boot 项目](#第三步：创建 Spring Boot 项目)

[3.1 使用 Spring Initializr 初始化项目](#3.1 使用 Spring Initializr 初始化项目)

[3.2 添加 MQTT 客户端依赖](#3.2 添加 MQTT 客户端依赖)

[第四步：编写 MQTT 配置与服务类](#第四步：编写 MQTT 配置与服务类)

[4.1 配置文件 application.yml](#4.1 配置文件 application.yml)

[4.2 创建 MQTT 配置类](#4.2 创建 MQTT 配置类)

[4.3 创建 MQTT 服务类](#4.3 创建 MQTT 服务类)

[第五步：提供 REST 接口测试发布功能](#第五步：提供 REST 接口测试发布功能)

第六步：运行与测试

[6.1 启动 Spring Boot 应用](#6.1 启动 Spring Boot 应用)

[6.2 测试接收外部消息](#6.2 测试接收外部消息)

[6.3 通过 HTTP 接口发布消息](#6.3 通过 HTTP 接口发布消息)

第七步：常见问题与解决方案

[🔗 参考资料](#🔗 参考资料)

前言

MQTT（Message Queuing Telemetry Transport）是一种轻量级的发布/订阅消息传输协议，广泛应用于物联网（IoT）、车联网、智能家居等领域。在 Java 生态中，Spring Boot 是构建微服务和后端系统的主流框架。本文将手把手教你 在 Windows 系统下安装 MQTT Broker（Mosquitto） ，并 使用 Spring Boot 集成 Eclipse Paho 客户端实现消息的发布与订阅，每一步都配有截图说明和代码解释，零基础也能轻松上手！

第一步：下载并安装 Mosquitto（MQTT Broker）

1.1 什么是 Mosquitto？

Mosquitto 是一个开源的 MQTT 消息代理（Broker），由 Eclipse 基金会维护，支持 MQTT v3.1.1 和 v5.0，轻量、稳定、跨平台。

1.2 下载安装包

  1. 打开官网下载页：https://mosquitto.org/download/
  2. 找到 Windows Installer 区域，点击链接（会跳转到文件列表页）
  3. 下载最新版 .exe 安装程序（例如 mosquitto-2.0.22-install-windows-x64.exe）

💡 提示：选择 x64 版本适用于 64 位 Windows 系统（绝大多数现代电脑都是 64 位）。

1.3 安装 Mosquitto

  1. 双击下载的 .exe 文件（建议右键 → "以管理员身份运行"）

  2. 在安装向导中，务必勾选以下两项：

    • ✅ Install mosquitto as a Windows service
      （将 Mosquitto 安装为系统服务，开机自启、后台运行）
    • ✅ Add mosquitto to PATH environment variable
      （将命令加入环境变量，方便在 CMD 中直接使用）

  3. 点击 Next → Install → Finish 完成安装。

修改安装路径为：D:\Program Files\mosquitto

第二步：验证 Mosquitto 是否安装成功

2.1 检查 Windows 服务

  1. 按 Win + R，输入 services.msc，回车
  2. 在服务列表中找到 mosquitto
  3. 确认其"状态"为 正在运行

2.2 使用命令行测试

  1. 打开 命令提示符（CMD） 或 PowerShell

  2. 输入以下命令查看帮助：

    mosquitto -h

如果输出帮助信息，说明已成功加入环境变量。

2.3 发布/订阅测试（关键步骤！）

打开 两个 CMD 窗口：

窗口 A：订阅主题
复制代码 
mosquitto_sub -h localhost -t "test/topic"

参数说明：

  • -h localhost：连接本地 Broker
  • -t "test/topic"：订阅的主题名
窗口 B：发布消息
复制代码 
mosquitto_pub -h localhost -t "test/topic" -m "Hello MQTT from Windows!"

-m 后面是消息内容

✅ 如果窗口 A 立即显示：

复制代码 
Hello MQTT from Windows!

恭喜！你的 MQTT Broker 已正常工作！

第三步：创建 Spring Boot 项目

3.1 使用 Spring Initializr 初始化项目

访问 https://start.spring.io/，配置如下：

  • Project: Maven
  • Language: Java
  • Spring Boot: 3.x（如 3.4.13）
  • Project Metadata:
    • Group: com.hui
    • Artifact: springboot-mqtt-demo
  • Dependencies:
    • Spring Web（用于提供 REST 接口）
    • Lombok（简化日志和 getter/setter）

点击 Generate 下载 ZIP，解压后用 IDEA 或 VS Code 打开。

3.2 添加 MQTT 客户端依赖

编辑 pom.xml，在 <dependencies> 中添加：

复制代码 
<!-- Eclipse Paho MQTT Client -->
<dependency>
    <groupId>org.eclipse.paho</groupId>
    <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
    <version>1.2.5</version>
</dependency>

⚠️ 注意：Spring Boot 3.x 基于 Jakarta EE 9+，但 Paho 仍使用 javax，目前兼容无问题。

第四步：编写 MQTT 配置与服务类

4.1 配置文件 application.yml

在 src/main/resources/application.yml 中添加：

复制代码 
mqtt:
  host: tcp://localhost:1883
  client-id: springboot-mqtt-client-${random.uuid}
  default-topic: test/topic
  • ${random.uuid} 确保每次启动客户端 ID 唯一，避免冲突
  • 默认连接本地 1883 端口（Mosquitto 默认端口）

4.2 创建 MQTT 配置类

新建包 com.example.springbootmqttdemo.config，创建 MqttConfig.java：

java 复制代码 
package com.hui.studymqtt.config;

import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MqttConfig {

    @Value("${mqtt.host}")
    private String host;

    @Value("${mqtt.client-id}")
    private String clientId;

    @Bean(destroyMethod = "close")
    public MqttClient mqttClient() throws Exception {
        MqttClient client = new MqttClient(host, clientId);
        MqttConnectOptions options = new MqttConnectOptions();
        options.setCleanSession(true); // 清理会话
        options.setConnectionTimeout(10); // 连接超时 10 秒
        options.setKeepAliveInterval(20); // 心跳间隔 20 秒
        client.connect(options);
        return client;
    }
}

destroyMethod = "close" 确保应用关闭时释放资源。

4.3 创建 MQTT 服务类

新建包 com.example.springbootmqttdemo.service，创建 MqttService.java：

java 复制代码 
package com.hui.studymqtt.service;

import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import java.nio.charset.StandardCharsets;

@Slf4j
@Service
public class MqttService {

    @Autowired
    private MqttClient mqttClient;

    @Value("${mqtt.default-topic}")
    private String defaultTopic;

    /**
     * 应用启动后自动订阅默认主题
     */
    @PostConstruct
    public void init() {
        subscribe(defaultTopic);
    }

    /**
     * 发布消息
     */
    public void publish(String topic, String message) {
        try {
            byte[] payload = message.getBytes(StandardCharsets.UTF_8);
            mqttClient.publish(topic, payload, 1, false); // QoS=1, 非保留
            log.info("✅ Published to [{}]: {}", topic, message);
        } catch (MqttException e) {
            log.error("❌ Publish failed", e);
        }
    }

    /**
     * 订阅主题
     */
    public void subscribe(String topic) {
        try {
            mqttClient.subscribe(topic, (tpc, msg) -> {
                String content = new String(msg.getPayload(), StandardCharsets.UTF_8);
                log.info("📥 Received from [{}]: {}", tpc, content);
                // TODO: 在此处处理业务逻辑（如入库、推送等）
            });
            log.info("🔔 Subscribed to topic: {}", topic);
        } catch (MqttException e) {
            log.error("❌ Subscribe failed", e);
        }
    }
}

第五步：提供 REST 接口测试发布功能

新建控制器 MqttController.java：

java 复制代码 
package com.hui.studymqtt.controller;


import com.hui.studymqtt.service.MqttService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/mqtt")
public class MqttController {

    @Autowired
    private MqttService mqttService;

    @PostMapping("/publish")
    public String publishMessage(@RequestParam String topic,
                                 @RequestBody String message) {
        mqttService.publish(topic, message);
        return "Message published to topic: " + topic;
    }
}

第六步：运行与测试

6.1 启动 Spring Boot 应用

确保 Mosquitto 服务正在运行（通过 services.msc 确认），然后启动 Spring Boot 项目。

控制台应输出：

6.2 测试接收外部消息

在 CMD 中执行：

复制代码 
mosquitto_pub -h localhost -t "test/topic" -m "Test from command line"

Spring Boot 控制台将打印：

6.3 通过 HTTP 接口发布消息

使用 Postman 或 curl 发送 POST 请求：

同时打开另一个 CMD 订阅：

✅ 双向通信成功！

第七步：常见问题与解决方案

问题 原因 解决方案
Connection lost Mosquitto 未启动 运行 net start mosquitto
Command not found 未加入 PATH 重新安装并勾选"Add to PATH"，或手动添加
客户端 ID 冲突 多个实例使用相同 ID 使用 ${random.uuid} 生成唯一 ID
中文乱码 编码不一致 统一使用 StandardCharsets.UTF_8

🔗 参考资料

📌 原创不易，欢迎点赞、收藏、关注！

相关推荐
知识分享小能手2 小时前
CentOS Stream 9入门学习教程，从入门到精通，CentOS Stream 9 中的 Shell 编程 —语法详解与实战案例(11）
linux·学习·centos
jiayong232 小时前
Windows 磁盘清理完全指南
windows
小码编匠2 小时前
WPF 实现高仿 Windows 通知提示框：工业级弹窗设计与实现
后端·c#·.net
狂奔小菜鸡2 小时前
Day27 | Java集合框架之List接口详解
java·后端·java ee
未秃头的程序猿2 小时前
《Spring Boot MongoDB革命性升级！silky-mongodb-spring-boot-starter发布，开发效率暴增300%！》
后端·mongodb
a程序小傲2 小时前
美团二面：KAFKA能保证顺序读顺序写吗?
java·分布式·后端·kafka
a努力。2 小时前
网易Java面试被问：fail-safe和fail-fast
java·windows·后端·面试·架构
白衣鸽子2 小时前
【基础数据篇】数据等价裁判：Comparer模式
后端·设计模式
计算机毕设指导62 小时前
基于微信小程序的宠物走失信息管理系统【源码文末联系】
java·spring boot·mysql·微信小程序·小程序·tomcat·宠物
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03UV安装并设置国内源04安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）05React CVE-2025-55182漏洞排查与修复指南06Linux下V2Ray安装配置指南07BongoCat - 跨平台键盘猫动画工具08【AutoGLM部署】本地私有化部署AI手机Agent09解决 WSL Ubuntu 中 /etc/resolv.conf 自动重置问题10从入门到实战：Gemini 3 使用指南速览