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 演示单进程原子占位。重复请求可以立即收到处理中,也可以复用已固化结果。若副作用发生后结果记录失败,保留原占位供查询和对账。进程退出时示例状态会丢失,生产实现应使用持久化存储。

java
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());
    }
}

预期输出:

text
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,而应落在持久化唯一约束中。

最终落地成一套可执行规则

设计写接口时,先定义业务唯一语义,再决定技术方案,而不是看到“防重复提交”就直接加分布式锁。一个成熟的幂等接口至少应该做到:同一业务意图有稳定标识;并发请求通过原子操作竞争唯一执行资格;相同键不同参数会被拒绝;成功结果可以复用;技术失败允许安全重试;核心业务还有数据库级最终约束。

如果只能记住一条原则,就是:幂等不是“拦住第二个请求”,而是让任意次数、任意并发顺序的重复请求,都只能产生一次正确的业务副作用,并且能够得到可解释的返回结果。

目录与阅读设置

记录一个想法

后端接口幂等到底应该怎么设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通