对外 API 的幂等设计，本质上是成本分配问题

“所有写操作都要幂等”已经成为 API 设计的常识，但幂等键放在哪一层、谁负责生成、重试窗口多长，这些决策决定了幂等是真正生效，还是仅仅在文档里存在。

一个比较务实的做法是要求调用方在创建、扣款等写操作中传入 Idempotent-Key，服务端用 Redis 的 SETNX 或等价机制锁住这个 key，配合业务唯一约束做双重保障。调用方重试时携带同一个 key，服务端返回首次执行的结果，而不是重新执行。这比服务端“自动去重”更可靠，因为只有调用方知道哪两次请求在业务语义上是同一次。

但幂等的成本被系统性地低估了。每一个幂等键都需要存储和过期策略，高并发写入下幂等存储本身会成为热点；跨服务调用时，幂等键需要在链路中传递，任何一个环节丢失都会让下游重复执行；异步任务和消息消费的幂等需要额外的去重表或状态机，而不是一个 header 能解决的。这些成本落在基础设施团队和业务团队之间，往往没有明确的归属。

另一个维度的判断是版本化。API 一旦发布就不应该原地修改语义，破坏性变更通过 URL 版本（/api/v1、/api/v2）隔离，让客户端按自己的节奏迁移。版本化的成本不是多写一个路由，而是旧版本要维护多久、废弃策略是否提前公告、监控能不能区分新旧版本的流量和错误率。

幂等和版本化都不是“加了就安全”的机制。它们是把重复执行的风险和变更的风险，从运行时事故转移到设计和运维阶段的显式成本。不愿意承担这些成本，就得接受重复下单、重复扣款和客户端被迫紧急升级的代价。