Java-210 Spring AMQP 整合 RabbitMQ：JavaConfig 注解配置、RabbitTemplate 发送/同步接收与坑位速查

武子康2025-12-24 9:00

TL;DR

  • 场景：Spring（JavaConfig/注解）快速接入 RabbitMQ，完成最小可跑的发消息与同步拉取。
  • 结论：用 CachingConnectionFactory + RabbitAdmin + RabbitTemplate + Queue Bean 即可完成基础链路；默认交换机直投队列名最省事。
  • 产出：可复用的配置骨架 + 常见错误定位与修复速查卡。

版本矩阵

项目 状态 说明
Spring Boot 版本 未提供 文中未给出；不同大版本（2.x/3.x）主要差异在 JDK 基线与依赖坐标，配置思路一致
Spring AMQP 版本 未提供 文中未给出；RabbitTemplate/RabbitAdmin/CachingConnectionFactory 的用法为长期稳定 API
RabbitMQ Broker 版本 未提供 文中未给出；示例使用默认端口 5672 与默认交换机直投，适配面较广
JDK 版本 已在文中体现 建议至少 JDK 8+（Boot 3.x 通常要求 17+）
连接方式 已验证 JavaConfig（@Configuration + @Bean），容器：AnnotationConfigApplicationContext 启动验证

Spring 整合 RabbitMQ

基本介绍

Spring AMQP 是 Spring 框架对 AMQP (Advanced Message Queuing Protocol) 协议的抽象实现，它提供了统一的编程模型来操作 AMQP。而 Spring Rabbit 是 Spring AMQP 的具体实现，专门针对 RabbitMQ 消息中间件进行了封装和扩展。

PS：续接上节的内容
PS：续接上节的内容
PS：续接上节的内容

基于注解

编写代码

RabbitConfiguration，这里注意，ConnectionFactory 的包不要导入错了！！！

java 复制代码 
package icu.wzk.config;

import org.springframework.amqp.core.AmqpAdmin;
import org.springframework.amqp.core.Queue;
import org.springframework.amqp.rabbit.connection.CachingConnectionFactory;
import org.springframework.amqp.rabbit.connection.ConnectionFactory;
import org.springframework.amqp.rabbit.core.RabbitAdmin;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@Configuration
public class RabbitConfiguration {

    private static final String HOST = "localhost";
    private static final int PORT = 5672;
    private static final String VHOST = "/";
    private static final String USERNAME = "admin";
    private static final String PASSWORD = "secret";

    /**
     * Spring AMQP 的连接工厂（生产/消费都用它）
     * - 内部会维护连接与 Channel 缓存
     * - 直接配置 host/port/vhost/user/pass 即可
     */
    @Bean
    public ConnectionFactory connectionFactory() {
        CachingConnectionFactory ccf = new CachingConnectionFactory(HOST, PORT);
        ccf.setVirtualHost(VHOST);
        ccf.setUsername(USERNAME);
        ccf.setPassword(PASSWORD);

        // 可选：限制缓存 channel 数量
        ccf.setChannelCacheSize(25);

        return ccf;
    }

    /** 自动声明 Queue/Exchange/Binding（只要你把它们声明成 Bean） */
    @Bean
    public AmqpAdmin amqpAdmin(ConnectionFactory factory) {
        return new RabbitAdmin(factory);
    }

    /** 发送/接收入口 */
    @Bean
    public RabbitTemplate rabbitTemplate(ConnectionFactory factory) {
        return new RabbitTemplate(factory);
    }

    /** 队列：建议 durable=true，避免 broker 重启丢队列 */
    @Bean
    public Queue queue() {
        return new Queue("myqueue", true, false, false);
    }
}

代码如下所示，切记切记，ConnectionFactory的包一定是： org.springframework.amqp.rabbit.connection.ConnectionFactory

demo程序讲解

使用 Spring 注解(JavaConfig) 方式实现 RabbitMQ 消息发送和同步接收的完整示例如下：

java 复制代码 
@Configuration
public class RabbitConfiguration {

    // 1. 声明连接工厂
    @Bean
    public ConnectionFactory connectionFactory() {
        CachingConnectionFactory factory = new CachingConnectionFactory();
        factory.setHost("localhost");
        factory.setPort(5672);
        factory.setUsername("guest");
        factory.setPassword("guest");
        return factory;
    }

