为什么 API 设计必须考虑幂等性？
API 需要幂等性，根本原因在于分布式系统中的网络通信是绝对不可靠的。当客户端发出请求后遭遇超时或连接中断时，它无法得知服务端是否已经成功执行了该操作，唯一的自救手段就是“重试”。如果 API 不具备幂等性，这种正常的网络重试就会导致重复扣款、重复创建订单或重复发送消息等灾难性的数据副作用。
什么是幂等性？从数学到计算机科学的映射
执行一次与执行一百次的结果完全一致
在数学中，幂等（Idempotence）指的是一个函数无论执行多少次，其结果都与仅执行一次的结果相同（即 ）。当这个概念被引入计算机科学和 API 设计时，它的含义变成了：无论客户端将该请求发送了多少次，只要请求的参数完全相同，服务器对系统状态（如数据库记录、文件状态）产生的副作用，以及最终返回给客户端的响应，都必须是完全一致的。
简单来说，一个幂等的接口就像一台“状态机”：它只关心“目标状态”是什么，而不关心你为了达到这个状态敲了多少次门。
网络不可靠与“重试风暴”的必然性
分布式系统的第一定律
在分布式系统中，有一条著名的谬误（Fallacies of Distributed Computing）：“网络是可靠的”。现实情况是，网络随时可能发生丢包、延迟、路由中断或网关重启。
当客户端向服务器发送一个请求（比如“创建订单”）时，可能会遇到以下尴尬的“盲区”：
- 请求在网络传输中丢失，服务器根本没收到。
- 服务器成功创建了订单，但返回的响应（Response）在网络中丢失了。
在这两种情况下，客户端都会因为“超时而判定请求失败”。为了完成业务，客户端的唯一选择就是重试（Retry）。亚马逊的 Builders’ Library 明确指出，重试是分布式系统中不可避免的正常行为；但如果没有幂等性机制的保护，这种看似合理的重试就会演变成破坏数据的“重试风暴”。
幂等性如何拯救真实世界的业务灾难？
支付与订单的“生死线”
幂等性最典型的应用场景就是资金交易。假设你在电商平台上购买了一件商品，点击“确认支付”后，页面因为网络卡顿转了半天的圈。此时，你的客户端（或浏览器）可能已经在后台自动发起了三次重试，或者你因为不耐烦手动多点了几次按钮。
如果支付接口不是幂等的，服务器收到这三个请求，就会真的从你的银行卡里扣除三笔钱。为了解决这个问题，现代支付网关（如 Stripe）引入了幂等键（Idempotency Key） 机制。
- 客户端生成唯一标识：客户端在发起请求时，会在 HTTP 头中携带一个全局唯一的 UUID（即幂等键）。
- 服务端防重校验：服务器在执行扣款逻辑前，会先去数据库或缓存中查询这个幂等键是否已经存在。
- 直接返回缓存结果：如果该键已存在，说明之前已经处理过这笔交易，服务器将直接返回第一次处理的结果（如“支付成功”），而不会再次执行扣款操作。
HTTP 协议的“原生幂等”与“非幂等”
在 RESTful API 设计中，不同的 HTTP 方法天生具有不同的幂等属性。根据 RFC 9110（HTTP 语义）规范，幂等性被明确定义为方法的安全语义。
| HTTP 方法 | 是否幂等 | 典型业务场景 | 潜在风险与防御策略 |
|---|---|---|---|
| GET | 是 | 查询用户信息、获取订单状态 | 无副作用，天然安全 |
| PUT | 是 | 更新用户资料（全量替换） | 多次执行结果一致，天然安全 |
| DELETE | 是 | 删除一条评论或资源 | 第一次删除成功，后续请求通常返回“资源不存在”或成功，状态不变 |
| POST | 否 | 创建新订单、发起支付转账 | 极易产生重复数据，必须依赖“幂等键”或数据库唯一索引来防御 |
“幂等性不仅仅是一种技术实现，它是对客户端的一种承诺：无论网络多么糟糕，无论客户端重试多少次，系统的最终状态都是安全且可预期的。”
弄明白了这个机制，你就能理解为什么后端工程师在面试时总是对“防重表”、“唯一索引”和“状态机流转”如此执着。幂等性本质上是一种“防御性编程”的哲学，它承认了外部环境的不可控，选择用系统内部的确定性去对抗网络的混沌。就像电梯的关门按钮，你按一次是关门，按十次依然是关门，它绝不会因为你多按了九次就把电梯门给拆了。下次当你在弱网环境下看到支付页面转圈，忍不住想要狂点“确认支付”时，不妨放心地按下去，因为在遥远的服务器机房里，一个由幂等键和分布式锁构成的隐形护盾，正在默默守护着你的钱包。