如何保证接口幂等性？

文章目录

1. 为什么要保证幂等性？
2. 如何保证接口幂等性
- ①：数据库唯一主键
- ②：CAS乐观锁机制 - 数据版本号
- ③：防重 Token 令牌
- ④：请求时携带唯一序列号ID
- ⑤：加本地锁或分布式锁
3. 案例：基于防重 Token 令牌实现接口幂等
4. 总结

1. 为什么要保证幂等性？

幂等性要求任意多次执行对资源本身所产生的影响均与一次执行的影响相同，如果不保证幂等性，在发生如下情况时就会出现问题：

前端重复提交表单：在填写一些表格时候，用户填写完成提交，很多时候会因网络波动没有及时对用户做出提交成功响应，致使用户认为没有成功提交，然后一直点提交按钮，这时就会发生重复提交表单请求。
用户恶意进行刷单：例如在实现用户投票这种功能时，如果用户针对一个用户进行重复提交投票，这样会导致接口接收到用户重复提交的投票信息，这样会使投票结果与事实严重不符。
接口超时重复提交：很多时候 HTTP 客户端工具都默认开启超时重试的机制，尤其是第三方调用接口时候，为了防止网络波动超时等造成的请求失败，都会添加重试机制，导致一个请求提交多次，如 feign、dubbo等
消息进行重复消费：当使用 MQ 消息中间件时候，如果发生消息中间件出现错误未及时提交消费信息，导致发生重复消费。

使用幂等性最大的优势在于使接口保证任何幂等性操作，免去因重试等造成系统产生的未知的问题。但引入幂等性也会对系统效率造成一定影响

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

现在流行的 Restful 推荐的几种 HTTP 接口方法中，分别存在幂等行与不能保证幂等的方法，如下：

方法	是否满足幂等	说明
GET	满足	仅获取资源，不修改资源，无论访问多少次都一样
POST	不满足	用于添加数据，多次执行，数据不一致
PUT	可能满足，也可能不满足	用于修改资源，更新数据中的某个值，一般情况下幂等但累加、累减时不幂等
DELETE	可能满足，也可能不满足	用于删除资源，删除同一条数据时幂等但当新增的一条数据也满足删除条件，此时也会删除新增的数据，不幂等！

2. 如何保证接口幂等性

①：数据库唯一主键

方案描述：

数据库唯一主键的实现主要是利用数据库中主键唯一约束的特性，一般来说唯一主键比较适用于“插入”时的幂等性，其能保证一张表中只能存在一条带该唯一主键的记录。

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

适用操作：

插入操作
删除操作

使用限制：

需要生成全局唯一主键 ID；

主要流程：

客户端执行创建请求，调用服务端接口。
服务端执行业务逻辑，生成一个分布式 ID，将该 ID 充当待插入数据的主键，然后执数据插入操作，运行对应的 SQL 语句。
服务端将该条数据插入数据库中，如果插入成功则表示没有重复调用接口。如果抛出主键重复异常，则表示数据库中已经存在该条记录，返回错误信息到客户端。

②：CAS乐观锁机制 - 数据版本号

方案描述：

数据库乐观锁方案一般只能适用于执行“更新操作”的过程，我们可以提前在对应的数据表中多添加一个字段，充当当前数据的版本标识。这样每次对该数据库该表的这条数据执行更新时，都会将该版本标识作为一个条件，值为上次待更新数据中的版本标识的值。

适用操作：

更新操作

使用限制：

需要数据库对应业务表中添加额外字段；

主要流程：

为了每次执行更新时防止重复更新，确定更新的一定是要更新的内容，我们通常都会添加一个 version 字段记录当前的记录版本，这样在更新时候将该值带上，那么只要执行更新操作就能确定一定更新的是某个对应版本下的信息。
这样每次执行更新时候，都要指定要更新的版本号，如下操作就能准确更新 version=5 的信息：
```
UPDATE my_table SET price=price+50,version=version+1 WHERE id=1 AND version=5
```
上面 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 中检测是否存在对应的“序列号ID”的 Key，如果存在就抛出重复执行的异常信息，然后响应对应的错误信息。如果不存在就以该“序列号ID”作为 Key，以下游关键信息作为 Value，进而存储到 Redis 中，然后正常执行接来来的业务逻辑。注意：插入数据到 Redis 一定要设置过期时间。

适用操作：

插入操作
删除操作

使用限制：

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

主要流程：

主要步骤：

下游服务请求之前生成分布式 ID 作为序列号，然后执行请求调用上游接口，并附带“唯一序列ID"。
上游服务进行安全效验，检测下游传递的参数中是否存在“唯一序列ID"。
上游服务到 Redis 中检测是否存在对应的“唯一序列ID" 的 Key
- 如果存在就抛出重复执行的异常信息，然后响应下游对应的错误信息。
- 如果不存在就以该“唯一序列ID"作为 Key，以下游关键信息作为 Value，进而存储到 Redis 中，然后正常执行接来来的业务逻辑。

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

⑤：加本地锁或分布式锁

单体架构项目可以加Synchronized、ReentrantLock等本地锁
分布式项目可以利用redis、zookeeper加分布式锁！

