接口幂等怎么做?Java后端4层防重复提交
摘要:用户连点、网关重试、MQ 重投,都能让同一笔订单落两次库。这篇讲透接口幂等的四层防线:Redis 预检挡并发、数据库唯一索引兜底、状态机更新防重复流转、MQ 消费端去重。全程 Spring Boot 完整代码,复制能跑。
用户手抖点了两下提交,订单列表里躺着两笔一模一样的单。你在前端加了按钮置灰,第二天客服又找上门——App 弱网重试、网关超时重发、MQ 重投,全都能绕过置灰。
接口幂等解决的就是这件事:同一个请求来一次和来十次,数据库里的结果必须一样。这篇文章用一个下单场景,把 Redis 预检、数据库唯一索引、状态机更新、MQ 消费去重这四层防线写成能直接跑的代码,再说清楚每一层会在什么情况下漏。
一、接口幂等到底是什么,为什么按钮置灰挡不住
接口幂等的定义只有一句话:同一个业务请求,执行一次和执行 N 次,对系统状态的改变完全相同。
关键词是“系统状态”。返回值一样不算幂等,没多写一行数据才算。比如扣库存接口,第一次扣 1 件返回成功,第二次返回“库存不足”,两次返回值不同,但库存只被扣了一次——这依然是幂等的。反过来,两次都返回成功、库存扣了 2 件,返回值一致却完全不幂等。
重复请求不会只从“用户点两下”这一个口子进来。真实线上至少有六条路:
| 重复来源 | 典型场景 | 两次请求体一样吗 |
|---|---|---|
| 用户重复点击 | 手抖、页面卡住连点 | 一样 |
| 客户端超时重试 | App 弱网,3 秒没响应自动重发 | 一样 |
| 网关重试 | Nginx、Spring Cloud Gateway 配了 retry | 一样 |
| RPC 框架重试 | OpenFeign、Dubbo 超时重发 | 一样 |
| 消息重投 | Kafka 重平衡、RocketMQ 消费失败重试 | 一样 |
| 定时任务重跑 | 补数据、人工触发两次 | 一样 |
看第三列。所有这些重复请求,请求体是一模一样的,服务端没有任何天然线索能区分“这是新请求”还是“上一笔的重发”。前端置灰只能挡住第一行,后面五行它一个都管不了。更何况用户换个手机、清个缓存,置灰直接失效。
下面三种写法,是线上最常见的“以为做了幂等”:
第一种,先查后插。 下单前先 select 一下订单存不存在,不存在再 insert。单线程跑没问题,两个请求同时到达就完了——两个线程都查到“不存在”,然后都插进去了。
第二种,只加 Redis 锁,不加数据库约束。 Redis 主从切换的那几秒,锁数据可能还没同步过去,新请求拿到锁,照样重复插入。
第三种,只在业务代码里做判断。 比如“如果订单状态是已支付就直接返回”。这个思路是对的,但它只能防住有明确状态流转的业务,防不住“新增”这种没有前置状态的操作。
顺便把三个容易混的概念分开:
- 幂等是目标:重复执行不出错。
- 去重是手段之一:记录处理过的请求。
- 分布式锁是另一回事:它保证同一时刻只有一个线程在跑,跑完锁就释放,下一个请求照样能进来。锁管“同时”,幂等管“曾经”。
二、底层原理:原子占位 + 唯一约束 + 状态判断
幂等能成立,靠的是三个东西凑齐:一个唯一的标识、一次原子的占位、一个不可回退的状态判断。缺一个就会漏。
2.1 唯一标识:幂等键从哪来
幂等键(idempotency key)是这次业务操作的身份证。同一个业务动作,重发多少次,键都一样。
设计幂等键有三条硬规矩:
- 由客户端生成,一次业务动作生成一个 UUID,放在请求头里。服务端生成没用——服务端每次收到请求都会生成新的,等于没做。
- 不能拼业务字段。有人用
userId + skuId当键,用户想买第二件同款就被挡住了。业务字段会变,幂等键不能变。 - 不能带时间戳、随机数、traceId。这三个东西每次请求都不一样,拼进去等于每次都换新键。
标准做法是请求头 X-Idempotency-Key: 8f3c...,客户端在用户点提交的那一刻生成,重试时复用同一个值。Stripe 的支付接口就是这么设计的。
2.2 原子占位:为什么 SET NX EX 能挡住并发
Redis 的 SET key value NX EX seconds 是一条命令完成“判断存在 + 写入 + 设过期”,所以它是原子的。
拆开写就会出问题。先 GET 判断,再 SET,两步之间别的线程能插进来,两个线程都判断“不存在”,都写成功。Redis 单线程串行执行命令,把判断和写入压进同一条命令,中间没有缝。
NX 的意思是“key 不存在才写”,EX 是过期时间。用官方命令参考里的写法就是:
SET idem:order:create:8f3c... 7d1e... NX EX 600
返回 OK 说明抢到了,返回 nil 说明有人已经占了位。
2.3 value 为什么要放一个随机 token
value 里放随机 token,是为了删除时只删自己的锁。
想象这个时序:请求 A 抢到锁,业务卡了 700 秒,锁在 600 秒时自动过期;请求 B 进来抢到锁开始跑;这时 A 终于跑完,执行 DEL 把 B 的锁删了;请求 C 立刻又抢到锁——同一时刻 B 和 C 在跑,幂等失效。
正确做法是删除前先比对 value:
if redis.call('get', KEYS[1]) == ARGV[1] then
return redis.call('del', KEYS[1])
else
return 0
end
比对和删除必须在 Redis 里一次做完,所以要用 Lua 脚本。放 Java 里先 get 再 del,中间又有窗口。
2.4 过期时间怎么定,失败要不要删 key
幂等键的 TTL 要大于“业务最长执行时间 + 客户端重试窗口”,成功了不删,失败了必须删。
不删成功记录的 key,是因为重复请求还得靠它挡。TTL 到了自然消失,用户过十分钟再点就是一笔新业务,这符合直觉。
失败必须删,是因为业务没成功,用户有权重试。如果业务抛异常了 key 还留着,用户在这 600 秒里怎么点都被拒绝,体验极差——这是新手最容易踩的坑。
2.5 三层防线各自管什么
| 防线 | 位置 | 挡住什么 | 漏在哪 |
|---|---|---|---|
| Redis 预检 | 请求入口 | 并发重复、短时间连点 | Redis 故障、主从切换丢锁 |
| 数据库唯一索引 | 存储层 | 所有并发重复(强一致) | 挡不住,但会抛异常,要处理 |
| 状态机更新 | 业务层 | 重复流转(重复支付、重复发货) | 只适用有状态流转的业务 |
三层不是三选一,是叠加。Redis 挡掉 99% 的重复,少打一次数据库;唯一索引兜住剩下的和 Redis 挂掉时的;状态机保证“重复请求不会推动业务往前走第二步”。
三、实战:一套能跑的下单幂等
下面是一个完整工程,Spring Boot + MySQL + Redis,复制到本地配好数据库和 Redis 就能启动。目录结构如下,schema.sql 放在 resources 根目录下,启动时会被自动执行:
idempotent-demo
├── pom.xml
└── src/main
├── java/com/example/idempotent
│ ├── IdempotentApplication.java
│ ├── config/WebMvcConfig.java
│ ├── idempotent/Idempotent.java
│ ├── idempotent/IdempotentGuard.java
│ ├── idempotent/IdempotentInterceptor.java
│ ├── mq/OrderPaidConsumer.java
│ ├── repository/OrderRepository.java
│ ├── service/OrderNoGenerator.java
│ ├── service/OrderService.java
│ └── web
│ ├── ApiResponse.java
│ ├── GlobalExceptionHandler.java
│ ├── OrderController.java
│ ├── OrderRequest.java
│ └── OrderView.java
└── resources
├── application.yml
└── schema.sql
3.1 pom.xml
用的是 Spring Boot 4 的模块化 starter,spring-boot-starter-webmvc 是新的 Web 起点,老的 spring-boot-starter-web 已经标记为不推荐。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>idempotent-demo</artifactId>
<version>1.0.0</version>
<name>idempotent-demo</name>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<version>26.10.0</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.2</version>
</plugin>
</plugins>
</build>
</project>
3.2 application.yml
server:
port: 8080
spring:
application:
name: idempotent-demo
datasource:
url: jdbc:mysql://127.0.0.1:3306/idem_demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
username: root
password: root123
driver-class-name: com.mysql.cj.jdbc.Driver
hikari:
maximum-pool-size: 20
minimum-idle: 5
connection-timeout: 3000
sql:
init:
mode: always
schema-locations: classpath:schema.sql
data:
redis:
host: 127.0.0.1
port: 6379
timeout: 2s
logging:
level:
com.example.idempotent: debug
spring.sql.init 会在启动时执行建表脚本,省得你手动跑 SQL。表用 IF NOT EXISTS,重复启动不会报错。
3.3 建表脚本 schema.sql
关键在 uk_idem_key 这个唯一索引上——它是最后一道防线,Redis 全挂了也靠它。
CREATE TABLE IF NOT EXISTS `t_order` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`order_no` VARCHAR(40) NOT NULL,
`idempotency_key` VARCHAR(128) NOT NULL,
`user_id` VARCHAR(64) NOT NULL,
`sku_id` VARCHAR(64) NOT NULL,
`quantity` INT NOT NULL,
`amount` DECIMAL(12,2) NOT NULL,
`status` VARCHAR(16) NOT NULL DEFAULT 'PENDING',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_order_no` (`order_no`),
UNIQUE KEY `uk_idem_key` (`idempotency_key`),
KEY `idx_user_created` (`user_id`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
idempotency_key 给 128 位,够放 UUID 加业务前缀。别图省事用 VARCHAR(255),utf8mb4 下 255 乘 4 是 1020 字节,虽然现在 InnoDB 单列索引上限是 3072 字节扛得住,但索引占的空间白白翻倍。
3.4 启动类
package com.example.idempotent;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class IdempotentApplication {
public static void main(String[] args) {
SpringApplication.run(IdempotentApplication.class, args);
}
}
3.5 自定义注解 @Idempotent
注解只做标记,标在需要幂等的接口方法上,带上场景名和过期秒数。场景名会拼进 Redis key,避免不同接口的键撞车。
package com.example.idempotent.idempotent;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Idempotent {
/** 业务场景,会拼进 Redis key,不同接口不要重名 */
String scene();
/** 幂等窗口,单位秒 */
long expireSeconds() default 300;
}
3.6 Redis 守卫 IdempotentGuard
这个类封装三件事:拼 key、抢位、安全释放。Lua 脚本在类加载时就建好,不用每次请求都拼字符串。
package com.example.idempotent.idempotent;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.script.DefaultRedisScript;
import org.springframework.data.redis.core.script.RedisScript;
import org.springframework.stereotype.Component;
import java.time.Duration;
import java.util.List;
import java.util.UUID;
@Component
public class IdempotentGuard {
/** 只有 value 匹配才删除,防止误删别人的锁 */
private static final RedisScript<Long> RELEASE_SCRIPT = new DefaultRedisScript<>(
"if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
Long.class);
private final StringRedisTemplate redisTemplate;
public IdempotentGuard(StringRedisTemplate redisTemplate) {
this.redisTemplate = redisTemplate;
}
public String buildKey(String scene, String idempotencyKey) {
return "idem:" + scene + ":" + idempotencyKey;
}
/**
* SET key value NX EX ttl,返回 true 表示抢到位置
*/
public boolean tryAcquire(String key, String ownerToken, Duration ttl) {
Boolean acquired = redisTemplate.opsForValue().setIfAbsent(key, ownerToken, ttl);
return Boolean.TRUE.equals(acquired);
}
public void release(String key, String ownerToken) {
redisTemplate.execute(RELEASE_SCRIPT, List.of(key), ownerToken);
}
public static String newOwnerToken() {
return UUID.randomUUID().toString().replace("-", "");
}
}
setIfAbsent(key, value, Duration) 这一行就是 SET NX EX,Spring Data Redis 没有把它拆成两条命令发出去。
3.7 拦截器 IdempotentInterceptor
拦截器在 Controller 之前跑,只做一件事:看看这个请求对应的 Redis key 还能不能抢到。抢不到就直接返回 409,业务代码一行都不执行。
package com.example.idempotent.idempotent;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import java.io.IOException;
import java.time.Duration;
@Component
public class IdempotentInterceptor implements HandlerInterceptor {
public static final String HEADER = "X-Idempotency-Key";
private static final String ATTR_KEY = "IDEMPOTENT_REDIS_KEY";
private static final String ATTR_TOKEN = "IDEMPOTENT_OWNER_TOKEN";
private final IdempotentGuard guard;
public IdempotentInterceptor(IdempotentGuard guard) {
this.guard = guard;
}
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
throws IOException {
if (!(handler instanceof HandlerMethod handlerMethod)) {
return true;
}
Idempotent annotation = handlerMethod.getMethodAnnotation(Idempotent.class);
if (annotation == null) {
return true;
}
String idempotencyKey = request.getHeader(HEADER);
if (idempotencyKey == null || idempotencyKey.isBlank()) {
writeJson(response, HttpServletResponse.SC_BAD_REQUEST,
"IDEMPOTENCY_KEY_MISSING", "请求头 X-Idempotency-Key 不能为空");
return false;
}
String key = guard.buildKey(annotation.scene(), idempotencyKey);
String ownerToken = IdempotentGuard.newOwnerToken();
boolean acquired = guard.tryAcquire(key, ownerToken, Duration.ofSeconds(annotation.expireSeconds()));
if (!acquired) {
writeJson(response, HttpServletResponse.SC_CONFLICT,
"IDEMPOTENT_REJECTED", "同一个幂等键的请求正在处理或已处理完成");
return false;
}
request.setAttribute(ATTR_KEY, key);
request.setAttribute(ATTR_TOKEN, ownerToken);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) {
Object key = request.getAttribute(ATTR_KEY);
Object token = request.getAttribute(ATTR_TOKEN);
if (!(key instanceof String redisKey) || !(token instanceof String ownerToken)) {
return;
}
// 4xx/5xx 说明这次业务没成功,释放位置让用户能重试;成功则保留到 TTL 到期
if (ex != null || response.getStatus() >= 400) {
guard.release(redisKey, ownerToken);
}
}
private void writeJson(HttpServletResponse response, int status, String code, String message)
throws IOException {
response.setStatus(status);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write(
"{\"code\":\"" + code + "\",\"message\":\"" + message + "\",\"data\":null}");
}
}
afterCompletion 里那个 response.getStatus() >= 400 很关键。参数校验失败返回 400、业务异常返回 500,这两种情况下位置必须让出来,否则用户改完参数重试还是被拒。
3.8 注册拦截器 WebMvcConfig
package com.example.idempotent.config;
import com.example.idempotent.idempotent.IdempotentInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
private final IdempotentInterceptor idempotentInterceptor;
public WebMvcConfig(IdempotentInterceptor idempotentInterceptor) {
this.idempotentInterceptor = idempotentInterceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(idempotentInterceptor).addPathPatterns("/api/**");
}
}
3.9 请求和响应对象
package com.example.idempotent.web;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
public record OrderRequest(
@NotBlank(message = "userId 不能为空") String userId,
@NotBlank(message = "skuId 不能为空") String skuId,
@Min(value = 1, message = "quantity 至少为 1") int quantity) {
}
package com.example.idempotent.web;
public record ApiResponse<T>(String code, String message, T data) {
public static <T> ApiResponse<T> ok(T data) {
return new ApiResponse<>("OK", "success", data);
}
public static <T> ApiResponse<T> fail(String code, String message) {
return new ApiResponse<>(code, message, null);
}
}
package com.example.idempotent.web;
import java.math.BigDecimal;
import java.time.LocalDateTime;
public record OrderView(
String orderNo,
String userId,
String skuId,
int quantity,
BigDecimal amount,
String status,
LocalDateTime createdAt) {
}
3.10 数据访问 OrderRepository
用 JdbcTemplate 写,不引入 ORM,逻辑看得更清楚。用 MyBatis 或 JPA 的话,把下面几个方法换成对应实现,业务层的判断一个字都不用改。
package com.example.idempotent.repository;
import com.example.idempotent.web.OrderView;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.core.RowMapper;
import org.springframework.stereotype.Repository;
import java.math.BigDecimal;
import java.util.List;
import java.util.Optional;
@Repository
public class OrderRepository {
private static final String INSERT_SQL = """
INSERT INTO t_order (order_no, idempotency_key, user_id, sku_id, quantity, amount, status)
VALUES (?, ?, ?, ?, ?, ?, 'PENDING')
""";
private static final RowMapper<OrderView> ROW_MAPPER = (rs, rowNum) -> new OrderView(
rs.getString("order_no"),
rs.getString("user_id"),
rs.getString("sku_id"),
rs.getInt("quantity"),
rs.getBigDecimal("amount"),
rs.getString("status"),
rs.getTimestamp("created_at").toLocalDateTime());
private final JdbcTemplate jdbcTemplate;
public OrderRepository(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public void insert(String orderNo, String idempotencyKey, String userId,
String skuId, int quantity, BigDecimal amount) {
jdbcTemplate.update(INSERT_SQL, orderNo, idempotencyKey, userId, skuId, quantity, amount);
}
public Optional<OrderView> findByIdempotencyKey(String idempotencyKey) {
List<OrderView> rows = jdbcTemplate.query("""
SELECT order_no, user_id, sku_id, quantity, amount, status, created_at
FROM t_order WHERE idempotency_key = ?
""", ROW_MAPPER, idempotencyKey);
return rows.stream().findFirst();
}
public Optional<String> findStatus(String orderNo) {
List<String> rows = jdbcTemplate.query(
"SELECT status FROM t_order WHERE order_no = ?",
(rs, rowNum) -> rs.getString("status"),
orderNo);
return rows.stream().findFirst();
}
/** 只有 PENDING 才能改成 PAID,返回 0 表示已经被改过了 */
public int markPaid(String orderNo) {
return jdbcTemplate.update(
"UPDATE t_order SET status = 'PAID' WHERE order_no = ? AND status = 'PENDING'",
orderNo);
}
}
3.11 业务层 OrderService
这里是第二层和第三层防线。insert 撞唯一索引时捕获 DuplicateKeyException,把已经存在的订单查出来返回——用户看到的是“下单成功”,而不是一个红叉。
package com.example.idempotent.service;
import com.example.idempotent.repository.OrderRepository;
import com.example.idempotent.web.OrderRequest;
import com.example.idempotent.web.OrderView;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.util.Optional;
@Service
public class OrderService {
private static final BigDecimal UNIT_PRICE = new BigDecimal("99.00");
private final OrderRepository orderRepository;
public OrderService(OrderRepository orderRepository) {
this.orderRepository = orderRepository;
}
@Transactional(rollbackFor = Exception.class)
public OrderView createOrder(OrderRequest request, String idempotencyKey) {
Optional<OrderView> existing = orderRepository.findByIdempotencyKey(idempotencyKey);
if (existing.isPresent()) {
return existing.get();
}
BigDecimal amount = UNIT_PRICE.multiply(BigDecimal.valueOf(request.quantity()));
String orderNo = OrderNoGenerator.next();
try {
orderRepository.insert(orderNo, idempotencyKey, request.userId(),
request.skuId(), request.quantity(), amount);
} catch (DuplicateKeyException e) {
// 并发下两边都没查到,另一边先插进去了,这里把它的结果捞出来
return orderRepository.findByIdempotencyKey(idempotencyKey)
.orElseThrow(() -> e);
}
return orderRepository.findByIdempotencyKey(idempotencyKey)
.orElseThrow(() -> new IllegalStateException("订单写入后查不到:" + orderNo));
}
@Transactional(rollbackFor = Exception.class)
public String pay(String orderNo) {
int updated = orderRepository.markPaid(orderNo);
if (updated == 1) {
return "PAID";
}
return orderRepository.findStatus(orderNo)
.orElseThrow(() -> new IllegalArgumentException("订单不存在:" + orderNo));
}
}
pay 方法没有加锁、没有查状态再更新,就靠 WHERE status = 'PENDING' 这一句。第一次更新返回 1,第二次返回 0,然后查出当前状态返回 PAID。调用方看到的两次结果一模一样,数据库只改了一次。
OrderNoGenerator 单独放一个类,单机自增加随机数,生产环境换成雪花算法即可:
package com.example.idempotent.service;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.atomic.AtomicInteger;
public final class OrderNoGenerator {
private static final DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS");
private static final AtomicInteger SEQ = new AtomicInteger(0);
private OrderNoGenerator() {
}
public static String next() {
return "ORD"
+ LocalDateTime.now().format(FORMATTER)
+ String.format("%04d", SEQ.incrementAndGet() % 10000)
+ ThreadLocalRandom.current().nextInt(100, 999);
}
}
3.12 接口层 OrderController
package com.example.idempotent.web;
import com.example.idempotent.idempotent.Idempotent;
import com.example.idempotent.idempotent.IdempotentInterceptor;
import com.example.idempotent.service.OrderService;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/orders")
public class OrderController {
private final OrderService orderService;
public OrderController(OrderService orderService) {
this.orderService = orderService;
}
@Idempotent(scene = "order:create", expireSeconds = 600)
@PostMapping
public ApiResponse<OrderView> create(
@RequestHeader(IdempotentInterceptor.HEADER) String idempotencyKey,
@Valid @RequestBody OrderRequest request) {
return ApiResponse.ok(orderService.createOrder(request, idempotencyKey));
}
@PostMapping("/{orderNo}/pay")
public ApiResponse<String> pay(@PathVariable String orderNo) {
return ApiResponse.ok(orderService.pay(orderNo));
}
}
3.13 全局异常处理
package com.example.idempotent.web;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ApiResponse<Void>> handleInvalid(MethodArgumentNotValidException ex) {
String message = ex.getBindingResult().getFieldErrors().stream()
.map(error -> error.getField() + ": " + error.getDefaultMessage())
.findFirst()
.orElse("参数校验失败");
return ResponseEntity.badRequest().body(ApiResponse.fail("INVALID_ARGUMENT", message));
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Void>> handleOther(Exception ex) {
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(ApiResponse.fail("INTERNAL_ERROR", ex.getMessage()));
}
}
3.14 跑起来验证
建库、起 Redis,然后 mvn spring-boot:run。用同一把幂等键连发两次:
curl -i -X POST http://127.0.0.1:8080/api/orders \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: 8f3c9a1e2b7d4f60" \
-d '{"userId":"u1001","skuId":"sku-88","quantity":2}'
第一次返回 200 和订单号。第二次拿同一把键再发,返回 409 和 IDEMPOTENT_REJECTED。把内容里 quantity 改成 0 再发(参数校验失败返回 400),之后改回 2 重发——依然能成功,说明 400 时 key 被正确释放了。
支付接口连调两次,把上一步返回的 orderNo 填进去:
ORDER_NO="把上一步返回的 orderNo 粘到这里"
curl -X POST "http://127.0.0.1:8080/api/orders/${ORDER_NO}/pay"
curl -X POST "http://127.0.0.1:8080/api/orders/${ORDER_NO}/pay"
两次都返回 PAID,t_order 里那条记录的 updated_at 只变了一次。
3.15 MQ 消费端怎么复用
HTTP 请求有拦截器,MQ 消费端没有。消费逻辑里直接把 IdempotentGuard 注进去用,逻辑一模一样:
package com.example.idempotent.mq;
import com.example.idempotent.idempotent.IdempotentGuard;
import org.springframework.stereotype.Component;
import java.time.Duration;
@Component
public class OrderPaidConsumer {
private final IdempotentGuard guard;
public OrderPaidConsumer(IdempotentGuard guard) {
this.guard = guard;
}
public void onMessage(String orderNo, String messageId) {
String key = guard.buildKey("mq:order-paid", messageId);
String token = IdempotentGuard.newOwnerToken();
if (!guard.tryAcquire(key, token, Duration.ofHours(24))) {
return;
}
boolean success = false;
try {
// 真正的业务:发券、加积分、发通知
success = true;
} finally {
if (!success) {
guard.release(key, token);
}
}
}
}
MQ 的幂等键用生产者生成的 messageId,不要用消息体算 MD5。消息体里经常带 traceId、发送时间、重试次数,每次重投都不一样,算出来的键也就每次都不同。
四、踩坑经验:这七处最容易被漏掉
1. 幂等键拼了业务字段,用户买不了第二件。
有人图省事用 userId:skuId,结果同一个人想再买一件同款直接被拒。幂等键描述的是“这一次操作”,不是“这个人买了什么”。
2. 业务失败没释放 key,用户被锁十分钟。
afterCompletion 里漏了状态码判断,参数校验失败的请求也占着位置。用户改完参数再提交,600 秒内全是 409。改法就是上面那个 response.getStatus() >= 400。
3. TTL 比业务耗时短,锁提前过期。 下单要调三个下游、跑十几秒,TTL 设了 5 秒。第 6 秒锁没了,重试请求又进来一遍。TTL 至少要是 P99 耗时的 10 倍,并且业务里最好加个“续期”兜底。
4. 只做了 Redis,没做唯一索引。 Redis 主从异步复制,主挂了切到从,最后几百毫秒的写可能丢。丢的正好是幂等键,重复请求就穿过去了。数据库唯一索引不依赖任何缓存,这一层不能省。
5. 唯一索引建在 order_no 上,没建在幂等键上。
order_no 是服务端生成的,每次都不一样,天然不会冲突。真正要挡的是“同一个幂等键插两次”,所以唯一索引必须建在 idempotency_key 上。
6. 网关重试时把请求头丢了。
Nginx 的 proxy_next_upstream 默认会重发请求,但有些自定义网关只转发 body,X-Idempotency-Key 到不了后端,后端每次看到一个空值。要么在网关白名单里放行这个头,要么统一在网关层补。
7. 事务里 catch 了 DuplicateKeyException,换库就崩。
MySQL 遇到唯一键冲突只回滚当前语句,事务还能继续用,所以 catch 完还能接着查。PostgreSQL 不行,整个事务直接 abort,再查就报错。跨库迁移时这块要重写。
沉淀下来的几条规矩:
- 幂等键由客户端生成,一次业务动作一个,重试复用
- Redis 预检挡并发,TTL 覆盖“最长业务耗时 + 重试窗口”
- 成功不释放,失败(4xx/5xx)必须释放
- 释放锁用 Lua 比对 value,别裸
DEL - 数据库唯一索引必须有,位置在幂等键字段上
- 有状态流转的业务,用
UPDATE ... WHERE status = ?而不是先查后改 - 重复请求返回什么要定清楚:快速失败给 409,或者返回上次的结果,二选一
五、性能对比和技术选型
四种方案的额外开销都在毫秒级以下,选型的依据是“能挡住哪类重复”,不是快慢。
| 方案 | 单次额外开销 | 挡住什么 | 主要缺点 |
|---|---|---|---|
Redis SET NX EX |
同机房 0.2~0.5ms | 并发重复、短时间连点 | Redis 故障时失效,需唯一索引兜底 |
| 数据库唯一索引 | 一次 B+ 树查找,约 0.1ms | 所有并发重复,强一致 | 冲突时抛异常,必须写捕获逻辑 |
状态机 UPDATE ... WHERE |
一次行锁更新 | 重复流转(支付、发货) | 只适用有状态业务 |
| 分布式锁(Redisson) | 0.5~1ms | 长事务串行化 | 粒度粗,吞吐掉得厉害 |
我的建议是组合,不是选一个:
- 写接口(下单、支付、退款):
@Idempotent注解 + Redis 预检 + 唯一索引,两层都上 - 状态流转:
UPDATE ... WHERE status = ?,不要先查后改 - MQ 消费:用
messageId做键,TTL 按消息保留期设 - 读接口:不用做,天然幂等
- 分布式锁:留给“同一资源串行处理”的场景,比如库存扣减,别拿它当幂等方案
还有个常被忽略的点:幂等键的存储本身要有高可用。Redis 用集群或哨兵,别用单机;数据库唯一索引是最后防线,它挂了整个系统都挂了,那是另一个层面的问题。
六、总结
接口幂等的本质是“原子占位 + 唯一约束 + 状态判断”,三层叠加才不漏。
落地就四步:客户端生成 X-Idempotency-Key 并透传到后端;拦截器用 SET NX EX 抢位,抢不到直接 409;数据库在幂等键上建唯一索引,捕获 DuplicateKeyException 后查回已有记录返回;状态流转用 WHERE status = ? 的条件更新。
最容易翻车的地方不在代码,在细节:TTL 设短了、失败没释放、唯一索引建错字段、网关把请求头吃了。这几个坑我都在线上见过,改起来都是几行代码,但排查起来能耗掉一整天。
最后说一句什么时候不用做:只读接口、天然幂等的 PUT/DELETE、以及“每次调用都必须产生新数据”的接口(比如记流水账),都不需要幂等键。别为了统一,给所有接口都套一层 Redis,白扛一次网络往返。
参考资料
- SET | Redis 官方命令参考
- Spring Data Redis Reference
- Interceptors | Spring Framework Reference
- MySQL 8.4 Reference Manual: CREATE INDEX Statement
- RFC 9110: HTTP Semantics - Idempotent Methods
文 / 会编程的吕洞宾