[Java] Spring Boot 3 + Redis 实现通用幂等防重中间件实战指南

技术栈：Spring Boot 3.0 + JDK 17 + Spring AOP +  Redis + Lua + SpEL
目标：开箱即用、生产就绪、注解驱动、支持高并发防重场景

一、为什么要做这个中间件？

1.1 痛点场景

• 用户点击“提交订单”按钮多次 → 生成多笔订单
• 网络超时重试 → 后端重复处理支付回调
• MQ 消息重复投递 → 账户余额被多次扣减
• 考生重复提交报名信息 → 数据库出现多条相同身份证记录

这些都违反了 幂等性（Idempotency） 原则：同一操作无论执行多少次，结果应一致。

1.2 现有方案的问题

于是，我们决定用 AOP + 注解 + Redis，打造一个通用、轻量、高性能的幂等中间件。

二、整体架构设计

2.1 系统架构图

整个过程在 毫秒级完成，且 无数据库压力。

2.2 核心组件

三、核心代码实现

3.1 注解定义

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Idempotent {
    String key();
    int expire() default 300;
    String value() default "1";
}

3.2 AOP 切面逻辑

@Aspect
public class IdempotentAspect{
    private final IdempotentService idempotentService;
    private final ExpressionParser parser = new SpelExpressionParser();
    private final StandardReflectionParameterNameDiscoverer discoverer =
    new StandardReflectionParameterNameDiscoverer();

    public IdempotentAspect(IdempotentService idempotentService){
        this.idempotentService = idempotentService;
    }

    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        String[] paramNames = discoverer.getParameterNames(signature.getMethod());
        Object[] args = joinPoint.getArgs();

        // 解析 SpEL key
        StandardEvaluationContext context = new StandardEvaluationContext();
        for (int i = 0; i < args.length; i++) {
            context.setVariable(paramNames[i], args[i]);
        }
        String key = parser.parseExpression(idempotent.key()).getValue(context, String.class);

        if (!idempotentService.tryLock(key, idempotent.expire())) {
            if (idempotent.mode() == Idempotent.Mode.REJECT) {
                throw new IllegalStateException("重复请求，请勿重复提交");
            }
            // TODO: RETURN_CACHE 模式（需结果缓存）
        }

        return joinPoint.proceed();
    }
}

3.3 自定义失败处理器（可扩展）

public interface IdempotentFailureHandler{
    void handle(String key, Method method);
}

@Component
public class DefaultIdempotentFailureHandler implements IdempotentFailureHandler{
    @Override
    public void handle(String key, Method method){
        // 默认什么都不做，由 AOP 抛出异常
    }
}

四、使用案例

案例 1：下单（防重复下单）

@PostMapping("/order")
@Idempotent(key = "'order:' + #userId + ':' + #goodsId", expire = 300)
public Result<String> createOrder(
    @RequestParam String userId,
    @RequestParam String goodsId){
    // 模拟下单逻辑
    orderService.create(userId, goodsId);
    return Result.success("下单成功");
}

若同一用户对同一商品在 5 分钟内重复下单，后续请求将被拒绝。

案例 2：考生报名（防身份证重复）

@PostMapping("/enroll")
@Idempotent(key = "'enroll:' + #candidate.idCard", expire = 300)
public Result<Void> enroll(@RequestBody Candidate candidate){
    // 防止同一身份证重复报名
    enrollmentService.save(candidate);
    return Result.OK();
}

// 简写一个dto类吧
public class Candidate{
    private String name;
    private String idCard;
    private String phone;
}

key 为 enroll:11010119900307XXXX，5分钟内无法重复提交。

案例 3：秒杀场景（用户 + 商品维度）

@PostMapping("/seckill")
@Idempotent(key = "'seckill:' + #userId + ':' + #goodsId", expire = 60)
public Result<String> seckill(@RequestParam String userId, @RequestParam Long goodsId){
    return seckillService.execute(userId, goodsId);
}

即使用户疯狂点击，1 分钟内只允许一次有效请求。

五、性能与可靠性

• 性能：Redis SET NX EX 是原子操作，单节点 QPS > 5w+
• 一致性：基于 Redis 分布式锁语义，天然支持集群
• 安全性：Key 由业务生成，无注入风险（SpEL 在受控上下文中执行）
• 资源：Key 自动过期，无内存泄漏风险

工具代码已经完整的放到GitHub上，使用超级简单，你的项目中引用依赖

<!-- https://mvnrepository.com/artifact/io.github.songrongzhen/once-kit-spring-boot-starter -->
<dependency>
    <groupId>io.github.songrongzhen</groupId>
    <artifactId>once-kit-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

然后在你的需要幂等和防止重复提交的接口上加上一行注解就OK

@Idempotent(key = "'order:' + #userId + ':' + #goodsId", expire = 300)

本文通过 Spring Boot 3、AOP 和 Redis 的结合，提供了一个解决分布式系统常见幂等性问题的生产级方案。其核心思想是利用 Redis 的原子操作实现轻量级锁，并通过注解与 AOP 切面将防重逻辑与业务代码解耦，极大地提升了开发效率与系统的健壮性。如果你正在为高并发下的重复请求问题头疼，不妨试试这个方案。更多关于 Java 和 数据库/中间件 的深度技术讨论，欢迎访问 云栈社区 与广大开发者一同交流。