    // 2. 声明 RabbitTemplate
    @Bean
    public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
        RabbitTemplate template = new RabbitTemplate(connectionFactory);
        // 设置消息转换器（可选）
        template.setMessageConverter(new Jackson2JsonMessageConverter());
        return template;
    }

    // 3. 声明队列
    @Bean
    public Queue myQueue() {
        return new Queue("myqueue");
    }

    // 4. 声明 RabbitAdmin（自动创建队列）
    @Bean
    public RabbitAdmin rabbitAdmin(ConnectionFactory connectionFactory) {
        return new RabbitAdmin(connectionFactory);
    }
}

@Service
public class MessageService {

    @Autowired
    private AmqpTemplate amqpTemplate;

    // 发送消息
    public void sendMessage(String message) {
        // 使用默认交换机(amq.default)发送消息
        // routingKey="myqueue" 将消息直接路由到同名队列
        amqpTemplate.convertAndSend("myqueue", message);
        System.out.println("发送消息: " + message);
    }

    // 同步接收消息
    public String receiveMessage() {
        // 同步拉取消息，队列为空返回null
        String message = (String) amqpTemplate.receiveAndConvert("myqueue");
        System.out.println("接收消息: " + message);
        return message;
    }
}

关键细节说明：

  1. 连接工厂配置：

    • CachingConnectionFactory 是常用的实现，支持连接池
    • 实际生产环境应从配置中心读取连接参数

  2. 消息转换：

    • 通过 setMessageConverter() 可以配置 JSON 等格式的转换器
    • 默认使用 SimpleMessageConverter 进行字符串转换

  3. 队列声明：

    • 队列声明后由 RabbitAdmin 自动创建到 broker
    • 可通过 QueueBuilder 设置队列属性（持久化、排他性等）

  4. 发送消息：

    • convertAndSend() 会自动将 Java 对象转换为消息
    • 默认交换机(amq.default)的路由规则要求 routingKey 必须完全匹配队列名

  5. 接收消息：

    • receiveAndConvert() 是同步阻塞操作
    • 适用于需要立即处理结果的场景
    • 长时间运行的服务应考虑使用 @RabbitListener 异步消费

应用场景示例：

java 复制代码 
@SpringBootApplication
public class Application implements CommandLineRunner {

    @Autowired
    private MessageService messageService;

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Override
    public void run(String... args) {
        // 发送测试消息
        messageService.sendMessage("Hello RabbitMQ");
        
        // 同步接收消息
        String received = messageService.receiveMessage();
        System.out.println("处理消息结果: " + received);
    }
}

注意事项：

  • 同步接收在高并发场景可能成为性能瓶颈
  • 消息处理失败时应考虑重试机制
  • 生产环境建议配置消息确认机制(acknowledgeMode)

启动程序

java 复制代码 
package icu.wzk;

import icu.wzk.config.RabbitConfiguration;
import org.springframework.amqp.core.AmqpTemplate;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
public class StartApp2 {

    private static final String QUEUE = "myqueue";

    public static void main(String[] args) {
        // 1) 启动基于注解的 Spring 容器，加载 RabbitConfiguration
        AnnotationConfigApplicationContext context =
                new AnnotationConfigApplicationContext(RabbitConfiguration.class);

        // 2) 获取 AMQP 操作入口（通常就是 RabbitTemplate）
        AmqpTemplate template = context.getBean(AmqpTemplate.class);

        // 3) 发送消息到队列（通过默认交换机实现）
        template.convertAndSend(QUEUE, "wzk");

        // 4) 同步拉取队列一条消息；若返回 null 说明当前队列为空/未投递成功/被其他消费者取走
        Object msg = template.receiveAndConvert(QUEUE);
        System.out.println(msg);

        // 5) 关闭容器，释放连接资源
        context.close();
    }
}

代码如下所示：

测试运行

错误速查

