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

作者：袖梨 2026-07-21

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