GraphQL mutation 重试后订单重复怎么防

现象#

网络超时后重发同一笔退款和同一笔订单，Shopify 侧出现两条记录，对账金额翻倍；日志里两次请求的参数完全一样。

原因#

• GraphQL 不认 Idempotency-Key 头，只有标了 @idempotent 的 mutation 才认键
• 每次重试都重新生成 UUID，等于主动告诉服务端这是一次全新操作
• 幂等键只保留 24 小时，隔天补跑的重试不再具备去重能力
• 并发重复请求返回 IDEMPOTENCY_CONCURRENT_REQUEST，被当成失败直接抛出

处理步骤#

1. 先确认目标 mutation 是否支持 @idempotent，不支持就自己在业务层去重
2. 支持时在调用前生成并持久化 UUID，重试复用同一个值，不要写在循环内部
3. 把 IDEMPOTENCY_CONCURRENT_REQUEST 当可重试状态，等一会儿去查结果而不是再写一次
4. 不支持的场景建去重表，以业务单号加 shop 域名做唯一索引，先占位再调用
5. 用 sourceIdentifier 或订单 note 记录外部单号，便于事后核对

验收标准#

同一业务单号重复提交十次只产生一条记录；并发重试能拿到首次响应或明确的可重试状态，不出现双写。