处理接口幂等性的两种常见方案

关注

原创最新推荐文章于 2026-04-21 11:50:54 发布 920 阅读 AI 写同款· GEO 优化 ›

【Spring Boot】实现接口幂等性的 4 种方案在HTTP/1.1中，对幂等性进行了定义。它描述了一次和多次请求某一个资源对于资源本身应该具有同样的结果（网络超时等问题除外），即第一次请求的时候对资源产生了副作用，但是以后的多次请求都不会再对资源产生副作用。这里的副作用是不会对结果产生破坏或者产生不可预料的结果。也就是说，其任意多次执行对资源本身所产生的影响均与一次执行的影响相同。幂等性是开发当中很常见也很重要的一个需求，尤其是支付、订单等与金钱挂钩的服务，保证接口幂等性尤其重要。对于下单等存在唯一主键的，可以使用“唯一主键方案”的方式实现；阅读详情

接口幂等性处理算是一个非常常见的需求了，我们在很多项目中其实都会遇到。今天我们来看看两种比较简单的实现思路。

1. 接口幂等性实现方案梳理

其实接口幂等性的实现方案还是蛮多的，我这里和小伙伴们分享两种比较常见的方案。

1.1 基于 Token

基于 Token 这种方案的实现思路很简单，整个流程分两步：

客户端发送请求，从服务端获取一个 Token 令牌，每次请求获取到的都是一个全新的令牌。
客户端发送请求的时候，携带上第一步的令牌，处理请求之前，先校验令牌是否存在，当请求处理成功，就把令牌删除掉。

大致的思路就是上面这样，当然具体的实现则会复杂很多，有很多细节需要注意，松哥之前也专门录过这种方案的视频，小伙伴们可以参考下，录了两个视频，一个是基于拦截器处理的，还有一个是基于 AOP 切面处理的：

基于拦截器处理（视频一）：

基于 AOP 切面处理（视频二）：

1.2 基于请求参数校验

最近在 TienChin 项目中使用的是另外一种方案，这种方案是基于请求参数来判断的，如果在短时间内，同一个接口接收到的请求参数相同，那么就认为这是重复的请求，拒绝处理，大致上就是这么个思路。

相比于第一种方案，第二种方案相对来说省事一些，因为只有一次请求，不需要专门去服务端拿令牌。在高并发环境下这种方案优势比较明显。

所以今天我就来和大家聊聊第二种方案的实现，后面在 TienChin 项目视频中也会和大家细讲。

2. 基于请求参数的校验

首先我们新建一个 Spring Boot 项目，引入 Web 和 Redis 依赖，新建完成后，先来配置一下 Redis 的基本信息，如下：

spring.redis.host=localhost
spring.redis.port=6379
spring.redis.password=123
复制代码

为了后续 Redis 操作方便，我们再来对 Redis 进行一个简单封装，如下：

@Component
public class RedisCache {
    @Autowired
    public RedisTemplate redisTemplate;
    public <T> void setCacheObject(final String key, final T value, final Integer timeout, final TimeUnit timeUnit) {
        redisTemplate.opsForValue().set(key, value, timeout, timeUnit);
    }
    public <T> T getCacheObject(final String key) {
        ValueOperations<String, T> operation = redisTemplate.opsForValue();
        return operation.get(key);
    }
}
复制代码

这个比较简单，一个存数据，一个读数据。

接下来我们自定义一个注解，在需要进行幂等性处理的接口上，添加该注解即可，将来这个接口就会自动的进行幂等性处理。

@Inherited
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RepeatSubmit {
    /**
     * 间隔时间(ms)，小于此时间视为重复提交
     */
    public int interval() default 5000;

    /**
     * 提示消息
     */
    public String message() default "不允许重复提交，请稍候再试";
}
复制代码

这个注解我们通过拦截器来进行解析，解析代码如下：

public abstract class RepeatSubmitInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (handler instanceof HandlerMethod) {
            HandlerMethod handlerMethod = (HandlerMethod) handler;
            Method method = handlerMethod.getMethod();
            RepeatSubmit annotation = method.getAnnotation(RepeatSubmit.class);
            if (annotation != null) {
                if (this.isRepeatSubmit(request, annotation)) {
                    Map<String, Object> map = new HashMap<>();
                    map.put("status", 500);
                    map.put("msg", annotation.message());
                    response.setContentType("application/json;charset=utf-8");
                    response.getWriter().write(new ObjectMapper().writeValueAsString(map));
                    return false;
                }
            }
            return true;
        } else {
            return true;
        }
    }

    /**
     * 验证是否重复提交由子类实现具体的防重复提交的规则
     *
     * @param request
     * @return
     * @throws Exception
     */
    public abstract boolean isRepeatSubmit(HttpServletRequest request, RepeatSubmit annotation);
}
复制代码

