消费失败与死信处理
🎯 引言
用户付款后,通知程序需要发送一条短信。程序还在正常运行,但短信接口返回了发送失败。这时有两个问题:要不要再试一次?如果一直发不成功,这条通知任务应该放在哪里?本篇先把无法完成的任务放进一个单独的队列,留待检查;再加入一次重试,成功就结束,重试仍失败才把任务送进这个队列。
🧱 短信没发成功,不等于通知程序退出了
假设支付编号是 P4001。队列中有一条内容为 P4001 的消息,表示“请为这笔支付发送通知”。通知消费者从队列收到消息,再调用短信接口。
如果短信操作成功,消费者可以调用前面学过的 ack(message),报告任务完成。如果短信接口返回错误,消费者仍然可以捕获错误、打印日志,并决定下一步怎么办。
本篇的“失败”指短信操作失败,消费者程序仍在运行。 以下实验也要求消费者与 RabbitMQ 的连接、接收消息的通道正常。
如果消费者进程已经崩溃,它就不能再执行后面的代码。RabbitMQ 检测到断连后,会在本例配置下将尚未确认的消息重新放回原队列。这是消费确认篇介绍的情况,不是本篇要演示的主动拒绝。
🧱 拒绝当前消息,不放回原队列
RabbitMQ 不知道短信接口返回了什么。即使业务代码抛出了异常,也不会自动把任务送到失败队列。
先选择最简单的处理方式:短信操作失败后,不再尝试这条任务,把它留到别处检查。消费者通过收到消息的通道执行:
channel.nack(message, false, false);
nack 表示拒绝这次收到的消息。三个参数这样理解:
| 参数 | 本例填写的值 | 含义 |
|---|---|---|
| 要拒绝的消息 | message | 当前收到的这条消息 |
| 是否同时拒绝多条 | false | 只拒绝当前这一条 |
| 是否重新放回原队列 | false | 不放回原队列 |
这行代码只说明“拒绝,并且不放回”,没有指定消息接下来存在哪里。因此还要提前在原队列上配置一个去处。没有相应配置时,消息会被丢弃。
RabbitMQ 将这类被拒绝且不重新入队的消息作为死信处理。配置好以后,RabbitMQ 会先把消息交给一个交换机,再由交换机送进另一个队列。
- 接收死信的交换机,叫死信交换机。
- 用来保存这些消息的队列,通常叫死信队列。
它们仍然是前面学过的交换机和队列,只是这次负责接收失败任务。消费者发送 nack,具体转发由 RabbitMQ 执行。
🛠 给通知任务配置失败去处
本例使用以下三个名称,分别对应三个对象:
| 名称 | 对象 | 用途 |
|---|---|---|
notice.tasks | 原队列 | 保存待处理的通知任务 |
notice.dead-exchange | 死信交换机 | 接收被拒绝的消息并转发 |
notice.dead-queue | 失败队列 | 保存等待检查的通知任务 |
准备好这些对象及绑定关系后,消费者根据短信操作结果选择不同处理方式。下图先演示不重试的情况,并假设消费者进程、RabbitMQ 连接和接收通道正常:
正在加载流程图…
成功分支不会进入 notice.dead-queue。失败分支也不是仅凭接口报错就自动转发,而是由消费者发送 nack 后触发;进程退出或连接断开不属于图中的主动拒绝。后面的重试示例会在发送 nack 之前增加有限次数的尝试。
沿用前面的练习目录和 config.mjs,创建准备程序:
import amqp from 'amqplib';
import { rabbitmqUrl } from './config.mjs';
const connection = await amqp.connect(rabbitmqUrl);
const channel = await connection.createChannel();
await channel.assertExchange('notice.dead-exchange', 'direct', { durable: false });
await channel.assertQueue('notice.dead-queue', { durable: false });
await channel.bindQueue('notice.dead-queue', 'notice.dead-exchange', 'rejected');
await channel.assertQueue('notice.tasks', {
durable: false,
deadLetterExchange: 'notice.dead-exchange',
deadLetterRoutingKey: 'rejected',
});
console.log('通知工作队列和失败队列已建立');
await channel.close();
await connection.close();
先建立失败交换机、失败队列和绑定,然后在原队列 notice.tasks 上填写:
deadLetterExchange: 'notice.dead-exchange',
deadLetterRoutingKey: 'rejected',
deadLetterExchange 表示“死信交给哪个交换机”。deadLetterRoutingKey 表示“转交时使用什么路由键”。上面的绑定也使用 rejected,所以消息能从交换机进入 notice.dead-queue。
这两个设置写在原队列上,因为 RabbitMQ 需要知道从这里移出的消息该往哪里送。
node setup-failure.mjs
本篇直接在代码里设置,便于练习。已有队列的配置冲突处理沿用前文;生产环境也可以通过服务端策略管理死信设置,见官方死信文档。
本例使用非持久化队列,只验证 RabbitMQ 持续运行期间的转发。默认死信转发在目标队列不可用等情况下可能丢失消息,不能把它当作可靠归档。
🛠 用一条消息验证转发
发送任务
创建 send-notice.mjs,从命令参数读取支付编号,发送到原队列:
import amqp from 'amqplib';
import { rabbitmqUrl } from './config.mjs';
const connection = await amqp.connect(rabbitmqUrl);
const channel = await connection.createChannel();
const paymentId = process.argv[2] ?? 'P1001';
channel.sendToQueue('notice.tasks', Buffer.from(paymentId));
console.log('已提交通知任务', paymentId);
await channel.close();
await connection.close();
模拟短信操作失败
创建 notice-failure.mjs。它不会调用真实短信接口,而是收到消息就打印失败日志,再发送 nack:
import amqp from 'amqplib';
import { rabbitmqUrl } from './config.mjs';
const connection = await amqp.connect(rabbitmqUrl);
const channel = await connection.createChannel();
await channel.prefetch(1);
await channel.consume('notice.tasks', (message) => {
if (message === null) return;
console.log('模拟通知失败', message.content.toString());
channel.nack(message, false, false);
}, { noAck: false });
console.log('等待通知任务');
noAck: false 使用手动确认。prefetch(1) 让这个消费者一次最多持有一条未确认消息,便于观察。回调执行完后,程序继续等待下一条消息,不会因为打印了失败日志就退出。
查看失败队列数量
创建 inspect-failed.mjs,查询 notice.dead-queue 中等待处理的消息数:
import amqp from 'amqplib';
import { rabbitmqUrl } from './config.mjs';
const connection = await amqp.connect(rabbitmqUrl);
const channel = await connection.createChannel();
const state = await channel.checkQueue('notice.dead-queue');
console.log('失败队列等待数量', state.messageCount);
await channel.close();
await connection.close();
messageCount 是等待消息的数量。这个查询不会领取或删除消息,也不会显示具体哪条消息进入了队列。
运行并比较结果
如果之前做过本实验,先让原队列中的旧任务处理完,再停止旧消费者。下面只运行一个通知消费者,并确保没有其他程序读写失败队列。
终端一启动消费者,保持运行:
node notice-failure.mjs
终端二先记下失败队列数量,再提交任务:
node inspect-failed.mjs
node send-notice.mjs P4001
终端一应打印:
模拟通知失败 P4001
再到终端二查询一次:
node inspect-failed.mjs
转发完成后,数量应比发送前增加 1。例如原来是 0,现在是 1。已有旧失败消息也可以比较新增量。
结合消费者收到 P4001 的日志、实验期间没有其他程序读写队列的前提,可以核对本次转发;这个数量本身不包含支付编号,也不证明短信发送成功。如果数量持续不变,先检查消费者是否收到 P4001,再核对死信交换机、绑定和原队列上的配置。
🔁 失败后再试一次
前面的程序收到任务后,模拟短信失败,随即拒绝消息。现在给它一次补救机会:如果第一次发送失败,就等一秒再发一次。发送成功就确认消息;两次都失败才拒绝消息,按已有配置转入死信队列。
修改消费者的处理逻辑
下面这段代码放在消费回调中,读取 paymentId 之后。sendNotice 是示例自定义的模拟函数,不会实际发送短信:它返回 true 表示成功,返回 false 表示失败。参数 1、2 分别标记第一次和第二次调用。
let sent = await sendNotice(paymentId, 1);
if (!sent) {
await delay(1000);
sent = await sendNotice(paymentId, 2);
}
if (sent) {
channel.ack(message);
} else {
channel.nack(message, false, false);
}
sent 保存最近一次发送的结果。第一次成功,便跳过 if (!sent),直接确认;第一次失败,才等待一秒并进行第二次调用,然后根据第二次的结果确认或拒绝。delay(1000) 是等待一秒,完整文件已从 node:timers/promises 导入这个函数。
重试前没有发送 ack 或 nack,因此等待期间消息仍未确认。这里的失败由模拟函数返回 false 表示;真实接口返回错误或抛出异常时,需要先处理接口结果,不能假定它也会返回 false。
准备实验
从完整示例包取出 notice-retry.mjs,放在现有 config.mjs 旁边。这个文件包含上面的处理逻辑、模拟函数和连接代码,下面直接运行它,无需单独拼装代码片段。
保留前面建立的队列和绑定,等旧任务处理结束,再停止 notice-failure.mjs。每轮只运行一个通知消费者,期间不让其他程序读写死信队列。
第一次失败,重试成功
终端一启动 recover 模式。它把第一次调用的结果设为失败、第二次设为成功,用来验证重试成功时的处理:
node notice-retry.mjs recover
终端二先记下死信队列数量,再发送任务:
node inspect-failed.mjs
node send-notice.mjs P5002
终端一应依次打印,前两行相隔约一秒:
通知失败 P5002 第 1 次
通知成功 P5002 第 2 次
已发送消费确认 P5002
保持消费者运行,在终端二再次执行 node inspect-failed.mjs。死信队列数量应与发送前相同:这条任务重试成功,未进入死信队列。
两次都失败
上一条任务处理完成后,在终端一按 Ctrl+C 停止 recover 消费者,再启动 down 模式。它让两次调用都返回失败:
node notice-retry.mjs down
终端二重新记下死信队列数量,再发送新任务:
node inspect-failed.mjs
node send-notice.mjs P5003
终端一应打印:
通知失败 P5003 第 1 次
通知失败 P5003 第 2 次
已拒绝消息,不重新入队 P5003
保持消费者运行,在终端二再次执行 node inspect-failed.mjs。RabbitMQ 完成转发后,死信队列数量应比本轮发送前增加 1。
两组日志中的最后一行都只表示客户端调用了 ack 或 nack;消息是否进入死信队列,按前面的方法结合队列数量变化核对。
这个示例只在当前处理过程中重试一次。如果进程中断,未确认消息按消费确认篇的规则重新投递,新启动的消费者会从第一次调用开始。因此,同一条任务经历多次中断后,短信调用总次数可能超过两次。
等待的一秒内,当前消费者仍持有未确认消息;由于设置了 prefetch(1),它暂时不能领取下一条任务。这种写法适合短暂重试。调用 nack(message, false, true) 则是把消息放回原队列,可能立即再次投递,不能代替这里的等待。
❓ 知识问答
Q1:短信接口恢复后,死信队列中的任务会自动再试吗?
不会。notice-retry.mjs 只读取 notice.tasks。消息进入 notice.dead-queue 后,当前程序不会再领取它,需要检查失败原因后另行安排补发。
Q2:死信只来自消费者主动拒绝吗?
不是,消息过期等情况也可能产生死信。本篇只演示消费者拒绝且不重新入队这一种原因。
🧪 小练习
先让当前任务处理结束,再停止消费者。用 normal 模式验证“第一次成功就不重试”:
node notice-retry.mjs normal
在另一终端记下死信队列数量,再发送 P5004:
node inspect-failed.mjs
node send-notice.mjs P5004
预期只打印一次“通知成功 P5004 第 1 次”,然后打印“已发送消费确认 P5004”;没有第二次调用,死信队列数量不增加。对照代码说明为什么这次跳过了 if (!sent)。
🎉 你已经能在通知失败后再试一次,并把仍然失败的任务留待检查了!
