​
什么是接口幂等性？

幂等性原本是数学上的概念，用在接口上就可以理解为：同一个接口，多次发出同一个请求，必须保证操作只执行一次。

调用接口发生异常并且重复尝试时，总是会造成系统所无法承受的损失，所以必须阻止这种现象的发生。

​
快速开始

1

引入依赖

在项目的 pom.xml 文件中添加幂等组件依赖：

<dependency>
    <groupId>com.pig4cloud.plugin</groupId>
    <artifactId>idempotent-spring-boot-starter</artifactId>
    <version>0.6.0</version>
</dependency>
2

配置 Redis 连接

在 application.yml 中配置 Redis 相关信息：

spring:
  cache:
    type: redis
  data:
    redis:
      host: 127.0.0.1
      port: 6379

理论上支持 redisson-spring-boot-starter 的全部配置项

3

添加幂等注解

在需要保证幂等性的接口方法上添加 @Idempotent 注解：

@Idempotent(key = "#demo.username", expireTime = 3, info = "请勿重复查询")
@GetMapping("/test")
public String test(Demo demo) {
    return "success";
}

​
注解配置详解

​
异常处理

当幂等性触发后，切面会抛出 IdempotentException 异常。需要在全局异常处理器中捕获此异常并处理。

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(IdempotentException.class)
    public ResponseEntity<String> handleIdempotentException(IdempotentException ex) {
        // 处理幂等异常，返回自定义的错误信息或业务逻辑
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(ex.getMessage());
    }
}

​
实现原理

​
最佳实践

@Idempotent(
    key = "#userId", 
    expireTime = 5, 
    timeUnit = TimeUnit.SECONDS,
    info = "操作过于频繁，请稍后重试",
    delKey = false
)
@PostMapping("/submit")
public Result submit(@RequestParam Long userId, @RequestBody SubmitData data) {
    // 业务逻辑
    return Result.success();
}

​
源码地址

GitHub 仓库

点击查看完整源码实现和更多示例

​
♥️ 获取支持

遇到问题？

如果您在使用过程中遇到任何问题、有功能建议或需求，请点击此卡片前往 Gitee 仓库提交 Issue。