Workflows steps 深入:重試、sleep 與等待事件 | Cloudflare 完整教學

// step.do 的完整形態
const result = await step.do(
  "呼叫外部 API",                    // ① 步驟名稱:必須是「確定性」的靜態字串
  {
    retries: {
      limit: 5,                      // 最大重試次數(0 = 不重試,Infinity = 無限重試)
      delay: "10 seconds",           // 基準間隔(可寫數字毫秒,或 '10 seconds' 字串)
      backoff: "exponential",        // 退避策略:constant | linear | exponential
    },
    timeout: "30 seconds",           // ② 單次嘗試逾時上限,超過即算這次失敗
  },
  async () => {                      // ③ 實際要跑的函式,回傳值會被持久化
    const res = await fetch("https://api.example.com/data");
    if (!res.ok) throw new Error(`API 回應 ${res.status}`); // 拋錯 → 觸發重試
    return res.json();
  }
);

// constant(常數):每次間隔固定不變
// 2s → 2s → 2s → 2s ...   適合上游恢復時間穩定的情境
await step.do("固定重試", { retries: { limit: 5, delay: "2 seconds", backoff: "constant" } }, fn);

// linear(線性):間隔線性遞增
// 2s → 4s → 6s → 8s ...   溫和的折衷
await step.do("線性重試", { retries: { limit: 5, delay: "2 seconds", backoff: "linear" } }, fn);

// exponential(指數):間隔倍增 —— 呼叫外部相依的預設首選
// 2s → 4s → 8s → 16s ...  上游抖動時快速重試,上游真掛時不狂轟濫炸
await step.do("指數重試", { retries: { limit: 5, delay: "2 seconds", backoff: "exponential" } }, fn);

await step.do(
  "帶嘗試資訊的步驟",
  { retries: { limit: 3, delay: "5 seconds", backoff: "exponential" } },
  async (ctx) => {
    // ctx.attempt:1 = 首次,2 = 第一次重試,以此類推
    if (ctx.attempt > 1) {
      console.log(`這是第 ${ctx.attempt - 1} 次重試`);
    }
    return await doWork();
  }
);

import { NonRetryableError } from "cloudflare:workflows";

const charge = await step.do(
  "驗證並扣款",
  { retries: { limit: 3, delay: "5 seconds", backoff: "exponential" } },
  async () => {
    const { paymentMethod, amount } = event.payload;

    // 業務前置條件不滿足 → 重試也沒用,立即放棄
    if (!paymentMethod) {
      throw new NonRetryableError("缺少付款方式,無法扣款");
    }

    const res = await fetch("https://payment.example.com/charge", {
      method: "POST",
      body: JSON.stringify({ paymentMethod, amount }),
    });

    if (res.status === 401) {
      throw new NonRetryableError("API 憑證無效"); // 認證錯誤:重試也不會過
    }
    if (res.status === 402) {
      throw new NonRetryableError("餘額不足");      // 業務狀態:不該重試
    }
    if (!res.ok) {
      // 500 / 503 等:可能是暫時性,交給 retries 機制重試
      throw new Error(`扣款 API 錯誤 ${res.status}`);
    }

    return res.json<{ transactionId: string }>();
  }
);

// 等待對帳系統確認扣款(最多等 6 小時)
try {
  const reconcile = await step.waitForEvent<{ confirmed: boolean; ref: string }>(
    "等待對帳確認",
    {
      type: "reconcile-result", // 只接受此 type 的事件(命名限字母數字與 - _)
      timeout: "6 hours",        // 逾時後拋出錯誤
    }
  );

  if (!reconcile.confirmed) {
    throw new NonRetryableError(`對帳未通過:${reconcile.ref}`);
  }
} catch {
  // 逾時或未確認 → 進入下方的重查補救流程(見下一節)
}

// 另一個 Worker / handler:對帳系統回呼進來時,喚醒對應實例
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { instanceId, confirmed, ref } = await request.json<{
      instanceId: string;
      confirmed: boolean;
      ref: string;
    }>();

    const instance = await env.BILLING_WORKFLOW.get(instanceId);
    await instance.sendEvent({
      type: "reconcile-result", // ★ 必須與 waitForEvent 的 type 完全一致
      payload: { confirmed, ref },
    });

    return Response.json({ status: "event delivered" });
  },
} satisfies ExportedHandler<Env>;

// 相對時間:從現在起睡多久(可寫字串或數字毫秒,最大 365 天)
await step.sleep("等對帳補上", "30 minutes");
await step.sleep("試用期", "7 days");
await step.sleep("短暫等待", 5000); // 5000ms = 5 秒

