API 设计 / 技术文章
后端接口幂等到底应该怎么设计
这篇文章解决后端接口在重试、连点、超时重发和并发请求下被重复执行的问题,适合 Java 后端与 API 设计人员。读完后,你应能为创建订单、支付回调、库存扣减等写接口设计出可落地、可并发校验、可恢复的幂等方案。
先明确:幂等不是“请求只能来一次”
接口幂等关注的不是请求次数,而是同一个业务意图重复到达时,业务结果不能被重复扩大。客户端完全可能因为网络超时、网关重试、消息重复投递或用户连续点击,把同一请求发送多次;后端不能把“客户端应该只发一次”当成正确性的前提。
例如,同一个“创建订单”意图重复提交三次,最终只能生成一张订单;同一个支付成功回调到达五次,账户也只能入账一次。至于第二次请求是返回原结果、返回处理中,还是提示冲突,属于接口契约设计问题。
真正需要先回答的是:什么才算“同一个业务意图”。如果这个边界没有定义清楚,后面的 Redis 锁、唯一索引和幂等表都只是技术补丁。
幂等键应该绑定业务意图,而不是绑定一次 HTTP 连接
通用写接口通常可以让调用方生成 Idempotency-Key,服务端再把它和用户、租户、接口作用域组合成真正的幂等键,例如 tenantId + userId + endpoint + idempotencyKey。这样既避免不同用户之间碰撞,也避免同一个键被不同接口误复用。
对于已经存在天然业务唯一标识的场景,优先直接使用业务键,而不是额外发明一套随机键。例如支付回调可以使用支付平台交易号,优惠券领取可以使用“用户 ID + 活动 ID”,订单明细导入可以使用上游批次号。
| 场景 | 更适合的幂等依据 | 主要约束 |
|---|---|---|
| 创建订单 | 客户端幂等键或业务请求号 | 同一键只能创建一张订单 |
| 支付回调 | 渠道交易号 | 同一交易只能入账一次 |
| 状态变更 | 业务 ID + 当前状态 | 只能从允许的旧状态迁移 |
| 库存扣减 | 订单号 + 商品行号 | 同一业务扣减不能重复发生 |
| 消息消费 | 消息唯一 ID | 同一消息只能产生一次业务副作用 |
服务端应按接口语义计算稳定的请求参数摘要,并把它与作用域、幂等键一起保存在同一条记录中。摘要应包含会改变业务结果的字段,避免把 JSON 键顺序、链路追踪 ID 等无关差异算作新意图。相同作用域下同键异参时拒绝请求,并对重放执行正常鉴权,防止复用其他主体的结果。参见 AWS 幂等 API 设计。
一次完整的幂等请求应该怎么走
一个可靠的通用幂等处理通常包含“原子占位、执行业务、固化结果、重复请求复用结果”四个动作。关键点是:是否获得执行资格必须通过原子操作决定,不能先查询再凭应用层判断。

建议至少保存这些信息:幂等作用域、幂等键、请求参数摘要、处理状态、业务结果标识、首次响应以及过期时间。这样重复请求不是简单得到“已经处理过”,而是可以得到与首次请求一致的业务结果。
如果重复请求到达时首个请求仍在处理中,可以选择返回 409 Conflict、202 Accepted,或者在服务端做一个有上限的短等待。不要无限阻塞,也不要在看到 PROCESSING 后再次执行业务。
并发下最危险的是“先查再执行”
很多看似正确的实现会先查询“这个键是否处理过”,没有记录就执行业务,最后再写幂等记录。单线程测试通常没问题,但两个请求并发到达时,它们可能同时查到“不存在”,随后各自执行一次业务,幂等立即失效。

