领读：

文中自定义注解AutoIdempotent，并通过拦截器拦截此注解，然后判断request中的token在redis中是否已经被消费，如果已被消费说明接口是重复提交，从而实现幂等设计。
通过本文，你应该学会：

  1. 自定义注解，拦截注解
  2. 幂等设计的原理，以及流程
  3. 如何实现自动验证token

前言: 在实际的开发项目中, 一个对外暴露的接口往往会面临很多次请求，我们来解释一下幂等的概念：任意多次执行所产生的影响均与一次执行的影响相同。按照这个含义，最终的含义就是 对数据库的影响只能是一次性的，不能重复处理。如何保证其幂等性，通常有以下手段：
1: 数据库建立唯一性索引，可以保证最终插入数据库的只有一条数据
2: token 机制，每次接口请求前先获取一个 token，然后再下次请求的时候在请求的 header 体中加上这个 token，后台进行验证，如果验证通过删除 token，下次请求再次判断 token
3: 悲观锁或者乐观锁，悲观锁可以保证每次 for update 的时候其他 sql 无法 update 数据 (在数据库引擎是 innodb 的时候, select 的条件必须是唯一索引, 防止锁全表)
4: 先查询后判断，首先通过查询数据库是否存在数据，如果存在证明已经请求过了，直接拒绝该请求，如果没有存在，就证明是第一次进来，直接放行。
redis 实现自动幂等的原理图：
image.png

一：搭建 redis 的服务 Api

1: 首先是搭建 redis 服务器。详情可参考：https://www.cnblogs.com/wyq178/p/10340234.html
2: 引入 springboot 中到的 redis 的 stater，或者 Spring 封装的 jedis 也可以，后面主要用到的 api 就是它的 set 方法和 exists 方法, 这里我们使用 springboot 的封装好的 redisTemplate

  1. /**
  2.  * redis工具类
  3.  */
  4. @Component
  5. public class RedisService {
  7.     @Autowired
  8.     private RedisTemplate redisTemplate;
  10.     /**
  11.      * 写入缓存
  12.      * @param key
  13.      * @param value
  14.      * @return
  15.      */
  16.     public boolean set(final String key, Object value) {
  17.         boolean result = false;
  18.         try {
  19.             ValueOperations<Serializable, Object> operations = redisTemplate.opsForValue();
  20.             operations.set(key, value);
  21.             result = true;
  22.         } catch (Exception e) {
  23.             e.printStackTrace();
  24.         }
  25.         return result;
  26.     }
  29.     /**
  30.      * 写入缓存设置时效时间
  31.      * @param key
  32.      * @param value
  33.      * @return
  34.      */
  35.     public boolean setEx(final String key, Object value, Long expireTime) {
  36.         boolean result = false;
  37.         try {
  38.             ValueOperations<Serializable, Object> operations = redisTemplate.opsForValue();
  39.             operations.set(key, value);
  40.             redisTemplate.expire(key, expireTime, TimeUnit.SECONDS);
  41.             result = true;
  42.         } catch (Exception e) {
  43.             e.printStackTrace();
  44.         }
  45.         return result;
  46.     }
  49.     /**
  50.      * 判断缓存中是否有对应的value
  51.      * @param key
  52.      * @return
  53.      */
  54.     public boolean exists(final String key) {
  55.         return redisTemplate.hasKey(key);
  56.     }
  58.     /**
  59.      * 读取缓存
  60.      * @param key
  61.      * @return
  62.      */
  63.     public Object get(final String key) {
  64.         Object result = null;
  65.         ValueOperations<Serializable, Object> operations = redisTemplate.opsForValue();
  66.         result = operations.get(key);
  67.         return result;
  68.     }
  70.     /**
  71.      * 删除对应的value
  72.      * @param key
  73.      */
  74.     public boolean remove(final String key) {
  75.         if (exists(key)) {
  76.             Boolean delete = redisTemplate.delete(key);
  77.             return delete;
  78.         }
  79.         return false;
  81.     }
  83. }
  1. package cn.com.sgcc.js.workflow.management.common.config;
  3. import org.springframework.beans.factory.annotation.Autowired;
  4. import org.springframework.context.annotation.Bean;
  5. import org.springframework.context.annotation.Configuration;
  6. import org.springframework.data.redis.connection.RedisConnectionFactory;
  7. import org.springframework.data.redis.core.RedisTemplate;
  8. import org.springframework.data.redis.serializer.StringRedisSerializer;
  10. /***
  11.  * redis config
  12.  * @author zhengpei
  13.  * @date 2021/7/12
  14.  */
  15. @Configuration
  16. public class RedisConfig {
  18.   @Autowired
  19.   private RedisConnectionFactory factory;
  21.   @Bean
  22.   public RedisTemplate<String, Object> redisTemplate() {
  23.     RedisTemplate<String, Object> redisTemplate = new RedisTemplate<>();
  24.     redisTemplate.setKeySerializer(new StringRedisSerializer());
  25.     redisTemplate.setHashKeySerializer(new StringRedisSerializer());
  26.     redisTemplate.setHashValueSerializer(new StringRedisSerializer());
  27.     redisTemplate.setValueSerializer(new StringRedisSerializer());
  28.     redisTemplate.setConnectionFactory(factory);
  29.     return redisTemplate;
  30.   }
  31. }

