SpringBoot：基于 Redis 自定義注解實現后端接口防重復提交校驗（冪等操作）

---

可基于 時間間隔 和 用于冪等判斷的參數名稱 實現防重復提交校驗

客戶端發送請求 ↓
[Spring Boot 應用入口]↓
┌─────────────────────────────────────────┐
│        CacheRequestFilter        		│ │ // 第一步：請求體緩存過濾器
│  ┌────────────────────────────────────┐ │
│  │ 判斷請求類型:              	        │ │
│  │ - 非JSON類型請求 → 直接放行			│ │
│  │ - JSON類型請求 (POST/PUT等)   		│ │
│  │   → 用CacheRequestWrapper包裝 		│ │
│  │   → 緩存請求體到內存（支持重復讀取）	│ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘↓
[DispatcherServlet 路由分發]  // 匹配到標注 @NoDuplicateSubmit 的控制器方法↓
┌─────────────────────────────────────────────────┐
│    NoDuplicateSubmitAspect     			    │ │ // 第二步：AOP切面攔截
│  ┌────────────────────────────────────────────┐ │
│  │ 構建Redis防重校驗Key：       				│ │
│  │ 1. 前綴（@NoDuplicateSubmit.prefix）		│ │
│  │ 2. 請求方法+路徑（如POST:/api/submit）		│ │
│  │ 3. 當前用戶ID（SecurityContextHolder獲取）	│ │
│  │ 4. 參數哈希值：            				    │ │
│  │    - 若指定paramNames → 用SpEL提取對應參數	│ │
│  │    - 若未指定但allParamVerify=true → 所有參數	│ │
│  │    - 否則 → 固定標識"none"					│ │
│  │    → 用MurmurHash計算哈希并轉Base64			│ │
│  └────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────┐ │
│  │ Redis重復校驗：								│ │
│  │ - 執行setIfAbsent（原子操作）				    │ │
│  │   → 若Key不存在 → 正常執行   				    │ │
│  │     （設置Key并指定過期時間）				    │ │
│  │   → 若Key已存在 → 重復提交   				    │ │
│  └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘├─ 重復提交 → 拋出ServerException│       ↓│  ┌─────────────────────────┐│  │ GlobalExceptionHandler  │  // 捕獲異常，返回友好提示│  └─────────────────────────┘│       ↓│  客戶端收到"請勿重復提交"錯誤│└─ 正常提交 → 執行控制器方法↓控制器處理業務邏輯（可重復讀取請求體）↓客戶端收到處理結果

具體操作如下：

---

Spring Boot 2.x + Spring Framework 5.x 版本

一、添加依賴

        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-redis</artifactId></dependency><!-- AOP --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-aop</artifactId></dependency><dependency><groupId>com.alibaba.fastjson2</groupId><artifactId>fastjson2</artifactId><version>2.0.36</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.24</version></dependency><dependency><groupId>com.google.guava</groupId><artifactId>guava</artifactId><version>30.0-jre</version></dependency><dependency><groupId>org.apache.commons</groupId><artifactId>commons-lang3</artifactId><version>3.14.0</version></dependency>

二、 構建可重復讀取inputStream的request

