# 重复提交守护者

**Repository Path**: jms_liu/duplicate-submit-spring-boot-starter

## Basic Information

- **Project Name**: 重复提交守护者
- **Description**: 随着系统对外暴露的API增多，面临被重复调用的风险。重复提交可能导致：
1、数据重复插入
2、资源被滥用
3、系统性能下降
因此，需在服务端实现统一、可靠的防重复提交机制，保障接口的幂等性和数据一致性。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

1. 需求背景
    - 这里是列表文本随着系统对外暴露的API增多，面临被重复调用的风险。重复提交可能导致：
    - 这里是列表文本数据重复插入
    - 这里是列表文本资源被滥用
    - 这里是列表文本系统性能下降
    - 这里是列表文本因此，需在服务端实现统一、可靠的防重复提交机制，保障接口的幂等性和数据一致性。


2. 适用范围
    - 这里是列表文本以下类型的接口建议启用防重复提交机制：
    - 这里是列表文本里是列表文本在Controller层添加注解，标识接口需要防重复提交
    - 这里是列表文本在server层添加注解，标识接口需要防重复提交
    - 这里是列表文本高并发场景接口
    - 用户可主动触发的接口
    
3. 核心需求
 - 防止短时间内的重复请求，同一用户在短时间内对同一接口发起相同参数的请求，应识别为重复提交
 - 基于唯一标识判断重复，基于请求IP和入参生成唯一标识，并使用Redis缓存该标识，如果缓存中存在该标识，则认为请求重复
 - 防重复提交的注解应该添加在Contoller层
 - 由于上层controller层是聚合层，所以防重复提交的注解应该添加在service层
 - 返回明确的错误码，避免客户端误判
 - 支持Spring Boot 2.5.5版本
 - 支持灵活配置，可对接口粒度开启/关闭防重功能，可配置防重时间窗口、缓存存储方式等
 - 高性能与低延迟
 - 分布式环境兼容

4. 技术方案设计
 - 4.1 实现方式
 - 4.1.1 核心实现策略
    - 基于AOP + 注解 + Redis的防重复提交机制
    - 唯一标识生成策略：IP地址 + 用户标识 + 接口路径 + 请求参数哈希值
    - 时间窗口控制：可配置的防重复时间间隔
    - 分布式兼容：基于Redis实现分布式锁机制
  4.1.2 技术选型
 - Spring Boot 2.5.5：基础框架
 - Spring AOP：面向切面编程，实现无侵入拦截
 - Redis：分布式缓存，存储防重复标识
 - SpEL表达式：支持动态参数提取
 - Jackson：JSON序列化，生成参数哈希
 - 4.2、架构流程
 - 4.2.1 整体流程设计
    a. 客户端请求 → Controller(注解标记) → Service → AOP拦截器 → 防重复检查 → 业务执行/拒绝
    b. 客户端请求 → Controller → Service(注解标记) → AOP拦截器 → 防重复检查 → 业务执行/拒绝
 4.2.2 详细执行流程
 - 请求接收：客户端发起HTTP请求
 - 注解识别：
    - AOP拦截器识别Service层方法上的防重复注解
 - 唯一标识生成：基于IP、用户、接口、参数生成唯一Key
 -  Redis检查：查询Redis中是否存在该Key
 - 防重复判断：
    ○ 不存在：设置Key到Redis，执行业务逻辑
    ○ 存在：返回重复提交错误，拒绝请求
 -  结果返回：向客户端返回执行结果或错误信息
4.3、核心架构
4.3.1 分层架构设计

4.3.2 系统交互图

4.3.3 系统交互图

4.3.4 核心组件设计
注解组件
 -  @PreventDuplicate：防重复提交注解
 - 支持配置：时间窗口、错误消息、参数提取策略
AOP切面组件
 - DuplicateSubmitAspect：拦截标记注解的方法
 - 实现前置通知和后置通知
防重复服务组件
 - DuplicateSubmitService：核心业务逻辑
 -  唯一标识生成、Redis操作、异常处理
配置组件
 -  DuplicateSubmitProperties：可配置参数
 -  支持YAML配置和动态调整

4.3.5 关键设计要点
时间窗口控制
 - 支持毫秒级精度的时间间隔配置
 - 自动过期机制，避免内存泄漏
分布式兼容性
 -  基于Redis的分布式锁机制
 -  支持集群环境下的防重复控制
性能优化策略
 - Redis Key过期时间自动设置
 -  参数哈希算法优化
 - 异常情况下的降级处理

4.4、配置灵活

4.4.0  Maven配置


![输入图片说明](image-1.png)

4.4.1  全局配置

# 防重复提交配置

![输入图片说明](image.png)

4.4.2 使用方法

   ![输入图片说明](image-2.png)

5、技术优势
 -  无侵入性：通过注解和AOP实现，不影响现有业务代码
 -  高性能：基于Redis的快速缓存机制
 - 分布式兼容：支持集群环境部署
 - 配置灵活：支持全局和方法级配置
 - 异常容错：具备降级机制和异常处理
 - 版本兼容：完全支持Spring Boot 2.5.5版本