// 絕對時間:睡到某個明確的時間點
await step.sleepUntil("延到隔日凌晨對帳", new Date("2026-09-02T02:00:00Z"));

import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";

interface BillingParams {
  userId: string;
  paymentMethod: string;
  amount: number;
  email: string;
}

interface Env {
  BILLING_WORKFLOW: Workflow<BillingParams>;
  DB: D1Database;
}

export class BillingWorkflow extends WorkflowEntrypoint<Env, BillingParams> {
  async run(event: WorkflowEvent<BillingParams>, step: WorkflowStep): Promise<void> {
    const { userId, amount, email } = event.payload;

    // ── 步驟 1:扣款(暫時性錯誤重試,業務錯誤立即放棄)──
    const charge = await step.do(
      "驗證並扣款",
      { retries: { limit: 3, delay: "5 seconds", backoff: "exponential" }, timeout: "30 seconds" },
      async () => {
        const { paymentMethod, amount } = event.payload;
        if (!paymentMethod) throw new NonRetryableError("缺少付款方式");

        const res = await fetch("https://payment.example.com/charge", {
          method: "POST",
          body: JSON.stringify({ userId, paymentMethod, amount }),
        });
        if (res.status === 402) throw new NonRetryableError("餘額不足");
        if (!res.ok) throw new Error(`扣款 API 錯誤 ${res.status}`); // 交給重試
        return res.json<{ transactionId: string }>();
      }
    );

    // ── 步驟 2:等待對帳確認(最多 6 小時),逾時則睡 30 分鐘後重查一次 ──
    let confirmed = false;
    try {
      const evt = await step.waitForEvent<{ confirmed: boolean }>(
        "等待對帳確認",
        { type: "reconcile-result", timeout: "6 hours" }
      );
      confirmed = evt.confirmed;
    } catch {
      // 逾時:先睡一段時間,給對帳系統補上的機會
      await step.sleep("等對帳補上", "30 minutes");

      // 主動向對帳 API 重查一次(這一步同樣有持久化與重試保護)
      confirmed = await step.do(
        "主動重查對帳",
        { retries: { limit: 3, delay: "10 seconds", backoff: "exponential" } },
        async () => {
          const res = await fetch(
            `https://payment.example.com/reconcile/${charge.transactionId}`
          );
          const data = await res.json<{ confirmed: boolean }>();
          return data.confirmed;
        }
      );
    }

    if (!confirmed) {
      // 仍未確認 → 標記並結束(此為業務決定,不重試)
      await step.do("標記對帳失敗", async () => {
        await this.env.DB.prepare(
          "UPDATE billings SET status = ? WHERE txn = ?"
        ).bind("reconcile-failed", charge.transactionId).run();
      });
      return;
    }

    // ── 步驟 3:寄送收據(副作用包進步驟,保證只寄一次)──
    await step.do("寄送收據", async () => {
      await fetch("https://mail.example.com/send", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          to: email,
          subject: "扣款成功收據",
          body: `已成功扣款 ${amount} 元,交易編號 ${charge.transactionId}。`,
        }),
      });
    });

    // ── 步驟 4:更新最終狀態 ──
    await step.do("標記完成", async () => {
      await this.env.DB.prepare(
        "UPDATE billings SET status = ? WHERE txn = ?"
      ).bind("completed", charge.transactionId).run();
    });
  }
}

// ❌ 錯誤:用 setTimeout 空等 —— 佔資源、撐不久、崩潰即失效
await step.do("等 7 天", async () => {
  await new Promise((r) => setTimeout(r, 7 * 24 * 3600 * 1000));
});

// ✅ 正確:用 step.sleep —— 卸下實例、不計費、可恢復
await step.sleep("等 7 天", "7 days");

// ❌ 錯誤:名稱含非確定性值,重播對不上
await step.do(`process-${Date.now()}`, fn);

// ❌ 錯誤:迴圈裡步驟撞名(每圈都叫 "process item")
for (const item of items) await step.do("process item", () => handle(item));

// ✅ 正確:用確定性的、彼此唯一的名稱
for (const item of items) await step.do(`process item ${item.id}`, () => handle(item));

// ❌ 錯誤:步驟外取當下時間做判斷,重播時值會變
const now = Date.now();
if (now % 2 === 0) await step.do("A", fnA); else await step.do("B", fnB);

// ✅ 正確:非決定性取值包進步驟,固定成持久化值
const now = await step.do("capture now", async () => Date.now());
if (now % 2 === 0) await step.do("A", fnA); else await step.do("B", fnB);