第15章 Queues 消息队列
文档:Queues
Queues 是一个消息代理。生产者 Worker 发送消息,消费者 Worker 随后以批次形式接收。每个队列占用一个 cell(单元格)。查阅 Cloudflare Queues 文档 了解 API 详情。
示例
Queues 示例通过请求发送一个任务,并在队列处理程序中处理该任务。如果任务路径以 /fail 结尾,系统将重试两次,随后示例从死信队列中读取该任务。
index.js
export default {
async fetch(request, env) {
const job = {
path: new URL(request.url).pathname,
createdAt: new Date().toISOString(),
};
await env.JOBS.send(job);
return Response.json({ queued: job });
},
async queue(batch) {
for (const message of batch.messages) {
if (batch.queue === "example-jobs-dead-letter") {
console.log("dead job", message.body);
message.ack();
continue;
}
if (message.body.path.endsWith("/fail")) {
console.log("retrying job", message.body, message.attempts);
message.retry({ delaySeconds: 1 });
continue;
}
console.log("processing job", message.body);
message.ack();
}
},
};
wrangler.jsonc
{
"name": "queues",
"main": "index.js",
"compatibility_date": "2026-01-01",
"queues": {
"producers": [{ "binding": "JOBS", "queue": "example-jobs" }],
"consumers": [
{
"queue": "example-jobs",
"max_batch_size": 10,
"max_batch_timeout": 5,
"max_retries": 2,
"dead_letter_queue": "example-jobs-dead-letter"
},
{ "queue": "example-jobs-dead-letter" }
]
}
}
API
env.JOBS.send(body, { contentType, delaySeconds })发送单条消息。contentType支持 "v8"、"json"、"text" 或 "bytes"。env.JOBS.sendBatch(messages)一次调用最多发送 100 条消息。- 消费者脚本导出
queue(batch, env, ctx)函数。batch.queue指定队列名称,batch.messages中的每一项包含 id、时间戳、body(主体内容)和 attempts(尝试次数)。 message.ack()和message.retry({ delaySeconds })用于结算单条消息。batch.ackAll()和batch.retryAll()用于结算整个批次。对于同一条消息,以首次调用为准。- 如果处理程序直接返回,则自动确认所有未结算的消息。如果处理程序抛出异常,则自动重试所有未确认的消息。
生产者
queues.producers 条目指定绑定名称和队列名称。整个 fleet(机队/集群)中所有指向同一队列的生产者都写入该队列。celld 强制执行 Cloudflare 的以下限制:
- 单条消息最大 128,000 字节
- 单次
sendBatch()调用最多 100 条消息,总计不超过 256,000 字节 delaySeconds最大值为 86,400 秒
生产者条目可设置 delivery_delay 作为默认延迟。当队列 cell 提交消息后,send() 才会解析完成。单个 cell 同时最多接受 256 个生产者调用,超出后会产生 cell 过载错误,生产者需自行重试。
消费者
queues.consumers 条目指定队列名称。仅允许一个脚本消费特定队列,因此若部署中包含两个脚本消费同一队列,部署将失败。该条目可配置以下参数:
max_batch_size:默认 10,最大 100max_batch_timeout:以秒为单位,默认 5,最大 60max_retries:默认 3max_concurrency:最大 250retry_delaydead_letter_queue
celld 在部署时验证每个参数。查阅 批量处理、重试与延迟 了解各参数含义。
celld 不保证投递顺序,且至少投递一次。重新投递时 message.id 保持不变,应用可将其作为幂等键使用。如果处理程序始终未结算批次,它将持有租约直到过期,celld 将此视为一次投递失败。celld 不对重试添加指数退避,需根据 message.attempts 自行计算延迟。超过 max_retries 的消息会被移至 dead_letter_queue;若消费者未配置死信队列,则直接删除该消息。
与 Cloudflare 的差异
- 一个队列仅限一个写入者。需增加队列数量以提升写入容量。
- 队列拥有者(owner)同时最多接受 256 个并发生产者调用,额外调用将被拒绝,生产者需重试。
- celld 保留消息 4 天,该期限不可配置。
- 拉取消费者(Pull consumers)、Queues HTTP API、控制台操作、手动附加消费者、R2 事件通知及队列事件订阅均不可用。
Cloudflare 兼容性页面列出了 运行时 API 和不支持的服务。