Vercel Workflow SDK 支持幂等启动:订单重试如何只创建一个流程

Vercel 将工作流启动与令牌占用合并为原子操作。本文拆解并发去重的接入方法,并说明业务标识、保留期限、消息重投和外部副作用仍需怎样设计。

订单接口最难排查的一类问题,是用户只点了一次确认,后台却启动了两条处理流程。浏览器超时重试、支付回调重投、队列消息再次送达,都可能让同一件业务进入系统多次。前端禁用按钮只能减少误操作,服务端仍需要明确回答:哪些请求属于同一次业务动作?

2026 年 11 月 4 日,Vercel 为 Workflow SDK 发布了一个针对这一问题的更新:启动运行与占用 Hook token 可以在同一个原子操作中完成。官方要求升级至 workflow 5.3.1。这项变化值得关注,因为它把过去由应用代码协调的一段竞态窗口,收进了工作流启动接口。官方更新,2026-11-04

先查询再启动,为什么挡不住并发

设想两个请求几乎同时处理同一笔订单。请求甲查询后发现流程不存在,请求乙也得到相同结果。随后,两者分别启动工作流。每个请求单独看都遵循了检查逻辑,组合起来却违反了业务约束。

这里的问题是检查与写入之间没有共同的排他边界。把查询放到更靠近启动的位置,或者在前端加一个短暂冷却,都无法证明并发安全。进程内的锁也很容易在多实例部署时失效,因为另一个实例并不知道这把锁的存在。

新版 start() 允许通过 experimental_hook 提交 token;重复启动会抛出 HookConflictError,并提供拥有者的 conflictingRunId,重复请求不会形成新的运行。这个保证针对工作流的创建入口。启动语义,2026-11-04

接入之前,先定义什么叫“同一件事”

Token 要表达业务身份

以下是工程设计建议。一个合理的标识可以包含租户、业务对象、操作类型和版本,例如“租户甲的订单乙执行第一次履约”。具体编码方式可以调整,但相同业务动作在重试时必须得到相同结果。

如果每次 HTTP 请求都生成一个随机标识,那么网络重试会被识别成新任务。反过来,只用用户 ID 又过于宽泛,同一个用户的两笔订单可能互相阻塞。标识粒度应由业务动作决定,而不是由接口路径或请求发生时间决定。

版本同样重要。导入文件的第一次处理和修正文件后的重新处理,可能应当属于两个合法任务。团队需要先规定哪些变化允许创建新任务,再把版本纳入标识。临时给 token 加时间戳虽然能绕开冲突,却也会绕开去重。

相同标识,不代表相同内容

假设同一订单 token 第一次对应金额一百元,第二次对应两百元。系统识别出重复启动,不等于认可第二份参数。建议在业务记录中保存关键参数摘要,重复请求到来时校验其一致性;不一致则返回明确的业务错误,并保留审计信息。

授权也必须在查询或返回已有任务之前完成。知道某个业务 ID 的人,不一定有权查看它的进度。多租户服务尤其不能因为捕获到了冲突,就直接向调用者返回另一租户的运行信息。

把重复请求和追加消息分开处理

官方还允许通过 resumeHook 向已有运行传递内容。Hook 在运行获准创建时就已存在,因此执行尚未开始时到达的消息也可以被缓冲,并按顺序交付。消息接入说明,2026-11-04

这为长流程提供了方便,但应用层应区分两类输入:原请求的再次送达,以及用户真的追加了一条新指令。例如订单备注发生修改,可以被设计为一条更新事件;支付完成通知的重复投递,则通常只需要确认已接收。

如果把每一次冲突都当成新消息转发,启动层虽然只剩一个运行,运行内部仍可能重复发送邮件或追加记录。建议更新消息携带稳定事件 ID,并让消费逻辑决定去重、覆盖还是累加。界面上的“已提交”和“正在处理”也应对应清晰状态,避免用户因等待而不断点击重试。

冲突响应也需要产品约定

已有任务仍在执行时,接口可以返回它的业务进度入口,让前端继续查询;已有任务失败时,则应展示失败原因和允许的恢复方式。不要把“已经存在”一律翻译为“已经成功”,否则用户会误以为订单已经完成。具体状态码与响应格式应遵循现有接口契约。

日志建议同时关联业务标识、运行 ID 和入口请求 ID。这样排查时可以区分正常重试、异常重复提交与真正的新业务动作。监控上也应把预期冲突和基础设施错误分开统计,否则一次上游重投就可能触发大量无效告警,掩盖真正需要处理的失败。

保留期限需要覆盖真实重试窗口

experimental_minRetention 可以让 token 在运行结束后继续保持不可用,其计时起点是 start(),用于拒绝较晚到达的重复请求。保留期说明,2026-11-04

实际配置时,应检查上游回调的最长重试周期、队列积压时间以及人工补发流程。一个几秒钟完成的任务,仍可能在数小时后收到旧通知。长流程则需要特别注意计时起点,不能直接把配置值理解成“完成后再保留这么久”。

保留期也不宜成为永久业务约束的唯一载体。对于永远只能发生一次的操作,建议在业务数据库中保留不可重复的操作记录。工作流 token 负责挡住启动冲突,业务记录负责解释历史结果,两者承担不同时间尺度的责任。

一次运行仍需保护外部副作用

启动去重并不自动解决所有重试问题。假设步骤已经成功调用外部服务,但在保存响应前连接中断,重试时就可能再次调用同一服务。Vercel 的架构指南也提醒,队列消费者和工作流步骤需要在目标系统保护副作用。官方架构指南,2026-10-14,背景资料

建议为关键外部动作另设稳定操作键;数据库写入结合唯一约束,支持幂等键的外部接口沿用同一键。对于无法确认成功与否、又不能可靠去重的操作,应进入查询或人工核对流程,避免盲目重试。

上线前至少覆盖五组测试:同一标识并发提交、启动成功但响应丢失、运行结束后旧请求重放、相同标识携带不同参数,以及步骤执行成功后模拟断线。断言既要检查运行数量,也要检查数据库记录和外部动作次数。

这次更新适合已经使用 Workflow SDK、并且依赖“查询后启动”进行去重的团队优先评估。先选一个可观测、容易回滚的流程迁移,记录冲突比例与业务结果,再逐步推广。可靠的工作流入口需要原子能力,也需要清楚的业务身份、授权边界和测试证据。

相关文章

评论

登录后即可参与讨论

暂无评论。