SYSTEM
RabbitMQ 高级特性:死信队列 + 延迟队列
src/content/notes/blog-dev/RabbitMQ高级特性-死信队列与延迟队列.md RabbitMQ 高级特性:死信队列 + 延迟队列
项目:blog 个人博客
技术栈:Spring Boot 3 + RabbitMQ + Redis + MySQL
日期:2026-08-04
一、整体设计思路
1.1 为什么需要死信队列(DLX)
在改造前,4 个业务消费者(评论、摘要、点赞、浏览记录)各自的错误处理是孤立的——每个业务队列绑定一个独立的死信交换机和死信队列(blog.comment.dlx.exchange → blog.comment.dlx.queue,以此类推),共 8 个 DLX 组件。
问题:
- 组件膨胀:4 个业务 = 4 个 DLX 交换机 + 4 个 DLX 队列 = 8 个额外 Bean
- 排查分散:失败消息散落在不同队列,运维需要逐个查看
- 扩展困难:每新增一个业务队列,就要配套新增一对 DLX
改造目标:4 个业务队列统一指向同一个死信交换机 blog.dlx.exchange,所有消费失败的消息汇聚到 blog.dlx.queue,在 RabbitMQ 管理页面一目了然。
1.2 为什么需要延迟队列
场景需求:订单超时取消、定时发布文章、延迟通知等。
方案选择:采用 TTL + DLX 模式(无需安装额外插件),而非 Delayed Message Exchange 插件。
| 方案 | 优点 | 缺点 |
|---|---|---|
| TTL + DLX | 无需插件,通用性强 | 所有消息同一个 TTL,不同延迟需不同队列 |
| Delayed Message Exchange | 消息级延迟,灵活 | 需安装插件,运维成本高 |
当前项目使用 TTL + DLX,通过消息级 setExpiration() 覆盖队列默认 TTL,灵活支持不同延迟时长。
1.3 整体架构图
┌──────────────────────────────────────────────────────────────────────┐
│ 业务交换机(TopicExchange) │
│ │
│ comment.exchange ──→ comment.queue ──→ CommentNotifyConsumer │
│ summary.exchange ──→ summary.queue ──→ SummaryConsumer │
│ like.exchange ──→ like.queue ──→ LikeConsumer │
│ history.exchange ──→ history.queue ──→ BrowseHistoryConsumer │
│ │ │
│ │ 消费异常 throw RuntimeException │
│ ↓ │
│ ┌─────────────────────┐ │
│ │ DLX_EXCHANGE │ ← 统一死信交换机(DirectExchange)│
│ │ blog.dlx.exchange │ │
│ └──────┬──────────────┘ │
│ │ │
│ ┌──────────┼──────────────┐ │
│ │ routing key: │ routing key: │
│ │ blog.dlx │ blog.delay │
│ ↓ ↓ │
│ ┌──────────────┐ ┌─────────────────────┐ │
│ │ DLX_QUEUE │ │ DELAY_PROCESS_QUEUE │ │
│ │ blog.dlx. │ │ blog.delay.process. │ │
│ │ queue │ │ queue │ │
│ │ (人工排查) │ │ (DelayConsumer) │ │
│ └──────────────┘ └─────────────────────┘ │
│ ↑ │
│ │ TTL 到期后路由 │
│ ┌────────┴──────────┐ │
│ │ DELAY_QUEUE │ │
│ │ blog.delay.queue │ ← 30s TTL │
│ └────────┬──────────┘ │
│ ↑ │
│ ┌────────┴──────────┐ │
│ │ DELAY_EXCHANGE │ │
│ │ blog.delay.exchange│ ← DirectExchange │
│ └────────┬──────────┘ │
│ ↑ │
│ 生产者发送延迟消息 │
└──────────────────────────────────────────────────────────────────────┘
关键设计决策:
- 死信消息和延迟消息通过不同的 routing key 隔离(
blog.dlxvsblog.delay),互不干扰 - 业务队列不加
x-message-ttl,防止消费积压时消息被意外过期 - 死信交换机使用
DirectExchange(而非TopicExchange),精确路由,避免误匹配
二、具体步骤与核心代码
步骤 1:改造 RabbitMQConfig.java(统一死信 + 新增延迟)
文件:config/RabbitMQConfig.java
设计思路:
- 删除旧的 8 个 DLX 常量(
COMMENT_DLX_EXCHANGE、SUMMARY_DLX_QUEUE等) - 新增统一死信交换机/队列(
DLX_EXCHANGE/DLX_QUEUE) - 新增延迟队列相关的 4 个组件(
DELAY_EXCHANGE/DELAY_QUEUE/DELAY_PROCESS_QUEUE+ 绑定) - 4 个业务队列的
x-dead-letter-exchange统一指向DLX_EXCHANGE
// ==================== 常量定义 ====================
// 业务交换机/队列/路由键(保持不变)
public static final String COMMENT_EXCHANGE = "blog.comment.exchange";
public static final String COMMENT_QUEUE = "blog.comment.queue";
public static final String COMMENT_ROUTING_KEY = "blog.comment.notify";
public static final String SUMMARY_EXCHANGE = "blog.summary.exchange";
public static final String SUMMARY_QUEUE = "blog.summary.queue";
public static final String SUMMARY_ROUTING_KEY = "blog.summary.generate";
public static final String LIKE_EXCHANGE = "blog.like.exchange";
public static final String LIKE_QUEUE = "blog.like.queue";
public static final String LIKE_ROUTING_KEY = "blog.like.save";
public static final String HISTORY_EXCHANGE = "blog.history.exchange";
public static final String HISTORY_QUEUE = "blog.history.queue";
public static final String HISTORY_ROUTING_KEY = "blog.history.save";
// 统一死信队列(处理消费失败的消息)
public static final String DLX_EXCHANGE = "blog.dlx.exchange";
public static final String DLX_QUEUE = "blog.dlx.queue";
public static final String DLX_ROUTING_KEY = "blog.dlx";
// 延迟队列(TTL + DLX 模式)
public static final String DELAY_EXCHANGE = "blog.delay.exchange";
public static final String DELAY_QUEUE = "blog.delay.queue";
public static final String DELAY_ROUTING_KEY = "blog.delay";
public static final String DELAY_PROCESS_QUEUE = "blog.delay.process.queue";
public static final long DELAY_TTL_MS = 30_000; // 30 秒
// ==================== 业务队列(统一 DLX) ====================
@Bean
public Queue commentQueue() {
return QueueBuilder.durable(COMMENT_QUEUE)
.withArgument("x-dead-letter-exchange", DLX_EXCHANGE) // ← 统一指向
.withArgument("x-dead-letter-routing-key", DLX_ROUTING_KEY)
.build();
}
@Bean
public Queue summaryQueue() {
// 注意:业务队列不加 x-message-ttl,防止消费积压时消息被意外过期
return QueueBuilder.durable(SUMMARY_QUEUE)
.withArgument("x-dead-letter-exchange", DLX_EXCHANGE)
.withArgument("x-dead-letter-routing-key", DLX_ROUTING_KEY)
.build();
}
// likeQueue、historyQueue 同理...
// ==================== 统一死信 ====================
@Bean
public DirectExchange dlxExchange() {
return new DirectExchange(DLX_EXCHANGE, true, false);
}
@Bean
public Queue dlxQueue() {
return QueueBuilder.durable(DLX_QUEUE).build();
}
@Bean
public Binding dlxBinding() {
return BindingBuilder.bind(dlxQueue())
.to(dlxExchange())
.with(DLX_ROUTING_KEY);
}
// ==================== 延迟队列 ====================
@Bean
public DirectExchange delayExchange() {
return new DirectExchange(DELAY_EXCHANGE, true, false);
}
@Bean
public Queue delayQueue() {
return QueueBuilder.durable(DELAY_QUEUE)
.withArgument("x-message-ttl", DELAY_TTL_MS) // TTL
.withArgument("x-dead-letter-exchange", DLX_EXCHANGE) // 复用 DLX
.withArgument("x-dead-letter-routing-key", DELAY_ROUTING_KEY) // 不同 routing key
.build();
}
@Bean
public Queue delayProcessQueue() {
return QueueBuilder.durable(DELAY_PROCESS_QUEUE).build();
}
@Bean
public Binding delayProcessBinding() {
return BindingBuilder.bind(delayProcessQueue())
.to(dlxExchange())
.with(DELAY_ROUTING_KEY);
}
步骤 2:创建延迟消息 DTO
文件:dto/DelayMessage.java
设计思路:使用 bizType 字段区分业务类型,payload 承载扩展 JSON 数据,支持多种延迟场景复用同一套队列。
@Data
public class DelayMessage implements Serializable {
private String bizType; // order_cancel / article_publish / remind
private String bizId; // 业务 ID
private Long userId;
private String payload; // 扩展数据(JSON)
private Long timestamp;
}
步骤 3:创建延迟消息消费者
文件:service/DelayConsumer.java
设计思路:
- 监听
DELAY_PROCESS_QUEUE(不是DELAY_QUEUE,因为DELAY_QUEUE只有 TTL,没有消费者) - 通过
switch按bizType路由到不同处理方法,扩展新业务只需加一个 case - 处理失败抛出
RuntimeException→ 进入统一 DLX_QUEUE,形成双层保障
@Component
public class DelayConsumer {
private static final Logger log = LoggerFactory.getLogger(DelayConsumer.class);
@RabbitListener(queues = RabbitMQConfig.DELAY_PROCESS_QUEUE)
public void handleDelayedMessage(DelayMessage message) {
log.info("收到延迟消息, bizType={}, bizId={}, 延迟时间={}ms",
message.getBizType(), message.getBizId(),
System.currentTimeMillis() - message.getTimestamp());
try {
switch (message.getBizType()) {
case "order_cancel":
handleOrderCancel(message);
break;
case "article_publish":
handleArticlePublish(message);
break;
case "remind":
handleRemind(message);
break;
default:
log.warn("未知延迟消息类型, bizType={}", message.getBizType());
}
} catch (Exception e) {
log.error("延迟消息处理失败", e);
throw new RuntimeException("延迟消息处理失败, 进入死信队列", e);
}
}
private void handleOrderCancel(DelayMessage message) {
// TODO: 查询订单状态,若仍为未支付则取消
log.info("模拟订单取消, orderId={}", message.getBizId());
}
private void handleArticlePublish(DelayMessage message) {
// TODO: 定时发布文章
log.info("模拟定时发布文章, articleId={}", message.getBizId());
}
private void handleRemind(DelayMessage message) {
// TODO: 延迟提醒
log.info("模拟延迟提醒, bizId={}", message.getBizId());
}
}
步骤 4:生产者使用示例
设计思路:生产者发送消息到 DELAY_EXCHANGE,通过 MessagePostProcessor 设置消息级 TTL 覆盖队列默认值,支持不同延迟时长。
DelayMessage msg = new DelayMessage();
msg.setBizType("order_cancel");
msg.setBizId("ORDER_20260101_001");
msg.setUserId(1001L);
msg.setTimestamp(System.currentTimeMillis());
rabbitTemplate.convertAndSend(
RabbitMQConfig.DELAY_EXCHANGE,
RabbitMQConfig.DELAY_ROUTING_KEY,
msg,
message -> {
// 消息级 TTL 覆盖队列默认值
message.getMessageProperties().setExpiration("60000"); // 60 秒
return message;
});
三、消费者如何触发死信队列
4 个业务消费者统一通过”抛出 RuntimeException”触发 NACK → 死信路由:
// LikeConsumer —— DB 写入失败
catch (Exception e) {
log.error("点赞持久化失败, articleId={}", message.getArticleId(), e);
throw new RuntimeException("点赞持久化失败,进入死信队列", e);
}
// BrowseHistoryConsumer —— DB 写入失败
catch (Exception e) {
log.error("浏览记录持久化失败", e);
throw new RuntimeException("浏览记录持久化失败,进入死信队列", e);
}
// CommentNotifyConsumer —— 通知发送失败
catch (Exception e) {
log.error("处理评论通知失败", e);
throw new RuntimeException(e);
}
// SummaryConsumer —— AI API 限流 / 调用失败
catch (Exception e) {
log.error("AI 摘要生成失败(可重试)", e);
throw new RuntimeException("摘要生成失败, 进入死信队列", e);
}
Spring AMQP 默认 defaultRequeueRejected=false,抛出异常后消息不重新入队,而是按队列配置的 x-dead-letter-exchange 路由到 blog.dlx.queue。
四、优化前后对比
| 维度 | 优化前 | 优化后 |
|---|---|---|
| DLX 交换机数量 | 4 个(每个业务一个) | 1 个统一 DLX |
| DLX 队列数量 | 4 个(每个业务一个) | 1 个统一 DLX + 1 个延迟处理队列 |
| 配置 Bean 数量 | 16 个(4业务×2交换机 + 4业务×2队列) | 11 个(4业务 + 1DLX + 3延迟) |
| 失败消息排查 | 需逐个查看 4 个队列 | 只看 blog.dlx.queue 一个队列 |
| 新增业务 DLX | 需新增一对交换机+队列 | 零代码,队列参数中指定 DLX 即可 |
| 延迟队列 | 无 | 支持 TTL + DLX 模式延迟 |
| 消息隔离 | 无隔离(失败消息和延迟消息混合) | routing key 隔离(blog.dlx vs blog.delay) |
五、遇到的 Bug 及修复
Bug 1:BlogCacheConstants 重复常量定义
现象:编译错误 Duplicate field
原因:点赞同步相关的常量(LIKE_SYNC_LOCK、ARTICLE_LIKE_DIRTY_KEY、ARTICLE_LIKE_COUNT_KEY)在类中定义了两次——一组 public static final,一组包级私有。
修复:删除重复的包级私有定义。
// 修复前(第 47-51 行有重复定义)
String LIKE_SYNC_LOCK = "blog:like:sync:lock";
String ARTICLE_LIKE_DIRTY_KEY = "blog:article:like:dirty";
String ARTICLE_LIKE_COUNT_KEY = "blog:article:like:count:";
// 修复后:删除以上三行,保留 public static final 版本
Bug 2:BrowseHistory 索引列名使用 Java 属性名
现象:@Index 的 columnList 使用 Java 驼峰属性名 browseTime,但 JPA 默认命名策略将其转为 browse_time,导致索引定义中的列名与物理列名不匹配,索引实际失效。
修复:columnList 中使用数据库列名。
// 修复前
@Index(name = "idx_user_time", columnList = "userId, browseTime DESC")
// 修复后
@Index(name = "idx_user_time", columnList = "userId, browse_time DESC")
Bug 3:BrowseHistoryConsumer 幂等性 key 粒度太粗
现象:同一用户对同一篇文章的浏览记录,永远只有第一次会持久化到 DB,后续全部被幂等性拦截。
原因:幂等性 key 只用了 userId:articleId,不含时间戳,导致不同时间点的浏览被当作重复消息。
修复:key 追加 message.getTimestamp()。
// 修复前
String doneKey = HISTORY_DONE_PREFIX + message.getUserId() + ":" + message.getArticleId();
// 修复后
String doneKey = HISTORY_DONE_PREFIX + message.getUserId() + ":" + message.getArticleId()
+ ":" + message.getTimestamp();
Bug 4:@Transactional 注解导入错误
现象:ArticleServiceImpl.syncLikeCountToDB() 的 @Transactional(rollbackFor = Exception.class) 编译报错。
原因:import 的是 jakarta.transaction.Transactional,该注解没有 rollbackFor 属性。
修复:改为 org.springframework.transaction.annotation.Transactional。
// 修复前
import jakarta.transaction.Transactional;
// 修复后
import org.springframework.transaction.annotation.Transactional;
Bug 5:redisUtil.get() 返回类型与 String 不兼容
现象:syncLikeCountToDB() 中 String countStr = redisUtil.get(...) 编译报错。
原因:redisUtil.get() 返回 Object,不能直接赋值给 String。
修复:改用 Object 接收,通过 instanceof Number 安全转换。
// 修复前
String countStr = redisUtil.get(ARTICLE_LIKE_COUNT_KEY + articleId);
int realLikeCount = Objects.nonNull(countStr) ? Integer.parseInt(countStr) : 0;
// 修复后
Object countObj = redisUtil.get(ARTICLE_LIKE_COUNT_KEY + articleId);
int realLikeCount = countObj instanceof Number ? ((Number) countObj).intValue() : 0;
Bug 6:启动报 PRECONDITION_FAILED(队列参数冲突)
现象:IDEA 启动时 RabbitMQ 报错:
PRECONDITION_FAILED - inequivalent arg 'x-dead-letter-exchange' for queue 'blog.comment.queue':
received 'blog.dlx.exchange' but current is 'blog.comment.dlx.exchange'
原因:RabbitMQ 中已存在旧队列,其 x-dead-letter-exchange 是旧值 blog.comment.dlx.exchange。新代码要声明同一个队列但 DLX 改为 blog.dlx.exchange,RabbitMQ 不允许修改已有队列的参数。
修复:删除 RabbitMQ 中所有旧队列,重启后 Spring 自动用新参数创建。删除的队列列表:
blog.comment.queue blog.comment.dlx.queue
blog.summary.queue blog.summary.dlx.queue
blog.like.queue blog.like.dlx.queue
blog.history.queue blog.history.dlx.queue
六、涉及文件清单
| 文件 | 操作 | 说明 |
|---|---|---|
config/RabbitMQConfig.java |
改造 | 统一 DLX + 新增延迟队列 |
dto/DelayMessage.java |
新建 | 延迟消息 DTO |
service/DelayConsumer.java |
新建 | 延迟消息消费者 |
common/constant/BlogCacheConstants.java |
修复 | 删除重复常量 |
entity/BrowseHistory.java |
修复 | 索引列名改为数据库列名 |
service/BrowseHistoryConsumer.java |
修复 | 幂等性 key 加时间戳 |
service/impl/ArticleServiceImpl.java |
修复 | @Transactional 导入 + 类型转换 |
七、总结
-
统一 DLX 降低运维成本:4 个业务队列共用一个死信交换机,失败消息汇聚到
blog.dlx.queue,在 RabbitMQ 管理页面一处查看。Bean 数量从 16 个减少到 11 个。 -
延迟队列采用 TTL + DLX 模式:无需额外插件,利用死信机制实现延迟投递。通过 routing key 隔离(
blog.dlxvsblog.delay)与死信消息互不干扰。生产者可通过消息级setExpiration()覆盖队列默认值,支持不同延迟时长。 -
业务队列不加 TTL:这是容易被忽略的细节。如果在业务队列上设置
x-message-ttl,当消费积压时,仍在队列中等待的消息会因超过 TTL 被过期丢弃,而非真正的”消费失败”。延迟队列和业务队列必须分开。 -
幂等性 key 要包含时间戳:对于”同一用户可多次浏览同一文章”这类场景,幂等性 key 只用
userId:articleId会导致后续浏览记录全部丢失。加上timestamp后,只有同一次投递的重复消息被拦截。 -
修改队列参数需先删除旧队列:RabbitMQ 不允许
queueDeclare修改已有队列的参数(如x-dead-letter-exchange)。生产环境变更队列配置时,需先通过管理页面或 CLI 删除旧队列,再重新声明。