ระดับ 5c · บทที่ 2/5

Queues และ Workflows — งานเบื้องหลังที่ retry ได้ และงานหลายขั้นที่ทนพัง

⏱ 55 นาทีลองในCloudflare ↗

เป้าหมาย

ย้ายงานช้า/งานที่พังได้ออกจาก 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_timeout 60 วิ)
  • ถ้า 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