零、前言

​ 业务接口幂等问题是在开发中遇到的，如果对业务接口代码不进行幂等控制，并且在前端没有对请求进行限制的情况下，可能会出现多次对接口调用，导致错误异常的发生。就上述情况，对PIGX自带的业务接口幂等实现进行了相关的学习，相关具体内容可以参考官方文档，本文章只是作为学习笔记。

一、接口幂等概念

幂等性原本是数学上的概念，在数学中表示对同一操作的多次执行，产生的结果与仅执行一次的结果相同。

用在接口上就可以理解为：同一个接口，多次发出同一个请求，必须保证操作只执行一次。 调用接口发生异常并且重复尝试时，总是会造成系统所无法承受的损失，所以必须阻止这种现象的发生。

实现接口幂等性通常需要考虑以下几个方面：

①请求参数：确保接口请求中的所有参数都是唯一的，不能重复。比如，在生成订单编号时可以使用时间戳或随机数等方式来保证唯一性

②接口设计：接口应该设计为“幂等性操作”，即无论调用多少次，结果都应该相同。例如，修改密码的接口应该设计为只能修改一次，多次修改的请求会被忽略。

③数据库操作：如果接口需要对数据库进行操作，需要确保每次操作都是幂等的。可以通过添加唯一索引或使用乐观锁等方式来避免重复操作

④错误处理：当请求出现异常时，接口应该处理异常并返回相应的错误信息。例如，当订单已经存在时，接口应该返回订单已存在的错误信息，而不是尝试再次创建订单

二、PIGX中具体实现方式

1、依赖的引入

情况①：

如果是其他项目，可以从中央仓库中引入PIGX提供的实现接口幂等的依赖

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

引入后的包内容如下所示

情况②：

如果项目中原先使用的就是pigx框架，那么在基础平台中的pigx-common-idempotent就已经自带

我们只需要引入pigx-common服务，就可以将实现接口幂等的依赖引入

2、Redis的配置

在配置文件中进行Redis的配置，设置redis存为我们的缓存中间件

通过如下配置，Spring框架会自动启用Redis作为缓存，并将Redis服务器的连接信息配置为指定的主机名和端口号

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

①spring.cache 对应的配置类是CacheProperties，这个配置项用来指定缓存的类型。在上述示例中，我们将缓存类型设置为Redis，表示使用Redis作为缓存。