症状 根因定位 修复
编译通过但运行期各种类型不匹配/Bean 找不到ConnectionFactory 导错包（非 org.springframework.amqp.rabbit.connection.ConnectionFactory） IDE 跳转到 ConnectionFactory 定义，确认包路径统一替换为 Spring Rabbit 的 ConnectionFactory；清理无关依赖冲突
ACCESS_REFUSED - Login was refused 用户名/密码错误，或账号无权限 RabbitMQ 管理台 Users/Permissions；应用日志修正账号密码；为 vhost 配置读写权限
NOT_FOUND - no virtual host '/' 或无权限 vhost 不存在或权限未授权 管理台 Vhosts/Permissions；确认 setVirtualHost创建 vhost；授权用户到该 vhost；应用侧改为正确 vhost
java.net.ConnectException: Connection refused Broker 未启动/端口不通/地址错 telnet/nc 到 host:port；容器网络/防火墙启动 RabbitMQ；开放端口；修正 host/port
启动后队列没创建 未注册 RabbitAdmin/AmqpAdmin Bean，或容器未加载配置类 Spring 容器 Bean 列表；启动日志是否初始化 RabbitAdmin保证 RabbitAdmin/AmqpAdmin 为 Bean 且使用同一 ConnectionFactory；确保配置类被加载
404 NOT_FOUND - no queue 'myqueue' 队列未声明/声明到不同 vhost；或名称不一致 管理台 Queues；核对 vhost 与队列名统一队列名；确保队列在同一 vhost 自动创建或手动创建
发送成功但 receiveAndConvert 打印 null 队列为空、消息被其他消费者取走、路由键不匹配、发送到错误 vhost 管理台队列 Ready/Unacked；查看是否有消费者；核对 routingKey先停掉其他消费者；确保使用默认交换机直投时 routingKey=队列名；核对 vhost
MessageConversionException / 反序列化失败 发送与接收的 MessageConverter 不一致（String/JSON 混用） 查看 RabbitTemplate 的 messageConverter；检查消息 content-type统一转换器；String 就用默认；JSON 就全链路 Jackson2JsonMessageConverter 并统一对象类型
Broker 重启后队列/绑定丢失 队列/交换器未持久化（durable=false）或自动删除 管理台查看队列 Durable 标记；声明代码生产建议 durable=true；明确 autoDelete/exclusive 的语义并按需设置
声称"receiveAndConvert 是同步阻塞"，但实际很快返回 receiveAndConvert 默认是非阻塞拉取，空即返回 null 观察调用耗时与返回值若要阻塞/异步消费，改用 @RabbitListener；或用轮询+超时策略实现等待语义（不建议高并发下使用同步拉取）

其他系列

🚀 AI篇持续更新中（长期更新）

AI炼丹日志-29 - 字节跳动 DeerFlow 深度研究框斜体样式架 私有部署 测试上手 架构研究 ，持续打造实用AI工具指南！
AI研究-132 Java 生态前沿 2025：Spring、Quarkus、GraalVM、CRaC 与云原生落地
🔗 AI模块直达链接

💻 Java篇持续更新中（长期更新）

Java-207 RabbitMQ Direct 交换器路由：RoutingKey 精确匹配、队列多绑定与日志分流实战

MyBatis 已完结，Spring 已完结，Nginx已完结，Tomcat已完结，分布式服务已完结，Dubbo已完结，MySQL已完结，MongoDB已完结，Neo4j已完结，FastDFS 已完结，OSS已完结，GuavaCache已完结，EVCache已完结，RabbitMQ正在更新... 深入浅出助你打牢基础！
🔗 Java模块直达链接

📊 大数据板块已完成多项干货更新（300篇）：

包括 Hadoop、Hive、Kafka、Flink、ClickHouse、Elasticsearch 等二十余项核心组件，覆盖离线+实时数仓全栈！
大数据-278 Spark MLib - 基础介绍 机器学习算法 梯度提升树 GBDT案例 详解
🔗 大数据模块直达链接

相关推荐
五阿哥永琪2 小时前
java基础 异常（Exception和Error）
java·开发语言
黑头人2 小时前
Error: JAVA_HOME is not set and Java could not be found
java·开发语言
Wang's Blog2 小时前
RabbitMQ: 集群深度优化：容器化高可用、网络分区处理与状态监控
网络·分布式·rabbitmq
qq_336313932 小时前
java基础-异常
java·开发语言
jiayong232 小时前
`.flattened-pom.xml` 深度解析
xml
kkkkkkkkl242 小时前
Spring Boot 中基于线程池的订单创建并行化实践
java·spring boot·juc
廋到被风吹走2 小时前
【Spring】ThreadLocal详解 线程隔离的魔法与陷阱
java·spring·wpf
星辰离彬2 小时前
2025 IDEA运行报错：运行 xxxxApplication 时出错。命令行过长。 通过 JAR 清单或通过类路径文件缩短命令行，然后重新运行。
java·后端·intellij-idea·jar
古城小栈2 小时前
Java 响应式编程：Spring WebFlux+Reactor 实战
java·开发语言·spring
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05解决 WSL Ubuntu 中 /etc/resolv.conf 自动重置问题06Gemini3 生成的基于手势控制3D粒子圣诞树07CentOS的ISO镜像下载08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09Multisim使用教程详尽版--(2025最新版)10Labelme从安装到标注：零基础完整指南