Java 后端 / 系统课时
设计接口幂等性
设计接口幂等性
本课解决创建订单、支付确认等关键接口被重复调用时产生重复数据的问题。通过幂等键、唯一约束和状态机设计,让接口在重复请求下仍保持正确结果。
学习目标
- 理解接口幂等性的业务价值和实现边界。
- 掌握幂等键与数据库约束结合的实现方式。
- 能够设计可重试且数据一致的业务接口。
理解重复请求产生的问题
网络重试、客户端重复点击、消息重复投递都会导致同一个业务操作执行多次。例如支付接口第一次请求成功,但响应丢失,客户端再次发起支付请求,如果没有幂等控制,就可能产生重复扣款。
幂等接口要求同一个业务请求执行一次或多次后,最终状态一致。注意幂等并不代表接口没有副作用,而是副作用结果可控。

使用幂等键记录请求状态
幂等键通常由客户端或服务端生成,用于唯一标识一次业务操作。服务端收到请求后,先检查该键是否已经处理。一个简单实现流程如下:
- 接收请求并校验幂等键。
- 查询幂等记录。
- 已完成则直接返回历史结果。
- 未处理则执行业务并保存最终状态。
下面示例展示使用 Redis 保存请求状态的核心逻辑。
java
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
private final StringRedisTemplate redis;
public OrderService(StringRedisTemplate redis) {
this.redis = redis;
}
public String createOrder(String requestId) {
String key = "order:idempotent:" + requestId;
Boolean first = redis.opsForValue()
.setIfAbsent(key, "PROCESSING");
if (Boolean.FALSE.equals(first)) {
return "REQUEST_ALREADY_EXISTS";
}
// 真实业务中这里执行订单创建事务
redis.opsForValue().set(key, "SUCCESS");
return "ORDER_CREATED";
}
}预期结果
text
第一次请求返回 ORDER_CREATED
相同 requestId 再次请求返回 REQUEST_ALREADY_EXISTS实际生产环境中,需要为处理中状态增加超时恢复机制,避免服务异常退出后永久占用幂等键。
使用数据库唯一约束兜底
仅依赖缓存实现幂等存在失效风险,因此关键业务通常增加数据库唯一约束。
例如订单表可以将业务流水号设置为唯一索引,即使并发请求同时进入,数据库也会阻止重复写入。
sql
CREATE TABLE orders (
id BIGINT PRIMARY KEY,
request_id VARCHAR(64) NOT NULL UNIQUE,
status VARCHAR(20) NOT NULL
);预期结果
text
再次插入相同 request_id 时,数据库拒绝重复记录缓存负责快速判断,数据库负责最终一致性,两者组合可以提升系统可靠性。
使用状态机管理业务流转
复杂业务不能只判断是否执行过,还需要管理业务状态。例如支付流程可能包含待支付、支付中、支付成功、支付失败等阶段。
状态机通过限制状态转换规则,避免重复支付、非法退款等问题。例如:
| 当前状态 | 允许转换 |
|---|---|
| 待支付 | 支付中 |
| 支付中 | 支付成功、支付失败 |
| 支付成功 | 申请退款 |
状态设计完成后,每次请求都需要验证当前状态是否允许执行目标动作。
幂等设计中的常见边界
幂等键需要明确生命周期,过短可能无法覆盖重试窗口,过长会增加存储压力。
对于异步消息消费,还需要结合消息唯一编号、消费记录和业务状态判断,不能简单依赖接口层幂等。
按自己的节奏,确认真正理解。