消费失败与死信处理

处理短信发送失败的通知任务,先验证失败消息的去处,再加入有限次数的重试。

🎯 引言

用户付款后,通知程序需要发送一条短信。程序还在正常运行,但短信接口返回了发送失败。这时有两个问题:要不要再试一次?如果一直发不成功,这条通知任务应该放在哪里?本篇先把无法完成的任务放进一个单独的队列,留待检查;再加入一次重试,成功就结束,重试仍失败才把任务送进这个队列。


🧱 短信没发成功,不等于通知程序退出了

假设支付编号是 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,创建准备程序:

setup-failure.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,从命令参数读取支付编号,发送到原队列:

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:

notice-failure.mjs
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 中等待处理的消息数:

inspect-failed.mjs
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)。


🎉 你已经能在通知失败后再试一次,并把仍然失败的任务留待检查了!