SpringBoot实现接口幂等性的5种方案

学亮编程手记

已于 2025-05-06 13:37:27 修改

阅读量820

点赞数 20

CC 4.0 BY-SA版权

分类专栏：后台编程文章标签： spring boot 后端 java

于 2025-05-04 18:46:26 首次发布

本文链接：https://blog.csdn.net/a772304419/article/details/147702437

后台编程专栏收录该内容

1619 篇文章

订阅专栏

Spring Boot实现接口幂等性的全面指南

幂等性是分布式系统设计中的重要概念，特别是在Spring Boot应用中实现接口幂等性对于保证数据一致性和系统稳定性至关重要。下面我将详细介绍多种实现方案及其具体实现方式。

一、幂等性基础概念

幂等性是指对同一操作执行多次与执行一次的效果相同，不会因为重复执行而产生副作用。在实际应用中，由于网络延迟、用户重复点击提交、系统自动重试等原因，可能导致同一请求被多次发送到服务端处理，如果没有实现幂等性，就可能导致数据重复、业务异常等问题。

为什么需要幂等性

前端重复提交表单：用户因网络波动未收到响应而多次点击提交按钮
用户恶意刷单：如重复提交投票导致结果失真
接口超时重试：HTTP客户端默认开启超时重试机制
消息重复消费：消息中间件在消费者断开时重新放回队列

二、Spring Boot实现幂等性的主要方案

1. Token令牌机制（推荐方案）

Token令牌策略是最常见的幂等性实现方式之一。

实现步骤：

客户端先调用获取token接口
服务端生成唯一token并存入Redis，设置过期时间
客户端调用业务接口时附带token参数
服务端验证token存在性并删除，防止重复使用

代码实现：

@RestController
@RequestMapping("/api")
public class OrderController {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
        
    @Autowired
    private OrderService orderService;
        
    // 获取token接口
    @GetMapping("/token")
    public Result<String> getToken() {
        String token = UUID.randomUUID().toString();
        redisTemplate.opsForValue().set("idempotent:token:" + token, "1", 10, TimeUnit.MINUTES);
        return Result.success(token);
    }
        
    // 创建订单接口
    @PostMapping("/order")
    public Result<Order> createOrder(@RequestHeader("Idempotent-Token") String token, 
                                    @RequestBody OrderRequest request) {
        String key = "idempotent:token:" + token;
        Boolean exist = redisTemplate.hasKey(key);
        if (exist == null || !exist) {
            return Result.fail("令牌不存在或已过期");
        }
                
        if (Boolean.FALSE.equals(redisTemplate.delete(key))) {
            return Result.fail("令牌已被使用");
        }
                
        Order order = orderService.createOrder(request);
        return Result.success(order);
    }
}

使用AOP简化实现：

// 自定义幂等性注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
    long timeout() default 10; // 过期时间，单位分钟
}

// AOP实现
@Aspect
@Component
public class IdempotentAspect {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
        
    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable {
        HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
        String token = request.getHeader("Idempotent-Token");
                
        if (StringUtils.isEmpty(token)) {
            throw new BusinessException("幂等性Token不能为空");
        }
                
        String key = "idempotent:token:" + token;
        Boolean exist = redisTemplate.hasKey(key);
                
        if (exist == null || !exist) {
            throw new BusinessException("令牌不存在或已过期");
        }
                
        if (Boolean.FALSE.equals(redisTemplate.delete(key))) {
            throw new BusinessException("令牌已被使用");
        }
                
        return joinPoint.proceed();
    }
}

2. 数据库唯一约束

利用数据库中主键唯一约束的特性实现幂等性。

实现方式：

使用分布式ID充当主键而非自增主键
插入数据时如果主键已存在则抛出异常

示例：

CREATE TABLE `order` (
  `id` int NOT NULL AUTO_INCREMENT,
  `order_no` varchar(32) NOT NULL DEFAULT '' COMMENT '订单号(唯一)',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uq_order_no` (`order_no`) COMMENT '唯一约束'
) ENGINE=InnoDB;

优缺点：

优点：实现简单，不需要额外编码
缺点：只适用于插入操作，需要处理异常

3. 乐观锁机制

通过版本号控制实现更新操作的幂等性。

实现方式：

数据表添加version字段
更新时带上版本号条件

示例：

UPDATE my_table 
SET price=price+50, version=version+1 
WHERE id=1 AND version=5

优缺点：

优点：适用于更新操作，实现简单
缺点：需要修改表结构，高并发时可能失败率高

4. 分布式锁

使用Redis或Zookeeper实现分布式锁保证幂等性。

Redis实现示例：

public String createOrder(OrderRequest request) {
    String lockKey = "order_lock:" + request.getOrderNo();
    String clientId = UUID.randomUUID().toString();
    
    try {
        // 尝试获取锁
        Boolean result = redisTemplate.opsForValue()
            .setIfAbsent(lockKey, clientId, 30, TimeUnit.SECONDS);
        
        if (!Boolean.TRUE.equals(result)) {
            throw new BusinessException("请勿重复提交订单");
        }
        
        // 执行业务逻辑
        return orderService.createOrder(request);
    } finally {
        // 释放锁
        if (clientId.equals(redisTemplate.opsForValue().get(lockKey))) {
            redisTemplate.delete(lockKey);
        }
    }
}

优缺点：

优点：适用于分布式环境
缺点：实现复杂，性能开销较大

5. 状态机控制

适用于有状态流转的业务场景，如订单状态。

实现方式：

定义状态枚举和状态流转规则
更新时校验当前状态是否允许流转到目标状态

示例：

public enum OrderStatus {
    UN_PAID(0, "待支付"),
    PAID(1, "已支付"),
    CANCELED(2, "已取消");
    
    // 省略构造函数和getter
}

public void cancelOrder(Long orderId) {
    Order order = orderRepository.findById(orderId);
    if (order.getStatus() != OrderStatus.UN_PAID) {
        throw new BusinessException("只有待支付订单才能取消");
    }
    order.setStatus(OrderStatus.CANCELED);
    orderRepository.save(order);
}

三、方案对比与选型建议

方案	适用场景	优点	缺点	实现复杂度
Token令牌	所有操作	通用性强，安全性高	需要额外接口获取token	中等
唯一约束	插入操作	实现简单	只适用于插入	低
乐观锁	更新操作	实现简单	需要修改表结构	低
分布式锁	分布式环境	适用于分布式系统	性能开销大	高
状态机	有状态流转的业务	业务逻辑清晰	只适用于特定场景	中等