接口幂等设计
解释接口幂等的含义、常见失效场景，以及幂等键、唯一约束、状态机和锁等落地手段。
#type / concept
#status / growing
#tech / dev / backend
#resource / http
#topic / reliability
[!info] related notes
- 所属 MOC: Node.js 后端面试 MOC, 后端开发 MOC
- 前置概念: HTTP语义方法, RESTful API
- 并列概念: 后端上传状态管理
- 关系笔记: Node.js 服务的日志、健康检查与优雅退出
接口幂等设计
一句话定义
幂等是指同一个请求执行一次和执行多次，最终对系统状态产生的结果一致。
核心机制 / 工作原理
幂等最常在这些场景里变得关键：
- 创建订单
- 提交审批
- 支付回调
- 文件分片上传
- 消息重复消费
因为网络不可靠，客户端、网关或消息系统都可能重试。同一请求如果不能重复执行而不出错，就容易制造重复数据或重复副作用。
最小例子 / 最小场景
幂等的 HTTP 语义
GET通常幂等PUT通常幂等DELETE通常幂等POST默认不幂等
订单创建常见做法
可以给创建接口增加幂等键：
POST /orders
Idempotency-Key: order-submit-123服务端处理逻辑通常是：
- 先检查这个 key 是否已处理
- 已处理就返回之前的结果
- 未处理才真正创建
- 把 key 和结果一起记录下来
边界与易混淆点
幂等不等于“完全没有副作用”
例如删除接口会改变状态，但重复删除多次，最终状态仍然一致，所以依然可以是幂等的。
前端防重复点击不是幂等的全部
按钮置灰只是第一层体验保护。真正可靠的幂等必须落在后端。
常见实现手段
- 幂等键
- 数据库唯一索引
- 条件更新
- 状态机
- 分布式锁
- 去重表
强一致场景不要只靠 Redis 锁
锁只能减少并发竞争，真正兜底通常还要回到数据库约束或状态流转设计。