Spring Boot实战：基于策略模式+代理模式手写幂等性注解组件

一、为什么需要幂等性？

核心定义：在分布式系统中，一个操作无论执行一次还是多次，最终结果都保持一致。
典型场景：

• 用户重复点击提交按钮
• 网络抖动导致的请求重试
• 消息队列的重复消费
• 支付系统的回调通知

不处理幂等的风险：

• 重复创建订单导致资金损失
• 库存超卖引发资损风险
• 用户数据重复插入破坏业务逻辑

二、实现步骤分解

1. 定义幂等注解

/*** 幂等注解** @author dyh*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {/*** 幂等的超时时间，默认为 1 秒** 注意，如果执行时间超过它，请求还是会进来*/int timeout() default 1;/*** 时间单位，默认为 SECONDS 秒*/TimeUnit timeUnit() default TimeUnit.SECONDS;/*** 提示信息，正在执行中的提示*/String message() default "重复请求，请稍后重试";/*** 使用的 Key 解析器** @see DefaultIdempotentKeyResolver 全局级别* @see UserIdempotentKeyResolver 用户级别* @see ExpressionIdempotentKeyResolver 自定义表达式，通过 {@link #keyArg()} 计算*/Class<? extends IdempotentKeyResolver> keyResolver() default DefaultIdempotentKeyResolver.class;/*** 使用的 Key 参数*/String keyArg() default "";/*** 删除 Key，当发生异常时候** 问题：为什么发生异常时，需要删除 Key 呢？* 回答：发生异常时，说明业务发生错误，此时需要删除 Key，避免下次请求无法正常执行。** 问题：为什么不搞 deleteWhenSuccess 执行成功时，需要删除 Key 呢？* 回答：这种情况下，本质上是分布式锁，推荐使用 @Lock4j 注解*/boolean deleteKeyWhenException() default true;}

2. 设计Key解析器接口

/*** 幂等 Key 解析器接口** @author dyh*/
public interface IdempotentKeyResolver {/*** 解析一个 Key** @param idempotent 幂等注解* @param joinPoint  AOP 切面* @return Key*/String resolver(JoinPoint joinPoint, Idempotent idempotent);}

3. 实现三种核心策略

• 默认策略：方法签名+参数MD5（防全局重复）
• 用户策略：用户ID+方法特征（防用户重复）
• 表达式策略：SpEL动态解析参数（灵活定制）

3.1 默认策略

