Java 接口幂等设计实战：从请求标识到 Redis 防重和唯一键兜底

下单、支付、领券、扣库存这类接口，最怕客户端因为网络抖动重复提交。用户点了一次按钮，前端重试了一次，网关又重放了一次，如果后端没有幂等保护，就可能创建两笔订单或扣两次库存。

本文用一条完整工作流讲清楚 Java 接口幂等怎么落地：先让客户端带请求标识，再在入口做校验，用 Redis 做快速防重，最后用数据库唯一键兜底。遇到超时和重复请求时，返回稳定结果，而不是再创建一份业务数据。

目标和边界：这篇解决什么问题

这里讨论的是“同一个业务请求重复到达后，只产生一次业务结果”。示例场景是 Java Spring Boot 的订单创建接口：

POST /api/orders
Idempotency-Key: 8c5f1a2b-7b11-4f68-9c25-demo

本文不讨论分布式事务的全部细节，也不把幂等当成万能锁。我们只聚焦一件事：同一个幂等键在合理时间窗口内重复请求时，接口应该返回同一份结果。

先说结论：可靠的做法不是只靠前端禁用按钮，也不是只靠 Redis。推荐组合是“请求标识 + Redis 快速防重 + 数据库唯一键兜底 + 可查询的业务状态”。这样即使 Redis 短暂异常，数据库仍然能挡住重复写入。

全流程总览：一次幂等请求从入口到落库

完整链路可以拆成五个节点：请求带标识，入口校验格式，Redis 尝试占位，业务写库，返回稳定响应。

阶段一：生成并校验请求标识

请求标识可以由客户端生成，也可以先调用后端接口申请。核心要求是同一次业务动作使用同一个值，不同业务动作使用不同值。

String key = request.getHeader("Idempotency-Key");
if (key == null || key.length() 

建议把用户 ID、接口名和幂等键组合成 Redis key，避免不同接口之间互相影响：

String redisKey = "idempo:order:create:" + userId + ":" + key;

检查点：日志里能看到同一次重试请求使用了同一个幂等键。如果每次重试都生成新值，后端无法判断它们属于同一个业务动作。

阶段二：用 Redis 做快速防重

Redis 的作用是快速挡住短时间内的重复请求。常见写法是 SETNX 加过期时间，只有第一次请求能成功占位。

Boolean first = stringRedisTemplate.opsForValue()
        .setIfAbsent(redisKey, "PROCESSING", Duration.ofMinutes(3));

if (!Boolean.TRUE.equals(first)) {
    String cached = stringRedisTemplate.opsForValue().get(redisKey + ":result");
    if (cached != null) {
        return ResponseEntity.ok(cached);
    }
    return ResponseEntity.status(202).body("processing");
}

这里不要把 TTL 设置得太短。业务还没完成，key 就过期，重复请求可能重新进入业务逻辑。也不要无限期保留，避免 Redis 积累过多无用键。

阶段三：数据库唯一键兜底

Redis 是第一道门，数据库唯一键是最后一道门。订单表里建议保存幂等键，并建立唯一约束：

ALTER TABLE orders
ADD COLUMN idempotency_key VARCHAR(80) NOT NULL,
ADD UNIQUE KEY uk_orders_idempo (idempotency_key);

业务保存时，把幂等键和订单数据一起写入。即使 Redis 因网络问题没有挡住重复请求，数据库也会拒绝第二次插入。

Order order = new Order();
order.setUserId(userId);
order.setAmount(command.amount());
order.setIdempotencyKey(key);
orderRepository.save(order);

检查点：同一个幂等键重复提交时，数据库里只能查到一条订单记录。

阶段四：重复请求、超时和补偿怎么处理

真实系统里最难的是“第一次请求其实成功了，但客户端没收到响应”。这时重复请求到达，不能简单报错，也不能再写一次订单，而是要查询已有状态。

推荐分支如下：

1. Redis 命中成功结果：直接返回缓存的订单号和状态。
2. Redis 只有处理中状态：返回 202，提示稍后查询。
3. Redis 没有 key 但数据库存在幂等键：返回数据库里的订单结果。
4. 数据库也不存在：按业务规则重新受理，或标记为待补偿。

这样做的重点是结果可查。幂等不是单纯阻止请求，而是让同一个业务动作最终收敛到同一个结果。

我的推荐流程

落地时可以按下面顺序推进：

1. 先给关键接口加 Idempotency-Key 规范，明确由谁生成、保存多久。
2. 入口层统一校验幂等键，缺失时直接拒绝。
3. Redis 使用 SETNX + TTL 做短期防重，并缓存成功响应摘要。
4. 数据库表增加幂等键字段和唯一约束。
5. 为重复请求、处理中、已成功、补偿中设计明确响应。
6. 压测重复提交和网络超时场景，确认不会生成第二条业务记录。

容易踩坑的地方

• 只做前端按钮禁用：刷新、重试、网关重放仍然会进后端。
• 只做 Redis 防重：Redis 异常或 TTL 过短时，仍可能重复写库。
• 幂等键范围太宽：不同用户共用同一个 key，导致互相拦截。
• 不保存成功结果：重复请求只能返回处理中，用户体验差。
• 异常分支没有查询数据库：第一次请求成功但响应丢失时，容易误判失败。

落地速查表

总结一下：Java 接口幂等设计要按链路来做，不要押宝在某一个组件上。请求标识负责识别同一次业务动作，Redis 负责快速防重，数据库唯一键负责兜底，状态查询负责处理超时和重试。把这四块串起来，接口才真正具备可落地的幂等能力。