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

来源：互联网 2026-07-22 08:05:08

摘要介绍了接口幂等性的概念与重要性，分析了网络波动、客户端重试等引发重复请求的场景，并指出支付、订单创建等接口对幂等性的高要求。重点阐述了四种实现方案：基于数据库唯一索引、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令牌

实现原理

该方案较为经典，流程清晰：

客户端先请求获取一个令牌
服务端生成唯一令牌并存储（通常放入Redis）
客户端携带令牌发起实际请求
服务端验证令牌是否存在，存在则执行操作并删除令牌
重复请求因令牌已被删除而直接拒绝

核心源码

Token生成与验证：

@Component
public class IdempotentTokenService {
    @Autowired
    private RedisTemplate 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 getToken() {
        String token = idempotentTokenService.generateToken();
        return ResponseEntity.ok(token);
    }
    
    /**
     * 创建订单
     */
    @PostMapping
    public ResponseEntity 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 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）创建一个"去重标记"。如果标记已存在，说明请求已被处理，直接拒绝。该方案与Token方案类似，但更加轻量，无需提前获取令牌。

核心源码

Redis幂等性服务：

@Component
public class RedisIdempotentService {
    @Autowired
    private RedisTemplate 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服务
需要合理设置过期时间
键的设计需要考虑唯一性

适用场景

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

方案五：基于乐观锁

实现原理

乐观锁通常依赖版本号（version字段）或时间戳。每次更新时检查版本号是否与之前读取的一致，一致则更新并将版本号加1，不一致则说明数据已被其他请求修改，更新失败。这种方式避免了锁竞争，但需要业务方处理重试。

核心源码

数据库表设计：

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 性能优化

合理设置过期时间：根据业务场景设置适当的过期时间，过短可能导致重复请求漏过，过长则浪费存储资源
批量处理：对于批量操作，考虑批量验证幂等性，减少多次IO
异步处理：对于耗时操作，考虑异步处理幂等性验证，避免阻塞主流程
缓存优化：使用Redis集群提高性能和可靠性，避免单点故障

4.3 安全性考虑

防止Token泄露：使用HTTPS传输Token，避免中间人截获
防止暴力破解：限制Token验证失败次数，防止恶意枚举
防止重放攻击：使用时间戳或随机数，确保每次请求具有唯一性
数据加密：对敏感数据进行加密存储，避免数据泄露风险

4.4 代码示例：综合方案

在实际项目中，通常不会只使用单一方案，而是组合运用。例如以下支付接口，同时使用了Token令牌与分布式锁，形成双重保障：

@RestController
@RequestMapping("/api/payment")
public class PaymentController {
    @Autowired
    private IdempotentTokenService idempotentTokenService;
    @Autowired
    private PaymentService paymentService;
    
    @GetMapping("/token")
    public ResponseEntity getToken() {
        String token = idempotentTokenService.generateToken();
        return ResponseEntity.ok(token);
    }
    
    @PostMapping
    public ResponseEntity 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);
        }
    }
}