业务接口幂等问题是在开发中遇到的,如果对业务接口代码不进行幂等控制,并且在前端没有对请求进行限制的情况下,可能会出现多次对接口调用,导致错误异常的发生。就上述情况,对PIGX自带的业务接口幂等实现进行了相关的学习,相关具体内容可以参考官方文档,本文章只是作为学习笔记。
幂等性原本是数学上的概念,在数学中表示对同一操作的多次执行,产生的结果与仅执行一次的结果相同。
用在接口上就可以理解为:同一个接口,多次发出同一个请求,必须保证操作只执行一次。 调用接口发生异常并且重复尝试时,总是会造成系统所无法承受的损失,所以必须阻止这种现象的发生。
实现接口幂等性通常需要考虑以下几个方面:
①请求参数:确保接口请求中的所有参数都是唯一的,不能重复。比如,在生成订单编号时可以使用时间戳或随机数等方式来保证唯一性
②接口设计:接口应该设计为“幂等性操作”,即无论调用多少次,结果都应该相同。例如,修改密码的接口应该设计为只能修改一次,多次修改的请求会被忽略。
③数据库操作:如果接口需要对数据库进行操作,需要确保每次操作都是幂等的。可以通过添加唯一索引或使用乐观锁等方式来避免重复操作
④错误处理:当请求出现异常时,接口应该处理异常并返回相应的错误信息。例如,当订单已经存在时,接口应该返回订单已存在的错误信息,而不是尝试再次创建订单
情况①:
如果是其他项目,可以从中央仓库中引入PIGX提供的实现接口幂等的依赖
<dependency>
<groupId>com.pig4cloud.plugingroupId>
<artifactId>idempotent-spring-boot-starterartifactId>
<version>0.4.0version>
dependency>
情况②:
如果项目中原先使用的就是pigx框架,那么在基础平台中的pigx-common-idempotent
就已经自带
我们只需要引入pigx-common
服务,就可以将实现接口幂等的依赖引入
在配置文件中进行Redis的配置,设置redis存为我们的缓存中间件
通过如下配置,Spring框架会自动启用Redis作为缓存,并将Redis服务器的连接信息配置为指定的主机名和端口号
spring:
cache:
type: redis
data:
redis:
host: 127.0.0.1
port: 6379
①spring.cache
对应的配置类是CacheProperties
,这个配置项用来指定缓存的类型。在上述示例中,我们将缓存类型设置为Redis,表示使用Redis作为缓存。
② spring.data.redis
:这个配置项用来指定连接Redis所需的参数。在上述示例中,我们指定了Redis服务器的主机名为127.0.0.1
,端口号为`6379
pigx主要是通过AOP去实现业务接口幂等,其最核心的就是其Idempotent
注解,其使用示例如下:
@Idempotent(key = "#demo.username", expireTime = 3, info = "请勿重复查询")
@GetMapping("/test")
public String test(Demo demo) {
return "success";
}
通过使用@Idempotent
注解,当多次请求进入test
方法时,框架会根据key
生成的唯一标识符判断是否已经执行过相同的请求。如果已经执行过,则直接返回之前的结果;如果没有执行过,则继续执行业务逻辑。
这样可以避免重复查询或操作带来的额外开销,并确保系统在重复请求时的一致性和可靠性。
对于PIGX
自带的幂等插件idempotent
的目录结构如下所示:
各目录内容说明如下:
- annotation // 关于@Idempotent注解的声明
- @Idempotent
- aspect // 关于AOP的切面方法
- IdempotentAspect
- exception // 自定义异常类
- IdempotentException
- expression // sqel表达式的解析工具
- ExpressionResolver
- KeyResolver
- IdempotentAutoConfiguration //幂等插件配置文件
- org.springframework.boot.autoconfigure.AutoConfiguration.imports //springboot自动配置文件
@idempotent
注解 配置详细说明@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。
IdempotentAspect
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,表示该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对象注入到当前类中
@Autowired
private Redisson redisson;
//通过spring的自动装配功能,将KeyResolver对象注入到当前类中
@Autowired
private KeyResolver keyResolver;
//通过spring的自动装配功能,将一个Optional对象注入到当前类中
//KeyStrResolver的一个可选注入项,它可以包含一个非空的值,也可以为空
@Autowired
private 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的是否在业务完成后删除key
boolean 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]:" + info
if (null != rMapCache.get(key)) {
// had stored
throw 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 对象,存储到 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
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();
}
}
① ThreadLocal
ThreadLocal 是一个 Java 类,它提供了线程局部变量的支持。每个线程都可以独立地访问和修改自己的线程局部变量,而不会干扰其他线程的变量。
使用 ThreadLocal 可以解决多线程并发访问共享变量时可能出现的线程安全问题。通过将数据存储在 ThreadLocal 对象中,每个线程都有自己独立的副本,线程之间的数据互不干扰。
在使用 ThreadLocal 时,通常的做法是创建一个 ThreadLocal 对象,并使用 set()
方法来设置当前线程的变量值,使用 get()
方法来获取当前线程的变量值。可以通过 remove()
方法来清除当前线程的变量值。
② Redisson
Redisson是一个Java Redis客户端,提供了简单易用的API接口,支持分布式锁、分布式集合、分布式对象等功能。它基于Redis客户端(Jedis、Lettuce)封装了一系列的分布式操作接口,使得Java开发者可以方便地使用Redis实现分布式应用程序。
Redisson的主要特点如下:
③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
*
* 租户字符串处理(方便其他模块获取)
*/
public class TenantKeyStrResolver implements KeyStrResolver {
/**
* 传入字符串增加 租户编号:in
* @param in 输入字符串
* @param split 分割符
* @return
*/
@Override
public String extract(String in, String split) {
return TenantContextHolder.getTenantId() + split + in;
}
/**
* 返回当前租户ID
* @return
*/
@Override
public String key() {
return String.valueOf(TenantContextHolder.getTenantId());
}
}
IdempotentException
自定义异常类IdempotentException
自定义异常类源码//RuntimeException 运行时异常的实现类
public class IdempotentException extends RuntimeException {
//无参构造器
public IdempotentException() {
super();
}
//有参构造器1
public IdempotentException(String message) {
super(message);
}
//有参构造器2
public IdempotentException(String message, Throwable cause) {
super(message, cause);
}
//有参构造器3
public IdempotentException(Throwable cause) {
super(cause);
}
//有参构造器4
protected IdempotentException(String message, Throwable cause, boolean enableSuppression,
boolean writableStackTrace) {
super(message, cause, enableSuppression, writableStackTrace);
}
}
KeyResolver
KeyResolver
源码及解析其中定义了一个解析处理key的抽象方法
public interface KeyResolver {
/**
* 解析处理 key
* @param idempotent 接口注解标识
* @param point 接口切点信息
* @return 处理结果
*/
String resolver(Idempotent idempotent, JoinPoint point);
}
ExpressionResolver
源码及其解析ExpressionResolver
是KeyResolver
的实现类,其主要的作用就是进行key的抽取,优先根据 spel 处理
/**
* @author lengleng
*
* 默认key 抽取, 优先根据 spel 处理
* @date 2020-09-25
*/
public class ExpressionResolver implements KeyResolver {
//创建一个 SpEL 表达式解析器实例SpelExpressionParser
private static final SpelExpressionParser PARSER = new SpelExpressionParser();
//创建一个 LocalVariableTableParameterNameDiscoverer 对象,用于获取方法参数的名称
private static final LocalVariableTableParameterNameDiscoverer DISCOVERER = new LocalVariableTableParameterNameDiscoverer();
//重写父类keyResolver的resolver方法
@Override
public 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;
}
}
IdempotentAutoConfiguration
//标记该类为配置类
//proxyBeanMethods = false,表示Spring 将不会为配置类的方法生成代理对象,这样可以避免额外的代理开销
@Configuration(proxyBeanMethods = false)
//指定在特定自动配置类RedisAutoConfiguration之后进行自动配置
@AutoConfigureAfter(RedisAutoConfiguration.class)
public class IdempotentAutoConfiguration {
/**
* 生成IdempotentAspect切面类的bean实例
* 切面 拦截处理所有 @Idempotent
* @return Aspect
*/
@Bean
public IdempotentAspect idempotentAspect() {
return new IdempotentAspect();
}
/**
* 生成key 解析器的bean实例
* key 解析器
* @return KeyResolver
*/
@Bean
@ConditionalOnMissingBean(KeyResolver.class)
public KeyResolver keyResolver() {
return new ExpressionResolver();
}
}
AutoConfiguration.imports
com.pig4cloud.pigx.common.idempotent.IdempotentAutoConfiguration
org.springframework.boot.autoconfigure.AutoConfiguration.imports
是一个 Spring Boot 的属性,用于指定需要在自动配置类中导入的其他配置类。
在 Spring Boot 中,自动配置是一种机制,它根据应用程序的依赖和配置信息,自动创建并配置相应的 Bean 实例。而 AutoConfiguration.imports
属性则提供了一种扩展机制,允许开发人员在自动配置类中导入其他配置类,以实现更为灵活和定制化的自动配置。
具体来说,AutoConfiguration.imports
属性是一个字符串数组,每个元素表示一个需要导入的配置类的全限定名。在自动配置过程中,Spring Boot 会自动加载这些配置类,并将它们合并到当前上下文中,以实现更全面的自动配置。
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个重复请求;