Spring Boot实现接口幂等性的四种解决方案

🚀 一、什么是接口幂等性

接口幂等性指的是一个操作或请求可以被重复执行多次，并获得相同的结果，而不会改变系统状态或产生副作用。这个概念对于构建可靠和可预测的系统非常重要。

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

这里的副作用是不会对结果产生破坏或者产生不可预料的结果。也就是说，其任意多次执行对资源本身所产生的影响均与一次执行的影响相同。

🚀 二、为什么需要实现幂等性

在接口调用时一般情况下都能正常返回信息不会重复提交，不过在遇见以下情况时可以就会出现问题，如：

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

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

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

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

使用幂等性最大的优势在于使接口保证任何幂等性操作，免去因重试等造成系统产生的未知的问题。

🚀 三、引入幂等性后对系统的影响

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

①把并行执行的功能改为串行执行。降低了执行效率。

②增加了额外控制幂等的业务逻辑，复杂化了业务功能。

所以在使用的时候需要考虑是否引入幂等性的必要性，根据实际业务场景具体分析，除了业务上的特殊要求外，一般情况下不需要引入接口幂等性。

🚀 四、Restful API接口的幂等性

在我们现在经常使用的Restful推荐的几种HTTP请求接口方法中，分别存在幂等性和不能保证幂等的方法。

①√满足幂等   ②×不满足幂等   ③-可能满足也可能不满足幂等，和实际业务逻辑有关

方法类型	是否幂等	描述
Get	√	Get 方法用于获取资源。其一般不会也不应当对系统资源进行改变，所以是幂等的。
Post	×	Post 方法一般用于创建新的资源。每次执行都会新增数据，所以不是幂等的。
Put	-	Put 方法一般用于修改资源。该操作则分情况来判断是不是满足幂等。 ①更新操作中直接根据某个值进行更新，也能保持幂等 ②执行累加操作的更新是非幂等。
Delete	-	Delete 方法一般用于删除资源。该操作则分情况来判断是不是满足幂等 当根据唯一值进行删除时，删除同一个数据多次执行效果一样。不过需要注意，带查询条件的删除就不一定满足幂等性了。例如在根据条件删除一批数据后，在删除的过程中新增加了一条数据，该条数据也满足条件，然后执行了一次删除，那么将会导致新增加的这条满足条件数据也被删除掉了，就不满足幂等性。

🚀 五、如何实现幂等性

💡方案一：数据库唯一主键

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

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

适用场景：①插入操作   ②删除操作

注意事项：需要生成全局唯一主键id

流程讲解：

①客户端执行请求，调用服务端接口

②服务端执行业务逻辑，生成一个分布式ID，将ID充当待插入数据的一个唯一键，不一定是主键，只要是全局唯一标识即可，然后执行数据插入操作，运行对应的SQL语句 。

③服务端将该条数据插入数据库中，插入时校验该分布式ID是否唯一（最好加索引），如果插入成功则表示没有重复调用接口。如果抛出异常，则表示数据库已经存在该条记录，返回错误信息。

💡方案二：数据库乐观锁

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

适用场景：更新操作

注意事项：需要对数据库表添加额外的字段。

 在每次更新数据时，都会要指定更新的版本号，当我们第一次更新时，可以准确的更新某一条数据，当后面的更新sql执行会不生效，因为version已被修改，当前条件的数据不存在，这样就能保住更新的幂等，多次更新对结果不会产生影响。

💡方案三：防重Token令牌

方案描述：针对客户端连续点击或者调用方的超时重试等情况，比如提交订单，定时调用等操作，这种操作就可以用Token的机制实现防止重复提交，简单来说就是调用方在调用接口的时候，先向后端请求一个全局ID（Token）,请求时携带这个全局ID一起请求（Token最好放在Headers中），后端对这个Token作为key，用户信息作为value存储到Redis中进行简直内容校验，如果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 不能正常工作。 

🚀 六、实现接口幂等示例代码

添加依赖，正常的springboot项目即可

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
        </dependency>

        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-pool2</artifactId>
            <version>2.11.1</version>
        </dependency>

创建与验证Token工具类

创建用于操作Token相关的Service类，其中：

• Token 创建方法： 使用 UUID 工具创建 Token 串，设置以 “idempotent_token:“+“Token串” 作为 Key，以用户信息当成 Value，将信息存入 Redis 中。

• Token 验证方法： 接收 Token 串参数，加上 Key 前缀形成 Key，再传入 value 值，执行 Lua 表达式（Lua 表达式能保证命令执行的原子性）进行查找对应 Key 与删除操作。执行完成后验证命令的返回结果，如果结果不为空且非0，则验证成功，否则失败。

package com.xiaobai.easyexceldemo.utils;

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 {

    @Autowired
    private 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 的 Key
        String key = IDEMPOTENT_TOKEN_PREFIX + token;
        // 存储 Token 到 Redis，且设置过期时间为5分钟
        redisTemplate.opsForValue().set(key, value, 5, TimeUnit.MINUTES);
        // 返回 Token
        return token;
    }

    /**
      * 验证 Token 正确性
      *
      * @param token token 字符串
      * @param value value 存储在Redis中的辅助验证信息
      * @return 验证结果
      */
    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;
        // 执行 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;
    }

}

创建控制层代码

package com.xiaobai.easyexceldemo.controller;

import com.xiaobai.easyexceldemo.utils.TokenUtilService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author: xiaobai
 * @Desc:
 * @create: 2024-09-08
 **/
@Slf4j
@RestController
public class TokenController {

    @Autowired
    private 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 = "mysql";
        // 根据 Token 和与用户相关的信息到 Redis 验证是否存在对应的信息
        boolean result = tokenService.validToken(token, userInfo);
        // 根据验证结果响应不同信息
        return result ? "正常调用" : "重复调用";
    }
}

创建测试类

package com.xiaobai.easyexceldemo;

import lombok.extern.slf4j.Slf4j;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
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;

/**
 * @author: xiaobai
 * @Desc:
 * @create: 2024-09-08
 **/
@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, "重复调用");
            }
        }
    }
}

🚀  七、总结

幂等性是开发中常见的一个需求，尤其在支付、订单等与金钱挂钩的服务，保证接口的幂等性尤其重要。

①对于下单等存在唯一主键的，可以使用“唯一主键方案”的方式实现

②对于更新订单状态等相类似的更新场景操作时，可以使用“乐观锁方案”实现更简单

③对于上下游这种，下游请求上游，上游服务可以使用“下游传递唯一序列号方案”更合适

④类似前端重复提交，重复下单，没有唯一id号的场景，可以通过Token与Redis配合的“防重Token方案”实现更加便捷。