重复提交拦得住：Spring Boot + Redis 实现接口幂等

前端双击、网络超时重试、网关重发——这些都会让同一个请求到后端两三次。如果这是个"下单"“转账"接口，重复处理就是真金白银的损失。幂等（idempotent）说的就是"同一个请求跑一次和跑多次结果一样”。我用 Spring Boot + Redis 给关键接口加了一道幂等闸，做法记一下。

一、重复提交从哪来

• 用户手快点了两次提交按钮；
• 客户端超时，自动重试了一次；
• 中间代理或网关因为没收到响应而重发。

这些请求业务字段完全一样，光靠后端逻辑很难区分。所以在入口用"唯一业务号"占个坑，第二次进来发现坑被占了，直接拒绝，是最直接的办法。

二、用 Redis 令牌拦一道

核心是用 Redis 的 SETNX（set if not exist）原子操作：第一次写入成功就放行，重复请求写入失败就拦掉。Spring 的 RedisTemplate 对应方法就是 setIfAbsent：

@Service
public class IdempotentService {

    @Autowired
    private StringRedisTemplate redis;

    // 返回 true 表示是首次请求，可以放行
    public boolean checkAndMark(String bizKey, long ttlSeconds) {
        Boolean ok = redis.opsForValue()
                .setIfAbsent("idem:" + bizKey, "1",
                             Duration.ofSeconds(ttlSeconds));
        return Boolean.TRUE.equals(ok);
    }
}

在 Controller 里取业务唯一号（如订单号 + 用户 ID）做 key：

@PostMapping("/pay")
public ResponseEntity<?> pay(@RequestBody PayReq req) {
    String key = req.getUserId() + ":" + req.getOrderId();
    if (!idempotent.checkAndMark(key, 300)) {
        return ResponseEntity.status(409).body("重复请求，已忽略");
    }
    // 正常业务处理...
    return ResponseEntity.ok("ok");
}

TTL 设个合理值（如 5 分钟），避免 key 永久堆积。

三、注解还是拦截器

接口多的话，建议抽成注解 + AOP，一个注解标上去就生效，最省事。

四、几个边界情况

• TTL 要比业务耗时更长：业务跑 10 秒、TTL 设 5 秒，正常请求都可能被自己后续的"重试"误伤。留足余量。
• key 要够唯一：只拿用户 ID 当 key，会误拦同一用户的不同订单；要带上业务单号。
• 分布式下必须用 Redis：单机用内存 Map 在多实例部署时各算各的，拦不住，Redis 才是共享的"坑位"。
• 异常处理要回滚坑位：如果业务抛异常，考虑是否删除 key 允许重试，否则这次失败用户永远不能再提交。

总结

接口幂等不是高级概念，本质就是"用一把带超时的分布式锁占坑"。Redis 的 SETNX 原子性强、带过期、天然共享，是这件事的标准解法。等这个模式跑顺了，抽成 AOP 注解，后面任何怕重复的接口，标一行注解就稳了。比起事后对账补单，入口拦一道省下的麻烦多得多。