SpringBoot-接口幂等性

幂等

幂等操作的特点是其任意多次执行所产生的影响均与一次执行的影响相同。

幂等函数或幂等方法是指可以使用相同参数重复执行，并能获得相同结果的函数。这些函数不会影响系统状态，也不用担心重复执行会对系统造成改变。

尤其是支付、订单等与金钱挂钩的服务，保证接口幂等性尤其重要。在实际开发中，我们需要针对不同的业务场景我们需要灵活的选择幂等性的实现方式：

• 对于下单等存在唯一主键的，可以使用“唯一主键方案”的方式实现。
• 对于更新订单状态等相关的更新场景操作，使用“乐观锁方案”实现更为简单。
• 对于上下游这种，下游请求上游，上游服务可以使用“下游传递唯一序列号方案”更为合理。
• 类似于前端重复提交、重复下单、没有唯一ID号的场景，可以通过 Token 与 Redis 配合的“防重 Token 方案”实现更为快捷。

接口幂等

在HTTP/1.1中，对幂等性进行了定义。它描述了一次和多次请求某一个资源对于资源本身应该具有同样的结果（网络超时等问题除外），即第一次请求的时候对资源产生了副作用，但是以后的多次请求都不会再对资源产生副作用。

为什么需要实现幂等性

1、前端重复提交表单： 在填写一些表格时候，用户填写完成提交，很多时候会因网络波动没有及时对用户做出提交成功响应，致使用户认为没有成功提交，然后一直点提交按钮，这时就会发生重复提交表单请求。

2、用户恶意进行刷单： 例如在实现用户投票这种功能时，如果用户针对一个用户进行重复提交投票，这样会导致接口接收到用户重复提交的投票信息，这样会使投票结果与事实严重不符。

3、接口超时重复提交： 很多时候 HTTP 客户端工具都默认开启超时重试的机制，尤其是第三方调用接口时候，为了防止网络波动超时等造成的请求失败，都会添加重试机制，导致一个请求提交多次。

4、消息进行重复消费： 当使用 MQ 消息中间件时候，如果发生消息中间件出现错误未及时提交消费信息，导致发生重复消费。

幂等性是为了简化客户端逻辑处理，能放置重复提交等操作，但却增加了服务端的逻辑复杂性和成本，其主要是：

• 把并行执行的功能改为串行执行，降低了执行效率。
• 增加了额外控制幂等的业务逻辑，复杂化了业务功能；

Restful API 接口的幂等性

实现幂等性的方案

方案一：数据库唯一主键

使用数据库唯一主键完成幂等性时需要注意的是，该主键一般来说并不是使用数据库中自增主键，而是使用分布式 ID 充当主键，这样才能能保证在分布式环境下 ID 的全局唯一性。

使用操作：插入操作，删除操作

使用限制：需要生成全局唯一主键ID

如果插入成功则标识没有重复调用接口，如果抛出主键重复异常，则标识数据库已经存在该条记录，返回错误信息到客户端

方案二：数据库乐观锁

只适用于“更新操作”的过程，在对应的数据表中添加一个字段，充当当前字段的版本标识。
每次对该数据库表的这条字段执行更新时，都会将该版本标识作为一个条件，值为上次待更新数据中的版本标识的值。

这样每次执行更新时候，都要指定要更新的版本号，如下操作就能准确更新 version=5 的信息：

UPDATE my_table SET price=price+50,version=version+1 WHERE id=1 AND version=5
1

上面 WHERE 后面跟着条件 id=1 AND version=5 被执行后，id=1 的 version 被更新为 6，所以如果重复执行该条 SQL 语句将不生效，因为 id=1 AND version=5 的数据已经不存在，这样就能保住更新的幂等，多次更新对结果不会产生影响。

方案三：防重 Token 令牌

针对客户端连续点击或者调用方的超时重试等
例如提交订单，此操作可以用token的机制防止重复提交。
调用方在调用接口的时候先向后端请求一个全局ID（Token），请求的时候携带这个全局ID一起请求（Token最好将其放到Headers中），后端需要对这个Token作为Key，用户信息作为Value到Redis中进行键值内容校验，如果Key存在且Value匹配就执行删除命令，然后正常执行后面的业务逻辑，如果不存在对应的key或Value不匹配就返回重复执行的错误信息。

