源码接口幂等底层原理？

访客源码剖析 2026-06-08 00:34:15 2

本文目录导读：

这是一个非常经典且重要的问题,接口幂等性（Idempotency）的核心思想是：任意多次执行所产生的影响，均与一次执行的影响相同。

为了实现这一点,底层原理主要围绕 “唯一标识” + “去重记录” 这一核心机制展开，并结合了分布式系统的数据一致性保障。

以下是底层实现的核心原理拆解,以及几种常见实现方式的底层逻辑。

核心原理：唯一键 + 状态机

几乎所有幂等方案的本质都是：

生成唯一标识：为每个可能重复的请求（或一次业务操作）生成一个全局唯一的ID（订单号、流水号、UUID、Token）。
记录请求状态：在处理请求之前，先检查这个唯一标识是否已经被处理过。
决策与处理：
- 未处理：执行核心业务逻辑，并将处理结果（通常包括请求ID）持久化到数据库或缓存中。
- 已处理：直接返回上一次处理的结果（或提示重复），不再执行业务逻辑。

这是最底层的保障,利用数据库唯一索引的强制约束性。

底层原理：
1. 创建一个专门的幂等表（idempotent），至少包含 id（主键）、request_id（请求唯一标识）、status（处理状态）等字段。
2. 为 request_id 字段建立唯一索引。
3. 核心步骤：执行业务逻辑前，先尝试向 idempotent 表插入一条记录（INSERT INTO idempotent (request_id, status) VALUES (‘xxx’, ‘PROCESSING’)）.
  - 成功：说明当前请求是第一次到达，继续执行后续业务逻辑，执行完毕后，更新该记录状态为 SUCCESS。
  - 失败（Duplicate Entry）：说明请求已经存在（重复请求），直接返回已存在的处理结果（例如查询状态为 SUCCESS 的结果）。
为什么可靠？
数据库的事务ACID特性保证了“插入”操作的原子性，在高并发下，只有一个线程能成功插入该唯一键，其余线程都会失败，这是最严厉的互斥锁。
一个关键细节：业务逻辑的执行与状态更新必须是同一个事务，如果业务执行成功，但更新状态失败，下次重试时依然会被认为是“未处理”，导致重复执行。

利用Redis的原子操作特性，避免了数据库的磁盘I/O，速度极快。

底层原理：
1. 使用 Redis 的字符串类型，Key 为 idempotent:request_id，Value 为业务处理结果（或状态）。
2. 核心步骤：使用 SET key value NX EX ttl 命令。
  - NX：表示只有当 Key 不存在时，才能 SET 成功，这保证了“第一次”处理的原子性。
  - EX ttl：为 Key 设置过期时间，防止内存泄漏（通常设置为业务最长允许的重试间隔）。
  - SET 成功：说明第一次请求，执行业务逻辑。
  - SET 失败：说明重复请求，直接返回存储的值。
为什么快且可靠？
- Redis 是单线程模型，SET NX 是原子操作，确保了同一时刻只有一个请求能设置成功。
- 结合 Lua 脚本，可以将“检查 Key 是否存在 -> 执行业务逻辑 -> 设置结果”这三个步骤封装成一个原子操作，避免在业务执行期间锁被释放或被覆盖。

适用于前端表单重复提交、API调用方重试等场景。

底层原理：
1. 获取令牌：客户端（前端）在发起关键操作前，先向服务端申请一个唯一的、一次性的 Token（通常存储在 Redis 中，并设置合理过期时间），服务端将 Token 返回给客户端。
2. 执行请求：客户端携带这个 Token 发起业务请求。
3. 校验与删除：服务端在执行业务逻辑前，先校验 Token 是否存在，并立即删除，这个“校验并删除”操作必须是原子的（常用 Redis 的 GETSET 或 Lua 脚本）。
  - 校验成功（删除成功）：Token 第一次被使用，执行业务。
  - 校验失败（删除失败/Token不存在）：Token 已过期或已被使用，代表重复请求，直接拒绝。
为什么能防重复提交？
- 关键在于“使用一次即销毁”，即使客户端由于网络原因没收到第一次的响应，再次携带同一个 Token 请求时，Token 已经不存在了，请求会被直接拦截。

方案	可靠性	性能	适用场景	核心底层依赖
数据库去重表	最高	较低（磁盘I/O）	对一致性要求极高，如支付、转账、订单创建	数据库事务 + 唯一索引
Redis + Lua	高（若Redis宕机可能丢失）	非常高（内存操作）	高并发、允许短时间数据不一致（比如缓存），如用户签到、积分发放	Redis单线程原子性 + NX
Token 机制	高	高	防前端重复点击、防重放攻击、API网关层	Redis + 一次性消费（原子删除）

状态机与幂等：对于更新操作（已支付 -> 已发货），底层实现往往依赖数据库乐观锁，更新的 SQL 语句中加上条件判断：
```
UPDATE order SET status = '已支付', version = version+1 WHERE order_id = ? AND status = '待支付' AND version = X;
```
update 影响行数为 0，说明订单状态已经被更新过（重复请求），直接返回成功。
时间戳/唯一ID的生成：全局唯一ID不能是时间戳+随机数这种简单拼接，在高并发下极易重复，生产环境常用：
- Snowflake（雪花算法）：根据机器ID、时间戳、序列号生成全局唯一ID。
- 数据库自增ID + 业务前缀：如 ORDER_202305010001。
- UUID：字符串格式，性能稍差，但简单。
外部调用的幂等性：如果你的系统需要调用第三方（如支付网关），必须要求对方回传业务方的唯一请求 ID，微信支付接口就要求商户传入 out_trade_no（商户订单号），同一个 out_trade_no 只能支付成功一次，这就是对方提供的幂等保障。