生产环境最稳妥的做法通常是让数据库唯一约束、Redis 原子写入或带条件的状态更新来决定唯一执行者。尤其是最终会写数据库的核心交易,业务表上的唯一约束仍然应该作为最后一道防线,因为应用锁和缓存都可能失效。
下面的 Java 示例用 ConcurrentHashMap.putIfAbsent 演示单进程原子占位。重复请求可以立即收到处理中,也可以复用已固化结果。若副作用发生后结果记录失败,保留原占位供查询和对账。进程退出时示例状态会丢失,生产实现应使用持久化存储。
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
public class IdempotencyDemo {
record RequestKey(String account, String operation, String key) {}
record Response(int status, String body) {}
record Entry(String fingerprint, CompletableFuture<Response> outcome) {}
private static final ConcurrentHashMap<RequestKey, Entry> STORE =
new ConcurrentHashMap<>();
private static final AtomicInteger ORDERS = new AtomicInteger();
static Response handle(RequestKey key, String fingerprint, boolean failAfterWrite) {
var owner = new Entry(fingerprint, new CompletableFuture<>());
var existing = STORE.putIfAbsent(key, owner);
if (existing != null) {
if (!existing.fingerprint().equals(fingerprint)) {
return new Response(409, "same key, different request");
}
return existing.outcome().getNow(new Response(202, "processing"));
}
Response result;
try {
int orderId = ORDERS.incrementAndGet(); // 模拟副作用已发生
if (failAfterWrite) {
throw new IllegalStateException("lost confirmation");
}
result = new Response(201, "order-" + orderId);
} catch (IllegalStateException unknown) {
result = new Response(202, "outcome unknown; reconcile");
}
owner.outcome().complete(result);
return result;
}
public static void main(String[] args) {
var key = new RequestKey("user-1", "create-order", "request-001");
var first = CompletableFuture.supplyAsync(() -> handle(key, "sku-1:2", false));
var second = CompletableFuture.supplyAsync(() -> handle(key, "sku-1:2", false));
CompletableFuture.allOf(first, second).join();
var success = handle(key, "sku-1:2", false);
if (!success.equals(new Response(201, "order-1")) || ORDERS.get() != 1) {
throw new AssertionError("duplicate order");
}
if (handle(key, "sku-1:3", false).status() != 409) {
throw new AssertionError("same key accepted with a different request");
}
var unknown = new RequestKey("user-1", "create-order", "request-002");
var original = handle(unknown, "sku-2:1", true);
var replay = handle(unknown, "sku-2:1", false);
if (original.status() != 202 || !original.equals(replay) || ORDERS.get() != 2) {
throw new AssertionError("unknown outcome was executed again");
}
System.out.println(success);
System.out.println(replay);
System.out.println("orders=" + ORDERS.get());
}
}预期输出:
Response[status=201, body=order-1]
Response[status=202, body=outcome unknown; reconcile]
orders=2第一个业务键的两个并发请求只产生一张订单。第二个业务键模拟写入后失去确认,重试看到待核对状态,订单数保持为 2。代码中的参数串与订单计数只是测试替身。真实接口返回 202 时应提供操作状态查询方式,后台也需要用业务记录或外部流水解决未知状态。
Redis、唯一索引和幂等表应该怎么选
数据库唯一索引最适合有明确业务唯一键的场景,也是交易型写入最重要的兜底。例如同一支付流水号不能重复入账,就应该让账务明细表直接对交易号建立唯一约束。它的优势是规则和最终数据处在同一个持久化边界内。
独立幂等表适合通用 API。它可以记录幂等键、参数摘要、处理状态和首次结果,并通过唯一索引解决并发竞争。业务和幂等结果落在同一数据库时,可在同一事务提交。若副作用发生在外部服务,本地事务不能覆盖对端。需要使用外部服务支持的稳定请求键、状态查询或对账机制。采用 Outbox 可以保证待发送记录与本地业务数据一起落盘,外部投递仍要按可能重复处理。
**Redis SET NX**适合高并发下快速抢占执行资格,但不要把“加了一个短期锁”直接等同于完整幂等。锁过期、Redis 故障、业务执行超时以及结果复用都需要额外设计。对于资金、订单、库存等核心数据,Redis 更适合作为前置协调层,而不是唯一正确性保障。
状态机条件更新适合状态迁移类接口。例如只有 PENDING 才允许更新为 PAID,可以通过“业务 ID + 旧状态”作为更新条件。即使请求重复到达,第二次也无法再次从 PENDING 执行同一迁移。
失败、超时和过期时间决定了方案是否真的可靠
幂等最容易出问题的地方不是成功路径,而是“服务端已经执行成功,但客户端没有收到响应”。此时客户端重试,服务端必须能识别第一次实际上已经完成,并返回第一次的业务 ID 或结果,而不是再次创建资源。
是否固化业务拒绝取决于接口契约。例如在首次结果固定的契约中,余额不足可以作为本次业务意图的最终结果。若调用方要重新尝试新的支付意图,按契约生成新业务标识。技术故障则应区分已确认未提交和结果未知。前者可按契约释放执行资格,后者必须保留原记录并核对已提交的业务数据或外部流水,不能仅凭超时、异常或租约过期就重放写入。
TTL 也不能随便设成几分钟。它应覆盖业务可能发生的真实重试窗口;如果业务语义要求“这个交易号永远只能处理一次”,最终约束就不应该依赖会过期的 Redis Key,而应落在持久化唯一约束中。
最终落地成一套可执行规则
设计写接口时,先定义业务唯一语义,再决定技术方案,而不是看到“防重复提交”就直接加分布式锁。一个成熟的幂等接口至少应该做到:同一业务意图有稳定标识;并发请求通过原子操作竞争唯一执行资格;相同键不同参数会被拒绝;成功结果可以复用;技术失败允许安全重试;核心业务还有数据库级最终约束。
如果只能记住一条原则,就是:幂等不是“拦住第二个请求”,而是让任意次数、任意并发顺序的重复请求,都只能产生一次正确的业务副作用,并且能够得到可解释的返回结果。