HTTP 請求體的輸入流 ( ServletInputStream ) 只能被讀取一次。當 AOP 攔截器（如日志切面、參數校驗切面）和控制器都需要讀取請求體時，如果不做處理，后續讀取會拋出異常

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequestWrapper;
import org.apache.commons.lang3.StringUtils;
import org.springframework.http.MediaType;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStreamReader;/*** HttpServletReqeust使請求輸入流支持二次讀取*/
public class CacheRequestFilter implements Filter {@Overridepublic void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)throws IOException, ServletException {ServletRequest requestWrapper = null;if (request instanceof HttpServletRequest&& StringUtils.startsWithIgnoreCase(request.getContentType(), MediaType.APPLICATION_JSON_VALUE)) {requestWrapper = new CacheRequestWrapper((HttpServletRequest) request);}if (null == requestWrapper) {chain.doFilter(request, response);} else {chain.doFilter(requestWrapper, response);}}public static class CacheRequestWrapper extends HttpServletRequestWrapper {private final String requestBody;public CacheRequestWrapper(HttpServletRequest request) throws IOException {super(request);StringBuilder sb = new StringBuilder();try (BufferedReader reader = request.getReader()) {String line;while ((line = reader.readLine()) != null) {sb.append(line);}}this.requestBody = sb.toString();}public String getRequestBody() {return this.requestBody;}@Overridepublic ServletInputStream getInputStream() throws IOException {ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(requestBody.getBytes());return new ServletInputStream() {@Overridepublic boolean isFinished() {return byteArrayInputStream.available() == 0;}@Overridepublic boolean isReady() {return true;}@Overridepublic void setReadListener(ReadListener readListener) {}@Overridepublic int read() throws IOException {return byteArrayInputStream.read();}};}@Overridepublic BufferedReader getReader() throws IOException {return new BufferedReader(new InputStreamReader(this.getInputStream()));}}}

三、使自定義的Filter生效

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class FilterConfig {@Beanpublic FilterRegistrationBean someFilterRegistration() {FilterRegistrationBean registration = new FilterRegistrationBean();registration.setFilter(new CacheRequestFilter());registration.addUrlPatterns("/*");registration.setName("cacheRequestFilter");registration.setOrder(FilterRegistrationBean.HIGHEST_PRECEDENCE);return registration;}
}

四、防重復提交常量類

/*** 防重復提交常量類*/
public final class NoDuplicateSubmitConstant {public static final String RESUBMIT_MSG = "請勿重復提交數據";public static final String REDIS_SEPARATOR = ":";public static final String RESUBMIT_CHECK_KEY_PREFIX = "no-duplicate-submit";}

五、創建防重復提交注解

創建一個自定義注解 @NoDuplicateSubmit ，用于標識需要防重復提交的方法

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.concurrent.TimeUnit;/*** 冪等注解，防止用戶重復提交表單信息*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NoDuplicateSubmit {/*** 觸發冪等失敗邏輯時，返回的錯誤提示信息*/String message() default NoDuplicateSubmitConstant.RESUBMIT_MSG;/*** 防重復提交校驗的時間間隔*/long interval() default 10;/*** 防重復提交校驗的時間間隔的單位*/TimeUnit timeUnit() default TimeUnit.SECONDS;/*** 自定義 Redis Key 前綴*/String prefix() default NoDuplicateSubmitConstant.RESUBMIT_CHECK_KEY_PREFIX;/*** 指定參與冪等判斷的參數名稱* 例如：Param傳參   @NoDuplicateSubmit(paramNames = {"#name"})   表示只使用name參數計算哈希*      Body傳參    @NoDuplicateSubmit(paramNames = {"#user.name"})  表示只使用user對象下的name參數計算哈希*/String[] paramNames() default {};/*** 僅當 {@link #paramNames()} 為空時, 開啟此開關，選擇是否校驗全部參數*/boolean allParamVerify() default false;}

六、創建防止重復提交攔截器

創建一個AOP切面類，用于攔截標注了 @NoDuplicateSubmit 注解的方法，并檢查是否重復提交