二：自定义注解 AutoIdempotent

自定义一个注解，定义此注解的主要目的是把它添加在需要实现幂等的方法上，凡是某个方法注解了它，都会实现自动幂等。后台利用反射如果扫描到这个注解，就会处理这个方法实现自动幂等，使用元注解 ElementType.METHOD 表示它只能放在方法上，etentionPolicy.RUNTIME 表示它在运行时

  1. import java.lang.annotation.ElementType;
  2. import java.lang.annotation.Retention;
  3. import java.lang.annotation.RetentionPolicy;
  4. import java.lang.annotation.Target;
  6. /***
  7.  * 自定义注解实现幂等性
  8.  * @author zhengpei
  9.  * @date 2021/7/12
  10.  */
  11. @Target(ElementType.METHOD)
  12. @Retention(RetentionPolicy.RUNTIME)
  13. public @interface AutoIdempotency {
  15. }

三：token 创建和检验

1:token 服务接口

我们新建一个接口，创建 token 服务，里面主要是两个方法，一个用来创建 token，一个用来验证 token。创建 token 主要产生的是一个字符串，检验 token 的话主要是传达 request 对象，为什么要传 request 对象呢？主要作用就是获取 header 里面的 token, 然后检验，通过抛出的 Exception 来获取具体的报错信息返回给前端

  1. public interface TokenService {
  3.     /**
  4.      * 创建token
  5.      * @return
  6.      */
  7.     public  String createToken();
  9.     /**
  10.      * 检验token
  11.      * @param request
  12.      * @return
  13.      */
  14.     public boolean checkToken(HttpServletRequest request) throws Exception;
  16. }

2:token 的服务实现类

token 引用了 redis 服务，创建 token 采用随机算法工具类生成随机 uuid 字符串, 然后放入到 redis 中 (为了防止数据的冗余保留, 这里设置过期时间为 10000 秒, 具体可视业务而定)，如果放入成功，最后返回这个 token 值。checkToken 方法就是从 header 中获取 token 到值 (如果 header 中拿不到，就从 paramter 中获取)，如若不存在, 直接抛出异常。这个异常信息可以被拦截器捕捉到，然后返回给前端。

  1. package cn.com.sgcc.js.workflow.management.common.manager.impl;
  3. import cn.com.sgcc.js.workflow.management.common.manager.TokenService;
  4. import cn.com.sgcc.js.workflow.management.common.util.RedisService;
  5. import cn.hutool.core.text.StrBuilder;
  6. import cn.hutool.core.util.StrUtil;
  7. import info.boruisi.framework.common.util.LoggerUtil;
  8. import info.boruisi.framework.common.util.RandomUtil;
  9. import org.hibernate.service.spi.ServiceException;
  10. import org.slf4j.Logger;
  11. import org.slf4j.LoggerFactory;
  12. import org.springframework.beans.factory.annotation.Autowired;
  13. import org.springframework.stereotype.Service;
  14. import javax.servlet.http.HttpServletRequest;
  16. /***
  17.  * token校验 服务实现
  18.  * @author zhengpei
  19.  * @date 2021/7/12
  20.  */
  21. @Service
  22. public class TokenServiceImpl implements TokenService {
  24.   private static final Logger LOGGER = LoggerFactory.getLogger(TokenServiceImpl.class);
  25.   private static final String TOKEN_PREFIX = "token:val:";
  26.   private static final String UNIQUE_TOKEN = "UNIQUE_TOKEN";
  27.   private static final String ILLEGAL_ARGUMENT = "参数中不存在幂等token";
  28.   private static final String REPETITIVE_OPERATION = "重复性请求操作";
  30.   @Autowired
  31.   RedisService redisService;
  33.   /**
  34.    * 创建 token
  35.    * @return token
  36.    */
  37.   @Override
  38.   public String createToken() {
  39.     String str = RandomUtil.createUUID(10);
  40.     StrBuilder token = new StrBuilder();
  41.     try {
  42.       token.append(TOKEN_PREFIX).append(str);
  43.       redisService.setEx(token.toString(), token.toString(), 10000L);
  44.       boolean notEmpty = StrUtil.isNotEmpty(token.toString());
  45.       if (notEmpty) {
  46.         return token.toString();
  47.       }
  48.     } catch (Exception ex) {
  49.       LoggerUtil.error(LOGGER, "createToken error", ex);
  50.     }
  51.     return null;
  52.   }
  54.   /**
  55.    * 校验token
  56.    * @param request HttpServletRequest
  57.    * @return
  58.    */
  59.   @Override
  60.   public boolean checkToken(HttpServletRequest request) {
  61.     String token = request.getHeader(UNIQUE_TOKEN);
  62.     if (StrUtil.isBlank(token)) {
  63.       // header中不存在token
  64.       token = request.getParameter(UNIQUE_TOKEN);
  65.       if (StrUtil.isBlank(token)) {
  66.         // parameter中也不存在token
  67.         throw new ServiceException(ILLEGAL_ARGUMENT);
  68.       }
  69.     }
  71.     if (!redisService.exists(token)) {
  72.       throw new ServiceException(REPETITIVE_OPERATION);
  73.     }
  75.     boolean remove = redisService.remove(token);
  76.     if (!remove) {
  77.       throw new ServiceException(REPETITIVE_OPERATION);
  78.     }
  79.     return true;
  80.   }
  82. }