② spring.data.redis：这个配置项用来指定连接Redis所需的参数。在上述示例中，我们指定了Redis服务器的主机名为127.0.0.1，端口号为`6379

3、具体使用示例

pigx主要是通过AOP去实现业务接口幂等，其最核心的就是其Idempotent注解，其使用示例如下：

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

通过使用@Idempotent注解，当多次请求进入test方法时，框架会根据key生成的唯一标识符判断是否已经执行过相同的请求。如果已经执行过，则直接返回之前的结果；如果没有执行过，则继续执行业务逻辑。

这样可以避免重复查询或操作带来的额外开销，并确保系统在重复请求时的一致性和可靠性。

三、原理分析

1、目录结构说明

对于PIGX自带的幂等插件idempotent的目录结构如下所示：

各目录内容说明如下：

- annotation     // 关于@Idempotent注解的声明- @Idempotent
- aspect		 // 关于AOP的切面方法- IdempotentAspect
- exception		 // 自定义异常类- IdempotentException
- expression	 // sqel表达式的解析工具- ExpressionResolver- KeyResolver
- IdempotentAutoConfiguration   //幂等插件配置文件- org.springframework.boot.autoconfigure.AutoConfiguration.imports   //springboot自动配置文件

2、@idempotent 注解 配置详细说明

2.1、@idempotent注解源码

@Inherited
@Target(ElementType.METHOD)
@Retention(value = RetentionPolicy.RUNTIME)
public @interface Idempotent {/*** 幂等操作的唯一标识，使用spring el表达式 用#来引用方法参数* @return Spring-EL expression*/String key() default "";/*** 有效期 默认：1 有效期要大于程序执行时间，否则请求还是可能会进来* @return expireTime*/int expireTime() default 1;/*** 时间单位 默认：s* @return TimeUnit*/TimeUnit timeUnit() default TimeUnit.SECONDS;/*** 提示信息，可自定义* @return String*/String info() default "重复请求，请稍后重试";/*** 是否在业务完成后删除key true:删除 false:不删除* @return boolean*/boolean delKey() default false;}

①key

key参数用于生成幂等性的唯一标识符，用于识别不同的请求或操作.具体来说，当多个请求或操作需要进行幂等性处理时，每个请求或操作需要有一个唯一的标识符来区分。这个标识符可以是请求参数、请求头信息、用户ID等等，根据实际场景而定。

在示例中，我们使用了SpEL表达式#demo.username作为唯一标识符，表示使用Demo对象的username属性作为标识符。也就是说，当多个请求的demo对象的username属性相同时，这些请求被认为是重复的，并且只有第一个请求会被执行，后续的请求会直接返回上次执行的结果。

②expireTime

幂等性键过期时间，单位为秒

③timeUnit

用于设置幂等性键过期时间的单位，默认是秒

④info

用于描述幂等性操作的提示信息，在某些情况下，当出现重复请求时，我们需要向客户端返回一些提示信息，告知客户端该请求已经被处理过，不能重复提交。因此，通过设置info参数，我们可以自定义提示信息，以便更好地向客户端反馈信息。

⑤delKey

是否在业务完成后删除key true:删除 false:不删除， 默认为false。

3、IdempotentAspect

3.1、IdempotentAspect源码及相关解析：

/*** The Idempotent Aspect** @author ITyunqing*///Spring框架中用于声明切面（Aspect）的注解
//通过在类上添加@Aspect注解，将其标识为一个切面类。切面类中可以包含各种通知（advice）和切点（pointcut），用于定义切面的具体行为和拦截规则
@Aspect
public class IdempotentAspect {//通过slf4j的LoggerFactory（日志工厂）创建一个Logger对象，用于在IdempotentAspect类中记录日志信息private static final Logger LOGGER = LoggerFactory.getLogger(IdempotentAspect.class);//创建一个名为THREAD_CACHE的私有的静态常量ThreadLocal对象//指定了泛型类型为Map<String, Object>，表示该ThreadLocal对象存储的值是一个键值对的映射//通过ThreadLocal类的withInitial方法，传入一个Supplier接口实例，该Supplier接口用于提供初始值。在这里，使用HashMap::new作为Supplier接口的实现，创建一个新的HashMap作为初始值。private static final ThreadLocal<Map<String, Object>> THREAD_CACHE = ThreadLocal.withInitial(HashMap::new);//定义了一个常量字符串变量RMAPCACHE_KEY，表示缓存中的键名，用于在缓存中存储幂等性相关的数据private static final String RMAPCACHE_KEY = "idempotent";//定义了一个常量字符串变量KEY，表示幂等性数据的键名，用于在幂等性相关的数据中标识唯一的幂等性请求private static final String KEY = "key";//定义了一个常量字符串变量DELKEY，表示删除缓存数据的键名，用于在缓存中标识需要删除的幂等性数据private static final String DELKEY = "delKey";//通过spring的自动装配功能，将Redisson对象注入到当前类中@Autowiredprivate Redisson redisson;//通过spring的自动装配功能，将KeyResolver对象注入到当前类中@Autowiredprivate KeyResolver keyResolver;//通过spring的自动装配功能，将一个Optional<KeyStrResolver>对象注入到当前类中//KeyStrResolver的一个可选注入项，它可以包含一个非空的值，也可以为空@Autowiredprivate Optional<KeyStrResolver> keyStrResolverOptional;//该注解表示定义一个切入点，使用@annotation表达式来匹配被指定注解标记的方法。在这里，切入点匹配的条件是被com.pig4cloud.pigx.common.idempotent.annotation.Idempotent注解标记的方法@Pointcut("@annotation(com.pig4cloud.pigx.common.idempotent.annotation.Idempotent)")//这是一个空方法体，作为切入点的定义。它没有任何实际的逻辑操作，只是用来定义一个切入点的名称public void pointCut() {}//切面的前置通知（@Before）：它在切入点方法执行之前被调用@Before("pointCut()")public void beforePointCut(JoinPoint joinPoint) {//通过RequestContextHolder类可以获取当前线程的RequestAttributes对象//将获取到的RequestAttributes对象强制转换为ServletRequestAttributes类型。ServletRequestAttributes是RequestAttributes的子接口，扩展了一些与Servlet请求相关的方法和属性ServletRequestAttributes requestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();//获取当前请求的 HttpServletRequest 对象HttpServletRequest request = requestAttributes.getRequest();//将 joinPoint 转换为 MethodSignature 对象MethodSignature signature = (MethodSignature) joinPoint.getSignature();//通过 MethodSignature 对象获取到当前方法的 Method 对象Method method = signature.getMethod();//如果当前方法上没有使用注解@Idempotent，则return返回if (!method.isAnnotationPresent(Idempotent.class)) {return;}//如果当前方法上有使用注解@Idempotent，获得该注解信息//通过调用 getAnnotation() 方法并传入 Idempotent.class 作为参数，可以获取到该方法上的 Idempotent 注解的实例对象Idempotent idempotent = method.getAnnotation(Idempotent.class);String key;// 若没有配置 幂等 标识编号，则使用 url + 参数列表作为区分（作为生成幂等性的唯一标识符）if (!StringUtils.hasLength(idempotent.key())) {String url = request.getRequestURL().toString();String argString = Arrays.asList(joinPoint.getArgs()).toString();key = url + argString;}else {// 使用jstl 规则区分（具体会在expression中进行讲解）key = keyResolver.resolver(idempotent, joinPoint);}//StrUtil.COLON：字符串常量：冒号 {@code ":"}//如果keyStrResolverOptional存在，则设置key的值为KeyStrResolver调用extract(key, StrUtil.COLON)方法的结果值//即在原先key的基础的前面加上租户id：if (keyStrResolverOptional.isPresent()) {key = keyStrResolverOptional.get().extract(key, StrUtil.COLON);}//获取注解idempotent的有效期long expireTime = idempotent.expireTime();//获取注解idempotent的提示信息String info = idempotent.info();//获取注解idempotent的时间单位TimeUnit timeUnit = idempotent.timeUnit();//获取注解idempotent的是否在业务完成后删除keyboolean delKey = idempotent.delKey();// do not need check null//RMapCache 是 Redisson 提供的一个接口，用于表示一个带有过期时间的分布式 Map 缓存，RMapCache 继承自 RMap 接口，提供了一些额外的方法，可以设置和获取缓存的过期时间，以及进行相关的缓存操作//通过 redisson 对象调用 getMapCache(RMAPCACHE_KEY) 方法，传入参数 RMAPCACHE_KEY 来获取对应的缓存对象//RMAPCACHE_KEY 是表示缓存的键值，可能是一个字符串或其他适当的类型RMapCache<String, Object> rMapCache = redisson.getMapCache(RMAPCACHE_KEY);//获取当前系统的时间，并将其转化为字符串，将其中的T替换为“ ”String value = LocalDateTime.now().toString().replace("T", " ");Object v1;//如果当前对应的键key已经有缓存对象，则抛出异常，异常信息为"[idempotent]:" + infoif (null != rMapCache.get(key)) {// had storedthrow new IdempotentException("[idempotent]:" + info);}//使用 synchronized 关键字来对代码块进行同步，确保在多线程环境下的安全性//通过 synchronized(this) 来锁定当前对象，以保证同一时间只有一个线程可以进入这个代码块synchronized (this) {//将键值对放入缓存中//该方法会返回之前关联到 key 上的值，如果该值为 null，则表示插入成功v1 = rMapCache.putIfAbsent(key, value, expireTime, timeUnit);//如果 v1 不为 null，即 putIfAbsent 返回了一个非空值，说明之前已经存在相同的键值对，此时抛出一个 IdempotentException 异常，表示幂等性校验失败if (null != v1) {throw new IdempotentException("[idempotent]:" + info);}//如果 v1 为 null，表示 putIfAbsent 成功插入了新的键值对，记录一条日志信息，并打印当前存储的 key、value、过期时间等信息else {LOGGER.info("[idempotent]:has stored key={},value={},expireTime={}{},now={}", key, value, expireTime,timeUnit, LocalDateTime.now().toString());}}//在当前线程中使用 ThreadLocal 来创建一个线程本地的 Map 对象，并将 key 和 delKey 存储到其中//通过 THREAD_CACHE.get() 方法获取当前线程绑定的 Map<String, Object> 对象，存储到 map 变量中Map<String, Object> map = THREAD_CACHE.get();//将键值对 KEY 和对应的变量 key 存储到 map 中map.put(KEY, key);//将键值对 DELKEY 和对应的变量 delKey 存储到 map 中map.put(DELKEY, delKey);}//切面的后置通知（@After）：它在切入点方法执行之后被调用@After("pointCut()")public void afterPointCut(JoinPoint joinPoint) {//从当前线程中获取之前存储的 map 对象，并将其存储到 map 变量中Map<String, Object> map = THREAD_CACHE.get();//判断 map 是否为空，如果为空，则直接返回，不执行后续操作if (CollectionUtils.isEmpty(map)) {return;}//获取一个名为 RMAPCACHE_KEY 的 RMapCache<Object, Object> 实例RMapCache<Object, Object> mapCache = redisson.getMapCache(RMAPCACHE_KEY);//判断该 RMapCache 是否为空。如果为空，则直接返回，不执行后续操作if (mapCache.size() == 0) {return;}//从 map 中获取 key ，并将 key 转换为字符串类型保存到 key 变量中String key = map.get(KEY).toString();//从 map 中获取 delKey， 将 delKey 强制转换为布尔型保存到 delKey 变量中boolean delKey = (boolean) map.get(DELKEY);//delKey为真，则调用 mapCache.fastRemove(key) 方法从 RMapCache 中删除指定的键值对，并记录一条日志信息if (delKey) {mapCache.fastRemove(key);LOGGER.info("[idempotent]:has removed key={}", key);}//从当前线程中删除 map 对象。这样做是为了避免在下次请求时出现数据混淆的情况THREAD_CACHE.remove();}}

3.2、相关内容补充

① ThreadLocal

ThreadLocal 是一个 Java 类，它提供了线程局部变量的支持。每个线程都可以独立地访问和修改自己的线程局部变量，而不会干扰其他线程的变量。

使用 ThreadLocal 可以解决多线程并发访问共享变量时可能出现的线程安全问题。通过将数据存储在 ThreadLocal 对象中，每个线程都有自己独立的副本，线程之间的数据互不干扰。

在使用 ThreadLocal 时，通常的做法是创建一个 ThreadLocal 对象，并使用 set() 方法来设置当前线程的变量值，使用 get() 方法来获取当前线程的变量值。可以通过 remove() 方法来清除当前线程的变量值。

② Redisson

Redisson是一个Java Redis客户端，提供了简单易用的API接口，支持分布式锁、分布式集合、分布式对象等功能。它基于Redis客户端（Jedis、Lettuce）封装了一系列的分布式操作接口，使得Java开发者可以方便地使用Redis实现分布式应用程序。

Redisson的主要特点如下：

• 对Redis的高效封装：Redisson对Redis客户端进行了高效的封装，提供了简单易用的API接口，使得Java开发者可以方便地实现复杂的分布式应用程序。
• 分布式锁：Redisson提供了分布式锁的实现，支持可重入锁、公平锁、联锁、红锁等多种类型的锁，并且保证了锁的正确性和高可用性。
• 分布式集合：Redisson支持分布式Set、List、Queue、Deque、Map、SortedSet等集合类型的操作，可以方便地实现分布式计算、消息队列等功能。
• 分布式对象：Redisson支持分布式ExecutorService、ScheduledExecutorService、Semaphore、CountDownLatch、ReadWriteLock等对象类型的操作，可以方便地实现分布式任务调度、并发控制等功能。

③MethodSignature

在 Spring AOP 中，joinPoint 是一个连接点（即程序执行过程中能够插入额外代码的点），它封装了当前方法的相关信息，包括方法名、参数等。

MethodSignature 是 JoinPoint 的一个子类，它用于表示方法签名，即方法名和参数类型等信息。通过 MethodSignature 对象，我们可以获取到当前方法的 Method 对象，进而获取该方法的返回值类型、参数列表等信息。

④KeyStrResolver

其是一个接口，源码如下

public interface KeyStrResolver {/*** 字符串加工* @param in 输入字符串* @param split 分割符* @return 输出字符串*/String extract(String in, String split);/*** 字符串获取* @return 模块返回字符串*/String key();
}

其具体实现类TenantKeyStrResolver的源码如下所示

/*** @author lengleng* @date 2020/9/29* <p>* 租户字符串处理（方便其他模块获取）*/
public class TenantKeyStrResolver implements KeyStrResolver {/*** 传入字符串增加 租户编号:in* @param in 输入字符串* @param split 分割符* @return*/@Overridepublic String extract(String in, String split) {return TenantContextHolder.getTenantId() + split + in;}/*** 返回当前租户ID* @return*/@Overridepublic String key() {return String.valueOf(TenantContextHolder.getTenantId());}}

4、IdempotentException自定义异常类

4.1、IdempotentException自定义异常类源码

//RuntimeException 运行时异常的实现类
public class IdempotentException extends RuntimeException {//无参构造器public IdempotentException() {super();}//有参构造器1public IdempotentException(String message) {super(message);}//有参构造器2public IdempotentException(String message, Throwable cause) {super(message, cause);}//有参构造器3public IdempotentException(Throwable cause) {super(cause);}//有参构造器4protected IdempotentException(String message, Throwable cause, boolean enableSuppression,boolean writableStackTrace) {super(message, cause, enableSuppression, writableStackTrace);}}

5、唯一标志处理器KeyResolver

5.1、 KeyResolver源码及解析

其中定义了一个解析处理key的抽象方法

public interface KeyResolver {/*** 解析处理 key* @param idempotent 接口注解标识* @param point 接口切点信息* @return 处理结果*/String resolver(Idempotent idempotent, JoinPoint point);}

5.2、ExpressionResolver源码及其解析

ExpressionResolver是KeyResolver的实现类，其主要的作用就是进行key的抽取，优先根据 spel 处理

/*** @author lengleng* <p>* 默认key 抽取， 优先根据 spel 处理* @date 2020-09-25*/
public class ExpressionResolver implements KeyResolver {//创建一个 SpEL 表达式解析器实例SpelExpressionParserprivate static final SpelExpressionParser PARSER = new SpelExpressionParser();//创建一个 LocalVariableTableParameterNameDiscoverer 对象，用于获取方法参数的名称private static final LocalVariableTableParameterNameDiscoverer DISCOVERER = new LocalVariableTableParameterNameDiscoverer();//重写父类keyResolver的resolver方法@Overridepublic String resolver(Idempotent idempotent, JoinPoint point) {//通过 point.getArgs() 获取方法的参数数组Object[] arguments = point.getArgs();// 获取方法参数的名称数组String[] params = DISCOVERER.getParameterNames(getMethod(point));//创建一个 StandardEvaluationContext 对象，用于提供表达式求值的上下文环境StandardEvaluationContext context = new StandardEvaluationContext();//如果方法参数的名称数组不为空且长度大于 0，则遍历参数名称数组，将参数名和对应的参数值存储到 context 中if (params != null && params.length > 0) {for (int len = 0; len < params.length; len++) {context.setVariable(params[len], arguments[len]);}}//使用 PARSER.parseExpression(idempotent.key()) 解析 idempotent.key() 字符串为一个 SpEL 表达式，并返回一个 Expression 对象Expression expression = PARSER.parseExpression(idempotent.key());//调用 Expression 对象的 getValue() 方法，传入 context 和期望的结果类型 String.class，以获取表达式的求值结果return expression.getValue(context, String.class);}/*** 根据切点解析方法信息* @param joinPoint 切点信息* @return Method 原信息*/private Method getMethod(JoinPoint joinPoint) {//通过 joinPoint.getSignature() 获取切入点的方法签名，然后将其转换为 MethodSignature 类型，并赋值给 signature 变量MethodSignature signature = (MethodSignature) joinPoint.getSignature();//从方法签名中获取切入点方法，并赋值给 method 变量Method method = signature.getMethod();//判断切入点方法所在的类是否是一个接口。如果是接口，则执行以下代码块if (method.getDeclaringClass().isInterface()) {try {//通过 joinPoint.getTarget().getClass() 获取切入点目标对象的类，并使用该类调用 getDeclaredMethod() 方法来获取具体实现类中与切入点方法相同名称和参数类型的方法，并将得到的方法赋值给 method 变量method = joinPoint.getTarget().getClass().getDeclaredMethod(joinPoint.getSignature().getName(),method.getParameterTypes());}catch (SecurityException | NoSuchMethodException e) {//如果在获取具体实现类中的方法时抛出了 SecurityException 或 NoSuchMethodException 异常，会捕获并抛出一个具有该异常的 RuntimeException 异常throw new RuntimeException(e);}}//返回获取到的方法对象return method;}}

6、幂等插件配置文件IdempotentAutoConfiguration

6.1、配置文件源码

//标记该类为配置类
//proxyBeanMethods = false，表示Spring 将不会为配置类的方法生成代理对象，这样可以避免额外的代理开销
@Configuration(proxyBeanMethods = false)
//指定在特定自动配置类RedisAutoConfiguration之后进行自动配置
@AutoConfigureAfter(RedisAutoConfiguration.class)
public class IdempotentAutoConfiguration {/*** 生成IdempotentAspect切面类的bean实例* 切面 拦截处理所有 @Idempotent* @return Aspect*/@Beanpublic IdempotentAspect idempotentAspect() {return new IdempotentAspect();}/*** 生成key 解析器的bean实例* key 解析器* @return KeyResolver*/@Bean@ConditionalOnMissingBean(KeyResolver.class)public KeyResolver keyResolver() {return new ExpressionResolver();}}

7、AutoConfiguration.imports

7.1、源码

com.pig4cloud.pigx.common.idempotent.IdempotentAutoConfiguration

7.2、作用

org.springframework.boot.autoconfigure.AutoConfiguration.imports 是一个 Spring Boot 的属性，用于指定需要在自动配置类中导入的其他配置类。

在 Spring Boot 中，自动配置是一种机制，它根据应用程序的依赖和配置信息，自动创建并配置相应的 Bean 实例。而 AutoConfiguration.imports 属性则提供了一种扩展机制，允许开发人员在自动配置类中导入其他配置类，以实现更为灵活和定制化的自动配置。

具体来说，AutoConfiguration.imports 属性是一个字符串数组，每个元素表示一个需要导入的配置类的全限定名。在自动配置过程中，Spring Boot 会自动加载这些配置类，并将它们合并到当前上下文中，以实现更全面的自动配置。

8、补充

1.请求开始前，根据key查询 查到结果：报错 | 未查到结果：存入key-value-expireTime

2.请求结束后，直接删除key ，不管key是否存在，直接删除 是否删除，可配置

3.expireTime过期时间，防止一个请求卡死，会一直阻塞，超过过期时间，自动删除

过期时间要大于业务执行时间，需要大概评估下;

4.此方案直接切的是接口请求层面。

5.过期时间需要大于业务执行时间，否则业务请求1进来还在执行中，前端未做遮罩，或者用户跳转页面后再回来做重复请求2，在业务层面上看，结果依旧是不符合预期的。

6.建议delKey = false。即使业务执行完，也不删除key，强制锁expireTime的时间。预防5的情况发生。

7.实现思路：同一个请求ip和接口，相同参数的请求，在expireTime内多次请求，只允许成功一次。

8.页面做遮罩，数据库层面的唯一索引，先查询再添加，等处理方式应该都处理下。

9.此注解只用于幂等，不用于锁，100个并发这种压测，会出现问题，在这种场景下也没有意义，实际中用户也不会出现1s或者3s内手动发送了50个或者100个重复请求,或者弱网下有100个重复请求；