import com.alibaba.fastjson2.JSON;
import com.google.common.hash.Hashing;
import lombok.RequiredArgsConstructor;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.lang.NonNull;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import javax.servlet.http.HttpServletRequest;
import java.lang.reflect.Method;
import java.rmi.ServerException;
import java.util.*;
import java.util.concurrent.TimeUnit;/*** 防止用戶重復提交表單信息切面控制器*/
@Aspect
@RequiredArgsConstructor
@Component
public final class NoDuplicateSubmitAspect {private static final Logger log = LoggerFactory.getLogger(NoDuplicateSubmitAspect.class);private final RedisTemplate<String, Object> redisTemplate;/*** 增強方法標記 {@link NoDuplicateSubmit} 注解邏輯*/@Around("@annotation(noDuplicateSubmit)")public Object noDuplicateSubmit(ProceedingJoinPoint joinPoint, NoDuplicateSubmit noDuplicateSubmit) throws Throwable {final String lockKey = buildLockKey(joinPoint, noDuplicateSubmit);final String message = noDuplicateSubmit.message();final long interval = noDuplicateSubmit.interval();final TimeUnit timeUnit = noDuplicateSubmit.timeUnit();// 原子操作：如果 key 不存在，則設置 key 并過期；如果存在，直接返回 falseBoolean isAbsent = redisTemplate.opsForValue().setIfAbsent(lockKey, "submit", interval, timeUnit);if (Boolean.FALSE.equals(isAbsent)) {// key 已存在 → 重復提交，拋異常throw new ServerException(message);}// key 不存在 → 正常執行方法（無需手動刪除 key，過期后自動刪除）return joinPoint.proceed();}/*** @param joinPoint* @return 構建重復提交的key*/private String buildLockKey(ProceedingJoinPoint joinPoint, @NonNull NoDuplicateSubmit noDuplicateSubmit) {StringBuilder keyBuilder =new StringBuilder(noDuplicateSubmit.prefix()).append(NoDuplicateSubmitConstant.REDIS_SEPARATOR).append(getMethodAndServletPath()).append(NoDuplicateSubmitConstant.REDIS_SEPARATOR).append(getCurrentUserId()).append(NoDuplicateSubmitConstant.REDIS_SEPARATOR).append(calcArgsMurmurHash(joinPoint, noDuplicateSubmit));return keyBuilder.toString();}/*** @return 獲取當前線程上下文 Method + ServletPath*/private String getMethodAndServletPath() {HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();return request.getMethod() + NoDuplicateSubmitConstant.REDIS_SEPARATOR + request.getServletPath();}/*** @return 當前操作用戶 ID*/private Long getCurrentUserId() {return SecurityContextHolder.getUserId();}/*** @return joinPoint 采用google的MurmurHash算法計算哈希做校驗*/private String calcArgsMurmurHash(ProceedingJoinPoint joinPoint, NoDuplicateSubmit noDuplicateSubmit) {final String[] paramNames = noDuplicateSubmit.paramNames();final boolean allParamVerify = noDuplicateSubmit.allParamVerify();MethodSignature methodSignature = (MethodSignature) joinPoint.getSignature();Method method = methodSignature.getMethod();Object[] args = joinPoint.getArgs();// 處理 paramNames 為空的場景if (paramNames.length == 0) {if (allParamVerify) {byte[] hashBytes = Hashing.murmur3_128().hashBytes(JSON.toJSONBytes(args)).asBytes();return Base64.getUrlEncoder().withoutPadding().encodeToString(hashBytes);} else {// 不校驗參數，返回固定標識return "none";}}Object[] argsForKey = ExpressionUtils.getExpressionValueAliasAble(args, method, paramNames);// 使用 Google Guava 的 Hashing 生成 128 位哈希byte[] hashBytes = Hashing.murmur3_128().hashBytes(JSON.toJSONBytes(argsForKey)).asBytes();// 轉為 Base64 編碼return Base64.getUrlEncoder().withoutPadding().encodeToString(hashBytes);}
}

在這個切面類中，我們通過@Around注解攔截所有標注了 @NoDuplicateSubmit 注解的方法。通過Redis，我們為每個請求生成一個唯一的key，并設置一個過期時間。如果在過期時間內再次提交相同的請求，就會被攔截。

七、SpEL工具類

import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.context.expression.MethodBasedEvaluationContext;
import org.springframework.core.LocalVariableTableParameterNameDiscoverer;
import org.springframework.expression.Expression;
import org.springframework.expression.ExpressionParser;
import org.springframework.expression.spel.standard.SpelExpressionParser;
import org.springframework.lang.NonNull;
import org.springframework.lang.Nullable;
import java.lang.reflect.Method;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;public class ExpressionUtils {private static final Map<String, Expression> EXPRESSION_CACHE = new ConcurrentHashMap<>(64);private static final ExpressionParser SPEL_PARSER = new SpelExpressionParser();/*** 可以通過別名獲取表達式的值,類似于spring cache的用法 可以給參數指定別名** @param arguments         方法* @param method            參數* @param expressionsString Spring EL表達式字符串* @param <T>               類型* @return 結果集*/@Nullablepublic static <T> T[] getExpressionValueAliasAble(@Nullable Object[] arguments, @NonNull Method method, String... expressionsString) {if (ArrayUtils.isEmpty(arguments) || ArrayUtils.isEmpty(expressionsString)) {return null;}Object[] result = new Object[expressionsString.length];for (int i = 0; i < result.length; i++) {result[i] = getExpressionValueAliasAble(arguments, method, expressionsString[i]);}//noinspection uncheckedreturn (T[]) result;}/*** 可以通過別名獲取表達式的值,類似于spring cache的用法 可以給參數指定別名** @param arguments        參數* @param method           方法* @param expressionString Spring EL表達式字符串* @param <T>              類型* @return 結果*/@Nullablepublic static <T> T getExpressionValueAliasAble(@Nullable Object[] arguments, @NonNull Method method, String expressionString) {if (ArrayUtils.isEmpty(arguments) || StringUtils.isBlank(expressionString)) {return null;}Expression expression = getExpression(expressionString);if (expression == null) {return null;}MethodBasedEvaluationContext evaluationContext = getEvaluationContextAliasAble(arguments, method);return (T) expression.getValue(evaluationContext);}/*** 獲取Expression對象** @param expressionString Spring EL 表達式字符串 例如 #{param.id}* @return Expression*/@Nullablepublic static Expression getExpression(@Nullable String expressionString) {if (StringUtils.isBlank(expressionString)) {return null;}if (EXPRESSION_CACHE.containsKey(expressionString)) {return EXPRESSION_CACHE.get(expressionString);}Expression expression = SPEL_PARSER.parseExpression(expressionString);EXPRESSION_CACHE.put(expressionString, expression);return expression;}/*** 獲取可以通過別名查找的EvaluationContext,類似于spring cache的用法 #a0.id,#p1.name** @param arguments 方法入參* @param method    方法* @return MethodBasedEvaluationContext*/@NonNullpublic static MethodBasedEvaluationContext getEvaluationContextAliasAble(@NonNull Object[] arguments, @NonNull Method method) {return new MethodBasedEvaluationContext(arguments, method, arguments, new LocalVariableTableParameterNameDiscoverer());}}

八、自定義異常處理

為防重復提交功能添加自定義異常處理，使其返回更加友好的錯誤信息：

/*** 全局異常捕獲類*/
@RestControllerAdvice
public class GlobalExceptionHandler {private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);@ExceptionHandler(value = ServerException.class)public ResultInfo abstractExceptionHandle(HttpServletRequest request, AbstractException ex) {logger.error("========================================== ServerException-Start ==========================================");String params = getRequestParams(request);logger.error("RequestURL     : {}", request.getRequestURL());logger.error("HTTP Method    : {}", request.getMethod());logger.error("Params         : {}", params);logger.error("IP             : {}", request.getRemoteAddr());logger.error("Cause          : ", ex);logger.error("ExMessage      : {}", ex.getMessage());logger.info("=========================================== ServerException-End ===========================================");return ResultInfo.error(ex);}

---

---

Spring Boot 3.x + Spring Framework6.x版本

只需更新 ExpressionUtils SpEL工具類 ，其他的方法和上面一樣

LocalVariableTableParameterNameDiscoverer 在 Spring 6.0.1 中被標記為 deprecated（過時） 并計劃移除，主要原因是 Spring 引入了更高效的參數名發現機制 StandardReflectionParameterNameDiscoverer。
以下是替代方案：

import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.context.expression.MethodBasedEvaluationContext;
import org.springframework.core.StandardReflectionParameterNameDiscoverer;
import org.springframework.expression.Expression;
import org.springframework.expression.ExpressionParser;
import org.springframework.expression.spel.standard.SpelExpressionParser;
import org.springframework.lang.NonNull;
import org.springframework.lang.Nullable;
import java.lang.reflect.Method;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;public class ExpressionUtils {private static final Map<String, Expression> EXPRESSION_CACHE = new ConcurrentHashMap<>(64);private static final ExpressionParser SPEL_PARSER = new SpelExpressionParser();/*** 可以通過別名獲取表達式的值,類似于spring cache的用法 可以給參數指定別名** @param arguments         方法* @param method            參數* @param expressionsString Spring EL表達式字符串* @param <T>               類型* @return 結果集*/@Nullablepublic static <T> T[] getExpressionValueAliasAble(@Nullable Object[] arguments, @NonNull Method method, String... expressionsString) {if (ArrayUtils.isEmpty(arguments) || ArrayUtils.isEmpty(expressionsString)) {return null;}Object[] result = new Object[expressionsString.length];for (int i = 0; i < result.length; i++) {result[i] = getExpressionValueAliasAble(arguments, method, expressionsString[i]);}//noinspection uncheckedreturn (T[]) result;}/*** 可以通過別名獲取表達式的值,類似于spring cache的用法 可以給參數指定別名** @param arguments        參數* @param method           方法* @param expressionString Spring EL表達式字符串* @param <T>              類型* @return 結果*/@Nullablepublic static <T> T getExpressionValueAliasAble(@Nullable Object[] arguments, @NonNull Method method, String expressionString) {if (ArrayUtils.isEmpty(arguments) || StringUtils.isBlank(expressionString)) {return null;}Expression expression = getExpression(expressionString);if (expression == null) {return null;}MethodBasedEvaluationContext evaluationContext = getEvaluationContextAliasAble(arguments, method);return (T) expression.getValue(evaluationContext);}/*** 獲取Expression對象** @param expressionString Spring EL 表達式字符串 例如 #{param.id}* @return Expression*/@Nullablepublic static Expression getExpression(@Nullable String expressionString) {if (StringUtils.isBlank(expressionString)) {return null;}if (EXPRESSION_CACHE.containsKey(expressionString)) {return EXPRESSION_CACHE.get(expressionString);}Expression expression = SPEL_PARSER.parseExpression(expressionString);EXPRESSION_CACHE.put(expressionString, expression);return expression;}/*** 獲取可以通過別名查找的EvaluationContext,類似于spring cache的用法 #a0.id,#p1.name** @param arguments 方法入參* @param method    方法* @return MethodBasedEvaluationContext*/@NonNullpublic static MethodBasedEvaluationContext getEvaluationContextAliasAble(@NonNull Object[] arguments, @NonNull Method method) {return new MethodBasedEvaluationContext(arguments, method, arguments, new StandardReflectionParameterNameDiscoverer());}}

---

創建示例Controller

創建一個簡單的Controller，用于測試防重復提交功能

@RestController
@RequestMapping()
public class TestController {@PostMapping("/test1")@NoDuplicateSubmit(message = "不要在提交了", interval = 120, paramNames = {"#name"})public ResultInfo<String> test1(@RequestParam String name) {return ResultInfo.success();}@PostMapping("/test2")@NoDuplicateSubmit(message = "不要在提交了", interval = 120, paramNames = {"#user.name"})public ResultInfo<String> test2(@RequestBody User user) {return ResultInfo.success();}public static class User {private String name;public String getName() {return name;}public void setName(String name) {this.name = name;}}
}

流程圖解