四：拦截器的配置

1:web 配置类，实现 WebMvcConfigurerAdapter，主要作用就是添加 autoIdempotentInterceptor 到配置类中，这样我们到拦截器才能生效，注意使用 @Configuration 注解，这样在容器启动是时候就可以添加进入 context 中

  1. package cn.com.sgcc.js.workflow.management.common.config;
  3. import org.springframework.context.annotation.Configuration;
  4. import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
  5. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  6. import javax.annotation.Resource;
  8. /***
  9.  * web 配置类
  10.  * @author zhengpei
  11.  * @date 2021/7/12
  12.  */
  13. @Configuration
  14. public class WebConfiguration implements WebMvcConfigurer {
  16.   @Resource
  17.   private AutoIdempotentInterceptor autoIdempotentInterceptor;
  19.   /**
  20.    * 添加拦截器
  21.    * @param registry  InterceptorRegistry
  22.    */
  23.   @Override
  24.   public void addInterceptors(InterceptorRegistry registry) {
  25.     registry.addInterceptor(autoIdempotentInterceptor);
  26.   }
  27. }

2: 拦截处理器：主要的功能是拦截扫描到 AutoIdempotent 到注解到方法, 然后调用 tokenService 的 checkToken() 方法校验 token 是否正确，如果捕捉到异常就将异常信息渲染成 json 返回给前端

  1. package cn.com.sgcc.js.workflow.management.common.config;
  3. import cn.com.sgcc.js.workflow.management.common.annotation.AutoIdempotency;
  4. import cn.com.sgcc.js.workflow.management.common.manager.TokenService;
  5. import info.boruisi.framework.common.util.JsonUtil;
  6. import info.boruisi.platform.framework.web.model.RestResult;
  7. import org.springframework.beans.factory.annotation.Autowired;
  8. import org.springframework.stereotype.Component;
  9. import org.springframework.web.method.HandlerMethod;
  10. import org.springframework.web.servlet.HandlerInterceptor;
  11. import org.springframework.web.servlet.ModelAndView;
  13. import javax.servlet.http.HttpServletRequest;
  14. import javax.servlet.http.HttpServletResponse;
  15. import java.io.PrintWriter;
  16. import java.lang.reflect.Method;
  18. /***
  19.  * 拦截器
  20.  * @author zhengpei
  21.  * @date 2021/7/12
  22.  */
  23. @Component
  24. public class AutoIdempotentInterceptor implements HandlerInterceptor {
  26.   @Autowired
  27.   private TokenService tokenService;
  29.   /**
  30.    * 预处理
  31.    *
  32.    * @param request  HttpServletRequest
  33.    * @param response HttpServletResponse
  34.    * @param handler  Object
  35.    * @return boolean
  36.    * @throws Exception Exception
  37.    */
  38.   @Override
  39.   public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
  41.     if (!(handler instanceof HandlerMethod)) {
  42.       return true;
  43.     }
  44.     HandlerMethod handlerMethod = (HandlerMethod) handler;
  45.     Method method = handlerMethod.getMethod();
  46.     //被Api AutoIdempotency标记的扫描
  47.     AutoIdempotency methodAnnotation = method.getAnnotation(AutoIdempotency.class);
  48.     if (methodAnnotation != null) {
  49.       try {
  50.         // 幂等性校验, 校验通过则放行, 校验失败则抛出异常, 并通过统一异常处理返回友好提示
  51.         return tokenService.checkToken(request);
  52.       } catch (Exception ex) {
  53.         RestResult failedResult = new RestResult(false, ex.getMessage());
  54.         writeReturnJson(response, JsonUtil.writeAsString(failedResult));
  55.         throw ex;
  56.       }
  57.     }
  58.     //必须返回true,否则会被拦截一切请求
  59.     return true;
  60.   }
  63.   @Override
  64.   public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
  66.   }
  68.   @Override
  69.   public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
  71.   }
  73.   /**
  74.    * 返回的json值
  75.    *
  76.    * @param response HttpServletResponse
  77.    * @param json     value
  78.    * @throws Exception
  79.    */
  80.   private void writeReturnJson(HttpServletResponse response, String json) throws Exception {
  81.     PrintWriter writer = null;
  82.     response.setCharacterEncoding("UTF-8");
  83.     response.setContentType("text/html; charset=utf-8");
  84.     try {
  85.       writer = response.getWriter();
  86.       writer.print(json);
  87.     } finally {
  88.       if (writer != null) {
  89.         writer.close();
  90.       }
  91.     }
  92.   }
  94. }


