接口幂等性设计与实战：支付、下单、重试场景怎么搞？

前言

用户点一次「提交订单」可能因为网络抖动、前端重复点击、网关重试而变成多次请求。如果接口不幂等，就会重复扣款、重复下单、重复发券。支付、下单、退款、发放权益这类接口，幂等是必选项，不是可选项。

本文从「什么是幂等」讲起，到常见实现方式（唯一键、token、状态机），再落到支付、下单、消息消费等实战场景，并给出 Java 示例和踩坑提醒，方便直接用到项目里。

1. 什么是幂等？

幂等：同一个请求执行一次和执行多次，对资源的影响是一样的；从结果上看，和只执行一次等价。

• 查询、删除（按ID）：天然幂等。查多次、删多次结果一致。
• 新增、更新、支付、下单：不设计就不幂等。重复调用会多扣钱、多下单。

所以幂等设计主要针对「会改变状态、会产生副作用的写操作」。

2. 为什么会有重复请求？

只要存在重试或重复调用，就要在业务层保证幂等，不能只依赖「只调一次」。

3. 常见实现思路

3.1 唯一键 + 数据库约束（最常用）

业务生成一个唯一请求号/幂等键（订单号、支付流水号、out_trade_no 等），写入时以该字段建唯一索引。第一次插入成功，后续相同键再插入会唯一冲突，直接视为重复请求，返回「已处理」或原结果。

优点：实现简单、可靠、不依赖外部存储。
缺点：依赖 DB 唯一约束；键要业务自己能生成且唯一（雪花、号段、UUID 等）。

-- 订单表CREATETABLEorders(idBIGINTPRIMARYKEY,order_noVARCHAR(64)NOTNULLUNIQUECOMMENT'订单号，幂等键',user_idBIGINTNOTNULL,amountDECIMAL(10,2),statusINT,created_atDATETIME);

// 伪代码publicOrdercreateOrder(CreateOrderRequestreq){StringorderNo=req.getOrderNo();// 前端或上游传入唯一订单号try{returnorderDao.insert(Order.builder().orderNo(orderNo).userId(req.getUserId())...build());}catch(DuplicateKeyExceptione){returnorderDao.getByOrderNo(orderNo);// 重复请求，返回原订单}}

3.2 幂等 token（防重复提交）

流程：先向服务端申请一个一次性幂等 token，提交时把 token 带上；服务端校验 token 存在则执行业务并删除（或标记使用），同一 token 再次请求则拒绝。

优点：适合前端「防重复点击」、无唯一业务单号时的表单提交。
缺点：需要存 token（Redis/DB），有过期和清理问题；高并发时要注意「校验-删除」的原子性。

// 1. 申请 token（可放在打开页面或点击「提交」时调一次）Stringtoken=UUID.randomUUID().toString();redis.set("idempotent:order:"+token,"1",5,MINUTES);// 2. 提交时带 tokenpublicOrdercreateOrder(StringidempotentToken,CreateOrderRequestreq){Stringkey="idempotent:order:"+idempotentToken;if(!redis.delete(key)){// 删除成功才继续，保证只用一次thrownewBizException("请勿重复提交");}returndoCreateOrder(req);}

注意：get + delete非原子，高并发下可能重复；Redis 可用 Lua 或「SET key 1 NX EX 5」配合删除，或直接用「存在则删除并返回是否删除成功」的语义。

3.3 状态机（防重复推进）

订单/支付单有明确状态（待支付→已支付→已发货…）。只有当前状态允许才执行操作，并在一次更新中「校验旧状态 + 更新新状态」。同一请求多次调用，第一次把状态改掉后，后续校验旧状态失败，不会重复推进。

优点：和业务强绑定，避免重复支付、重复发货等。
缺点：要设计清晰的状态和流转；更新时要带条件（如WHERE status = 待支付），并判断影响行数。

-- 只有「待支付」才能变成「已支付」UPDATEordersSETstatus='已支付',pay_time=NOW()WHEREorder_no=?ANDstatus='待支付';-- 若 affected rows = 0，说明已支付或已取消，直接返回幂等结果