适用：

• 插入操作
• 更新操作
• 删除操作

需要生成全局唯一 Token 串；
需要使用第三方组件 Redis 进行数据效验；

① 服务端提供获取 Token 的接口，该 Token 可以是一个序列号，也可以是一个分布式 ID 或者 UUID 串。

② 客户端调用接口获取 Token，这时候服务端会生成一个 Token 串。

③ 然后将该串存入 Redis 数据库中，以该 Token 作为 Redis 的键（注意设置过期时间）。

④ 将 Token 返回到客户端，客户端拿到后应存到表单隐藏域中。

⑤ 客户端在执行提交表单时，把 Token 存入到 Headers 中，执行业务请求带上该 Headers。

⑥ 服务端接收到请求后从 Headers 中拿到 Token，然后根据 Token 到 Redis 中查找该 key 是否存在。

⑦ 服务端根据 Redis 中是否存该 key 进行判断，如果存在就将该 key 删除，然后正常执行业务逻辑。如果不存在就抛异常，返回重复提交的错误信息。

在并发情况下，执行 Redis 查找数据与删除需要保证原子性，否则很可能在并发下无法保证幂等性。其实现方法可以使用分布式锁或者使用 Lua 表达式来注销查询与删除操作。

方案四：下游传递唯一序列号

所谓请求序列号，其实就是每次向服务端请求时候附带一个短时间内唯一不重复的序列号，该序列号可以是一个有序 ID，也可以是一个订单号，一般由下游生成，在调用上游服务端接口时附加该序列号和用于认证的 ID

当上游服务器收到请求信息后拿取该 序列号 和下游 认证ID 进行组合，形成用于操作 Redis 的 Key，然后到 Redis 中查询是否存在对应的 Key 的键值对，根据其结果：

• 如果存在，就说明已经对该下游的该序列号的请求进行了业务处理，这时可以直接响应重复请求的错误信息。
• 如果不存在，就以该 Key 作为 Redis 的键，以下游关键信息作为存储的值（例如下游商传递的一些业务逻辑信息），将该键值对存储到 Redis 中 ，然后再正常执行对应的业务逻辑即可。

适用操作：

• 插入操作
• 更新操作
• 删除操作

要求第三方传递唯一序列号
需要使用第三方组件Redis进行数据校验

① 下游服务生成分布式 ID 作为序列号，然后执行请求调用上游接口，并附带“唯一序列号”与请求的“认证凭据ID”。

② 上游服务进行安全效验，检测下游传递的参数中是否存在“序列号”和“凭据ID”。

③ 上游服务到 Redis 中检测是否存在对应的“序列号”与“认证ID”组成的 Key，如果存在就抛出重复执行的异常信息，然后响应下游对应的错误信息。如果不存在就以该“序列号”和“认证ID”组合作为 Key，以下游关键信息作为 Value，进而存储到 Redis 中，然后正常执行接来来的业务逻辑。

上面步骤中插入数据到 Redis 一定要设置过期时间。这样能保证在这个时间范围内，如果重复调用接口，则能够进行判断识别。如果不设置过期时间，很可能导致数据无限量的存入 Redis，致使 Redis 不能正常工作。

业务实例

这里使用防重 Token 令牌方案，该方案能保证在不同请求动作下的幂等性，实现逻辑可以看上面写的”防重 Token 令牌”方案

1、引入依赖

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0modelVersion>

    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.3.4.RELEASEversion>
    parent>

    <groupId>mydlq.clubgroupId>
    <artifactId>springboot-idempotent-tokenartifactId>
    <version>0.0.1version>
    <name>springboot-idempotent-tokenname>
    <description>Idempotent Demodescription>

    <properties>
        <java.version>1.8java.version>
    properties>

    <dependencies>
        
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-data-redisartifactId>
        dependency>
        <dependency>
            <groupId>org.apache.commonsgroupId>
            <artifactId>commons-pool2artifactId>
        dependency>
        
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
        dependency>
    dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
            plugin>
        plugins>
    build>

project>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

2、配置redis连接参数

spring:
  redis:
    ssl: false
    host: 127.0.0.1
    port: 6379
    database: 0
    timeout: 1000
    password:
    lettuce:
      pool:
        max-active: 100
        max-wait: -1
        min-idle: 0
        max-idle: 20
