知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 49 - 如何设计幂等接口 > 导读:用户在 App 上点了"提交订单",网络卡住没反应,又点了一次;或者前端做了超时重试——后端就收到了两个一模一样的请求,创建出两张订单。读完本文你能说清幂等的准确定义、POST 为什么天生不幂等、Token / 唯一索引 / 状态机 / 去重表 / AOP 注解五种方案各自怎么落地、以及该按什么标准选型。适合正在做交易类接口或有相关面试准备的 Java 后端工程师。 ## 一、先建立全局认知 ### Q:为什么"提交订单"会被执行两次? A:用户在 App 上点击"提交订单"按钮,由于网络慢没有响应,用户又点了一次。或者前端做了超时重试。结果后端收到两个一模一样的请求: ``` 请求 1:POST /api/order {userId: 10086, productId: 2001, quantity: 1} → 创建订单 A 请求 2:POST /api/order {userId: 10086, productId: 2001, quantity: 1} → 又创建订单 B ← 重复了! 幂等的定义:同一个操作执行一次和执行多次,效果相同 - GET 天然幂等(查询) - DELETE 天然幂等(删除同一条数据多次效果一样) - PUT 天然幂等(更新为固定值) - POST 不幂等(每次创建新资源)← 需要特殊处理 ``` 术语先对齐:**幂等(Idempotent)**在 HTTP 语境下指"同一个请求执行一次和执行 N 次,服务端最终状态完全相同"。注意它说的是**状态相同**,不是"返回值相同"——第二次调用完全可以返回第一次的结果。 这里的关键认知是:**重复请求是客户端行为不可控的必然结果**。用户会手抖连点、前端会超时重试、网关会失败重发。服务端无法阻止请求到达两次,只能保证"到两次也不出问题"。 ### Q:哪些 HTTP 方法天然幂等,哪些不幂等?为什么? A:GET、DELETE、PUT 天然幂等,POST 不幂等——根因在于它们对"资源"的语义不同。 - **GET 天然幂等**:只做查询,不改变服务端状态。 - **DELETE 天然幂等**:删除同一条数据多次,结果都是"这条数据不存在"。第二次删除虽然返回 404,但状态一致。 - **PUT 天然幂等**:PUT 的语义是"把资源整体替换为这个固定值",执行多次结果相同。 - **POST 不幂等**:POST 的语义是"新建一个资源",每次执行都会产生新资源,这是它的设计本意。 所以幂等设计的"重灾区"正是 POST 类接口——创建订单、发起支付、提交表单。这也解释了为什么后面所有方案都服务于同一类目标:**给"语义上不幂等"的 POST 操作加上幂等保护**。 ## 二、理解核心机制 ### Q:Token 机制怎么设计?为什么校验要用 Lua 脚本? A:流程是"下单页先领 Token,提交时带上,服务端校验并一次性消费"。用 Lua 是为了让"校验存在"和"删除 Token"这两步原子完成。 ```java // 流程: // 1. 进入下单页面 → 前端请求后端获取 Token // 2. 提交订单 → 前端带上 Token // 3. 后端校验 Token(存在则删除并执行,不存在则拒绝) @RestController public class TokenController { @GetMapping("/api/token") public Result<String> getToken() { String token = UUID.randomUUID().toString(); redis.opsForValue().set("idempotent:" + token, "1", 15, TimeUnit.MINUTES); return Result.ok(token); } } @RestController public class OrderController { @PostMapping("/api/order") public Result<Order> createOrder(@RequestHeader("X-Idempotent-Token") String token, @RequestBody OrderDTO dto) { // Lua 脚本:校验 + 删除原子操作 String script = "if redis.call('GET', KEYS[1]) == ARGV[1] then " + "return redis.call('DEL', KEYS[1]) else return 0 end"; Long result = redis.execute(new DefaultRedisScript<>(script, Long.class), List.of("idempotent:" + token), "1"); if (result == 0) { return Result.fail("请勿重复提交"); } // Token 校验通过,执行业务 Order order = orderService.createOrder(dto); return Result.ok(order); } } ``` 关键点与适用场景: - **Token 是一次性的**:校验通过的同时删除,所以同一个 Token 只能成功提交一次,第二次必然被拒。这个特性决定了它最适合"表单提交"这类**用户主动触发的一次性操作**。 - **为什么必须原子**:如果先 `GET` 判断、再 `DEL` 删除,两个并发请求可能同时判断成功、都去删、都执行——等于没防住。Redis 执行 Lua 脚本是单线程原子的,这段"判断 + 删除"不会被并发穿插。 - **Token 有 TTL**(示例 15 分钟),过期后自动失效,避免未使用完的 Token 无限堆积。 - 代价是**多一次交互**:前端必须先领 Token 再提交,接入成本比纯服务端方案高。 ### Q:唯一索引方案怎么做?重复时应该返回什么? A:在表上加唯一索引,让数据库兜底,捕获 `DuplicateKeyException` 后返回已存在的订单。 ```sql -- 订单表加唯一索引 CREATE TABLE orders ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_no VARCHAR(32) UNIQUE NOT NULL, -- 订单号唯一 biz_key VARCHAR(64) UNIQUE, -- 业务去重键(如 userId+productId+日期) ... ); ``` ```java @Service public class OrderService { public Order createOrder(OrderDTO dto) { String bizKey = dto.getUserId() + ":" + dto.getProductId() + ":" + LocalDate.now(); Order order = buildOrder(dto); order.setBizKey(bizKey); try { orderMapper.insert(order); return order; } catch (DuplicateKeyException e) { // 重复请求,返回已有订单 return orderMapper.selectByBizKey(bizKey); } } } ``` 关键点与适用场景: - 这套方案把幂等责任**下沉到数据库**:不需要额外中间件,只要索引建对,就天然成立,是最"稳"的方案。 - **重复时返回已有订单而不是报错**,这是个重要的产品级取舍:对用户而言"点击重试后看到订单创建成功"才是正确体验;如果返回"重复提交"错误,用户会以为没下单成功而继续尝试。 - 它的前提是**能设计出合适的业务唯一键**(`bizKey`)。示例用 `userId + productId + 日期` 表示"同一用户同一天对同一商品的购买动作只算一次",这个规则必须由业务方拍板,键选错会导致误判或漏判。 - 局限:如果业务确实允许"同一用户同一天多次购买同一商品",这个 bizKey 就不能用,需要引入更细的维度(如客户端生成的请求 ID)。 ### Q:状态机幂等怎么用? A:适用于有状态流转的业务(订单状态变更、支付回调等),用 `WHERE status=原状态` 做条件更新,靠影响行数判断是否首次。 ```java // 适用于有状态流转的业务(订单状态变更、支付回调等) @Service public class PayCallbackService { @Transactional public void onPaySuccess(Long orderId) { // UPDATE orders SET status='PAID', pay_time=NOW() // WHERE order_id=#{orderId} AND status='CREATED' int rows = orderMapper.updateStatus(orderId, "CREATED", "PAID"); if (rows == 0) { // 状态已变更(重复回调),直接返回 log.info("订单已支付,忽略重复回调: orderId={}", orderId); return; } // 首次回调,执行后续逻辑 inventoryService.deductStock(orderId); pointService.addPoints(orderId); } } ``` 关键点与适用场景: - 本质是把"幂等判断"塞进 SQL 的 `WHERE` 条件里——数据库保证单行的更新是原子的,因此不会出现"两个请求都认为自己是第一次"的竞态。 - `rows == 0` 意味着状态已经不是 `CREATED`,说明这次回调是重复的,直接返回即可。 - **注意后续逻辑必须放在 `rows > 0` 的分支里**:扣库存、加积分这些副作用只能在首次成功时执行一次。这是最容易被写错的地方。 - 局限同前面提到的状态机方案:只能用于状态单向流转的业务,无法覆盖"无前置状态"的操作。 ### Q:去重表方案怎么封装成通用能力? A:建一张独立的去重表,把"插入判重 → 执行 → 保存结果"封装成一个通用方法,任何接口都能复用。 ```java // 通用方案:独立的去重表,适用于任何接口 @Service public class IdempotentService { // CREATE TABLE idempotent_record ( // biz_type VARCHAR(32) NOT NULL, // biz_id VARCHAR(128) NOT NULL, // result TEXT, // create_time DATETIME DEFAULT NOW(), // PRIMARY KEY (biz_type, biz_id) // ); @Transactional public <T> T execute(String bizType, String bizId, Supplier<T> action) { // 1. 尝试插入去重记录 try { idempotentMapper.insert(new IdempotentRecord(bizType, bizId)); } catch (DuplicateKeyException e) { // 重复请求,返回之前的结果 IdempotentRecord record = idempotentMapper.select(bizType, bizId); return JSON.parseObject(record.getResult(), (Type) Object.class); } // 2. 首次请求,执行业务逻辑 T result = action.get(); // 3. 保存执行结果 idempotentMapper.updateResult(bizType, bizId, JSON.toJSONString(result)); return result; } } // 使用示例 @PostMapping("/api/order") public Result<Order> createOrder(@RequestBody OrderDTO dto) { String bizId = dto.getUserId() + ":" + dto.getProductId() + ":" + LocalDate.now(); Order order = idempotentService.execute("CREATE_ORDER", bizId, () -> orderService.createOrder(dto)); return Result.ok(order); } ``` 关键点与适用场景: - 主键设计是 `(biz_type, biz_id)` 复合主键,用 `biz_type` 区分不同业务,使一张表能服务多个接口。 - 它比唯一索引方案多了一个能力:**把第一次的执行结果存下来**,重复请求直接返回同一份结果。这是"幂等"最完整的形态——不仅状态一致,返回值也一致。 - `@Transactional` 保证"插入去重记录 + 执行 action + 保存结果"是一个整体;任一步失败都会回滚,重复请求仍可重试。 - 局限:`result` 用 JSON 序列化存储,要求返回值可序列化,且大对象会占空间。 ### Q:注解 + AOP 怎么把幂等变成"无侵入"? A:自定义一个 `@Idempotent` 注解,用 AOP 切面在方法执行前用 Redis `SETNX` 抢锁,业务代码几乎零改动。 ```java // 自定义幂等注解 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Idempotent { String key() default ""; // SpEL 表达式提取幂等键 long timeout() default 300; // 幂等窗口(秒) String message() default "请勿重复提交"; } // AOP 切面 @Aspect @Component public class IdempotentAspect { @Around("@annotation(idempotent)") public Object around(ProceedingJoinPoint point, Idempotent idempotent) throws Throwable { // 解析 SpEL 表达式获取幂等键 String key = parseKey(idempotent.key(), point); String redisKey = "idempotent:" + key; // SETNX 加锁 Boolean success = redis.opsForValue() .setIfAbsent(redisKey, "1", idempotent.timeout(), TimeUnit.SECONDS); if (Boolean.FALSE.equals(success)) { throw new BizException(idempotent.message()); } try { return point.proceed(); } catch (Exception e) { // 业务异常,删除幂等标记,允许重试 redis.delete(redisKey); throw e; } } } // 使用 @Idempotent(key = "#dto.userId + ':' + #dto.productId", timeout = 60) @PostMapping("/api/order") public Result<Order> createOrder(@RequestBody OrderDTO dto) { return Result.ok(orderService.createOrder(dto)); } ``` 关键点与适用场景: - **SpEL 表达式**让幂等键可以从方法参数动态生成(如 `#dto.userId + ':' + #dto.productId`),一个切面就能服务各种接口。 - **业务异常时删除标记**是必须的:否则业务失败后,用户在幂等窗口内重试会被一直拦住,形成"假死"。 - 它与 Token 机制的差别在于:Token 由客户端携带、一次性消费;AOP 注解的幂等键由服务端自行计算、在 `timeout` 窗口内生效。前者适合表单,后者适合"同一参数短时间内的重复调用"。 - 局限:依赖 Redis,且窗口时间内相同参数的合法重复请求(比如用户确实想买两次)会被误拦,`timeout` 取值要结合业务节奏。 ### Q:五种方案应该怎么选? A:先判断业务有没有状态、能不能给出唯一键,再决定要"轻"还是要"全"。 | 方案 | 优点 | 缺点 | 适用场景 | |------|------|------|---------| | Token 机制 | 通用,前后端配合 | 需要两次请求(获取+使用) | 表单提交 | | 唯一索引 | 简单可靠 | 需要有合适的业务唯一键 | 创建类接口 | | 状态机 | 最优雅,无额外存储 | 仅适用于状态流转业务 | 状态变更类接口 | | 去重表 | 通用,可保存结果 | 多一张表 | 通用方案 | | AOP 注解 | 优雅,非侵入 | 依赖 Redis | 快速接入 |  [编辑 Excalidraw 源图](/images/java-interview-copy/business-scenario/49-design-idempotent-api-design-idempotent-api-patterns-diagram.excalidraw) 选型的思考顺序: 1. 业务有状态流转(订单、支付)→ 直接上状态机幂等,零成本。 2. 创建类接口且有天然唯一键 → 唯一索引,把责任交给数据库。 3. 需要返回与首次一致的结果 → 去重表。 4. 表单提交、需要前端配合 → Token 机制。 5. 接口多、想快速铺开 → AOP 注解。 实际项目里这些方案常常**分层叠加**:前端 Token 拦用户手抖,服务端唯一索引兜底并发,状态机保证业务正确。多一道防线不冲突,成本也各不相同。 ## 三、放进真实场景 ### Q:幂等和防重复提交有什么区别? A:防重复提交是幂等的一个子场景。幂等更广泛:包括网络重试、MQ 重复消费、定时任务重复执行等。防重复提交主要针对用户操作层面。 从设计角度补充一句:**防重复提交关注"拦截"**(把重复请求挡在门外,如 Token 机制),**幂等关注"结果一致"**(允许请求进来,但保证状态不变)。前者是手段,后者是目标。工程上通常两者都要有——前端拦截减少无效流量,服务端幂等保证最终正确。 ### Q:分布式环境下 Token 机制的 Token 存在哪里? A:存 Redis。因为多个服务实例都需要能校验同一个 Token,本地缓存不行。Redis 的 SETNX + TTL 天然适合这个场景。 延伸一下:如果 Token 存本地缓存,用户第一次请求打到实例 A、重试时被负载均衡打到实例 B,B 上查不到这个 Token,要么误判为非法、要么放行造成重复。所以"多实例共享"是选型的硬约束,Redis 提供了共享存储 + 原子操作 + 自动过期的三合一能力。 ### Q:落地幂等接口时有哪些生产经验? A:按"症状 → 原因 → 解决方案"整理四类高频问题: 1. **症状**:加了幂等,压测时仍出现重复单据。**原因**:幂等键粒度太粗。**解决方案**:检查唯一键维度,必要时引入客户端生成的 requestId 提高精度。 2. **症状**:Token 机制挡不住重复。**原因**:先查后删分两步执行,并发下两个请求都通过了校验。**解决方案**:用 Lua 脚本把校验与删除合并为一个原子操作。 3. **症状**:业务报错后,用户重试一直被提示"请勿重复提交"。**原因**:AOP 方案里业务异常没有清除幂等标记。**解决方案**:在 `catch` 分支删除 Redis 标记后再抛出异常。 4. **症状**:状态机幂等生效了,但库存被扣了两次。**原因**:副作用逻辑放在了 `rows` 判断之外。**解决方案**:把扣库存、加积分等副作用严格限制在 `rows > 0` 分支内。 统一规律:**幂等的坑几乎都出在"原子性"和"副作用边界"上——判断要原子、副作用要一次。** ## 四、总结与自测 ### Q:面试里怎么答这道题? A:先给定义,再列方案,最后讲选型逻辑: 1. Token 机制:进入页面获取 Token,提交时 Lua 脚本原子校验删除,适合表单提交场景。 2. 唯一索引:数据库层面保证,利用 `DuplicateKeyException` 判断重复,简单可靠。 3. 状态机:`WHERE status=原状态` 乐观锁,天然幂等,适合状态流转业务。 4. 通用方案:AOP + Redis SETNX 注解化,非侵入式,快速为任何接口添加幂等能力。 收尾点出取舍:方案没有优劣之分,**有状态用状态机、有唯一键用唯一索引、要通用用去重表或 AOP**,实际项目往往是多道防线叠加。 ### Q:设计幂等接口时,最需要想清楚的两个问题是什么? A:一是"**用什么做幂等键**",二是"**失败后能不能重试**"。 - 幂等键决定了去重精度:粒度太粗会误拦合法请求,太细(比如带时间戳)则等于没做。它必须由业务方明确"什么是同一个操作"。 - 失败可重试决定了幂等标记的生命周期:如果业务失败后不清除标记或记录状态,重试就会被误判为重复而永久失败。所以去重记录不能只有"存在/不存在"两态,通常还需要"处理中/成功/失败"来支持重试。 --- ## 自测 1. 幂等的准确含义是什么?为什么说它指的是"状态相同"而不是"返回值相同"? 2. GET、DELETE、PUT 为什么天然幂等,而 POST 不幂等?幂等设计的重点为什么落在 POST 上? 3. Token 机制为什么必须用 Lua 脚本做"校验 + 删除"?不用原子操作会出什么问题? 4. 唯一索引方案在捕获 `DuplicateKeyException` 后,为什么要返回已有订单而不是直接报错? 5. 状态机幂等方案中,扣库存、加积分这类副作用应该放在哪里?放错会有什么后果?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入