intn=orderDao.updateStatusToPaid(orderNo);if(n==0){Orderexisting=orderDao.getByOrderNo(orderNo);if(existing.getStatus().equals("已支付")){returnexisting;// 幂等：已处理过}thrownewBizException("订单状态不允许支付");}

3.4 分布式锁

对「同一业务键」加锁，例如 RedisSET key NX EX，拿到锁的请求执行业务，执行完释放；同一键的并发请求只有一个能拿到锁。
注意：锁只能串行化并发，不能区分「同一次请求重试」和「另一次新请求」。通常和唯一键或 token 配合：先保证「同一请求」用同一个幂等键，再用锁保护「校验+执行」的原子性（可选）。

4. 场景一：支付回调/支付结果同步

支付渠道（微信/支付宝）可能多次回调或推送，必须幂等。

做法：

• 以支付渠道的支付单号（或 out_trade_no + 渠道）为幂等键，建唯一索引。
• 回调里：先按支付单号查本地是否已有「已支付」记录；没有则插入支付流水（唯一键），再更新订单状态（用状态机：仅当待支付→已支付）。
• 插入唯一键冲突或状态机更新影响行数为 0，都视为重复，返回 success，避免渠道反复重试。

@TransactionalpublicvoidonPayNotify(PayNotifyRequestreq){StringpayOrderNo=req.getPayOrderNo();if(payRecordDao.existsByPayOrderNo(payOrderNo)){return;// 已处理，直接返回成功}payRecordDao.insert(PayRecord.builder().payOrderNo(payOrderNo)...build());orderDao.updateStatusToPaid(req.getOrderNo());}

5. 场景二：下单接口

做法：

• 前端或网关生成订单号（或用后端生成的唯一 requestId），下单请求带 orderNo。
• 表上 order_no 唯一索引；insert 成功即创建，DuplicateKey 则 select 返回原订单（同一订单号视为重复下单）。

若不想让前端传订单号，可以用「用户 + 商品 + 短时间窗口」生成幂等键，或先生成订单号再调下单（先拿号、再提交）。

6. 场景三：消息队列消费

MQ 至少一次语义下，同一条消息可能被投递多次，消费端必须幂等。

做法：

• 以消息业务主键（如订单号、支付单号、消息ID）为幂等键，在 DB 或 Redis 记录「已处理」。
• 先查是否已处理；未处理则执行业务并写入「已处理」；已处理则直接 ack，不重复执行业务。

publicvoidconsume(Messagemsg){StringidempotentKey=msg.getOrderNo();if(redis.setNX("consumed:"+idempotentKey,"1",24,HOURS)){try{doCreateOrder(msg);}finally{// 可延长 key 或落库，防止 MQ 重试时 key 已过期}}// 已处理过，直接 ack}

7. 场景四：退款、取消、发放权益

思路一致：

• 退款：以退款单号或「订单号+退款批次」为幂等键，唯一表 + 状态机（仅待退款→退款中/已退款）。
• 取消订单：订单号 + 状态机（仅待支付/待发货→已取消）。
• 发券/发积分：以「用户+活动+发放批次」或流水号做唯一键，重复则跳过。

8. 实战注意点

8.1 幂等键谁生成？

• 订单号、支付单号：建议服务端生成（雪花/号段），前端只传「创建订单」意图；或前端传 requestId，服务端用 requestId 做幂等键。
• 支付回调：以渠道的支付单号为准，不要只用自家订单号（同一订单可能多次支付尝试）。

8.2 返回什么？

重复请求时，建议返回与第一次一致的结果（如订单详情、支付结果），并 HTTP 200，这样前端和渠道都按成功处理，不会继续重试。不要返回 4xx 导致调用方误以为失败而重试。

8.3 过期与清理

• token 幂等：设置合理过期时间，并避免 key 无限增长。
• 流水表：可按时间分表或归档，唯一键在有效期内即可。

8.4 事务与顺序

幂等校验（如查是否已存在）和业务写要在同一事务里，避免并发下重复通过校验。状态机更新用「WHERE 旧状态」并检查影响行数，保证只推进一次。

9. 总结

原则：会改状态、会扣钱、会发权益的接口，都设计成幂等；幂等键选好、状态机画清楚、重复请求返回首次结果，就能覆盖绝大多数后端场景。