SpringBoot接口幂等性方案：4种策略+代码实战，告别重复提交

👉 这是一个或许对你有用的社群

🐱 一对一交流/面试小册/简历优化/求职解惑，欢迎加入「芋道快速开发平台」知识星球。下面是星球提供的部分资料： 

• 《项目实战（视频）》：从书中学，往事上“练”
• 《互联网高频面试题》：面朝简历学习，春暖花开
• 《架构 x 系统设计》：摧枯拉朽，掌控面试高频场景题
• 《精进 Java 学习指南》：系统学习，互联网主流技术栈
• 《必读 Java 源码专栏》：知其然，知其所以然

来源：程序语言

• 背景
• 1.Token 令牌 —— 最经典、最稳
• 2.数据库唯一索引 —— 低成本、强一致
• 3.分布式锁 —— 高并发大杀器
• 4.请求内容摘要 —— 最透明、最通用

背景

网络抖动、用户手抖、MQ 重试……任何一次“重复请求”都可能让钱 扣钱、商品多发 。

今天一次讲透 4 种常用幂等性实现，附可 copy 的代码 。

基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能

• 项目地址：https://github.com/YunaiV/ruoyi-vue-pro
• 视频教程：https://doc.iocoder.cn/video/

1.Token 令牌 —— 最经典、最稳

思路： 先拿令牌 → 再执行业务 → 用完即焚。

核心关键字： 预生成、一次性、Redis 原子删除。

精简代码（含注解）

@RestController
@RequestMapping("/order")
publicclassOrderController {

    @Autowired
    private StringRedisTemplate redis;

    // ① 预生成 Token，给前端
    @GetMapping("/token")
    public String getToken() {
        Stringtoken= UUID.randomUUID().toString();
        // 10 分钟有效期，足够前端完成下单
        redis.opsForValue().set("tk:" + token, "1", Duration.ofMinutes(10));
        return token;
    }

    // ② 下单接口，Header 中带令牌
    @PostMapping
    public Result create(@RequestHeader("Idempotent-Token") String token,
                         @RequestBody OrderReq req) {
        Stringkey="tk:" + token;
        // 原子删除：成功返回 true 表示第一次使用
        Booleanfirst= redis.delete(key);
        if (Boolean.FALSE.equals(first)) {
            return Result.fail("**请勿重复下单**");
        }
        // 真正创建订单
        Orderorder= orderService.create(req);
        return Result.ok(order);
    }
}

注解：

• UUID 保证全局唯一，Redis TTL 防呆。
• delete 是原子操作，天然并发安全。
• 用 Header 传递令牌，保持接口语义纯净。

基于 Spring Cloud Alibaba + Gateway + Nacos + RocketMQ + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能

• 项目地址：https://github.com/YunaiV/yudao-cloud
• 视频教程：https://doc.iocoder.cn/video/

2.数据库唯一索引 —— 低成本、强一致

思路： 把“业务唯一键”做成唯一索引，重复写直接抛异常。

核心关键字： 天然幂等、异常即幂等。

代码示例

@Entity
@Table(name = "t_payment",
       uniqueConstraints = @UniqueConstraint(columnNames = "transaction_id"))
publicclassPayment {
    @Id
    private Long id;

    // 支付平台返回的流水号
    @Column(name = "transaction_id")
    private String txId;

    private BigDecimal amount;
    private String status;
}

@Service
publicclassPayService {
    @Autowired
    private PaymentRepo repo;

    public Result pay(PayReq req) {
        try {
            Paymentp=newPayment();
            p.setTxId(req.getTxId());
            p.setAmount(req.getAmount());
            p.setStatus("SUCCESS");
            repo.save(p);   // 重复就抛 DataIntegrityViolationException
            return Result.ok("**支付成功**");
        } catch (DataIntegrityViolationException e) {
            // 异常即查询结果，避免重复扣款
            Paymentexist= repo.findByTxId(req.getTxId());
            return Result.ok("**已支付**", exist.getId());
        }
    }
}

注解：

• 唯一索引兜底，数据库层面 100 % 防重。
• try-catch 把异常转成正常响应，用户体验丝滑。
• 无外部依赖，适配老旧系统也毫无压力。

3.分布式锁 —— 高并发大杀器

思路： 对“订单号 / 用户ID”加分布式锁，抢到锁再干活。

核心关键字： 互斥、超时、可重入。

Redisson 简洁版

@Service
publicclassStockService {

    @Autowired
    private RedissonClient redisson;

    public Result deduct(DeductCmd cmd) {
        StringlockKey="lock:stock:" + cmd.getProductId();
        RLocklock= redisson.getLock(lockKey);
        try {
            // 最多等 3 秒，持锁 5 秒自动释放
            if (!lock.tryLock(3, 5, TimeUnit.SECONDS)) {
                return Result.fail("**处理中，请稍后**");
            }
            // 业务幂等检查：根据请求 ID 查记录
            if (repo.existsByRequestId(cmd.getRequestId())) {
                return Result.ok("**已扣减**");
            }
            // 真正扣库存
            repo.deductStock(cmd);
            return Result.ok("**扣减成功**");
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return Result.fail("**系统繁忙**");
        } finally {
            if (lock.isHeldByCurrentThread()) {
                lock.unlock();
            }
        }
    }
}

注解：

• Redisson 自带 watchdog，自动续期，不怕死锁。
• requestId 做幂等表，锁+唯一索引 双保险。
• lock.isHeldByCurrent线程 防止误删别人的锁。

4.请求内容摘要 —— 最透明、最通用

思路： 把请求体做 MD5/SHA256，作为幂等键。

核心关键字： 零额外交互、客户端无感。

自定义注解 + AOP

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public@interface Idempotent {
    intexpire()default3600;   // 秒
}

@Aspect
@Component
publicclassIdempotentAspect {

    @Autowired
    private StringRedisTemplate redis;

    @Around("@annotation(idem)")
    public Object around(ProceedingJoinPoint pjp, Idempotent idem)throws Throwable {
        HttpServletRequestreq= ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
        // ① 计算请求体摘要
        Stringbody= IOUtils.toString(req.getReader());
        Stringdigest= DigestUtils.md5DigestAsHex(body.getBytes(StandardCharsets.UTF_8));
        Stringkey="idem:digest:" + digest;

        // ② 第一次：setIfAbsent 返回 true
        Booleanabsent= redis.opsForValue().setIfAbsent(key, "1", Duration.ofSeconds(idem.expire()));
        if (Boolean.FALSE.equals(absent)) {
            return Result.fail("**重复请求**");
        }
        try {
            return pjp.proceed();
        } catch (Exception e) {
            redis.delete(key);  // 异常时释放，允许重试
            throw e;
        }
    }
}

// 使用
@RestController
publicclassTransferApi {
    @PostMapping("/transfer")
    @Idempotent(expire = 7200)
    public Result transfer(@RequestBody TransferCmd cmd) {
        return Result.ok(transferSvc.doTransfer(cmd));
    }
}

注解：

• MD5 把任意长度报文压缩成 32 位，冲突概率极低。
• setIfAbsent 保证原子性，异常回删避免误杀。
• 注解 + AOP 零侵入，老接口 1 行代码即可拥有幂等。

小结

实施清单

• 检查你的核心接口有没有唯一业务键。
• 优先使用数据库唯一索引，成本最低。
• 并发量高再上分布式锁或Token，不要过度设计。
• 给关键接口加上监控告警，幂等失败时第一时间知道。