单体架构加ReentrantLock锁如下：

   //声明 ReentrantLock 锁private final Lock lock = new ReentrantLock();/*** 保存*/@RequestMapping(value = "/save", method = RequestMethod.POST)@ApiOperation("保存定损任务")public R save(@RequestBody @Valid @ApiParam(name = "预约定损对象", required = true) KfAppointmentDsEntity kfAppointmentDs) {List<Map<String, Object>> list = null;try {//加锁lock.lock();//校验时：保证同时只有一个线程List<KfAppointmentDsEntity> entities = kfAppointmentDsService.list(Wrappers.<KfAppointmentDsEntity>lambdaQuery().eq(KfAppointmentDsEntity::getAccidentno, accidentno).eq(KfAppointmentDsEntity::getCarnum, carnum).eq(KfAppointmentDsEntity::getFactoryName, factoryName).eq(KfAppointmentDsEntity::getDsArea, dsArea).eq(KfAppointmentDsEntity::getEstimatedprice, estimatedprice));// 如果已经提交，返回错误信息if (entities.size() > 0) {log.info("请勿重复提交此案件============案件号：{}，车牌：{}", accidentno, carnum);return R.error("请勿重复提交此案件！");}.....//省略其他逻辑//执行保存kfAppointmentDsService.save(kfAppointmentDs);} finally {//最终解锁lock.unlock();}//其他异步事件可以加入阻塞队列try {queue.add(kfAppointmentDs.getId());} catch (Exception e) {log.info("任务入队失败！ 任务id：{}，事故号：{}", kfAppointmentDs.getId(), kfAppointmentDs.getAccidentno());}//企业微信发送通知qywxSendMessage.sendMessage(kfAppointmentDs);return R.ok().put("data", list);}

分布式架构

基于redis实现分布式锁！
基于zookeeper实现分布式锁！

3. 案例：基于防重 Token 令牌实现接口幂等

3.1 引入依赖

<?xml version="1.0" encoding="UTF-8"?>
<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.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.3.4.RELEASE</version></parent><groupId>mydlq.club</groupId><artifactId>springboot-idempotent-token</artifactId><version>0.0.1</version><name>springboot-idempotent-token</name><description>Idempotent Demo</description><properties><java.version>1.8</java.version></properties><dependencies><!--springboot web--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--springboot data redis--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-redis</artifactId></dependency><dependency><groupId>org.apache.commons</groupId><artifactId>commons-pool2</artifactId></dependency><!--lombok--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

3.2 增加redis配置文件参数

在 application 配置文件中配置连接 Redis 的参数，如下：

spring:redis:ssl: falsehost: 127.0.0.1port: 6379database: 0timeout: 1000password:lettuce:pool:max-active: 100max-wait: -1min-idle: 0max-idle: 20

3.3 创建与验证 Token 工具类

Token 创建方法：使用 UUID 工具创建 Token 串，设置以 “idempotent_token:“+“Token 串” 作为 Key，
以用户信息当成 Value，将信息存入 Redis 中。
Token 验证方法：接收 Token 串参数，加上 Key 前缀形成 Key，再传入 value 值，执行 Lua 表达式（Lua 表达式能保证命令执行的原子性），进行查找对应 Key 与删除操作。执行完成后验证命令的返回结果，如果结果不为空且非 0，则验证成功，否则失败。

import java.util.Arrays;
import java.util.UUID;
import java.util.concurrent.TimeUnit;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.script.DefaultRedisScript;
import org.springframework.data.redis.core.script.RedisScript;
import org.springframework.stereotype.Service;@Slf4j
@Service
public class TokenUtilService {@Autowiredprivate StringRedisTemplate redisTemplate;/*** 存入 Redis 的 Token 键的前缀*/private static final String IDEMPOTENT_TOKEN_PREFIX = "idempotent_token:";/*** 创建 Token 存入 Redis，并返回该 Token** @param value 用于辅助验证的 value 值* @return 生成的 Token 串*/public String generateToken(String value) {// 实例化生成 ID 工具对象String token = UUID.randomUUID().toString();// 设置存入 Redis 的 KeyString key = IDEMPOTENT_TOKEN_PREFIX + token;// 存储 Token 到 Redis，且设置过期时间为 5 分钟redisTemplate.opsForValue().set(key, value, 5, TimeUnit.MINUTES);// 返回 Tokenreturn token;}/*** 验证 Token 正确性** @param token token 字符串* @param value value 存储在 Redis 中的辅助验证信息* @return 验证结果*/public boolean validToken(String token, String value) {// 设置 Lua 脚本，其中 KEYS[1] 是 key，KEYS[2] 是 valueString 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 前缀拼接 KeyString key = IDEMPOTENT_TOKEN_PREFIX + token;// 执行 Lua 脚本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;}}

3.4 创建测试的 Controller 类

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

import lombok.extern.slf4j.Slf4j;
import mydlq.club.example.service.TokenUtilService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;@Slf4j
@RestController
public class TokenController {@Autowiredprivate TokenUtilService tokenService;/*** 获取 Token 接口** @return Token 串*/@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 ? "正常调用" : "重复调用";}}

3.5 写测试类进行测试

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

import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;@Slf4j
@SpringBootTest
@RunWith(SpringRunner.class)
public class IdempotenceTest {@Autowiredprivate WebApplicationContext webApplicationContext;@Testpublic void interfaceIdempotenceTest() throws Exception {// 初始化 MockMvcMockMvc 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, "重复调用");}}}}

显示如下：

[main] IdempotenceTest:  获取的 Token 串：980ea707-ce2e-456e-a059-0a03332110b4
[main] IdempotenceTest:  第 1 次调用测试接口
[main] IdempotenceTest:  正常调用
[main] IdempotenceTest:  第 2 次调用测试接口
[main] IdempotenceTest:  重复调用
[main] IdempotenceTest:  第 3 次调用测试接口
[main] IdempotenceTest:  重复调用
[main] IdempotenceTest:  第 4 次调用测试接口
[main] IdempotenceTest:  重复调用
[main] IdempotenceTest:  第 5 次调用测试接口
[main] IdempotenceTest:  重复调用

4. 总结

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

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

上面只是给与一些建议，再次强调一下，实现幂等性需要先理解自身业务需求，根据业务逻辑来实现这样才合理，