rust-idempotent-workflows

Rust 幂等工作流

使用此技能，让 Rust 工作流在客户端重试、工作进程崩溃、请求竞争以及无法回滚外部副作用时依然可靠。

核心工作流

1. 编写代码前，先描述故障场景。列出数据库每次写入后以及每次外部副作用后，如果进程崩溃会发生什么。
2. 确定幂等边界：HTTP 端点、命令处理器、队列任务、Webhook 或外部回调。
3. 选择幂等策略：
   • 通过唯一业务键实现天然幂等。
   • 使用客户端提供的幂等键，并保存响应以供重放。
   • 使用服务端生成的去重键。
   • 使用 Outbox 或队列表处理副作用。
4. 如果状态转换和幂等记录必须保持一致，就在同一事务中写入两者。
5. 确保并发重复请求的处理结果是确定的。使用唯一约束、锁、可串行化事务或显式冲突处理。
6. 除非服务提供商保证更高的交付语义，否则将外部副作用视为至少一次。保存足够的状态，以便重试或对账。
7. 添加测试，涵盖重复请求、超时后重试、并发请求、可行时的崩溃窗口，以及工作进程重试行为。

幂等键规则

添加幂等键或保存并重放行为前，请阅读 references/idempotency.md。

• 将密钥绑定到经过身份验证的用户或租户。
• 重放响应时，存储请求负载的哈希值。
• 对完全相同的重放请求，返回原始响应。
• 如果同一密钥被用于不同的负载，则拒绝请求。
• 仅在产品和服务提供商的重试窗口期均已结束后，才过期记录。

后台任务规则

添加队列表、轮询工作进程、重试或外部副作用时，请阅读 references/background-workers.md。

• 发送外部副作用前，先提交持久化意图。
• 有意使用 pending、in_progress、succeeded 和 failed 状态。
• 保留重试次数、下次尝试时间戳以及上次错误摘要。
• 确保工作进程可安全地在多个进程中运行。

并发规则

如果修复涉及重复请求、锁、隔离级别或唯一约束，请阅读 references/concurrency.md。

当多个应用实例可能处理同一工作流时，使用数据库作为去重的事实来源。

参考文件

• references/idempotency.md：幂等键、保存并重放，以及请求负载绑定。
• references/background-workers.md：队列表、工作进程循环、重试边界和 Outbox 行为。
• references/concurrency.md：锁的选择、事务隔离以及重复请求测试。