这个拦截器是一个抽象类，将接口方法拦截下来，然后找到接口上的 @RepeatSubmit 注解，调用 isRepeatSubmit 方法去判断是否是重复提交的数据，该方法在这里是一个抽象方法，我们需要再定义一个类继承自这个抽象类，在新的子类中，可以有不同的幂等性判断逻辑，这里我们就是根据 URL 地址+参数来判断幂等性条件是否满足：

@Component
public class SameUrlDataInterceptor extends RepeatSubmitInterceptor {
    public final String REPEAT_PARAMS = "repeatParams";

    public final String REPEAT_TIME = "repeatTime";
    public final static String REPEAT_SUBMIT_KEY = "REPEAT_SUBMIT_KEY";

    private String header = "Authorization";

    @Autowired
    private RedisCache redisCache;

    @SuppressWarnings("unchecked")
    @Override
    public boolean isRepeatSubmit(HttpServletRequest request, RepeatSubmit annotation) {
        String nowParams = "";
        if (request instanceof RepeatedlyRequestWrapper) {
            RepeatedlyRequestWrapper repeatedlyRequest = (RepeatedlyRequestWrapper) request;
            try {
                nowParams = repeatedlyRequest.getReader().readLine();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }

        // body参数为空，获取Parameter的数据
        if (StringUtils.isEmpty(nowParams)) {
            try {
                nowParams = new ObjectMapper().writeValueAsString(request.getParameterMap());
            } catch (JsonProcessingException e) {
                e.printStackTrace();
            }
        }
        Map<String, Object> nowDataMap = new HashMap<String, Object>();
        nowDataMap.put(REPEAT_PARAMS, nowParams);
        nowDataMap.put(REPEAT_TIME, System.currentTimeMillis());

        // 请求地址（作为存放cache的key值）
        String url = request.getRequestURI();

        // 唯一值（没有消息头则使用请求地址）
        String submitKey = request.getHeader(header);

        // 唯一标识（指定key + url + 消息头）
        String cacheRepeatKey = REPEAT_SUBMIT_KEY + url + submitKey;

        Object sessionObj = redisCache.getCacheObject(cacheRepeatKey);
        if (sessionObj != null) {
            Map<String, Object> sessionMap = (Map<String, Object>) sessionObj;
            if (compareParams(nowDataMap, sessionMap) && compareTime(nowDataMap, sessionMap, annotation.interval())) {
                return true;
            }
        }
        redisCache.setCacheObject(cacheRepeatKey, nowDataMap, annotation.interval(), TimeUnit.MILLISECONDS);
        return false;
    }

    /**
     * 判断参数是否相同
     */
    private boolean compareParams(Map<String, Object> nowMap, Map<String, Object> preMap) {
        String nowParams = (String) nowMap.get(REPEAT_PARAMS);
        String preParams = (String) preMap.get(REPEAT_PARAMS);
        return nowParams.equals(preParams);
    }

    /**
     * 判断两次间隔时间
     */
    private boolean compareTime(Map<String, Object> nowMap, Map<String, Object> preMap, int interval) {
        long time1 = (Long) nowMap.get(REPEAT_TIME);
        long time2 = (Long) preMap.get(REPEAT_TIME);
        if ((time1 - time2) < interval) {
            return true;
        }
        return false;
    }
}
复制代码

我们来看下具体的实现逻辑：

首先判断当前的请求对象是不是 RepeatedlyRequestWrapper，如果是，说明当前的请求参数是 JSON，那么就通过 IO 流将参数读取出来
如果在第一步中，并没有拿到参数，那么说明参数可能并不是 JSON 格式，而是 key-value 格式，那么就以 key-value 的方式读取出来参数，并将之转为一个 JSON 字符串。
接下来构造一个 Map，将前面读取到的参数和当前时间存入到 Map 中。
接下来构造存到 Redis 中的数据的 key，这个 key 由固定前缀 + 请求 URL 地址 + 请求头的认证令牌组成，这块请求头的令牌还是非常重要需要有的，只有这样才能区分出来当前用户提交的数据（如果是 RESTful 风格的接口，那么为了区分，也可以将接口的请求方法作为参数拼接到 key 中）。
接下来就去 Redis 中获取数据，获取到之后，分别去比较参数是否相同以及时间是否过期。
如果判断都没问题，返回 true，表示这个请求重复了。
否则返回说明这是用户对这个接口第一次提交数据或者是已经过了时间窗口了，那么就把参数字符串重新缓存到 Redis 中，并返回 false，表示请求没问题。

好啦，做完这一切，最后我们再来配置一下拦截器即可：

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    RepeatSubmitInterceptor repeatSubmitInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(repeatSubmitInterceptor)
                .addPathPatterns("/**");
    }
}
复制代码

如此，我们的接口幂等性就处理好啦～在需要的时候，就可以直接在接口上使用啦：

@RestController
public class HelloController {

    @PostMapping("/hello")
    @RepeatSubmit(interval = 100000)
    public String hello(@RequestBody String msg) {
        System.out.println("msg = " + msg);
        return "hello";    }
}