1
2
3
4
5
6
7
8
9
10
11
12
13
14

3、创建与验证Token工具类

@Slf4j
@Service
public class TokenUtilService{
	
	@Autowired
	private StringRedisTemplate redisTemplate;

	//存入redis的token前缀
	private static final String IDEMPORTENT_TOKEN_PREFIX = "idempotent_token:";

	public String generateToken(String value){
		
		String token = UUID.randomUUID().toString();

		String key = IDEMPOTENT_TOKEN_PREFIX + token;

		redisTemplate.opsForValue().set(key,value,5,TimeUnit.MINUTES);
		return token;
	}

	public boolean validToken(String token,String value){
		
		//设置lua脚本，其中KEYS[1]是key，KEYS[2]是value
		String script = "if redis.call('get', KEYS[1]) == KEYS[2] then return redis.call('del', KEYS[1]) else return 0 end";
		RedisScript<Long> redisScript = new DefaultRedisScript<>(script,Long.class);
		
		//根据key前缀拼接key
		String key = IDEMPOTENT_TOKEN_PREFIX + token;
		//执行lau脚本
		Long result = redisTemplate.execute(redisScript, Arrays.asList(key, value)); 
		// 根据返回结果判断是否成功成功匹配并删除 Redis 键值对，若果结果不为空和0，则验证通过
        if (result != null && result != 0L) {
            log.info("验证 token={},key={},value={} 成功", token, key, value);
            return true;
        }
        log.info("验证 token={},key={},value={} 失败", token, key, value);
        return false;
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

4、创建测试的Coltroller

创建用于测试的 Controller 类，里面有获取 Token 与测试接口幂等性的接口

@Slf4j
@RestController
public class TokenController {

    @Autowired
    private TokenUtilService tokenService;
    
	@GetMapping("/token")
	public String getToken(){
		
		/ 获取用户信息（这里使用模拟数据）
        // 注：这里存储该内容只是举例，其作用为辅助验证，使其验证逻辑更安全，如这里存储用户信息，其目的为:
        // - 1)、使用"token"验证 Redis 中是否存在对应的 Key
        // - 2)、使用"用户信息"验证 Redis 的 Value 是否匹配。
        String userInfo = "mydlq";
        // 获取 Token 字符串，并返回
        return tokenService.generateToken(userInfo);
	}

	 /**
     * 接口幂等性测试接口
     *
     * @param token 幂等 Token 串
     * @return 执行结果
     */
    @PostMapping("/test")
    public String test(@RequestHeader(value = "token") String token) {
        // 获取用户信息（这里使用模拟数据）
        String userInfo = "mydlq";
        // 根据 Token 和与用户相关的信息到 Redis 验证是否存在对应的信息
        boolean result = tokenService.validToken(token, userInfo);
        // 根据验证结果响应不同信息
        return result ? "正常调用" : "重复调用";
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

5、启动类

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}
1
2
3
4
5
6
7
8

6、测试

写个测试类进行测试，多次访问同一个接口，测试是否只有第一次能否执行成功。

@Slf4j
@SpringBootTest
@RunWith(SpringRunner.class)
public class IdempotenceTest {

    @Autowired
    private WebApplicationContext webApplicationContext;

    @Test
    public void interfaceIdempotenceTest() throws Exception {
        // 初始化 MockMvc
        MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext).build();
        // 调用获取 Token 接口
        String token = mockMvc.perform(MockMvcRequestBuilders.get("/token")
                .accept(MediaType.TEXT_HTML))
                .andReturn()
                .getResponse().getContentAsString();
        log.info("获取的 Token 串：{}", token);
        // 循环调用 5 次进行测试
        for (int i = 1; i <= 5; i++) {
            log.info("第{}次调用测试接口", i);
            // 调用验证接口并打印结果
            String result = mockMvc.perform(MockMvcRequestBuilders.post("/test")
                    .header("token", token)
                    .accept(MediaType.TEXT_HTML))
                    .andReturn().getResponse().getContentAsString();
            log.info(result);
            // 结果断言
            if (i == 0) {
                Assert.assertEquals(result, "正常调用");
            } else {
                Assert.assertEquals(result, "重复调用");
            }
        }
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

注解实现幂等性

①、自定义注解

@Target(value = ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent{

	//参数名，表示将从哪个参数中获取属性值。获取到的属性值将作为KEY。
	String name() default "";

	//属性，表示将获取哪个属性的值。
	String field() default "";

	//参数类型
	Class type(); 
}
1
2
3
4
5
6
7
8
9
10
11
12
13

②、统一的请求入参对象

@Data
public class RequestData<T> {

    private Header header;

    private T body;

}

1
2
3
4
5
6
7
8
9

@Data
public class Header {

    private String token;

}
1
2
3
4
5
6
7

@Data
public class Order {

    String orderNo;

}
1
2
3
4
5
6

③、AOP处理

@Aspect
@Component
public class IDempotentAspect{
	
	@Resource
	private RedisIdempotentStorage redisIdempotentStorage;

	@Pointcut("@annotation(com.springboot.micrometer.annotation.Idempotent)")
	public void idempotent(){}
	
	@Around("idempotent()")
	public Object methodAround(ProceedingJoinPoint joinPoint) throws Throwable {
		
		MethodSignature signature = (MethodSignature)jointPoint.getSignature();
		Method method = signature.getMethod();
        Idempotent idempotent = method.getAnnotation(Idempotent.class);
		
		
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

public class AopUtils{
	
	public static Object getFieldValue(Object obj,String name)throws Exception{
		
		return object;
	}

	public static Map<String,Object> getParamValue(ProceedingJoinPoint joinPoint){
		
		return params;
	}
}
1
2
3
4
5
6
7
8
9
10
11
12

④、Token值生成

@RestController
@RequestMapping("/idGenerator")
public class IdGeneratorController{
	
	@Resource
	private RedisIdempotentStorage redisIdempotentStorage;

	@RequestMapping("/getIdGeneratorToken")
	public String getIdGeneratorToken(){
		String generateId  IdGeneratorUtil.generateId();
		redisIdempotentStorage.save(generateId);
		return generateId;
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

public interface IdempotentStorage{
	
	void save(String idempotentId);
	boolean delete(String idempotentId);
}
1
2
3
4
5

@Component
public class RedisIdempotentStorage implements IdempotentStorage{
	
	@Resource
	private RedisTemplate<String,Serializable> redisTemplate;

	@Override
	public void save(String idempotentId){
		redisTemplate.opsForValue().set(idempotentId, idempotentId, 10, TimeUnit.MINUTES);
	}

	@Override
    public boolean delete(String idempotentId) {
        return redisTemplate.delete(idempotentId);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class IdGeneratorUtil {

    public static String generateId() {
        return UUID.randomUUID().toString();
    }

}
1
2
3
4
5
6
7

⑤、请求示例

调用接口之前，先申请一个token，然后带着服务端返回的token值，再去请求。

@RestController
@RequestMapping("/order")
public class OrderController {

    @RequestMapping("/saveOrder")
    @Idempotent(name = "requestData", type = RequestData.class, field = "token")
    public String saveOrder(@RequestBody RequestData<Order> requestData) {
        return "success";
    }

}
1
2
3
4
5
6
7
8
9
10
11

请求获取token值。

带着token值，第一次请求成功。

第二次请求失败。

SpringCloud分布式系统实现幂等性的方式

MVCC方案

多版本并发控制，该策略主要使用update with condition（更新带条件来防止）来保证多次外部请求调用对系统的影响是一致的。在系统设计的过程中，合理的使用乐观锁，通过version或者updateTime（timestamp）等其他条件，来做乐观锁的判断条件，这样保证更新操作即使在并发的情况下，也不会有太大的问题。例如

select * from tablename where condition=#condition# //取出要跟新的对象，带有版本versoin
update tableName set name=#name#,version=version+1 where version=#version#
1
2

在更新的过程中利用version来防止，其他操作对对象的并发更新，导致更新丢失。为了避免失败，通常需要一定的重试机制。

去重表

在插入数据的时候，插入去重表，利用数据库的唯一索引特性，保证唯一的逻辑。

这种方法适用于在业务中有唯一标的插入场景中，比如在以上的支付场景中，如果一个订单只会支付一次，所以订单ID可以作为唯一标识。这时，我们就可以建一张去重表，并且把唯一标识作为唯一索引，在我们实现时，把创建支付单据和写入去去重表，放在一个事务中，如果重复创建，数据库会抛出唯一约束异常，操作就会回滚。

select for update，整个执行过程中锁定该订单对应的记录。注意：这种在DB读大于写的情况下尽量少用。

select + insert

并发不高的后台系统，或者一些任务JOB，为了支持幂等，支持重复执行，简单的处理方法是，先查询下一些关键数据，判断是否已经执行过，在进行业务处理，就可以了。注意：核心高并发流程不要用这种方法。

状态机幂等

在设计单据相关的业务，或者是任务相关的业务，肯定会涉及到状态机，就是业务单据上面有个状态，状态在不同的情况下会发生变更，一般情况下存在有限状态机，这时候，如果状态机已经处于下一个状态，这时候来了一个上一个状态的变更，理论上是不能够变更的，这样的话，保证了有限状态机的幂等。

这种方法适合在有状态机流转的情况下，比如就会订单的创建和付款，订单的付款肯定是在之前，这时我们可以通过在设计状态字段时，使用int类型，并且通过值类型的大小来做幂等，比如订单的创建为1000，付款成功为1。付款失败为999。

token机制，防止页面重复提交

业务要求：页面的数据只能被点击提交一次，

发生原因：由于重复点击或者网络重发，或者nginx重发等情况会导致数据被重复提交

解决办法：

集群环境：采用token加redis（redis单线程的，处理需要排队）
单JVM环境：采用token加redis或token加jvm内存
处理流程：

数据提交前要向服务的申请token，token放到redis或jvm内存，token有效时间
提交后后台校验token，同时删除token，生成新的token返回
token特点:要申请，一次有效性，可以限流

对外提供接口的api如何保证幂等

如微信提供的付款接口：需要接入商户提交付款请求时附带：source来源，seq序列号。source+seq在数据库里面做唯一索引，防止多次付款，(并发时，只能处理一个请求)

「总结：」 幂等性应该是合格程序员的一个基因，在设计系统时，是首要考虑的问题，尤其是在像支付宝，银行，互联网金融公司等涉及的都是钱的系统，既要高效，数据也要准确，所以不能出现多扣款，多打款等问题，这样会很难处理，用户体验也不好 。

全局唯一ID

如果使用全局唯一ID，就是根据业务的操作和内容生成一个全局ID，在执行操作前先根据这个全局唯一ID是否存在，来判断这个操作是否已经执行。如果不存在则把全局ID，存储到存储系统中，比如数据库、redis等。如果存在则表示该方法已经执行。

从工程的角度来说，使用全局ID做幂等可以作为一个业务的基础的微服务存在，在很多的微服务中都会用到这样的服务，在每个微服务中都完成这样的功能，会存在工作量重复。另外打造一个高可靠的幂等服务还需要考虑很多问题，比如一台机器虽然把全局ID先写入了存储，但是在写入之后挂了，这就需要引入全局ID的超时机制。

使用全局唯一ID是一个通用方案，可以支持插入、更新、删除业务操作。但是这个方案看起来很美但是实现起来比较麻烦，下面的方案适用于特定的场景，但是实现起来比较简单。

分布式锁

在进入方法时，先去获取锁，假如获取到锁，就继续后面的流程。假如没有获取到锁，就等待锁的释放直到获取到锁。当执行完方法时，释放锁。当然，锁要设个超时时间，防止意外没有释放到锁。它用来解决分布式系统的幂等性，常用的实现方案是 redis 和 zookeeper 等工具。

总结：

幂等性增加了额外控制幂等的业务逻辑，复杂化了业务功能，把并行执行的功能改为串行执行，降低了执行效率。

幂等性虽然复杂化了业务功能和降低了执行效率，但为了保证系统的正确性，是必要的。就上面更新 X 的例子，在单台服务器上，给那段代码加上锁，并给 X 设为 volatile，就保证来数据的正确性了。

在分布式环境下并且 X 是从数据库或者文件里查询出来的，用上面加锁的方式实现就不能保证数据的正确性了，这时候就需要用到分布式锁了。所以，保证方法或接口的幂等性是非常有必要的，因为数据是不能出现任何问题的。