做后端时间久了就会发现，面试题里背得滚瓜烂熟的概念，到了生产环境往往是另一副面孔。接口的幂等性设计就是典型代表：几乎每个后端工程师都能说出"幂等就是多次请求结果一致"这句话，但真到出现重复扣款、重复下单、库存被多扣这类线上事故时，能第一时间把问题锁到"接口缺了幂等保护"这个根因上的团队，并不多。我自己也经历过几次半夜被拉起来处理的重复支付事件，后来把这块彻底研究透了，才真正理解为什么说幂等性设计是分布式系统里最基础也最容易被忽略的一环。
这篇文章我会从一次典型事故出发，把接口幂等性从原理到落地完整拆一遍，内容包括：如何判断一个接口需不需要做幂等保护、五大主流方案的适用边界、Token方案和状态机方案的代码级实现细节，以及那些真正会让线上出问题的隐性陷阱。无论你是刚接触后端的新人，还是已经负责核心支付模块的技术负责人，这篇文章都能帮你少走几段弯路。
1. 一场重复扣款事故，让我重新认识了接口幂等
1.1 事故现场：用户只是多点了两下
曾经参与过一个电商项目，某天线上突然出现一批对账不平的订单，追踪后发现都是从同一个收银台页面进来的。用户在前端点击"确认支付"按钮时，因为网络抖动没有立即收到响应，于是又点了一次。第一次请求其实已经到了服务端，只是响应慢；第二次请求紧接着也到了服务端。两个请求都通过了参数校验、都执行了支付流水插入、都调用了资金账户扣款，最终结果就是同一个订单被扣了两次钱。
这类场景别说普通用户，很多技术人员自己都可能踩过。类似的触发路径还有：
- 客户端超时后自动重试，重试请求携带的还是同一个业务数据
- 消息中间件投递消息时，消费者处理成功后由于网络原因没有提交ACK，导致消息被重新投递
- 定时任务在分布式环境下被多个节点同时捞到了同一批数据
- 第三方支付平台回调通知时，出于可靠投递的目地往往会重复推送多次
这些路径有一个共同特征：同一个业务动作，在系统里以多条相同请求的形式出现了。如果接口层不具备幂等性，每一条请求都会作为独立操作去执行，副作用就会被无限放大。
1.2 从数学定义到工程定义
幂等（Idempotent）原本是数学里的概念，指的是某个操作执行一次和执行N次，产生的结果完全一致。用公式表达就是 f(f(x)) = f(x)。工程上翻译过来，就是同一个请求重复发送多次，服务端只应该产生一份业务结果。
举个例子。你调一个创建订单的接口，请求体里携带了订单号、商品ID、数量等信息。假设这个接口具备幂等能力，那同一份请求体被发送两次时，第一次创建了订单，第二次就直接返回"订单已存在"或者返回第一次创建时的订单信息，而不会新建第二个订单。如果接口不具备幂等能力，两次请求就会生成两笔订单，库存被扣掉两份。
这里有一个常见的认知偏差需要澄清：很多人把幂等性和并发安全混在一起。实际上两者关注点不同，幂等关注的是"重复请求"带来的副作用，并发安全关注的是"多个不同请求同时操作同一份数据"时的正确性。但两者的实现手段经常重合，比如唯一索引、分布式锁、乐观锁，既能让接口在重复请求下保持幂等，也能让并发请求安全执行。所以在设计幂等方案时，往往要同时考虑并发场景。
判断一个操作是否幂等，最简单的测试方法就是：把同一个请求原封不动发送两遍，看系统最终的数据状态是否和只发送一遍完全一致。如果一致，幂等；如果不一致，不等我继续，这就是需要补设计的地方。
2. 先分清天然幂等与必须额外设计的接口
2.1 HTTP方法本身就有幂等语义
在设计接口前，先看看HTTP协议本身已经替我们解决了哪些问题。HTTP方法天然带有幂等性语义，这是很多人容易忽略的起点。
| HTTP方法 | 是否天然幂等 | 原因与典型场景 |
|---|---|---|
| GET | 是 | 查询操作，不改变数据状态，执行多少次结果都一样 |
| PUT | 是 | 全量更新，把资源设置为指定值，重复设置同一个值不会产生额外副作用 |
| DELETE | 是 | 删除操作，语义上删除不存在的数据和删除已删除的数据结果等同 |
| POST | 否 | 新增操作，每次执行都会产生新资源，是最需要幂等保护的 |
| PATCH | 否 | 局部更新，尤其是"金额+1""库存-1"这类增量操作，重复执行会使状态失控 |
写到这里，你应该注意到一个非常反直觉的点：DELETE 在语义上是幂等的，但这是指"删除目标"的最终状态，不代表每次响应都一样。第一次删除时返回 200，第二次删除资源已经不存在，返回 404，这是正常的。但在工程上，如果调用方的重试逻辑把 404 当作异常继续重试，就会形成无效循环。所以用 DELETE 时，接口设计者必须明确告诉调用方：删除不存在也同样被视为一次成功操作。
2.2 业务场景里的幂等需求分级
把HTTP方法层面的语义搞清楚了，再来看业务侧。不是所有接口都需要做幂等设计，做之前要分清场景。
强幂等场景，必须做设计：
- 涉及资金的操作：支付、退款、充值、提现
- 涉及资源发放的操作：优惠券领取、积分累加、库存扣减
- 涉及状态流转的操作：下单、订单确认、取消订单
- 涉及唯一凭证的操作：注册、发单号、开票
弱幂等场景，可以做简单处理甚至不做：
- 纯查询类接口，本身没有副作用
- 日志上报、埋点上报类接口，多一条少一条对业务无实质影响
- 用户行为记录、流量统计类接口，通常采用"先写后算"或异步归并的方式
判断方法其实很简单：这个操作重复执行一次，会不会产生"用户感知得到或资金对不上"的变化？如果会，就纳入幂等设计范围。
还有一个容易被遗漏的点：对外暴露的API和对内消费的MQ处理器，幂等需求是同级的。很多团队给HTTP接口做了完善的幂等保护，却在MQ消费者里直接写业务逻辑，结果消息重投后照样重复处理。幂等保护应该覆盖所有入口，而不只是用户直接触达的那一层。
3. 五大主流幂等方案：适用边界和选型逻辑
这一节我把实际项目中最常用的五种幂等方案完整梳理一遍。你不需要每一种都掌握得很深，但一定要知道每一种适合什么场景、有什么局限，这样选型时才不会拍脑袋。
3.1 方案一：数据库唯一约束
这是最可靠、最落地的幂等方案，核心思路就是利用数据库唯一索引从物理上拦截重复数据。在订单表里，给业务订单号建立唯一索引，两个相同请求同时插入时，只有一个能成功，另一个会触发唯一键冲突异常。
CREATE TABLE `t_order` ( `id` bigint NOT NULL AUTO_INCREMENT, `order_no` varchar(64) NOT NULL, `user_id` bigint NOT NULL, `amount` decimal(10,2) NOT NULL, PRIMARY KEY (`id`), UNIQUE KEY `uk_order_no` (`order_no`) ) ENGINE=InnoDB;代码层面要做的事情是：先正常执行插入，捕获唯一键冲突异常，在异常处理里把"重复请求"转成"业务上成功"的响应。也就是让第二次请求拿到和第一次等价的结果，而不是直接给调用方抛一个500。
这个方案的优势非常突出：不依赖Redis，不依赖分布式锁，数据准确率百分百可靠。缺点在于它只能解决"插入"类型的幂等，对"更新"类型的操作就力不从心了，而且插入失败会产生一次多余的数据库写操作消耗。
3.2 方案二：Token令牌机制
Token令牌方案是交互类接口最常用的方案，典型场景是前端表单提交。
流程是这样的：
- 客户端在打开页面或开始业务流程时，先调用服务端的"获取Token"接口
- 服务端生成一个唯一Token，存到Redis里，设置过期时间，返回给客户端
- 客户端在后续业务请求中携带这个Token
- 服务端处理业务前先校验并消费Token：检查Redis里是否存在，不存在或已被消费则直接拒绝
- 业务执行成功后Token被删除，下次再用同一个Token就不再生效
这个方案的关键在于"消费Token"必须是一个原子动作。如果代码里先查询Token是否存在，再删除Token，这中间一旦两个请求同时通过校验，就会造成重复执行。正确做法是用Redis的原子操作或者Lua脚本把"查询+删除"合并成一个不可分割的操作。
Token方案适合用户主动触发的交互型接口，比如提交订单、发布文章、提交报名信息。它不适合纯API调用场景，因为每次调用都要先获取Token，额外多了一次网络往返，对高性能接口的开销太大。
3.3 方案三：乐观锁/版本号
乐观锁方案解决的是更新类操作的重复提交问题，核心思路是在更新时带上版本条件，只有版本号匹配才允许更新成功。
UPDATE t_order SET status = 'PAID', version = version + 1 WHERE order_no = 'xxx' AND version = 1;假设当前订单的version是1，两个重复请求同时执行这条SQL，数据库的行锁会保证只有一个请求更新成功，另一个请求的影响行数为0。程序根据影响行数判断是否操作成功，影响行数为0时直接返回"重复操作"或"操作无效"。
相比分布式锁，乐观锁实现简单，不需要额外组件，适合并发冲突不频繁但有更新需求的场景。缺点也很明确：如果业务冲突频繁，大量请求会因为版本号不匹配而失败，用户体验会变差。此时就需要配合重试机制或考虑换用其他方案。
3.4 方案四：状态机
状态机方案在订单、工单、审批流这类状态有严格流转方向的业务中格外好用。它的逻辑是：一个业务对象只能从合法的前置状态迁移到后置状态，重复请求如果发现当前状态已经不是它期望的前置状态，就直接拒绝。
举个例子，订单状态机的流转关系是：待支付 -> 已支付 -> 已发货 -> 已完成。当用户重复发起支付请求时，第一个请求把订单从"待支付"更新为"已支付"，第二个请求到达后发现订单已经不处于"待支付"状态，就会直接返回"订单已支付，请勿重复操作"。
状态机方案和乐观锁可以搭配使用，也可以独立使用。它的优点是语义清晰，符合真实业务规则，且天然具备幂等性；缺点是需要预先梳理完整的业务状态流转路径，如果后续业务变更增加新状态，维护成本会比较高。
3.5 方案五：去重表/幂等表
去重表方案的核心是建立一张专门的幂等记录表，利用唯一索引做拦截。
CREATE TABLE `t_idempotent_record` ( `id` bigint NOT NULL AUTO_INCREMENT, `biz_type` varchar(32) NOT NULL, `biz_key` varchar(128) NOT NULL, `create_time` datetime NOT NULL, PRIMARY KEY (`id`), UNIQUE KEY `uk_biz_type_key` (`biz_type`, `biz_key`) ) ENGINE=InnoDB;业务请求到达时，先尝试往这张表插入一条记录（biz_type 表示业务类型，biz_key 表示业务唯一键）。插入成功，说明这是第一次请求，可以继续执行业务逻辑；插入失败，说明是重复请求，直接返回。
这个方案需要注意事务边界。如果幂等记录表的插入和业务操作不在同一个事务里，一旦业务操作失败而幂等记录已经写入，后续重试就会被幂等表拦截。通常做法是：先插入幂等记录，再执行业务操作，如果业务操作失败则把幂等记录删除或标记为失败状态，允许重试。
3.6 方案选型对比
| 方案 | 核心依赖 | 适用场景 | 局限 |
|---|---|---|---|
| 数据库唯一约束 | 数据库 | 新增类接口、流水记录 | 更新类操作不适用 |
| Token令牌机制 | Redis | 前端交互、表单提交 | 多一次往返，不适合高频API |
| 乐观锁/版本号 | 数据库 | 更新类接口、状态类操作 | 冲突频繁时体验差 |
| 状态机 | 业务代码 | 订单、审批流程 | 状态建模复杂，变更成本高 |
| 去重表/幂等表 | 数据库 | 通用幂等拦截 | 需要管理额外表，事务边界易错 |
选型建议很简单：资金类和订单类接口，优先用数据库唯一约束加状态机组合；交互类接口，加Token令牌机制；更新类场景，用乐观锁。至于分布式锁，它在某些场景下也能辅助幂等，但它的作用更多是保证并发互斥，而不是直接解决重复请求问题，这里就不把它作为独立的幂等方案来推荐了。
4. Token方案的落地拆解：从注解到AOP的原子消费
选Token方案做例子完整拆解，是因为它在交互接口中用得最频繁，踩坑的人也是最多的。下面我会直接用代码说明一个完整的实现路径。
4.1 幂等注解的定义
先定义一个自定义注解，用来标记哪些接口需要做幂等保护：
@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Idempotent { // Token在Redis中的key前缀，用于区分不同业务 String prefix() default "idempotent:token:"; // Token过期时间，默认5分钟 int expireSeconds() default 300; }这个注解的参数不建议太复杂，prefix和过期时间这两个基本够用了。真正复杂的逻辑全部收拢在切面里，让业务代码保持干净。
4.2 获取Token的接口
客户端在进入业务页面时，先调用这个接口拿到Token：
@RestController public class TokenController { @Autowired private StringRedisTemplate stringRedisTemplate; @PostMapping("/getToken") public Result<String> getToken() { String token = UUID.randomUUID().toString().replace("-", ""); String key = "idempotent:token:" + token; // 用setIfAbsent而不是简单set，避免极端情况下key被覆盖 Boolean success = stringRedisTemplate.opsForValue() .setIfAbsent(key, "1", Duration.ofMinutes(5)); if (Boolean.TRUE.equals(success)) { return Result.success(token); } return Result.error("生成Token失败，请重试"); } }生成Token的逻辑没什么花哨的，UUID足够保证唯一性。需要注意两点：一是Token里不要拼业务信息，它只是一个不透明的凭证；二是过期时间按业务复杂度来定，表单提交类5分钟比较合适，太短会误伤用户填写时间长的场景。
4.3 核心AOP切面：原子消费Token
这是整个方案最核心的部分。切面要做的事：从请求参数里取出Token，校验Redis中是否存在，存在则删除并放行，不存在则拦截返回。
不少团队的做法是先exists判断、再delete删除，分开两步走，这在并发场景下一定有问题。两个请求同时通过exists校验，然后同时执行delete，结果是两个请求都拿到了"Token存在"的通行证，业务被执行了两次。正确做法是把这个过程做成原子的：
@Aspect @Component public class IdempotentAspect { @Autowired private StringRedisTemplate stringRedisTemplate; // 用Lua脚本原子执行：查询 + 删除 private static final String CHECK_DELETE_SCRIPT = "if redis.call('get', KEYS[1]) == ARGV[1]" + "then return redis.call('del', KEYS[1])" + "else return 0 end"; @Around("@annotation(idempotent)") public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable { // 从请求中获取Token，这个工具方法根据实际参数结构实现 String token = getTokenFromRequest(joinPoint); if (StringUtils.isBlank(token)) { throw new BizException("缺少幂等Token"); } String key = idempotent.prefix() + token; Long result = stringRedisTemplate.execute( new DefaultRedisScript<>(CHECK_DELETE_SCRIPT, Long.class), Collections.singletonList(key), "1"); if (result == null || result == 0) { throw new BizException("请勿重复提交"); } return joinPoint.proceed(); } }这段Lua脚本做的事情是：如果Redis里key的值等于"1"，就删除这个key并返回1；如果key不存在或值不匹配，返回0。查询和删除在同一个脚本里执行，Redis单线程执行Lua脚本的特性天然保证了原子性，不会有并发竞态窗口。
4.4 重复请求的返回体验设计
幂等拦截后返回什么，是一个容易被忽略但很重要的细节。很多人直接把异常抛出去，调用方收到的是500，用户看到的是"系统错误"，体验很差不说，还可能诱导用户再试一次，形成恶性循环。
我习惯的做法是定义统一的业务异常码，错误信息直接告诉用户"请勿重复提交，页面即将跳转"，同时把业务成功的标志返回给调用方。因为对于用户来说，重复点击之后他关心的是"我的操作到底成没成功"，而不是"系统报了什么错"。交互设计上，前端拿到重复提交的提示后要做页面状态回跳或自动关闭按钮，形成完整闭环。
5. 状态机方案在订单接口里的实战应用
Token方案解决的是"同一时刻或短时间内重复请求"的问题，但如果重复请求穿过了Token层，或者压根没走Token层而是走了消息队列，就需要状态机来兜底。这一节以订单接口为例，看状态机怎么在实际业务里保驾护航。
5.1 订单状态与合法流转路径
先梳理一张订单状态流转表：
| 当前状态 | 操作 | 后置状态 |
|---|---|---|
| 待支付 | 用户支付 | 已支付 |
| 待支付 | 用户取消 | 已取消 |
| 已支付 | 商家发货 | 已发货 |
| 已发货 | 确认收货 | 已完成 |
| 已支付 | 用户申请退款 | 退款处理中 |
| 退款处理中 | 退款完成 | 已退款 |
这张表看起来简单，但它把整个订单生命周期里所有合法路径都约束清楚了。所谓状态机幂等，就是只有处于合法前置状态的请求才允许执行对应操作，其他所有请求一律拒绝。
5.2 状态迁移校验代码
实际业务里写一个状态迁移校验方法：
public boolean canTransit(OrderStatus currentStatus, OrderEvent event) { switch (currentStatus) { case PENDING_PAY: return event == PAY_SUCCESS || event == CANCEL; case PAID: return event == SHIP || event == APPLY_REFUND; case SHIPPED: return event == CONFIRM_RECEIPT; case REFUNDING: return event == REFUND_SUCCESS; default: return false; } }然后在更新SQL里把前置状态作为更新条件一起带上：
UPDATE t_order SET status = 'PAID', pay_time = NOW() WHERE order_no = 'xxx' AND status = 'PENDING_PAY';上面这条SQL是状态机方案的关键所在。更新条件里带上"status = 'PENDING_PAY'"，数据库行锁会保证两个并发请求只有一个能更新成功，另一个影响行数为0。只需要判断影响行数，就能知道这个请求是有效操作还是重复操作。
5.3 状态机与其他方案的组合
状态机方案最适合作为第二道幂等防线。我见过最稳的组合方式是：第一层用Token方案拦截用户重复点击；第二层用数据库唯一索引在订单流水表里做硬约束；第三层用状态机保证订单主表状态不重复流转。三层各司其职，重复请求几乎没有任何机会穿透到资金层。
要注意的是，状态机方案虽然能防止订单状态被重复变更，但它不直接防止"重复入账"。比如支付系统把一个支付成功的流水同时发到积分系统和优惠券系统，两个系统各自基于这个流水做了累加，订单状态本身没问题，积分却加了两次。所以凡是基于同一事件衍生出的多条业务动作，都要各自做幂等处理，不能指望订单状态机覆盖所有下游操作。
6. 幂等设计会咬人的隐性陷阱：五个关键细节
方案本身不复杂，真正让团队头疼的问题大多出现在细节里。我整理了五个高频陷阱，每一个都对应过真实的线上事故。
6.1 "先检查后执行"根本不具备原子性
很多人实现的所谓幂等逻辑是这样的：先判断订单状态，如果不是待支付就返回，如果是待支付就执行更新。这个判断逻辑在单线程下没问题，但在并发下完全失效。两个请求同时读到了"待支付"状态，然后都通过了判断，最终都执行了更新。
正确做法是让约束下沉到数据库层面，用唯一索引、行锁或乐观锁条件让数据库从物理上拦住重复操作。业务代码里的"先查询再判断"只能作为辅助手段，不能作为幂等保证。
6.2 幂等键的生成规则是门技术活
幂等键（Idempotency Key）是指用来识别"是否是同一请求"的唯一标识。有些接口直接让客户端传一个UUID当幂等键，这存在两个问题：一是客户端可能在重试时生成新的UUID，导致服务端认为是两次不同请求；二是客户端可以恶意构造不同的幂等键来绕过防重。
服务端的做法应该是：幂等键要么取自业务数据里本身有的字段（如订单号、流水号），要么由服务端在第一次请求时生成并返回给调用方，后续重试必须携带同一个幂等键。比如第三方支付回调里的"商户订单号"，就是天然的幂等键。
6.3 回调接口的幂等：通知会重复，处理结果必须一致
很多系统对接第三方平台后，回调接口是重复请求的重灾区。第三方为了确保通知到达，会在一定时间内多次推送回调，直到服务端返回明确的成功标志。如果回调处理器不幂等，每来一次通知就做一次入账操作，资金数据必然错乱。
回调接口的幂等处理套路是固定的：先按外部流水号查本地记录，存在则直接返回成功，不存在则处理并落库。同时把更新条件加严，比如引入外部流水号唯一索引，触发了唯一键冲突直接返回成功。这样不管回调重复多少次，最终结果都是一样的。
6.4 幂等记录需要设过期时间吗
Token方案里Redis里的Token一般是有过期时间的，这是为了不让Token无限占用存储。但对于另一类幂等记录，比如支付流水表里的唯一索引记录，长时间保留是必要的。你无法预测一个支付回调会在多长时间后重试，如果把唯一索引对应的记录手动删掉或过期了，重复回调就会重新入账。
这里有一个设计上的权衡：高频重复的防重（表单Token）用短过期时间，低频但必须长期防重的防重（支付流水、订单号）用持久化存储。不要一概而论。
6.5 幂等设计与事务的边界
写幂等逻辑的时候，最容易把事务边界搞错。常见问题有两种：一是把幂等记录表的插入放在业务大事务里，一旦业务后面的步骤耗时较长，数据库连接被长时间占用，并发能力急剧下降；二是先写业务数据再写幂等记录，业务写成功但幂等记录写失败，结果重试时又执行了一遍业务逻辑。
我的实践经验是：幂等记录的写入要尽可能在业务逻辑之前完成，用独立的事务或原子操作，然后用一个明确的字段标记业务处理状态。业务处理失败时，幂等记录的状态改回"失败"或直接删除，允许重试。分布式事务在这里并不总是需要的，很多场景用一个状态字段就能管理清楚。
如果要让我用一句最实在的话总结，我会说：看一个接口设计得好不好，不是看它功能多完整，而是看它把重复请求处理得多优雅。我在实际项目里已经形成了条件反射，任何一个涉及资金、涉及状态流转、涉及资源发放的接口，上线前都会拿三个问题过一遍：这个操作重复执行会产生副作用吗？重复请求会从哪几条路径进来？用户如果连点十次，最终数据会变成什么样？把这几个问题想清楚，再去选具体的方案，基本就不会出大问题。接口幂等性设计没有银弹，指望一个方案解决所有场景也不现实，但把重复路径和业务约束摸清之后，剩下的只是选一个团队能长期维护透的方案而已。
