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

🔗 参考资料

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

相关推荐
IGAn CTOU44 分钟前
王炸级更新！Spring Boot 3.4 正式发布，新特性真香！
java·spring boot·后端
柯西劝我别收敛1 小时前
Koordinator-Scheduler 调度器源码解析
后端·云原生
ILYT NCTR1 小时前
爬虫学习案例3
爬虫·python·学习
tycooncool1 小时前
Spring中的IOC详解
java·后端·spring
303781 小时前
消息推送削峰落地方案
后端
爱敲代码的小黄1 小时前
我重新梳理了一遍 RAG，终于明白它不只是接个向量库
后端·面试·agent
不灭锦鲤2 小时前
网络安全学习第59天
学习·安全·web安全
张赐荣2 小时前
跨平台无障碍版随机数生成器
windows
楼田莉子2 小时前
同步/异步日志系统：日志落地模块\日志器模块\异步日志模块
linux·服务器·c++·学习·设计模式
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点032026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free04AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析05零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）06GPT-6发布日深度解析-Symphony架构200万Token实战07从零部署 Hermes Agent：一只"会成长的 AI 马"保姆级安装教程08基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南09智元机器人发布4款新品，2026营收目标5亿元10从限购到畅通：GLM-5.1 Coding Plan接入攻略