一项能力能否长期维护，不取决于演示是否成功，而取决于团队能否解释每个状态、每次重试和每一份残留数据。 Idempotency-Key 是一次业务意图标识，不是随机缓存键。服务端将它绑定认证主体、endpoint 与规范化 body，避免跨操作碰撞。
API 契约不仅是字段类型，还包括单位、缺省语义、幂等性、错误分类和版本窗口。客户端必须能区分可重试、需用户操作与永久拒绝，避免统一重试制造副作用。
设计时必须回答的问题
先把下面几项写成可评审的规则，而不是散落在回调和界面判断里。规则越清楚，后续扩容、兼容和排错越少靠猜。
- 首次请求原子创建 pending lease，完成后保存状态与必要响应；并发重复等待或返回 409/425，payload 不同返回明确 misuse。
- 把协议事实、用户意图和自动恢复分层；自动化只能恢复事实，不能推翻用户明确选择。
- 上线参数必须有保守默认值、服务端上限和灰度开关，不能把浏览器传来的数字直接当作资源预算。
“HTTP Idempotency-Key 契约：重复请求、并发和结果缓存”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
边界情况不是附加项
不要把异常路径理解成弹一次提示。它还包括在途工作如何停、对端如何获知、残留数据如何处置，以及下一次操作是否会继承旧状态。
- 代理自动重试 POST 而客户端每次生成新 key 仍会重复；永久保存完整响应又扩大隐私存储和成本。
- 只修正界面状态而没有清理底层资源，下一次操作继承队列、锁或过期凭据并再次失败。
- 只在理想数据量下测试，真实的大文件、长会话或高并发会越过隐含上限并产生级联故障。
用证据确认它真的可用
发布闸门应包含确定性回归、随机时序探索和真实浏览器组合。发现一次失败后保存 seed 与状态轨迹，让它永久成为可重放用例。
- 在并发、提交后断线、pending owner 崩溃、key 过期和不同 body 复用下测试，只允许一项业务副作用且恢复有时限。
- 让刷新、取消、超时和远端完成在同一调度窗口发生，断言系统只产生一个终态和一次副作用。
- 发布前记录成功率、p50/p95/p99 延迟、错误分类和资源高水位，并为回退条件设定明确阈值。
最终交付标准应当是：正常路径足够快，异常路径能够收敛，用户意图不会被自动恢复覆盖，运维人员也能从有限而安全的证据定位问题。