五：测试用例

1: 模拟业务请求类

首先我们需要通过 /get/token 路径通过 getToken() 方法去获取具体的 token，然后我们调用 testIdempotence 方法，这个方法上面注解了 @AutoIdempotent，拦截器会拦截所有的请求，当判断到处理的方法上面有该注解的时候，就会调用 TokenService 中的 checkToken() 方法，如果捕获到异常会将异常抛出调用者，下面我们来模拟请求一下：

  1. @RestController
  2. public class BusinessController {
  5.     @Resource
  6.     private TokenService tokenService;
  8.     @Resource
  9.     private TestService testService;
  11.     @PostMapping("/get/token")
  12.     public String  getToken(){
  13.         String token = tokenService.createToken();
  14.         if (StrUtil.isNotEmpty(token)) {
  15.             ResultVo resultVo = new ResultVo();
  16.             resultVo.setCode(Constant.code_success);
  17.             resultVo.setMessage(Constant.SUCCESS);
  18.             resultVo.setData(token);
  19.             return JSONUtil.toJsonStr(resultVo);
  20.         }
  21.         return StrUtil.EMPTY;
  22.     }
  25.     @AutoIdempotent
  26.     @PostMapping("/test/Idempotence")
  27.     public String testIdempotence() {
  28.         String businessResult = testService.testIdempotence();
  29.         if (StrUtil.isNotEmpty(businessResult)) {
  30.             ResultVo successResult = ResultVo.getSuccessResult(businessResult);
  31.             return JSONUtil.toJsonStr(successResult);
  32.         }
  33.         return StrUtil.EMPTY;
  34.     }
  35. }

2: 使用 postman 请求

首先访问 get/token 路径获取到具体到 token：
image.png
利用获取到到 token, 然后放到具体请求到 header 中, 可以看到第一次请求成功，接着我们请求第二次：
image.png
第二次请求，返回到是重复性操作，可见重复性验证通过，再多次请求到时候我们只让其第一次成功，第二次就是失败：
image.png

六：总结

本篇博客介绍了使用 springboot 和拦截器、redis 来优雅的实现接口幂等，对于幂等在实际的开发过程中是十分重要的，因为一个接口可能会被无数的客户端调用，如何保证其不影响后台的业务处理，如何保证其只影响数据一次是非常重要的，它可以防止产生脏数据或者乱数据，也可以减少并发量，实乃十分有益的一件事。而传统的做法是每次判断数据，这种做法不够智能化和自动化，比较麻烦。而今天的这种自动化处理也可以提升程序的伸缩性。