/*** 默认（全局级别）幂等 Key 解析器，使用方法名 + 方法参数，组装成一个 Key** 为了避免 Key 过长，使用 MD5 进行“压缩”** @author dyh*/
public class DefaultIdempotentKeyResolver implements IdempotentKeyResolver {/*** 核心方法：生成幂等Key（基于方法特征+参数内容）* @param joinPoint   AOP切入点对象，包含方法调用信息* @param idempotent  方法上的幂等注解对象* @return 生成的唯一幂等Key（32位MD5哈希值）*/@Overridepublic String resolver(JoinPoint joinPoint, Idempotent idempotent) {// 获取方法完整签名（格式：返回值类型 类名.方法名(参数类型列表)）// 示例：String com.example.UserService.createUser(Long,String)String methodName = joinPoint.getSignature().toString();// 将方法参数数组拼接为字符串（用逗号分隔）// 示例：参数是 [123, "张三"] 将拼接为 "123,张三"String argsStr = StrUtil.join(",", joinPoint.getArgs());// 将方法签名和参数字符串合并后计算MD5// 目的：将可能很长的字符串压缩为固定长度，避免Redis Key过长return SecureUtil.md5(methodName + argsStr);}}

3.2 用户策略

/*** 用户级别的幂等 Key 解析器，使用方法名 + 方法参数 + userId + userType，组装成一个 Key* <p>* 为了避免 Key 过长，使用 MD5 进行“压缩”** @author dyh*/
public class UserIdempotentKeyResolver implements IdempotentKeyResolver {/*** 生成用户级别的幂等Key** @param joinPoint  AOP切入点对象（包含方法调用信息）* @param idempotent 方法上的幂等注解* @return 基于用户维度的32位MD5哈希值* <p>* 生成逻辑分四步：* 1. 获取方法签名 -> 标识具体方法* 2. 拼接参数值 -> 标识操作数据* 3. 获取用户身份 -> 隔离用户操作* 4. MD5哈希计算 -> 压缩存储空间*/@Overridepublic String resolver(JoinPoint joinPoint, Idempotent idempotent) {// 步骤1：获取方法唯一标识（格式：返回类型 类名.方法名(参数类型列表)）// 示例："void com.service.UserService.updatePassword(Long,String)"String methodName = joinPoint.getSignature().toString();// 步骤2：将方法参数转换为逗号分隔的字符串// 示例：参数是 [1001, "新密码"] 会拼接成 "1001,新密码"String argsStr = StrUtil.join(",", joinPoint.getArgs());// 步骤3：从请求上下文中获取当前登录用户ID// 注意：需确保在Web请求环境中使用，未登录时可能返回nullLong userId = WebFrameworkUtils.getLoginUserId();// 步骤4：获取当前用户类型（例如：0-普通用户，1-管理员）// 作用：区分不同权限用户的操作Integer userType = WebFrameworkUtils.getLoginUserType();// 步骤5：将所有要素拼接后生成MD5哈希值// 输入示例："void updatePassword()1001,新密码1231"// 输出示例："d3d9446802a44259755d38e6d163e820"return SecureUtil.md5(methodName + argsStr + userId + userType);}
}

3.3 表达式策略

/*** 基于 Spring EL 表达式，** @author dyh*/
public class ExpressionIdempotentKeyResolver implements IdempotentKeyResolver {// 参数名发现器：用于获取方法的参数名称（如：userId, orderId）// 为什么用LocalVariableTable：因为编译后默认不保留参数名，需要这个工具读取调试信息private final ParameterNameDiscoverer parameterNameDiscoverer = new LocalVariableTableParameterNameDiscoverer();// 表达式解析器：专门解析Spring EL表达式// 为什么用Spel：Spring官方标准，支持复杂表达式语法private final ExpressionParser expressionParser = new SpelExpressionParser();/*** 核心方法：解析生成幂等Key** @param joinPoint  AOP切入点（包含方法调用信息）* @param idempotent 方法上的幂等注解* @return 根据表达式生成的唯一Key*/@Overridepublic String resolver(JoinPoint joinPoint, Idempotent idempotent) {// 步骤1：获取当前执行的方法对象Method method = getMethod(joinPoint);// 步骤2：获取方法参数值数组（例如：[订单对象, 用户对象]）Object[] args = joinPoint.getArgs();// 步骤3：获取方法参数名数组（例如：["order", "user"]）String[] parameterNames = this.parameterNameDiscoverer.getParameterNames(method);// 步骤4：创建表达式上下文（相当于给表达式提供变量环境）StandardEvaluationContext evaluationContext = new StandardEvaluationContext();// 步骤5：将参数名和参数值绑定到上下文（让表达式能识别#order这样的变量）if (ArrayUtil.isNotEmpty(parameterNames)) {for (int i = 0; i < parameterNames.length; i++) {// 例如：将"order"参数名和实际的Order对象绑定evaluationContext.setVariable(parameterNames[i], args[i]);}}// 步骤6：解析注解中的表达式（例如："#order.id"）Expression expression = expressionParser.parseExpression(idempotent.keyArg());// 步骤7：执行表达式计算（例如：从order对象中取出id属性值）return expression.getValue(evaluationContext, String.class);}/*** 辅助方法：获取实际执行的方法对象* 为什么需要这个方法：处理Spring AOP代理接口的情况** @param point AOP切入点* @return 实际被调用的方法对象*/private static Method getMethod(JoinPoint point) {// 情况一：方法直接定义在类上（非接口方法）MethodSignature signature = (MethodSignature) point.getSignature();Method method = signature.getMethod();if (!method.getDeclaringClass().isInterface()) {return method; // 直接返回当前方法}// 情况二：方法定义在接口上（需要获取实现类的方法）try {// 通过反射获取目标类（实际实现类）的方法// 例如：UserService接口的create方法 -> UserServiceImpl的create方法return point.getTarget().getClass().getDeclaredMethod(point.getSignature().getName(), // 方法名method.getParameterTypes());    // 参数类型} catch (NoSuchMethodException e) {// 找不到方法时抛出运行时异常（通常意味着代码结构有问题）throw new RuntimeException("方法不存在: " + method.getName(), e);}}
}

4. 编写AOP切面

/*** 拦截声明了 {@link Idempotent} 注解的方法，实现幂等操作* 幂等切面处理器** 功能：拦截被 @Idempotent 注解标记的方法，通过Redis实现请求幂等性控制* 流程：* 1. 根据配置的Key解析策略生成唯一标识* 2. 尝试在Redis中设置该Key（SETNX操作）* 3. 若Key已存在 → 抛出重复请求异常* 4. 若Key不存在 → 执行业务逻辑* 5. 异常时根据配置决定是否删除Key** @author dyh*/
@Aspect  // 声明为AOP切面类
@Slf4j   // 自动生成日志对象public class IdempotentAspect {/*** Key解析器映射表（Key: 解析器类型，Value: 解析器实例）* 示例：* DefaultIdempotentKeyResolver.class → DefaultIdempotentKeyResolver实例* ExpressionIdempotentKeyResolver.class → ExpressionIdempotentKeyResolver实例*/private final Map<Class<? extends IdempotentKeyResolver>, IdempotentKeyResolver> keyResolvers;/*** Redis操作工具类（处理幂等Key的存储）*/private final IdempotentRedisDAO idempotentRedisDAO;/*** 构造方法（依赖注入）* @param keyResolvers 所有Key解析器的Spring Bean集合* @param idempotentRedisDAO Redis操作DAO*/public IdempotentAspect(List<IdempotentKeyResolver> keyResolvers, IdempotentRedisDAO idempotentRedisDAO) {// 将List转换为Map，Key是解析器的Class类型this.keyResolvers = CollectionUtils.convertMap(keyResolvers, IdempotentKeyResolver::getClass);this.idempotentRedisDAO = idempotentRedisDAO;}/*** 环绕通知：拦截被@Idempotent注解的方法* @param joinPoint 切入点（包含方法、参数等信息）* @param idempotent 方法上的@Idempotent注解实例* @return 方法执行结果* @throws Throwable 可能抛出的异常** 执行流程：* 1. 获取Key解析器 → 2. 生成唯一Key → 3. 尝试锁定 → 4. 执行业务 → 5. 异常处理*/@Around(value = "@annotation(idempotent)")  // 切入带有@Idempotent注解的方法public Object aroundPointCut(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable {// 步骤1：根据注解配置获取对应的Key解析器IdempotentKeyResolver keyResolver = keyResolvers.get(idempotent.keyResolver());// 断言确保解析器存在（找不到说明Spring容器初始化有问题）Assert.notNull(keyResolver, "找不到对应的 IdempotentKeyResolver");// 步骤2：使用解析器生成唯一Key（例如：MD5(方法签名+参数)）String key = keyResolver.resolver(joinPoint, idempotent);// 步骤3：尝试在Redis中设置Key（原子性操作）// 参数说明：// key: 唯一标识// timeout: 过期时间（通过注解配置）// timeUnit: 时间单位（通过注解配置）boolean success = idempotentRedisDAO.setIfAbsent(key, idempotent.timeout(), idempotent.timeUnit());// 步骤4：处理重复请求if (!success) {// 记录重复请求日志（方法签名 + 参数）log.info("[幂等拦截] 方法({}) 参数({}) 存在重复请求",joinPoint.getSignature().toString(),joinPoint.getArgs());// 抛出业务异常（携带注解中配置的错误提示信息）throw new ServiceException(GlobalErrorCodeConstants.REPEATED_REQUESTS.getCode(),idempotent.message());}try {// 步骤5：执行原始业务方法return joinPoint.proceed();} catch (Throwable throwable) {// 步骤6：异常处理（参考美团GTIS设计）// 配置删除策略：当deleteKeyWhenException=true时，删除Key允许重试if (idempotent.deleteKeyWhenException()) {// 记录删除操作日志（实际生产可添加更详细日志）log.debug("[幂等异常处理] 删除Key: {}", key);idempotentRedisDAO.delete(key);}// 继续抛出异常（由全局异常处理器处理）throw throwable;}}
}

5. 实现Redis原子操作

/*** 幂等 Redis DAO** @author dyh*/
@AllArgsConstructor
public class IdempotentRedisDAO {/*** 幂等操作** KEY 格式：idempotent:%s // 参数为 uuid* VALUE 格式：String* 过期时间：不固定*/private static final String IDEMPOTENT = "idempotent:%s";private final StringRedisTemplate redisTemplate;public Boolean setIfAbsent(String key, long timeout, TimeUnit timeUnit) {String redisKey = formatKey(key);return redisTemplate.opsForValue().setIfAbsent(redisKey, "", timeout, timeUnit);}public void delete(String key) {String redisKey = formatKey(key);redisTemplate.delete(redisKey);}private static String formatKey(String key) {return String.format(IDEMPOTENT, key);}}

6. 自动装配

/*** @author dyh* @date 2025/4/17 18:08*/
@AutoConfiguration(after = DyhRedisAutoConfiguration.class)
public class DyhIdempotentConfiguration {@Beanpublic IdempotentAspect idempotentAspect(List<IdempotentKeyResolver> keyResolvers, IdempotentRedisDAO idempotentRedisDAO) {return new IdempotentAspect(keyResolvers, idempotentRedisDAO);}@Beanpublic IdempotentRedisDAO idempotentRedisDAO(StringRedisTemplate stringRedisTemplate) {return new IdempotentRedisDAO(stringRedisTemplate);}// ========== 各种 IdempotentKeyResolver Bean ==========@Beanpublic DefaultIdempotentKeyResolver defaultIdempotentKeyResolver() {return new DefaultIdempotentKeyResolver();}@Beanpublic UserIdempotentKeyResolver userIdempotentKeyResolver() {return new UserIdempotentKeyResolver();}@Beanpublic ExpressionIdempotentKeyResolver expressionIdempotentKeyResolver() {return new ExpressionIdempotentKeyResolver();}}

三、核心设计模式解析

1. 策略模式（核心设计）

应用场景：多种幂等Key生成策略的动态切换
代码体现：

// 策略接口
public interface IdempotentKeyResolver {String resolver(JoinPoint joinPoint, Idempotent idempotent);
}// 具体策略实现
public class DefaultIdempotentKeyResolver implements IdempotentKeyResolver {@Overridepublic String resolver(...) { /* MD5(方法+参数) */ }
}public class ExpressionIdempotentKeyResolver implements IdempotentKeyResolver {@Overridepublic String resolver(...) { /* SpEL解析 */ }
}

UML图示：

2. 代理模式（AOP实现）

应用场景：通过动态代理实现无侵入的幂等控制
代码体现：

@Aspect
public class IdempotentAspect {@Around("@annotation(idempotent)") // 切入点表达式public Object around(...) {// 通过代理对象控制原方法执行return joinPoint.proceed(); }
}

执行流程：
客户端调用 → 代理对象拦截 → 执行幂等校验 → 调用真实方法

四、这样设计的好处

1. 业务解耦
   • 幂等逻辑与业务代码完全分离
   • 通过注解实现声明式配置
2. 灵活扩展
   • 新增Key策略只需实现接口
   • 支持自定义SpEL表达式
3. 高可靠性
   • Redis原子操作防并发问题
   • 异常时自动清理Key（可配置）
4. 性能优化
   • MD5压缩减少Redis存储压力
   • 细粒度锁控制（不同Key互不影响）
5. 易用性
   • 开箱即用的starter组件
   • 三种内置策略覆盖主流场景

五、使用示例

@Idempotent(keyResolver = UserIdempotentKeyResolver.class,timeout = 10,message = "请勿重复提交订单"
)
public void createOrder(OrderDTO dto) {// 业务逻辑
}