任务失败重试与异常处理
🎯 引言
学完本文,你能配置有限次数的失败重试,区分可以重试与不应重试的错误,并设置已完成和失败任务的清理规则。
沿用 BullMQ 快速入门 的配置与处理函数。本课程使用 BullMQ 5.61.2。
🧱 任务失败与异常分类
处理函数抛出错误时,BullMQ 会把这次执行记为失败。如果 Job 配置了重试次数,它可能稍后再次进入可执行状态;错误原因会保存在 Job 记录中。
适合重试的是可能暂时恢复的故障,例如外部服务超时;格式校验错误、必需资料缺失等问题通常不会因重复执行而改变。重试只安排再次尝试,不会修复输入数据。
BullMQ 要求失败值为 Error 对象,才能可靠记录错误信息。不要捕获错误后只打印日志并正常返回,否则队列会把任务当作成功。
🔁 重试次数与退避策略
attempts 设置一次 Job 最多执行多少次,包括首次执行;退避策略决定失败后等待多久再重试。等待时间可以固定,也可以逐步延长,避免故障期间立即连续请求依赖服务。
新建 retry-worker.mjs,第一次故意失败,第二次正常处理:
import { Worker } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';
import { writeText } from './write-text.mjs';
async function processJob(job) {
console.log('尝试次数:', job.attemptsMade + 1);
if (job.attemptsMade === 0) throw new Error('模拟暂时故障');
return writeText(job);
}
const worker = new Worker(queueName, processJob, {
connection: { ...connection, maxRetriesPerRequest: null },
});
worker.on('failed', (job, error) => console.error('本次失败:', job?.id, error.message));
worker.on('completed', job => console.log('最终完成:', job.id));
worker.on('error', error => console.error(error.message));
process.once('SIGINT', async () => { await worker.close(); });
在 add-retry.mjs 中使用重试选项提交任务:
import { Queue } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';
const queue = new Queue(queueName, {
connection: { ...connection, maxRetriesPerRequest: 1 },
});
queue.on('error', error => console.error(error.message));
try {
const job = await queue.add('write-text', { text: '重试后生成' }, {
attempts: 3,
backoff: { type: 'exponential', delay: 1000 },
});
console.log('任务编号:', job.id);
} finally {
await queue.close();
}
启动 Worker,再运行提交脚本。Worker 会先打印模拟故障,再次尝试后打印完成。exponential 让等待间隔随失败次数增长;attempts: 3 表示至多三次总执行。
🧱 不可恢复错误的处理
不可恢复错误是不论重试多少次都无法通过相同输入完成的错误。BullMQ 的 UnrecoverableError 可让当前 Job 直接停止重试并进入失败状态。
例如任务数据缺少文件编号属于输入问题,可以在处理函数验证后直接拒绝:
import { UnrecoverableError } from 'bullmq';
if (typeof job.data.fileId !== 'string') {
throw new UnrecoverableError('缺少文件编号');
}
这段检查放在处理函数开头。不要对临时网络错误使用不可恢复错误,否则任务不会按配置重试。
🪤 Worker 中断与任务恢复
Worker 中断时,尚未确认完成的任务可能在锁超时后被重新领取。这是为了避免任务因进程退出而永久卡在处理中,也意味着业务操作可能重复执行。
服务正常关闭时调用 worker.close(),让当前处理有机会结束。突然断电、强制结束进程或网络断开仍可能中断工作,因此任务处理函数应设计为重复执行时不会造成额外副作用。
连接错误与任务函数错误不是同一类失败:前者影响 Worker 领取工作,后者是一次 Job 的处理结果。按需监听 Worker 的 error 和 Job 的 failed,不要把 Redis 重连当成任务重试策略。
🧹 已完成与失败任务的清理
清理规则限制 Redis 中保留的历史 Job 数量和时间。它删除任务记录,不会撤销已完成的业务操作,也不会自动删除任务生成的文件。
在 queue.add() 的选项中加入:
removeOnComplete: { age: 3600, count: 100 },
removeOnFail: { age: 86400, count: 1000 },
age 单位为秒,count 是最多保留的记录数。完成记录保留一小时或最多一百项,失败记录保留一天或最多一千项,先达到的条件会触发清理。清理以惰性方式发生,不能当成精确计时器。
需要长期审计时,应将必要的任务编号、结果和错误另存到业务数据库或日志系统,再决定队列历史的保留时间。详见 BullMQ 自动清理说明。
❓ 知识问答
Q1:failed 事件每次触发就说明不会再试了吗?
不一定。它可能表示某次尝试失败;Job 仍有重试次数时还会再次执行。
Q2:重试三次是首次执行后再试三次吗?
不是。attempts: 3 表示包含首次执行在内最多三次。
Q3:任务成功后清理 Job,会删除它生成的文件吗?
不会。清理删除 Redis 中的 Job 记录,文件需要由应用另行管理。
🧪 小练习
让处理函数每次都抛出普通错误,观察三次失败;再改为 UnrecoverableError,比较失败后是否继续重试。
// 请在这里编写代码
🎉 恭喜你已经掌握任务重试与历史记录管理啦!
