SpringBoot中接口幂等性的5种实现方法详解

更新时间：2026年07月21日 09:11:43 作者：(farerboy)

本文深入浅出地讲解了幂等性的概念和重要性,并提供5种SpringBoot实现方案,分别是基于数据库唯一索引、Token令牌、分布式锁、Redis和乐观锁,从原理到代码帮你选择最适合业务场景的幂等性解决方案,有效防止重复提交,提升系统稳定性

1. 幂等性的概念与重要性

1.1 什么是幂等性

幂等性（Idempotence）是指无论对同一操作执行多少次，结果都是相同的。在API设计中，幂等性确保了重复请求不会导致意外的副作用。

1.2 为什么需要幂等性

网络波动：网络不稳定可能导致请求重复发送
客户端重试：客户端在超时后可能会重试请求
用户误操作：用户可能重复点击提交按钮
分布式系统：分布式环境下，消息可能重复投递

1.3 幂等性的应用场景

支付接口
订单创建接口
数据更新接口
资源创建接口

2. 实现方案

方案一：基于数据库唯一索引

实现原理

通过在数据库表中添加唯一索引，确保重复的请求不会导致数据重复插入。

核心源码

数据库表设计：

CREATE TABLE `order` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `order_no` varchar(32) NOT NULL COMMENT '订单号',
  `user_id` bigint(20) NOT NULL COMMENT '用户ID',
  `amount` decimal(10,2) NOT NULL COMMENT '金额',
  `status` int(11) NOT NULL COMMENT '状态',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_order_no` (`order_no`) COMMENT '订单号唯一索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表';

Service层实现：

@Service
public class OrderService {
    @Autowired
    private OrderMapper orderMapper;
    
    @Transactional
    public Order createOrder(OrderCreateRequest request) {
        // 生成唯一订单号
        String orderNo = generateOrderNo();
        
        Order order = new Order();
        order.setOrderNo(orderNo);
        order.setUserId(request.getUserId());
        order.setAmount(request.getAmount());
        order.setStatus(0);
        order.setCreateTime(new Date());
        
        try {
            orderMapper.insert(order);
            return order;
        } catch (DuplicateKeyException e) {
            // 唯一索引冲突，说明订单已存在
            return orderMapper.selectByOrderNo(orderNo);
        }
    }
    
    private String generateOrderNo() {
        // 生成唯一订单号的逻辑
        return "ORD" + System.currentTimeMillis() + RandomUtil.randomString(6);
    }
}

优劣势分析

优点：

实现简单，依赖数据库自身的约束
可靠性高，数据库保证唯一性

缺点：

仅适用于插入操作
并发性能受数据库限制
错误处理需要捕获异常

适用场景

订单创建
用户注册
资源分配

方案二：基于Token令牌

实现原理

客户端请求获取令牌
服务端生成唯一令牌并存储
客户端携带令牌发起请求
服务端验证令牌并执行操作
操作完成后删除令牌

核心源码

Token生成与验证：

@Component
public class IdempotentTokenService {
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    /**
     * 生成幂等性令牌
     */
    public String generateToken() {
        String token = UUID.randomUUID().toString();
        // 存储令牌，设置过期时间为5分钟
        redisTemplate.opsForValue().set("idempotent_token:" + token, token, 5, TimeUnit.MINUTES);
        return token;
    }
    
    /**
     * 验证令牌
     */
    public boolean validateToken(String token) {
        if (StringUtils.isEmpty(token)) {
            return false;
        }
        String key = "idempotent_token:" + token;
        // 原子操作，获取并删除令牌
        return redisTemplate.delete(key);
    }
}

Controller层实现：

@RestController
@RequestMapping("/api/order")
public class OrderController {
    @Autowired
    private IdempotentTokenService idempotentTokenService;
    @Autowired
    private OrderService orderService;
    
    /**
     * 获取幂等性令牌
     */
    @GetMapping("/token")
    public ResponseEntity<String> getToken() {
        String token = idempotentTokenService.generateToken();
        return ResponseEntity.ok(token);
    }
    
    /**
     * 创建订单
     */
    @PostMapping
    public ResponseEntity<Order> createOrder(@RequestHeader("X-Idempotent-Token") String token, 
                                           @RequestBody OrderCreateRequest request) {
        // 验证令牌
        if (!idempotentTokenService.validateToken(token)) {
            return ResponseEntity.badRequest().build();
        }
        
        Order order = orderService.createOrder(request);
        return ResponseEntity.ok(order);
    }
}

优劣势分析

优点：

适用范围广，可用于各种操作
实现灵活，可自定义过期时间
性能较好，基于Redis操作

缺点：

需要额外的Redis存储
增加了请求次数（获取令牌）
客户端需要额外处理令牌

适用场景

支付接口
表单提交
数据更新

方案三：基于分布式锁

实现原理

通过分布式锁确保同一时间只有一个请求执行操作，避免并发问题。

核心源码

分布式锁实现：

@Component
public class DistributedLockService {
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    /**
     * 获取分布式锁
     */
    public boolean tryLock(String key, long expireTime) {
        Boolean result = redisTemplate.opsForValue().setIfAbsent(key, "locked", expireTime, TimeUnit.MILLISECONDS);
        return Boolean.TRUE.equals(result);
    }
    
    /**
     * 释放分布式锁
     */
    public void releaseLock(String key) {
        redisTemplate.delete(key);
    }
}

Service层实现：

@Service
public class PaymentService {
    @Autowired
    private DistributedLockService distributedLockService;
    @Autowired
    private PaymentMapper paymentMapper;
    
    public Payment processPayment(PaymentRequest request) {
        // 生成锁键
        String lockKey = "payment_lock:" + request.getOrderNo();
        
        try {
            // 尝试获取锁，设置过期时间为30秒
            if (!distributedLockService.tryLock(lockKey, 30000)) {
                throw new BusinessException("支付处理中，请稍后再试");
            }
            
            // 检查是否已支付
            Payment existingPayment = paymentMapper.selectByOrderNo(request.getOrderNo());
            if (existingPayment != null && existingPayment.getStatus() == 1) {
                return existingPayment;
            }
            
            // 处理支付逻辑
            Payment payment = new Payment();
            payment.setOrderNo(request.getOrderNo());
            payment.setAmount(request.getAmount());
            payment.setStatus(1);
            payment.setCreateTime(new Date());
            
            paymentMapper.insert(payment);
            return payment;
        } finally {
            // 释放锁
            distributedLockService.releaseLock(lockKey);
        }
    }
}

优劣势分析

优点：

适用范围广，可用于各种操作
支持并发场景
实现灵活，可自定义锁的粒度

缺点：

依赖分布式锁实现
可能存在锁竞争问题
实现复杂度较高

适用场景

支付处理
库存扣减
数据同步

方案四：基于Redis实现

实现原理

通过Redis的原子操作（如SETNX）实现幂等性控制。

核心源码

Redis幂等性实现：

@Component
public class RedisIdempotentService {
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    /**
     * 检查并设置幂等性键
     */
    public boolean checkAndSet(String key, long expireTime) {
        Boolean result = redisTemplate.opsForValue().setIfAbsent(key, "processed", expireTime, TimeUnit.MILLISECONDS);
        return Boolean.TRUE.equals(result);
    }
    
    /**
     * 生成幂等性键
     */
    public String generateKey(String prefix, String... params) {
        StringBuilder sb = new StringBuilder(prefix);
        for (String param : params) {
            sb.append(":").append(param);
        }
        return sb.toString();
    }
}

Service层实现：

@Service
public class OrderService {
    @Autowired
    private RedisIdempotentService redisIdempotentService;
    @Autowired
    private OrderMapper orderMapper;
    
    public Order createOrder(OrderCreateRequest request) {
        // 生成幂等性键
        String key = redisIdempotentService.generateKey("order_create", 
                                                     request.getUserId(), 
                                                     request.getProductId());
        
        // 检查是否已处理
        if (!redisIdempotentService.checkAndSet(key, 30000)) {
            throw new BusinessException("订单已处理，请不要重复提交");
        }
        
        // 创建订单逻辑
        Order order = new Order();
        order.setUserId(request.getUserId());
        order.setProductId(request.getProductId());
        order.setAmount(request.getAmount());
        order.setStatus(0);
        order.setCreateTime(new Date());
        
        orderMapper.insert(order);
        return order;
    }
}

优劣势分析

优点：

实现简单，基于Redis原子操作
性能优异，Redis操作速度快
适用范围广

缺点：

依赖Redis服务
需要合理设置过期时间
键的设计需要考虑唯一性

适用场景

高频接口
表单提交
数据更新

方案五：基于乐观锁

实现原理

通过版本号或时间戳实现乐观锁，确保数据更新的一致性。

核心源码

数据库表设计：

CREATE TABLE `product` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL COMMENT '产品名称',
  `stock` int(11) NOT NULL COMMENT '库存',
  `version` int(11) NOT NULL DEFAULT '0' COMMENT '版本号',
  `update_time` datetime NOT NULL COMMENT '更新时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='产品表';

Service层实现：

@Service
public class ProductService {
    @Autowired
    private ProductMapper productMapper;
    
    @Transactional
    public boolean deductStock(Long productId, int quantity) {
        // 获取产品信息
        Product product = productMapper.selectById(productId);
        if (product == null) {
            throw new BusinessException("产品不存在");
        }
        
        // 检查库存
        if (product.getStock() < quantity) {
            throw new BusinessException("库存不足");
        }
        
        // 更新库存，使用乐观锁
        int result = productMapper.updateStock(productId, quantity, product.getVersion());
        if (result == 0) {
            // 更新失败，说明版本号已变化
            throw new BusinessException("库存更新失败，请重试");
        }
        
        return true;
    }
}

Mapper层实现：

public interface ProductMapper {
    @Update("UPDATE product SET stock = stock - #{quantity}, version = version + 1, update_time = NOW() WHERE id = #{productId} AND version = #{version}")
    int updateStock(@Param("productId") Long productId, @Param("quantity") int quantity, @Param("version") int version);
}

优劣势分析

优点：

实现简单，基于数据库版本号
无锁设计，并发性能好
适用于更新操作

缺点：

仅适用于更新操作
可能需要重试机制
实现复杂度较高

适用场景

库存扣减
数据更新
状态变更

3. 方案比较

方案	实现复杂度	性能	可靠性	适用场景	依赖
基于数据库唯一索引	低	中	高	插入操作	数据库
基于Token令牌	中	高	高	各种操作	Redis
基于分布式锁	高	中	高	并发操作	Redis/Zookeeper
基于Redis实现	中	高	高	各种操作	Redis
基于乐观锁	中	高	中	更新操作	数据库

4. 最佳实践

4.1 选择合适的方案

插入操作：优先使用基于数据库唯一索引的方案
更新操作：优先使用基于乐观锁的方案
高频接口：优先使用基于Redis的方案
并发操作：优先使用基于分布式锁的方案
通用场景：优先使用基于Token令牌的方案

4.2 性能优化

合理设置过期时间：根据业务场景设置适当的过期时间
批量处理：对于批量操作，考虑批量验证幂等性
异步处理：对于耗时操作，考虑异步处理幂等性验证
缓存优化：使用Redis集群提高性能和可靠性

4.3 安全性考虑

防止Token泄露：使用HTTPS传输Token
防止暴力破解：限制Token验证失败次数
防止重放攻击：使用时间戳或随机数
数据加密：对敏感数据进行加密存储

4.4 代码示例：综合方案

@RestController
@RequestMapping("/api/payment")
public class PaymentController {
    @Autowired
    private IdempotentTokenService idempotentTokenService;
    @Autowired
    private PaymentService paymentService;
    
    @GetMapping("/token")
    public ResponseEntity<String> getToken() {
        String token = idempotentTokenService.generateToken();
        return ResponseEntity.ok(token);
    }
    
    @PostMapping
    public ResponseEntity<Payment> processPayment(@RequestHeader("X-Idempotent-Token") String token, 
                                               @RequestBody PaymentRequest request) {
        // 1. 验证Token
        if (!idempotentTokenService.validateToken(token)) {
            return ResponseEntity.badRequest().body(null);
        }
        
        // 2. 处理支付
        Payment payment = paymentService.processPayment(request);
        return ResponseEntity.ok(payment);
    }
}

@Service
public class PaymentService {
    @Autowired
    private DistributedLockService distributedLockService;
    @Autowired
    private PaymentMapper paymentMapper;
    
    public Payment processPayment(PaymentRequest request) {
        String lockKey = "payment_lock:" + request.getOrderNo();
        
        try {
            // 3. 获取分布式锁
            if (!distributedLockService.tryLock(lockKey, 30000)) {
                throw new BusinessException("支付处理中，请稍后再试");
            }
            
            // 4. 检查是否已支付
            Payment existingPayment = paymentMapper.selectByOrderNo(request.getOrderNo());
            if (existingPayment != null && existingPayment.getStatus() == 1) {
                return existingPayment;
            }
            
            // 5. 处理支付逻辑
            Payment payment = new Payment();
            payment.setOrderNo(request.getOrderNo());
            payment.setAmount(request.getAmount());
            payment.setStatus(1);
            payment.setCreateTime(new Date());
            
            paymentMapper.insert(payment);
            return payment;
        } finally {
            // 6. 释放锁
            distributedLockService.releaseLock(lockKey);
        }
    }
}

5. 总结

幂等性是API设计中非常重要的特性，它确保了系统的可靠性和一致性。在SpringBoot应用中，我们可以通过多种方式实现接口幂等性：

基于数据库唯一索引：简单可靠，适用于插入操作
基于Token令牌：灵活通用，适用于各种操作
基于分布式锁：支持并发，适用于复杂场景
基于Redis实现：性能优异，适用于高频接口
基于乐观锁：无锁设计，适用于更新操作

在实际应用中，我们应该根据具体的业务场景选择合适的实现方案，也可以结合多种方案来提高系统的可靠性和性能。

通过合理的幂等性设计，可以有效防止重复请求导致的问题，提高系统的稳定性和用户体验。

以上就是SpringBoot中接口幂等性的5种实现方法详解的详细内容，更多关于SpringBoot接口幂等性的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

Java 获取Word中所有的插入和删除修订的方法
这篇文章主要介绍了Java 获取Word中所有插入和删除修订，在 Word 文档中启用跟踪更改功能后，会记录文档中的所有编辑行为，例如插入、删除、替换和格式更改。对插入或删除的内容，本文介绍获取方法,需要的朋友可以参考下
2022-04-04
linux的shell命令检测某个java程序是否执行
ps -ef |grep java|grep
2016-04-04
在Java中实现让线程按照自己指定的顺序执行
这篇文章主要介绍了在Java中实现让线程按照自己指定的顺序执行，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-06-06
一篇文章教你使用SpringBoot如何实现定时任务
这篇文章主要给大家介绍了关于如何利用一篇文章教你使用SpringBoot实现定时任务的相关资料，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-10-10
SpringBoot获取http数据、打印HTTP参数的4种方式
Java的话本地打断点可以调试获取rest入参,但是在生产环境可能我们获取入参（Http header/parameter）可能就没有那么的轻松了,所以本文给大家介绍了SpringBoot获取http数据、打印HTTP参数的4种方式,需要的朋友可以参考下
2024-03-03
深入理解java中的拷贝机制
这篇文章主要给大家深入介绍了java中的拷贝机制，网上关于java中拷贝的文章也很多，但觉得有必要再深的介绍下java的拷贝机制，有需要的朋友可以参考学习，下面来一起看看吧。
2017-02-02
Java自带的加密类MessageDigest类代码示例
这篇文章主要介绍了Java自带的加密类MessageDigest类代码示例，分享了常见的三种加密方式代码示例，具有一定参考价值，需要的朋友可以了解下。
2017-11-11
Java如何实现图片裁剪预览功能
通常注册账户上传用户图像时需要进行预览，这篇文章就是教我们如何用 Java 实现图片裁剪预览功能，需要的朋友可以参考下
2015-07-07
自己写的简易版Java日志类分享
这篇文章主要介绍了自己写的简易版Java日志类分享,本文直接给出实现代码,需要的朋友可以参考下
2015-06-06
SpringBoot中JPA更新时部分字段无效
本文主要介绍了SpringBoot中JPA更新时部分字段无效，在通过注解自动更新时，部分字段在调试时可以找到，却没有被自动更新到数据库中，下面就介绍一下解决方法
2023-04-04