Cloudflare 在 2026 年 11 月 5 日替 Durable Objects 呼叫加入 runtime 層自動重試。Worker 或另一個 Durable Object 經由 stub 發出的 fetch() 與 RPC 呼叫,若在抵達目標前遇到可重試錯誤,runtime 會自動再送;預設最多四次重試,加上原始請求共五次嘗試,且不會在第一次呼叫開始超過十秒後再啟動新的重試。

這不是「任何失敗都會再跑」。程式自己拋出的錯誤、請求已抵達物件後才發生的錯誤、.overloaded 為 true 的錯誤,以及 HTTP 500 等正常回應都不在自動重試範圍。官方也明確排除帶有不可重送 stream 的請求、部分 RPC 參數、promise pipelining 與轉傳而來的 stub。若把這次更新理解成通用的 500 retry,會設計出錯誤的監控與回復策略。

最大風險不是沒重試,而是重試疊加

許多既有系統已在 SDK wrapper、service layer、queue consumer 或前端加入自己的 exponential backoff。Cloudflare runtime 現在會在每一次應用層嘗試裡再做最多四次重試;若外層仍嘗試三次,最壞情況便可能形成十五次 runtime attempt。官方說 runtime retry 不計入 subrequest limit,但它仍占用等待時間,也會讓告警、逾時與上游工作量變得更難判讀。

先建立呼叫清冊,找出所有 get()、getByName()、Durable Object stub wrapper、共用 retry helper、queue redelivery 與 HTTP client policy。對每一層記錄最大次數、timeout、backoff、哪些錯誤會觸發,以及誰負責產生 idempotency key。不能只搜尋 retry 字串,因為某些框架會以 interceptor、resilience policy 或 queue visibility timeout 實作相同效果。

短暫網路中斷、物件搬移或重啟,適合交給 runtime 處理。業務規則失敗、資料驗證錯誤、庫存不足或 rate limit,則應由應用層依語意決定是否重試。若外層 retry 只是為了補 Durable Object 在搬移時的連線錯誤,可降低次數或移除;若它還要處理其他服務,則保留外層,但為 Durable Object stub 設定較小的 runtime 上限,避免兩層都用最大值。

retryable() 不是效能開關

當連線在 method 開始後中斷,runtime 可能不知道第一次是否已執行。預設行為是讓 Durable Object 拒絕重送,避免同一個 method 執行兩次。只有開發者用 retryable() 明確標記 method 後,runtime 才能在這種不確定狀態重新執行它。

適合標記的操作通常具備冪等性,例如「把商品數量設為 3」、「以固定 event ID upsert 狀態」或「寫入相同版本的設定」。不適合的操作包括「數量加一」、「扣款」、「寄信」、「產生新的優惠券」或「沒有唯一鍵的 append」。判斷標準不是 method 名稱看起來像 update,而是相同輸入執行兩次後,外部可觀察結果是否仍等同執行一次。

若一個 method 同時寫 Durable Object storage、呼叫付款 API 並發布事件,即使本地 storage 使用 transaction,也不代表整段跨系統流程冪等。這類操作要先拆成可辨識狀態的步驟,以 operation ID 建立去重紀錄,再決定是否標記。無法證明冪等時,寧可維持預設拒絕不確定重送,讓呼叫端進入查詢狀態或人工補償流程。

建議的遷移與驗收順序

第一步先升級測試工具。預設自動重試不需要程式改動,但要使用 retryable() 或每個 stub 的 retry 選項,官方要求 Wrangler 4.158.0 或更新版本。把 Wrangler 固定在 lockfile 與 CI,不要讓本機能編譯、正式 pipeline 卻仍用舊版本。

第二步替關鍵 stub 明確設定策略。可以用 maxRetries 控制 0 到 10 次,用 timeoutMs 控制 500 到 60,000 毫秒。低延遲互動請求通常應縮短 timeout;背景同步可以容許較長時間,但仍要小於 queue visibility timeout 或整體 job deadline。若既有應用層已完整處理 retry,可先設 maxRetries: 0 作為控制組,再逐步交給 runtime。

第三步做故障注入。至少驗證物件重啟前的失敗、連線中斷、程式主動拋錯、HTTP 500、overloaded 與 request body 為 stream 等情境。記錄邏輯操作數、runtime attempts、method 真正執行次數、端到端延遲與最終錯誤,確認監控不會把一次使用者操作誤算成多筆訂單或多次扣款。

第四步分批移除重複 retry。先從 idempotent read 與 set-style write 開始,觀察錯誤率與尾端延遲,再處理跨系統命令。保留快速回復方式,例如 feature flag 切換外層策略;但回復不能只是把所有 retry 都打開,否則事故期間最容易形成 retry storm。

怎麼選擇由哪一層負責

單純 Worker 到 Durable Object 的短暫傳輸失敗,優先使用 runtime 預設,因為它理解請求是否抵達與同一 request identity。需要處理 HTTP response、第三方 API 或完整工作流程的失敗,則保留應用層策略。Queue 本身的 redelivery 是工作單位重跑,還要用 event ID 去重,不能拿它取代一次 stub call 的傳輸重試。

完成標準應包含:每個重要呼叫只有一個明確的 retry owner、非冪等 method 未被誤標、外層與 runtime 的最大嘗試數可推算、timeout 小於上層 deadline、監控能區分 logical operation 與 attempt。這次更新確實能降低短暫中斷,但真正的可靠性來自可證明的冪等界線,而不是把重試次數調得更高。