尧图网站建设 
1. 从一次重复扣款事故说起为什么我们需要API幂等性那天下午运营同事急匆匆地跑过来说后台连续收到了好几个用户的投诉都是同一个问题明明只下了一单银行卡却被扣了两次甚至三次款。我第一反应是去查支付流水果然同一个订单号支付网关那边竟然返回了三条成功的回调记录。再一看日志那段时间网络有点波动我们的订单服务在调用支付接口后因为超时没收到明确响应触发了重试机制结果支付网关那边其实第一次就处理成功了只是响应包在网络传输中丢了。后续的重试请求到达时支付网关一看是同一个订单号又老老实实地执行了扣款操作。这就是典型的非幂等操作引发的生产事故。所谓幂等性是一个数学和计算机科学里的概念简单来说就是一个操作无论执行一次还是多次只要输入相同产生的结果状态都是完全一致的。对于我们的API特别是修改数据的写操作POST, PUT, DELETE幂等性设计不是“锦上添花”而是保障系统数据一致性、防止业务逻辑混乱的“生命线”。你可能会想GET请求是天然幂等的因为它只是查询不改变状态。问题往往出在那些“写操作”上。想象一下这些场景用户点击“提交订单”按钮因为页面卡顿连点了好几下前端应用在弱网环境下自动重试请求消息队列消费者处理失败消息被重新投递分布式系统调用超时后的补偿重试……如果没有幂等性兜底每一个场景都可能变成一场数据灾难——重复创建订单、重复支付、重复发货、重复发放优惠券。所以今天我们不聊那些高深的理论就从一个一线开发者的视角拆解在实战中如何为你的API穿上这件“防弹衣”。我们会从原理、到常见的实现方案、再到不同业务场景下的选型与避坑手把手让你掌握这套关键时刻能“保命”的设计模式。2. 幂等性的核心状态机与操作分类在动手设计之前我们必须从根上理解为什么有些操作天生容易“重复”以及我们究竟要保护的是什么。2.1 操作的两种类型与幂等诉求我们可以把服务端操作粗暴地分为两类非幂等操作Non-idempotent每次执行都会改变系统状态多次执行会导致累积效应或错误状态。最典型的就是POST /orders创建订单。调用一次生成一个订单调用N次就生成N个订单。这类操作是幂等性设计的重点防护对象。天然幂等操作Idempotent多次执行效果与一次执行相同。这包括GET /orders/{id}查询多少次订单数据都不会变。PUT /orders/{id}更新订单信息。你第一次调用把状态改为“已支付”后续再用相同参数调用订单状态依然是“已支付”不会变成别的。注意这里的前提是PUT用于整体替换资源而非局部更新。如果使用PATCH进行局部更新则需要额外设计幂等性。DELETE /orders/{id}删除一个订单。第一次调用成功删除第二次调用时订单已不存在返回404或200但系统的最终状态订单不存在是一致的。HTTP协议规范对方法的幂等性有建议但实际业务中我们不能完全依赖协议。例如一个POST /transfer的转账接口从业务逻辑上看绝对是非幂等的我们必须通过业务逻辑设计使其具备幂等性。2.2 业务状态机是幂等设计的基石所有幂等性设计的核心都是围绕业务状态机进行的。你需要清晰地定义出你的业务对象如订单、支付单、优惠券一生中会经历哪些状态以及状态之间允许如何转换。以订单为例一个简化的状态机可能是待支付-支付中-已支付-已发货-已完成。同时也可能有已取消等终态。幂等性处理的关键在于当请求试图将一个对象从状态A转移到状态B时系统需要检查当前状态是否允许这次转移。如果当前状态已经是B那么这次操作应该被视为“已经成功过”直接返回成功不做任何实质性变更。这就是幂等。如果当前状态是C比如从已支付试图再转到支付中这通常是一个非法操作应该返回明确的业务错误如“订单状态异常”而不是盲目执行。很多重复问题根源在于服务端没有维护这样一个清晰的状态机或者处理请求时没有进行状态校验只是盲目地执行了更新数据库的SQL语句比如UPDATE order SET status ‘paid’ WHERE id 123这条语句执行多少次结果都一样status都是’paid’但它没有防止从错误状态转移过来的问题。更完善的幂等需要结合状态判断。3. 实战方案一Token令牌机制防重提交这是前端防重复提交最常用、也最直观的方案特别适用于用户交互场景。3.1 流程与原理它的核心思想是每次进入需要防重的页面如表单页时服务端生成一个唯一的令牌Token同时在前端页面如隐藏域和服务器端如Redis进行存储。当用户提交表单时必须将这个Token带回服务端。服务端校验Token是否存在且未被使用如果存在则执行业务逻辑并立即删除或标记该Token为已使用如果不存在则认为是重复提交直接拒绝。具体步骤获取Token客户端调用GET /api/idempotent/token。服务端生成一个全局唯一的字符串如UUID将其作为Value存入RedisKey可以为idempotent:token:{tokenValue}并设置一个合理的过期时间如5分钟。同时将这个Token返回给客户端。携带Token请求客户端在提交业务请求如POST /api/orders时必须在HTTP Header如X-Idempotent-Token或请求体中将这个Token带上。服务端校验服务端拦截器或AOP切面首先检查请求中是否包含Token。无Token可按需处理可直接放行不启用幂等或直接拒绝。建议对明确需要幂等的接口强制要求Token返回错误。有Token尝试以该Token为Key向Redis发起GETDEL命令原子性地获取并删除。如果GETDEL成功获取到值说明是第一次请求放行执行业务。如果GETDEL返回nil说明Token已被使用重复请求直接返回“重复提交”的错误响应。3.2 为什么用GETDEL而不是GETDEL这是关键细节考虑以下时序请求A到来GET到Token存在。在执行业务逻辑前请求B到来也GET到同一个Token存在因为A还没删。两个请求都认为自己合法继续执行业务导致重复。最后两个请求都去DELToken。使用GETDEL或SETNX设置如果不存在这类原子操作可以确保“判断”和“占用”这两个动作是原子的从根本杜绝了并发场景下的重复问题。这是实现幂等性的一个黄金法则状态判断与变更必须是原子的。3.3 适用场景与优缺点优点理解简单实现直观。对前端友好能有效防止用户手抖、网络延迟导致的重复点击。缺点需要额外的接口来获取Token增加了一次网络交互。严格依赖一个中心化的存储如Redis来保证原子性在分布式环境下需要注意Redis本身的高可用。主要防御的是“短时间内的重复提交”对于消息队列重试等长时间跨度场景不太适合Token可能过期。个人踩坑心得Token的过期时间需要仔细权衡。太短用户填写复杂表单可能超时太长又浪费存储空间且可能增加安全风险。通常5-30分钟是个合理的范围。另外务必确保Token的生成有足够的随机性使用安全的随机数生成器防止被猜测。4. 实战方案二唯一索引与插入防重对于创建资源的场景如创建订单、生成流水号利用数据库的唯一索引是最简单、最坚固的幂等保障。它的原理是让数据库这个“最终守门员”来拒绝重复的数据。4.1 基于业务唯一键的设计假设我们有一个orders表业务上允许用户对同一商品再次下单所以我们不能以user_id和product_id做唯一索引。常见的做法是在创建订单前由客户端或服务端生成一个业务唯一键比如叫order_no订单号或out_trade_no商户订单号。这个ID必须是全局唯一的通常可以使用“业务前缀时间戳随机数”或“雪花算法”等分布式ID生成器来创建。然后在orders表上为order_no字段建立唯一索引。处理流程客户端或服务端生成唯一的order_no。执行插入订单的SQLINSERT INTO orders (order_no, user_id, amount, status, ...) VALUES (?, ?, ?, pending, ...)。如果这是第一次请求插入成功。如果是重复请求携带相同的order_no数据库会抛出唯一键冲突异常如Duplicate entry。服务端捕获这个异常然后不是直接返回错误给客户端而是转而查询数据库中已存在的、具有该order_no的订单将其信息返回给客户端。对于客户端而言它得到的结果一个已创建的订单和第一次请求成功的结果是一致的。-- 伪代码示例 try { orderDao.insert(newOrder); // 尝试插入 return success(newOrder); } catch (DuplicateKeyException e) { // 捕获唯一键冲突 Order existingOrder orderDao.selectByOrderNo(newOrder.getOrderNo()); // 这里可以进一步校验比如订单状态、用户是否匹配等防止恶意请求 if (existingOrder ! null existingOrder.getUserId().equals(currentUserId)) { return success(existingOrder); // 返回已存在的订单 } else { throw new BusinessException(订单创建冲突请稍后重试); } }4.2 适用场景与优缺点优点实现简单依赖数据库本身的能力可靠性极高。没有额外的中间件依赖如Redis。能防御任何情况下的重复插入包括并发请求。缺点仅适用于“创建”场景对于更新操作无效。将压力转移到了数据库高频插入场景下唯一索引冲突可能成为性能瓶颈。需要在业务逻辑里妥善处理数据库异常并将其转化为对客户端友好的幂等响应。个人踩坑心得千万不要在捕获到DuplicateKeyException后只是简单地返回一个“重复提交”的错误。对于创建订单这样的场景客户端更关心的是“我的订单到底创建成功没有订单号是什么”。所以查询并返回已存在的资源是幂等接口设计的标准做法。这要求你的API响应格式在“首次成功”和“重复请求”时保持一致。5. 实战方案三状态机与乐观锁对于更新操作如支付回调、状态变更单纯防重插入就不够了。我们需要结合前面提到的业务状态机和乐观锁机制。5.1 支付回调的幂等设计案例这是最经典的场景。支付网关会异步回调我们的服务端接口POST /api/payment/callback通知我们订单支付结果。由于网络问题支付网关可能会多次发送相同的回调。我们的接口必须幂等。表结构设计参考CREATE TABLE payment_order ( id bigint PRIMARY KEY, order_no varchar(64) NOT NULL COMMENT 业务订单号, out_trade_no varchar(64) NOT NULL COMMENT 支付网关订单号, amount int NOT NULL COMMENT 金额分, status tinyint NOT NULL COMMENT 状态0-待支付1-支付成功2-支付失败3-已关闭, version int NOT NULL DEFAULT 0 COMMENT 数据版本号用于乐观锁, callback_info json COMMENT 支付回调信息, UNIQUE KEY uk_order_no (order_no), UNIQUE KEY uk_out_trade_no (out_trade_no) );幂等处理流程参数校验与业务键提取从回调参数中解析出唯一标识本次支付的业务键通常是out_trade_no支付网关订单号或我们传给网关的order_no。查询当前状态根据业务键查询支付单payment_order。状态判断幂等的核心场景A记录不存在。这可能是非法回调或者订单数据尚未同步。应记录告警并返回失败让支付网关稍后重试或根据业务逻辑决定是否创建。场景B记录存在且状态为“支付成功”。说明之前已经处理成功了。直接返回成功的响应如SUCCESS即可无需任何更新操作。场景C记录存在且状态为“待支付”。这是正常流程继续下一步。场景D记录存在且状态为“支付失败”或“已关闭”。说明订单已终态但收到了成功回调。这可能是严重异常需要记录错误日志并人工介入核查接口应返回失败。乐观锁更新对于场景C我们执行更新操作。但为了防御极端的并发情况比如两个回调请求同时到达都通过了步骤3的状态判断我们需要使用乐观锁。UPDATE payment_order SET status 1, version version 1, callback_info ‘{...}’ WHERE out_trade_no ‘xxx’ AND status 0 AND version #{currentVersion};这条SQL的妙处在于它将状态判断和更新合并成了一个原子操作。WHERE条件中status 0确保了只有“待支付”的订单才能被更新为“支付成功”。version #{currentVersion}确保了更新的是我们刚才查询出来的那个版本的数据。检查更新结果执行SQL后检查数据库返回的“受影响行数”affected rows。如果affected_rows 1说明更新成功是第一个处理该回调的请求。接下来可以执行业务后续逻辑如更新订单状态、发放权益等。如果affected_rows 0说明更新失败。原因可能是1) 其他请求已抢先更新版本号变了2) 订单状态已不是“待支付”。此时应该重新查询一次订单的最新状态然后回到步骤3进行状态判断。这通常意味着其他请求已处理成功当前请求按“重复请求”处理直接返回成功。5.2 适用场景与优缺点优点能完美处理更新操作的幂等性特别是状态流转场景。结合数据库事务能保证数据强一致性。乐观锁相比悲观锁SELECT … FOR UPDATE性能更好在高并发场景下更优。缺点实现复杂度较高需要精心设计状态机和更新逻辑。需要数据库支持行级锁和返回受影响行数。在超高并发下乐观锁更新失败率会增高可能导致大量请求需要重试或回查。个人踩坑心得支付回调接口的响应内容非常重要。很多支付网关会根据你的响应内容如字符串SUCCESS来判断是否通知成功。即使你是幂等处理重复请求直接返回成功也必须返回与第一次成功时完全相同的成功响应否则支付网关可能认为通知失败而持续重试。另外整个回调处理逻辑务必保持幂等包括后续的更新订单、发短信、发优惠券等操作否则还是可能造成数据不一致。6. 实战方案四分布式锁与全局唯一请求ID在分布式系统、特别是微服务架构下一个业务流可能涉及多个服务间的多次调用。单纯每个接口幂等还不够我们需要保证整个业务链路的幂等。这时“全局唯一请求ID”配合“分布式锁”或“幂等表”是一种更高级的模式。6.1 全局唯一请求IDRequest ID其核心思想是在业务请求发起的最源头如网关、前端生成一个全局唯一的request_id这个ID伴随着这个业务请求的整个生命周期穿透所有服务调用。每个服务在处理请求时都依据这个request_id来判断是否已经处理过。生成与传递生成可以使用UUID、雪花算法等。通常在API网关层生成并注入到HTTP Header中如X-Request-Id。传递在服务内部调用时通过RPC、HTTP Client等必须显式地将这个request_id传递给下游服务。这是实现链路追踪和幂等的关键。6.2 基于“幂等表”的实现这是处理分布式幂等非常稳健的一种方式。我们单独建立一张表来记录已经处理过的请求。CREATE TABLE idempotent_record ( id bigint PRIMARY KEY AUTO_INCREMENT, request_id varchar(128) NOT NULL COMMENT 全局请求ID, business_key varchar(128) NOT NULL COMMENT 业务唯一键可与request_id相同或不同, service_name varchar(64) NOT NULL COMMENT 服务名, method_name varchar(64) NOT NULL COMMENT 方法名, status tinyint NOT NULL COMMENT 处理状态0-处理中1-成功2-失败, result text COMMENT 处理结果快照JSON格式, created_at datetime NOT NULL, updated_at datetime NOT NULL, UNIQUE KEY uk_request (request_id, service_name, method_name), KEY idx_business (business_key) );处理流程请求到达服务A的某个接口。服务A从Header中获取request_id结合自身服务名和方法名构成一个唯一标识。在数据库事务中执行插入操作INSERT INTO idempotent_record (request_id, service_name, method_name, status, ...) VALUES (?, ?, ?, 0, ...)。这里利用了数据库的唯一索引来保证并发下的原子性。插入成功说明是第一次请求。执行业务逻辑业务成功后在同一个事务内更新该记录状态为1成功并可将关键结果存入result字段。提交事务。插入失败唯一键冲突说明该请求已被处理过。此时查询表中该request_id对应的记录。如果记录状态为1成功则直接从result字段中反序列化出上次的处理结果直接返回给客户端。如果记录状态为0处理中这可能意味着上一个请求正在处理发生了并发。此时可以稍等片刻如sleep几十毫秒后重查或者直接返回一个“处理中请稍后查询”的响应。这需要根据业务容忍度设计。如果记录状态为2失败则可以根据业务决定是返回之前的失败结果还是允许重试此时可以删除旧记录重新插入但要谨慎。6.3 适用场景与优缺点优点通用性强几乎适用于所有需要幂等的场景特别是分布式链路。通过存储结果可以真正做到无论调用多少次返回完全相同的结果。便于排查问题可以通过request_id追溯整个请求的处理历史。缺点架构复杂度最高需要引入额外的“幂等表”增加了数据库压力。对数据库性能有要求request_id的唯一索引可能成为热点。需要谨慎处理“处理中”状态防止客户端长时间等待。个人踩坑心得幂等表的设计中result字段存储结果快照非常有用但不要存储过大的对象。建议只存储核心的、用于构建响应体的数据。另外这张表的数据需要定期清理如按时间归档或删除否则会无限膨胀。可以考虑按created_at分区或者将已完成的记录转移到历史表。对于超高并发场景插入幂等表的操作本身可能成为瓶颈此时可以考虑使用更快的存储如Redis来实现第一步的“抢占”但最终一致性还是需要数据库来保证架构会变得更复杂。7. 方案选型与架构思考面对这么多方案在实际项目中该如何选择没有银弹只有最适合你当前场景的权衡。7.1 方案对比速查表方案核心原理适用场景优点缺点技术复杂度Token令牌一次性令牌用后即焚前端防重复提交用户交互场景简单直观前端友好需额外接口依赖Redis适合短时间低唯一索引数据库唯一约束创建资源如订单、流水实现简单可靠性极高仅限创建场景数据库压力低状态机乐观锁业务状态校验与原子更新更新资源状态如支付回调精准控制业务流强一致实现复杂需设计状态机中幂等表存储请求处理记录与结果分布式链路通用性强最通用结果可复用架构复杂需维护表性能挑战高7.2 选型决策指南看场景如果是防止用户前端重复点击首选Token令牌。体验好实现快。如果是创建具有唯一业务编码的资源首选唯一索引。让数据库做你最可靠的守门员。如果是异步回调、状态变更首选状态机乐观锁。这是业务逻辑最匹配的方式。如果是复杂的分布式事务、Saga模式中的补偿操作考虑幂等表或全局请求ID模式。看团队与架构团队技术栈是否熟悉分布式锁、Redis现有数据库性能如何能否承受唯一索引的并发冲突业务是否已经有一套链路追踪体系如TraceId可以复用其Request ID。看一致性要求要求强一致不能有任何重复可能唯一索引和幂等表配合数据库事务是更好的选择。可以接受极低概率的重复如缓存原子操作失败Redis Token方案在做好高可用后也能满足。7.3 必须避开的“天坑”只防前端不防后端只在网关或Controller层用Token防重但消息队列的消费者、定时任务、RPC调用之间没有幂等设计。幂等性应该是业务逻辑层的属性需要在最终操作数据的地方保证。把“防重”和“幂等”划等号“防重”是防止重复请求进来“幂等”是保证重复请求进来后结果一致。如果你只是简单地拦截了第二个请求并返回“请勿重复提交”对于创建订单的API用户并不知道第一个请求是否成功体验很差。真正的幂等接口应该告诉用户“你要的订单已经创建好了这是订单信息”。忽略并发场景只考虑串行重复没考虑两个完全相同的请求同时到达。这就是为什么强调要用GETDEL、唯一索引、乐观锁这些原子操作。日志记录不当对于幂等接口日志记录要格外小心。如果每次重复请求都打一条ERROR日志监控系统会被警报淹没。应该区分情况对于已处理成功的重复请求记录为INFO或DEBUG级别即可。过度设计一个简单的内部管理后台的提交接口不一定需要引入复杂的分布式幂等表。评估业务影响和发生概率选择合适的方案避免为了“炫技”而过度设计。API幂等性设计本质上是对系统不确定性的防御性编程。网络会抖动、组件会失败、用户会连点这些都是确定性的事实。一个好的系统不是假设这些不会发生而是当它们发生时系统依然能表现得正确和稳定。从理解业务状态机开始选择合适的武器Token、唯一键、状态机、幂等表在数据操作的最终边界上构建你的幂等防线你的系统就离“稳定可靠”更近了一大步。 API幂等性设计实战：从原理到四种防重复方案详解
1. 从一次重复扣款事故说起为什么我们需要API幂等性那天下午运营同事急匆匆地跑过来说后台连续收到了好几个用户的投诉都是同一个问题明明只下了一单银行卡却被扣了两次甚至三次款。我第一反应是去查支付流水果然同一个订单号支付网关那边竟然返回了三条成功的回调记录。再一看日志那段时间网络有点波动我们的订单服务在调用支付接口后因为超时没收到明确响应触发了重试机制结果支付网关那边其实第一次就处理成功了只是响应包在网络传输中丢了。后续的重试请求到达时支付网关一看是同一个订单号又老老实实地执行了扣款操作。这就是典型的非幂等操作引发的生产事故。所谓幂等性是一个数学和计算机科学里的概念简单来说就是一个操作无论执行一次还是多次只要输入相同产生的结果状态都是完全一致的。对于我们的API特别是修改数据的写操作POST, PUT, DELETE幂等性设计不是“锦上添花”而是保障系统数据一致性、防止业务逻辑混乱的“生命线”。你可能会想GET请求是天然幂等的因为它只是查询不改变状态。问题往往出在那些“写操作”上。想象一下这些场景用户点击“提交订单”按钮因为页面卡顿连点了好几下前端应用在弱网环境下自动重试请求消息队列消费者处理失败消息被重新投递分布式系统调用超时后的补偿重试……如果没有幂等性兜底每一个场景都可能变成一场数据灾难——重复创建订单、重复支付、重复发货、重复发放优惠券。所以今天我们不聊那些高深的理论就从一个一线开发者的视角拆解在实战中如何为你的API穿上这件“防弹衣”。我们会从原理、到常见的实现方案、再到不同业务场景下的选型与避坑手把手让你掌握这套关键时刻能“保命”的设计模式。2. 幂等性的核心状态机与操作分类在动手设计之前我们必须从根上理解为什么有些操作天生容易“重复”以及我们究竟要保护的是什么。2.1 操作的两种类型与幂等诉求我们可以把服务端操作粗暴地分为两类非幂等操作Non-idempotent每次执行都会改变系统状态多次执行会导致累积效应或错误状态。最典型的就是POST /orders创建订单。调用一次生成一个订单调用N次就生成N个订单。这类操作是幂等性设计的重点防护对象。天然幂等操作Idempotent多次执行效果与一次执行相同。这包括GET /orders/{id}查询多少次订单数据都不会变。PUT /orders/{id}更新订单信息。你第一次调用把状态改为“已支付”后续再用相同参数调用订单状态依然是“已支付”不会变成别的。注意这里的前提是PUT用于整体替换资源而非局部更新。如果使用PATCH进行局部更新则需要额外设计幂等性。DELETE /orders/{id}删除一个订单。第一次调用成功删除第二次调用时订单已不存在返回404或200但系统的最终状态订单不存在是一致的。HTTP协议规范对方法的幂等性有建议但实际业务中我们不能完全依赖协议。例如一个POST /transfer的转账接口从业务逻辑上看绝对是非幂等的我们必须通过业务逻辑设计使其具备幂等性。2.2 业务状态机是幂等设计的基石所有幂等性设计的核心都是围绕业务状态机进行的。你需要清晰地定义出你的业务对象如订单、支付单、优惠券一生中会经历哪些状态以及状态之间允许如何转换。以订单为例一个简化的状态机可能是待支付-支付中-已支付-已发货-已完成。同时也可能有已取消等终态。幂等性处理的关键在于当请求试图将一个对象从状态A转移到状态B时系统需要检查当前状态是否允许这次转移。如果当前状态已经是B那么这次操作应该被视为“已经成功过”直接返回成功不做任何实质性变更。这就是幂等。如果当前状态是C比如从已支付试图再转到支付中这通常是一个非法操作应该返回明确的业务错误如“订单状态异常”而不是盲目执行。很多重复问题根源在于服务端没有维护这样一个清晰的状态机或者处理请求时没有进行状态校验只是盲目地执行了更新数据库的SQL语句比如UPDATE order SET status ‘paid’ WHERE id 123这条语句执行多少次结果都一样status都是’paid’但它没有防止从错误状态转移过来的问题。更完善的幂等需要结合状态判断。3. 实战方案一Token令牌机制防重提交这是前端防重复提交最常用、也最直观的方案特别适用于用户交互场景。3.1 流程与原理它的核心思想是每次进入需要防重的页面如表单页时服务端生成一个唯一的令牌Token同时在前端页面如隐藏域和服务器端如Redis进行存储。当用户提交表单时必须将这个Token带回服务端。服务端校验Token是否存在且未被使用如果存在则执行业务逻辑并立即删除或标记该Token为已使用如果不存在则认为是重复提交直接拒绝。具体步骤获取Token客户端调用GET /api/idempotent/token。服务端生成一个全局唯一的字符串如UUID将其作为Value存入RedisKey可以为idempotent:token:{tokenValue}并设置一个合理的过期时间如5分钟。同时将这个Token返回给客户端。携带Token请求客户端在提交业务请求如POST /api/orders时必须在HTTP Header如X-Idempotent-Token或请求体中将这个Token带上。服务端校验服务端拦截器或AOP切面首先检查请求中是否包含Token。无Token可按需处理可直接放行不启用幂等或直接拒绝。建议对明确需要幂等的接口强制要求Token返回错误。有Token尝试以该Token为Key向Redis发起GETDEL命令原子性地获取并删除。如果GETDEL成功获取到值说明是第一次请求放行执行业务。如果GETDEL返回nil说明Token已被使用重复请求直接返回“重复提交”的错误响应。3.2 为什么用GETDEL而不是GETDEL这是关键细节考虑以下时序请求A到来GET到Token存在。在执行业务逻辑前请求B到来也GET到同一个Token存在因为A还没删。两个请求都认为自己合法继续执行业务导致重复。最后两个请求都去DELToken。使用GETDEL或SETNX设置如果不存在这类原子操作可以确保“判断”和“占用”这两个动作是原子的从根本杜绝了并发场景下的重复问题。这是实现幂等性的一个黄金法则状态判断与变更必须是原子的。3.3 适用场景与优缺点优点理解简单实现直观。对前端友好能有效防止用户手抖、网络延迟导致的重复点击。缺点需要额外的接口来获取Token增加了一次网络交互。严格依赖一个中心化的存储如Redis来保证原子性在分布式环境下需要注意Redis本身的高可用。主要防御的是“短时间内的重复提交”对于消息队列重试等长时间跨度场景不太适合Token可能过期。个人踩坑心得Token的过期时间需要仔细权衡。太短用户填写复杂表单可能超时太长又浪费存储空间且可能增加安全风险。通常5-30分钟是个合理的范围。另外务必确保Token的生成有足够的随机性使用安全的随机数生成器防止被猜测。4. 实战方案二唯一索引与插入防重对于创建资源的场景如创建订单、生成流水号利用数据库的唯一索引是最简单、最坚固的幂等保障。它的原理是让数据库这个“最终守门员”来拒绝重复的数据。4.1 基于业务唯一键的设计假设我们有一个orders表业务上允许用户对同一商品再次下单所以我们不能以user_id和product_id做唯一索引。常见的做法是在创建订单前由客户端或服务端生成一个业务唯一键比如叫order_no订单号或out_trade_no商户订单号。这个ID必须是全局唯一的通常可以使用“业务前缀时间戳随机数”或“雪花算法”等分布式ID生成器来创建。然后在orders表上为order_no字段建立唯一索引。处理流程客户端或服务端生成唯一的order_no。执行插入订单的SQLINSERT INTO orders (order_no, user_id, amount, status, ...) VALUES (?, ?, ?, pending, ...)。如果这是第一次请求插入成功。如果是重复请求携带相同的order_no数据库会抛出唯一键冲突异常如Duplicate entry。服务端捕获这个异常然后不是直接返回错误给客户端而是转而查询数据库中已存在的、具有该order_no的订单将其信息返回给客户端。对于客户端而言它得到的结果一个已创建的订单和第一次请求成功的结果是一致的。-- 伪代码示例 try { orderDao.insert(newOrder); // 尝试插入 return success(newOrder); } catch (DuplicateKeyException e) { // 捕获唯一键冲突 Order existingOrder orderDao.selectByOrderNo(newOrder.getOrderNo()); // 这里可以进一步校验比如订单状态、用户是否匹配等防止恶意请求 if (existingOrder ! null existingOrder.getUserId().equals(currentUserId)) { return success(existingOrder); // 返回已存在的订单 } else { throw new BusinessException(订单创建冲突请稍后重试); } }4.2 适用场景与优缺点优点实现简单依赖数据库本身的能力可靠性极高。没有额外的中间件依赖如Redis。能防御任何情况下的重复插入包括并发请求。缺点仅适用于“创建”场景对于更新操作无效。将压力转移到了数据库高频插入场景下唯一索引冲突可能成为性能瓶颈。需要在业务逻辑里妥善处理数据库异常并将其转化为对客户端友好的幂等响应。个人踩坑心得千万不要在捕获到DuplicateKeyException后只是简单地返回一个“重复提交”的错误。对于创建订单这样的场景客户端更关心的是“我的订单到底创建成功没有订单号是什么”。所以查询并返回已存在的资源是幂等接口设计的标准做法。这要求你的API响应格式在“首次成功”和“重复请求”时保持一致。5. 实战方案三状态机与乐观锁对于更新操作如支付回调、状态变更单纯防重插入就不够了。我们需要结合前面提到的业务状态机和乐观锁机制。5.1 支付回调的幂等设计案例这是最经典的场景。支付网关会异步回调我们的服务端接口POST /api/payment/callback通知我们订单支付结果。由于网络问题支付网关可能会多次发送相同的回调。我们的接口必须幂等。表结构设计参考CREATE TABLE payment_order ( id bigint PRIMARY KEY, order_no varchar(64) NOT NULL COMMENT 业务订单号, out_trade_no varchar(64) NOT NULL COMMENT 支付网关订单号, amount int NOT NULL COMMENT 金额分, status tinyint NOT NULL COMMENT 状态0-待支付1-支付成功2-支付失败3-已关闭, version int NOT NULL DEFAULT 0 COMMENT 数据版本号用于乐观锁, callback_info json COMMENT 支付回调信息, UNIQUE KEY uk_order_no (order_no), UNIQUE KEY uk_out_trade_no (out_trade_no) );幂等处理流程参数校验与业务键提取从回调参数中解析出唯一标识本次支付的业务键通常是out_trade_no支付网关订单号或我们传给网关的order_no。查询当前状态根据业务键查询支付单payment_order。状态判断幂等的核心场景A记录不存在。这可能是非法回调或者订单数据尚未同步。应记录告警并返回失败让支付网关稍后重试或根据业务逻辑决定是否创建。场景B记录存在且状态为“支付成功”。说明之前已经处理成功了。直接返回成功的响应如SUCCESS即可无需任何更新操作。场景C记录存在且状态为“待支付”。这是正常流程继续下一步。场景D记录存在且状态为“支付失败”或“已关闭”。说明订单已终态但收到了成功回调。这可能是严重异常需要记录错误日志并人工介入核查接口应返回失败。乐观锁更新对于场景C我们执行更新操作。但为了防御极端的并发情况比如两个回调请求同时到达都通过了步骤3的状态判断我们需要使用乐观锁。UPDATE payment_order SET status 1, version version 1, callback_info ‘{...}’ WHERE out_trade_no ‘xxx’ AND status 0 AND version #{currentVersion};这条SQL的妙处在于它将状态判断和更新合并成了一个原子操作。WHERE条件中status 0确保了只有“待支付”的订单才能被更新为“支付成功”。version #{currentVersion}确保了更新的是我们刚才查询出来的那个版本的数据。检查更新结果执行SQL后检查数据库返回的“受影响行数”affected rows。如果affected_rows 1说明更新成功是第一个处理该回调的请求。接下来可以执行业务后续逻辑如更新订单状态、发放权益等。如果affected_rows 0说明更新失败。原因可能是1) 其他请求已抢先更新版本号变了2) 订单状态已不是“待支付”。此时应该重新查询一次订单的最新状态然后回到步骤3进行状态判断。这通常意味着其他请求已处理成功当前请求按“重复请求”处理直接返回成功。5.2 适用场景与优缺点优点能完美处理更新操作的幂等性特别是状态流转场景。结合数据库事务能保证数据强一致性。乐观锁相比悲观锁SELECT … FOR UPDATE性能更好在高并发场景下更优。缺点实现复杂度较高需要精心设计状态机和更新逻辑。需要数据库支持行级锁和返回受影响行数。在超高并发下乐观锁更新失败率会增高可能导致大量请求需要重试或回查。个人踩坑心得支付回调接口的响应内容非常重要。很多支付网关会根据你的响应内容如字符串SUCCESS来判断是否通知成功。即使你是幂等处理重复请求直接返回成功也必须返回与第一次成功时完全相同的成功响应否则支付网关可能认为通知失败而持续重试。另外整个回调处理逻辑务必保持幂等包括后续的更新订单、发短信、发优惠券等操作否则还是可能造成数据不一致。6. 实战方案四分布式锁与全局唯一请求ID在分布式系统、特别是微服务架构下一个业务流可能涉及多个服务间的多次调用。单纯每个接口幂等还不够我们需要保证整个业务链路的幂等。这时“全局唯一请求ID”配合“分布式锁”或“幂等表”是一种更高级的模式。6.1 全局唯一请求IDRequest ID其核心思想是在业务请求发起的最源头如网关、前端生成一个全局唯一的request_id这个ID伴随着这个业务请求的整个生命周期穿透所有服务调用。每个服务在处理请求时都依据这个request_id来判断是否已经处理过。生成与传递生成可以使用UUID、雪花算法等。通常在API网关层生成并注入到HTTP Header中如X-Request-Id。传递在服务内部调用时通过RPC、HTTP Client等必须显式地将这个request_id传递给下游服务。这是实现链路追踪和幂等的关键。6.2 基于“幂等表”的实现这是处理分布式幂等非常稳健的一种方式。我们单独建立一张表来记录已经处理过的请求。CREATE TABLE idempotent_record ( id bigint PRIMARY KEY AUTO_INCREMENT, request_id varchar(128) NOT NULL COMMENT 全局请求ID, business_key varchar(128) NOT NULL COMMENT 业务唯一键可与request_id相同或不同, service_name varchar(64) NOT NULL COMMENT 服务名, method_name varchar(64) NOT NULL COMMENT 方法名, status tinyint NOT NULL COMMENT 处理状态0-处理中1-成功2-失败, result text COMMENT 处理结果快照JSON格式, created_at datetime NOT NULL, updated_at datetime NOT NULL, UNIQUE KEY uk_request (request_id, service_name, method_name), KEY idx_business (business_key) );处理流程请求到达服务A的某个接口。服务A从Header中获取request_id结合自身服务名和方法名构成一个唯一标识。在数据库事务中执行插入操作INSERT INTO idempotent_record (request_id, service_name, method_name, status, ...) VALUES (?, ?, ?, 0, ...)。这里利用了数据库的唯一索引来保证并发下的原子性。插入成功说明是第一次请求。执行业务逻辑业务成功后在同一个事务内更新该记录状态为1成功并可将关键结果存入result字段。提交事务。插入失败唯一键冲突说明该请求已被处理过。此时查询表中该request_id对应的记录。如果记录状态为1成功则直接从result字段中反序列化出上次的处理结果直接返回给客户端。如果记录状态为0处理中这可能意味着上一个请求正在处理发生了并发。此时可以稍等片刻如sleep几十毫秒后重查或者直接返回一个“处理中请稍后查询”的响应。这需要根据业务容忍度设计。如果记录状态为2失败则可以根据业务决定是返回之前的失败结果还是允许重试此时可以删除旧记录重新插入但要谨慎。6.3 适用场景与优缺点优点通用性强几乎适用于所有需要幂等的场景特别是分布式链路。通过存储结果可以真正做到无论调用多少次返回完全相同的结果。便于排查问题可以通过request_id追溯整个请求的处理历史。缺点架构复杂度最高需要引入额外的“幂等表”增加了数据库压力。对数据库性能有要求request_id的唯一索引可能成为热点。需要谨慎处理“处理中”状态防止客户端长时间等待。个人踩坑心得幂等表的设计中result字段存储结果快照非常有用但不要存储过大的对象。建议只存储核心的、用于构建响应体的数据。另外这张表的数据需要定期清理如按时间归档或删除否则会无限膨胀。可以考虑按created_at分区或者将已完成的记录转移到历史表。对于超高并发场景插入幂等表的操作本身可能成为瓶颈此时可以考虑使用更快的存储如Redis来实现第一步的“抢占”但最终一致性还是需要数据库来保证架构会变得更复杂。7. 方案选型与架构思考面对这么多方案在实际项目中该如何选择没有银弹只有最适合你当前场景的权衡。7.1 方案对比速查表方案核心原理适用场景优点缺点技术复杂度Token令牌一次性令牌用后即焚前端防重复提交用户交互场景简单直观前端友好需额外接口依赖Redis适合短时间低唯一索引数据库唯一约束创建资源如订单、流水实现简单可靠性极高仅限创建场景数据库压力低状态机乐观锁业务状态校验与原子更新更新资源状态如支付回调精准控制业务流强一致实现复杂需设计状态机中幂等表存储请求处理记录与结果分布式链路通用性强最通用结果可复用架构复杂需维护表性能挑战高7.2 选型决策指南看场景如果是防止用户前端重复点击首选Token令牌。体验好实现快。如果是创建具有唯一业务编码的资源首选唯一索引。让数据库做你最可靠的守门员。如果是异步回调、状态变更首选状态机乐观锁。这是业务逻辑最匹配的方式。如果是复杂的分布式事务、Saga模式中的补偿操作考虑幂等表或全局请求ID模式。看团队与架构团队技术栈是否熟悉分布式锁、Redis现有数据库性能如何能否承受唯一索引的并发冲突业务是否已经有一套链路追踪体系如TraceId可以复用其Request ID。看一致性要求要求强一致不能有任何重复可能唯一索引和幂等表配合数据库事务是更好的选择。可以接受极低概率的重复如缓存原子操作失败Redis Token方案在做好高可用后也能满足。7.3 必须避开的“天坑”只防前端不防后端只在网关或Controller层用Token防重但消息队列的消费者、定时任务、RPC调用之间没有幂等设计。幂等性应该是业务逻辑层的属性需要在最终操作数据的地方保证。把“防重”和“幂等”划等号“防重”是防止重复请求进来“幂等”是保证重复请求进来后结果一致。如果你只是简单地拦截了第二个请求并返回“请勿重复提交”对于创建订单的API用户并不知道第一个请求是否成功体验很差。真正的幂等接口应该告诉用户“你要的订单已经创建好了这是订单信息”。忽略并发场景只考虑串行重复没考虑两个完全相同的请求同时到达。这就是为什么强调要用GETDEL、唯一索引、乐观锁这些原子操作。日志记录不当对于幂等接口日志记录要格外小心。如果每次重复请求都打一条ERROR日志监控系统会被警报淹没。应该区分情况对于已处理成功的重复请求记录为INFO或DEBUG级别即可。过度设计一个简单的内部管理后台的提交接口不一定需要引入复杂的分布式幂等表。评估业务影响和发生概率选择合适的方案避免为了“炫技”而过度设计。API幂等性设计本质上是对系统不确定性的防御性编程。网络会抖动、组件会失败、用户会连点这些都是确定性的事实。一个好的系统不是假设这些不会发生而是当它们发生时系统依然能表现得正确和稳定。从理解业务状态机开始选择合适的武器Token、唯一键、状态机、幂等表在数据操作的最终边界上构建你的幂等防线你的系统就离“稳定可靠”更近了一大步。