vercel 17天前 · 2026-11-05 04:33:21 · 17 阅读
Workflow SDK 新增幂等启动功能
Workflow SDK 的 start() 函数现在可以在一个原子操作中同时接纳 run 并声明 hook,重复启动会安全地失败。原子启动取代了之前的 getHookByToken() 加 start() 两步模式——那种模式在查找和启动之间存在空隙,导致了文档中记录的重复启动竞态问题。
1import { resumeHook, start } from "workflow/api";2import { HookConflictError } from "workflow/errors";3import { processOrder } from "./workflows/process-order";4
5export async function POST(request: Request) {6 const { orderId, note } = await request.json();7 const token = `order:${orderId}`;8
9 try {10 const run = await start(processOrder, [orderId, note], {11 experimental_hook: { token },12 });13 return Response.json({ runId: run.runId, started: true });14 } catch (error) {15 if (!HookConflictError.is(error)) throw error;16 // 将重复请求的 payload 路由到持有该 token 的 run17 const hook = await resumeHook(token, { note });18 return Response.json({ runId: hook.runId, started: false });19 }20}幂等地启动 run,并把重复请求的 payload 路由给已持有该 token 的 run
Copy link to heading在 run 内部订阅消息
已声明的 Hook 从 run 被接纳的那一刻起就存在了,因此即使 run 还没开始执行,resumeHook 也能正常工作,早期的 payload 会被缓存并按顺序投递。在工作流内部,使用相同的 token 调用 createHook({ token }) 会绑定到已声明的 hook 上:这是有保证的,不会注册任何新内容,不增加额外步骤,并且 getConflict() 会返回 null。
1import { createHook } from "workflow";2
3type OrderUpdate = { note: string };4
5export async function processOrder(orderId: string, note: string) {6 "use workflow";7
8 await recordNote(orderId, note);9
10 // 绑定到 start 时声明的 hook:不可能冲突,也不会有额外步骤11 const updates = createHook<OrderUpdate>({ token: `order:${orderId}` });12 for await (const update of updates) {13 await recordNote(orderId, update.note);14 }15}在 run 内部绑定 start 时的 Hook,按顺序消费 payload
复制标题链接无需额外代码即可实现幂等性
该令牌即为幂等性键,且源自你自身的业务领域:它可以是订单 ID、发票 ID、导入 ID 或请求 ID。单凭此令牌即可保证幂等性。只有一次运行拥有它;若重复调用 start(),系统会抛出携带所有者 conflictingRunId 的 HookConflictError,而不会创建新的运行。工作流甚至完全无需开启该 hook。若始终未开启,则该令牌仅充当幂等性键,运行将正常完成。
设置 experimental_minRetention 后,在运行结束前该令牌将持续不可用,计时从 start() 开始。因此,迟到的重复请求仍会被拒绝。
请升级至 workflow 5.3.1 版本并阅读幂等性文档,即可开始使用。
原始来源: vercel