เป้าหมาย
ย้ายงานช้า/งานที่พังได้ออกจาก request ของผู้ใช้: ใช้ Queues สำหรับงานเดี่ยวๆ จำนวนมาก (ส่งอีเมล, resize รูป, webhook) พร้อม retry และ Dead Letter Queue (DLQ) และใช้ Workflows สำหรับกระบวนการหลายขั้นที่ต้องรอ (จองของ → รอจ่ายเงิน → จัดส่ง) โดยไม่ทำงานซ้ำเมื่อพังกลางทาง
เลือกเครื่องมือให้ถูก
| งาน | ใช้ | เหตุผล |
|---|---|---|
| งานเดี่ยวจำนวนมาก ไม่สนลำดับ (อีเมล, log, thumbnail) | Queues | batch, retry, DLQ, คุม concurrency ได้ |
| ขั้นตอนหลายขั้น มีรอ (นาที-วัน) รอคน/ระบบอื่นตอบ | Workflows | เก็บผลแต่ละ step, sleep ได้ถึง 1 ปี, waitForEvent |
| ตั้งเวลาต่อ "สิ่งหนึ่ง" (หมดเวลาจองของห้องนี้) | DO alarm (บท 01) | ผูกกับ state ของ object |
| งานรอบเวลาของทั้งระบบ (สรุปรายวัน) | Cron Trigger (ระดับ 4c) หรือ schedules ของ Workflow |
ไม่ต้องมี trigger จากผู้ใช้ |
Queues: หลักที่ต้องจำ
- ส่งอย่างน้อยหนึ่งครั้ง (at-least-once) → consumer ต้อง idempotent ใส่
jobIdในข้อความแล้วเช็กว่าเคยทำแล้วหรือยัง - ไม่รับประกันลำดับ — ถ้าลำดับสำคัญ ใช้ DO หรือ Workflow
- consumer ได้ทีละ batch (
max_batch_sizeสูงสุด 100, รอได้ถึงmax_batch_timeout60 วิ) - ถ้า handler throw ทั้ง batch จะ retry ทั้งก้อน → ใช้
msg.ack()/msg.retry()รายข้อความ จะได้ไม่ทำข้อความที่สำเร็จแล้วซ้ำ - ครบ
max_retries(ค่าเริ่ม 3) แล้วยังพัง → ไป DLQ ถ้าไม่ตั้ง DLQ ข้อความ ถูกทิ้ง
| ค่า | ความหมาย | ค่าเริ่มต้น |
|---|---|---|
max_batch_size |
ข้อความต่อ batch | 10 |
max_batch_timeout |
วินาทีที่รอให้ batch เต็ม | 5 |
max_retries |
retry ต่อข้อความ | 3 |
dead_letter_queue |
คิวรับข้อความที่ retry ครบ | — (ทิ้ง) |
max_concurrency |
consumer พร้อมกันสูงสุด — ใช้กัน API ปลายทางล่ม | ขยายอัตโนมัติ |
ข้อจำกัดสำคัญ: ข้อความ ≤ 128 KB · sendBatch ≤ 100 ข้อความ · delaySeconds ≤ 24 ชม. · 5,000 ข้อความ/วินาที/คิว · consumer รันได้ ≤ 15 นาที
เงิน: คิดเป็น operation ทุก 64 KB — ส่งสำเร็จ 1 ข้อความ ≈ 3 ops (write/read/delete) และ ทุกครั้งที่ retry = อีก 1 read
| Workers Free | Workers Paid | |
|---|---|---|
| Operations | 10,000/วัน | 1 ล้าน/เดือน แล้ว $0.40 ต่อล้าน |
| เก็บข้อความ | 24 ชม. (ตายตัว) | 4 วัน ตั้งได้ถึง 14 วัน |
ตัวอย่าง: 1 ล้านข้อความ/วัน × 30 วัน × 3 ops = 90 ล้าน ops → ≈ (90 − 1) × $0.40 ≈ $35.60/เดือน
Workflows: หลักที่ต้องจำ
const data = await step.do("ชื่อ step ที่ไม่ซ้ำ", { retries: { limit: 5, delay: "10 seconds", backoff: "exponential" }, timeout: "2 minutes" }, async () => { ... });
await step.sleep("รอ 1 วัน", "1 day");
const ev = await step.waitForEvent<{ ok: boolean }>("รอจ่ายเงิน", { type: "payment", timeout: "1 hour" });- ผลของ
step.doถูกบันทึก — ถ้า instance พังแล้วรันใหม่ step ที่สำเร็จแล้วจะไม่ถูกรันซ้ำ (คืนค่าที่บันทึกไว้) - ค่าเริ่มต้นของ step: retry 5 ครั้ง, delay 10 วิ แบบ exponential, timeout 10 นาทีต่อครั้ง
- กฎทอง: side effect ทุกอย่าง (เรียก API, เขียน DB,
Math.random(),Date.now()) ต้องอยู่ในstep.do— โค้ดนอก step อาจถูกรันซ้ำทุกครั้งที่ workflow ตื่น - ชื่อ step ต้อง คงที่ (ห้ามใส่เวลาหรือค่าสุ่มในชื่อ) ไม่งั้นระบบหาผลที่บันทึกไว้ไม่เจอ
- ผลต่อ step ≤ 1 MiB — ของใหญ่เก็บใน R2 แล้วคืนแค่ key
- error ที่ไม่ควร retry (บัตรถูกปฏิเสธ) →
throw new NonRetryableError(...)จากcloudflare:workflows - งานที่ต้อง "ย้อนกลับ" เมื่อพังทีหลัง (คืนของที่จองไว้) → ส่ง rollback options เป็นอาร์กิวเมนต์ตัวสุดท้ายของ
step.do(ตัวที่ 3 ถ้าไม่มี config, ตัวที่ 4 ถ้ามี config) — rollback จะรันย้อนลำดับเมื่อ workflow fail ทีหลัง (แบบ saga) - instance ที่กำลัง sleep/รอ event ไม่นับ concurrency limit
ลองเลย 🧪
ทำในโปรเจกต์เดียว: npm create cloudflare@latest -- jobs-demo → Hello World example → Worker only → TypeScript → Deploy: No แล้ว cd jobs-demo
ทดลอง A — Queue + retry + DLQ
npx wrangler queues create email-jobs
npx wrangler queues create email-jobs-dlqผลที่ควรเห็น (ข้อความอาจต่างเล็กน้อยตามเวอร์ชัน wrangler):
Creating queue 'email-jobs'
Created queue 'email-jobs'แทน wrangler.jsonc:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "jobs-demo",
"main": "src/index.ts",
"compatibility_date": "2026-10-01",
"observability": { "enabled": true },
"queues": {
"producers": [{ "queue": "email-jobs", "binding": "EMAIL_JOBS" }],
"consumers": [
{
"queue": "email-jobs",
"max_batch_size": 10,
"max_batch_timeout": 5,
"max_retries": 3,
"dead_letter_queue": "email-jobs-dlq",
"max_concurrency": 2
},
{ "queue": "email-jobs-dlq", "max_batch_size": 10 }
]
},
"workflows": [
{ "name": "order-flow", "binding": "ORDER_FLOW", "class_name": "OrderFlow" }
]
}แทน src/index.ts:
import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
import type { WorkflowEvent } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";
type EmailJob = { jobId: string; to: string; fail?: boolean };
type OrderParams = { orderId: string; sku: string };
async function sendEmail(job: EmailJob) {
if (job.fail) throw new Error("SMTP ปลายทางตอบ 503"); // จำลองปลายทางล่ม
console.log({ event: "email_sent", jobId: job.jobId, to: job.to });
}
export class OrderFlow extends WorkflowEntrypoint<Env, OrderParams> {
async run(event: WorkflowEvent<OrderParams>, step: WorkflowStep) {
const { orderId, sku } = event.payload;
const reservation = await step.do("reserve stock", async () => {
console.log({ event: "reserved", orderId, sku });
return { reservationId: `res-${orderId}` };
});
const payment = await step.waitForEvent<{ ok: boolean }>("wait for payment", {
type: "payment",
timeout: "1 hour",
});
await step.do("charge result", async () => {
if (!payment.payload.ok) throw new NonRetryableError("ลูกค้าจ่ายไม่สำเร็จ");
return { charged: true };
});
await step.sleep("cool down before shipping", "10 seconds");
return await step.do(
"create shipment",
{ retries: { limit: 3, delay: "5 seconds", backoff: "exponential" }, timeout: "1 minute" },
async () => ({ orderId, reservationId: reservation.reservationId, tracking: `TH${orderId}` }),
);
}
}
export default {
async fetch(request, env): Promise<Response> {
const url = new URL(request.url);
if (url.pathname === "/signup" && request.method === "POST") {
const { to, fail } = await request.json<{ to: string; fail?: boolean }>();
await env.EMAIL_JOBS.send({ jobId: crypto.randomUUID(), to, fail });
return Response.json({ queued: true }, { status: 202 }); // ตอบผู้ใช้ทันที ไม่รอส่งอีเมล
}
if (url.pathname === "/orders" && request.method === "POST") {
const orderId = String(Date.now());
const instance = await env.ORDER_FLOW.create({ id: `order-${orderId}`, params: { orderId, sku: "COFFEE-1KG" } });
return Response.json({ instanceId: instance.id });
}
const pay = url.pathname.match(/^\/orders\/(order-\d+)\/pay$/);
if (pay && request.method === "POST") {
const { ok } = await request.json<{ ok: boolean }>();
const instance = await env.ORDER_FLOW.get(pay[1]);
await instance.sendEvent({ type: "payment", payload: { ok } });
return Response.json(await instance.status());
}
const status = url.pathname.match(/^\/orders\/(order-\d+)$/);
if (status) return Response.json(await (await env.ORDER_FLOW.get(status[1])).status());
return new Response("not found", { status: 404 });
},
async queue(batch, env): Promise<void> {
if (batch.queue === "email-jobs-dlq") {
for (const msg of batch.messages) {
console.error({ event: "dead_letter", body: msg.body, attempts: msg.attempts });
msg.ack(); // ของจริง: เก็บลง R2/D1 แล้วแจ้งเตือนคน
}
return;
}
for (const msg of batch.messages) {
try {
await sendEmail(msg.body as EmailJob);
msg.ack(); // สำเร็จ → ไม่ทำซ้ำแม้ข้อความอื่นพัง
} catch (err) {
const delaySeconds = Math.min(30 * 2 ** (msg.attempts - 1), 600);
console.warn({ event: "email_retry", id: msg.id, attempts: msg.attempts, delaySeconds });
msg.retry({ delaySeconds }); // backoff ทีละข้อความ
}
}
},
} satisfies ExportedHandler<Env>;npx wrangler types
npx wrangler deploy
npx wrangler tail jobs-demo --format prettyเปิด terminal ใหม่:
curl -s -X POST https://jobs-demo.[subdomain].workers.dev/signup -H 'content-type: application/json' -d '{"to":"[email protected]"}'
curl -s -X POST https://jobs-demo.[subdomain].workers.dev/signup -H 'content-type: application/json' -d '{"to":"[email protected]","fail":true}'ผลที่ควรเห็นใน tail (ข้อความที่ 2 ใช้เวลาหลายนาทีกว่าจะไป DLQ เพราะ delay 30 → 60 → 120 วิ):
{"event":"email_sent","jobId":"…","to":"[email protected]"}
{"event":"email_retry","attempts":1,"delaySeconds":30}
{"event":"email_retry","attempts":2,"delaySeconds":60}
...
{"event":"dead_letter","body":{"to":"[email protected]","fail":true},"attempts":1}สังเกต: attempts ใน DLQ นับตามการส่งของคิว DLQ เอง ไม่ใช่จำนวนครั้งที่พังในคิวเดิม — ถ้าต้องการประวัติ (error ล่าสุด, เวลาที่เริ่ม) ให้ใส่ไว้ใน body เอง
ทดลอง B — Workflow ที่รอเหตุการณ์จากภายนอก
curl -s -X POST https://jobs-demo.[subdomain].workers.dev/ordersผลที่ควรเห็น: {"instanceId":"order-1760000000000"} แล้วส่ง event จ่ายเงินสำเร็จ:
curl -s -X POST https://jobs-demo.[subdomain].workers.dev/orders/[instanceId]/pay -H 'content-type: application/json' -d '{"ok":true}'
npx wrangler workflows instances describe order-flow [instanceId]ผลที่ควรเห็น: step reserve stock ✅, wait for payment ✅, cool down before shipping (sleep) แล้ว create shipment ✅ status complete และ output มี tracking
ลองสร้าง order ใหม่แล้วส่ง {"ok":false} → status errored จาก NonRetryableError ทันที ไม่มี retry
ส่ง event ด้วย CLI แทน HTTP ก็ได้:
npx wrangler workflows instances send-event order-flow [instanceId] --type payment --payload '{"ok":true}'ถ้าพัง: error เรื่อง event type ไม่ถูกต้อง → type มีจุด . หรือช่องว่าง (ใช้ได้แค่ตัวอักษร ตัวเลข - _ ยาว ≤ 100 ตัว) · instance ค้าง waiting → type ใน sendEvent ไม่ตรงกับ waitForEvent
เก็บกวาด (Free ไม่เสียเงิน แต่ลบให้เรียบร้อย)
npx wrangler delete
npx wrangler queues delete email-jobs
npx wrangler queues delete email-jobs-dlqกับดักที่เจอบ่อย
| อาการ | สาเหตุ / แก้ |
|---|---|
| ลูกค้าได้อีเมลซ้ำ 2-3 ฉบับ | throw ทั้ง batch → ข้อความที่สำเร็จถูก retry ด้วย — ใช้ ack() รายข้อความ + เช็ก jobId ก่อนส่ง |
| ข้อความหายเงียบ | ไม่ได้ตั้ง dead_letter_queue — ครบ retry แล้วถูกทิ้ง |
| API ปลายทางโดนยิงจนล่ม | consumer ขยายตัวเอง — ตั้ง max_concurrency และ retry({ delaySeconds }) แบบ backoff |
| บิล Queues สูงผิดปกติ | retry วนเยอะ (ทุก retry = 1 read) หรือข้อความ > 64 KB — เก็บของใหญ่ใน R2 ส่งแค่ key |
| Workflow ส่งอีเมลซ้ำหลัง deploy | เรียก API นอก step.do หรือชื่อ step เปลี่ยนทุกครั้ง (ใส่เวลาในชื่อ) |
| step error "output too large" | คืนข้อมูลเกิน 1 MiB — เก็บ R2 คืน key |
waitForEvent timeout แล้วทั้ง instance fail |
ตั้งใจให้ทำต่อได้ → ครอบ try/catch แล้วทำทางเลือกสำรอง (ยกเลิก order, คืนของ) |
สรุปจำง่าย
Queue = งานเดี่ยวจำนวนมาก at-least-once ไม่เรียงลำดับ → idempotent + ack รายข้อความ + DLQ เสมอ — Workflow = หลายขั้นที่รอได้ → side effect อยู่ใน
step.doชื่อ step คงที่ — error ที่ retry ไม่หายใช้NonRetryableError