让重复触发只跑一次:把 hook token 当幂等键,而不是先查一遍再执行
重复执行这件事,几乎不会以「重复执行」的名字出现。它以四种样子出现:客户说被扣了两次钱、用户收到两封一模一样的邮件、后台多出一条重复订单、报表数字比实际多一成。
共同点都是同一件事被执行了两遍,而且没有任何一层拦下来。
先看错误示范,因为大多数人写的就是这个
最常见的写法是「先查一下有没有,没有就创建」:
const existing = await findRunByOrderId(orderId);
if (existing) return existing;
return await start(processOrder, [orderId]);
这两行之间有一个窗口。查询返回「没有」到 start() 真正落地之间,如果第二个请求进来,它查到的也是「没有」。支付回调的两次重试间隔常常只有几百毫秒,正好落在这个窗口里。
数据库层面也是一样:SELECT 再 INSERT,没加唯一约束,并发下照样插两条。
Vercel 的 Workflow SDK 之前提供的 getHookByToken() + start() 就是这个模式,官方文档自己承认了这里有重复启动的竞态。11 月 4 日他们把这条路堵了——start() 现在能在同一步里「承认一次运行」并「认领一个 hook」。
正确姿势:token 就是幂等键
核心思路只有一句话:幂等键不是随机生成的,是你的业务 ID。
订单号、发票号、导入批次号、支付流水号——这些天然唯一、天然重复的值,就是最好的 token。用一个随机 uuid 当 token 等于没有幂等。
// app/api/orders/route.ts
import { resumeHook, start } from "workflow/api";
import { HookConflictError } from "workflow/errors";
import { processOrder } from "./workflows/process-order";
export async function POST(request: Request) {
const { orderId, note } = await request.json();
const token = `order:${orderId}`;
try {
const run = await start(processOrder, [orderId, note], {
experimental_hook: { token },
});
return Response.json({ runId: run.runId, started: true });
} catch (error) {
if (!HookConflictError.is(error)) throw error;
// 重复请求的负载不能丢,转交给已经持有 token 的那次运行
const hook = await resumeHook(token, { note });
return Response.json({ runId: hook.runId, started: false });
}
}
三件事同时发生了:运行被承认、token 被认领、重复请求被挡住。第二个请求拿到的是 started: false 和原来那个 runId,不是一条错误。
这比抛个 409 让调用方自己重试要好,因为重试的调用方通常不会读你的错误码。
工作流内部怎么接
token 已经在 start() 时被认领了,工作流里再声明同一个 token,是绑定到那个已存在的 hook,不会新建、不额外消耗一个 step:
// workflows/process-order.ts
import { createHook } from "workflow";
type OrderUpdate = { note: string };
export async function processOrder(orderId: string, note: string) {
"use workflow";
await recordNote(orderId, note);
const updates = createHook<OrderUpdate>({ token: `order:${orderId}` });
for await (const update of updates) {
await recordNote(orderId, update.note);
}
}
关键点在时序:hook 从运行被承认的那一刻就存在,所以 resumeHook 可以在工作流还没开始执行时就写进去,早到的负载会被缓冲、按顺序投递。这解决了一个很烦的问题——重复请求往往比第一次跑得更早到达某个检查点。
如果你压根不需要接收后续消息,也可以完全不开 hook。此时 token 只承担幂等键的作用,运行结束就完事。
最后一道闸:让 token 过期
幂等键有一个副作用:它会被永久占用。如果同一笔订单在三个月后合法地需要重跑一次,你会被自己的旧 token 挡住。
SDK 给了 experimental_minRetention,控制 token 在运行结束后还保留多久,从 start() 的时刻开始算。设成 24 小时,超过 24 小时的重复请求就不会再被识别成重复——这正是你要的语义:短窗口内防重,长窗口外允许重来。
不用 Vercel 怎么办
同一套逻辑在 Postgres 里是两行 SQL:
INSERT INTO job_runs (idem_key, status, created_at)
VALUES ($1, 'running', now())
ON CONFLICT (idem_key) DO NOTHING
RETURNING id;
idem_key 上建唯一索引。返回 0 行说明这一次是重复的,去查已有那行的 id 拿回来用。原子性由数据库保证,不需要事务包裹先查后写。
Redis 也行:SET key value NX EX 86400,返回 OK 是第一次,返回 nil 是重复。EX 就是上面说的保留期。
不管用哪个,判断逻辑必须是「尝试占用,失败了才认输」,不能是「先看有没有,再决定占不占」。
怎么知道自己做对了
5 条,逐条过:
- 并发压测:用同一个 orderId 同时发 20 个请求,数据库里只应该有 1 条运行记录,另外 19 个返回
started: false且runId相同。 - 负载不丢:第 2 个请求带的 note 必须出现在最终结果里,不是被丢掉。检查方式是对比入参和落库的 note 条数。
- 异常路径:把
processOrder里第一行改成throw,确认失败后 token 能被释放或按保留期回收——否则这笔订单永远重跑不了。 - 过期语义:把
experimental_minRetention设成 1 分钟,等 90 秒后再发同一个 token,确认它能重新启动,而不是一直报冲突。 - 业务 ID 唯一性:抽查 100 条 token,确认没有一条是 uuid 或时间戳拼出来的。这条最难自动化,但一旦违反,前面四条全白做。
一个容易忽略的坑
HookConflictError 上带着 conflictingRunId。不要把它当日志字段随手一扔——应该把它写进响应体返回给调用方。前端拿到「你的请求已被处理,运行 ID 是 xxx」,用户就不会再点第二次;返回一个笼统的 409,用户只会再点一次,然后你又多一条重复请求。
幂等做得好不好,最后看的不是后端,是用户还会不会重复提交。
原文:https://vercel.com/changelog/atomic-start-hooks-in-the-workflow-sdk