API接口的幂等性（Idempotency）设计：利用Token与数据库锁防止重复提交

好的，我们开始。

API 接口的幂等性设计：利用 Token 与数据库锁防止重复提交

大家好，今天我们来深入探讨一个在 API 设计中至关重要的话题：幂等性。幂等性是指一个操作，无论执行多少次，其结果都与执行一次相同。在分布式系统中，由于网络延迟、重试机制等原因，API 接口很容易出现重复提交的情况，如果不加以控制，可能会导致数据不一致或者业务逻辑错误。本文将围绕如何利用 Token 机制和数据库锁来设计幂等的 API 接口，防止重复提交的问题展开讨论，并结合实际代码示例进行说明。

一、幂等性的重要性和常见场景

在深入技术细节之前，我们先来明确一下为什么幂等性如此重要，以及在哪些场景下我们需要特别关注它。

• 数据一致性： 想象一下，一个支付接口如果不是幂等的，用户支付成功后，由于网络问题，客户端没有收到响应，用户重试支付，结果被扣了两次款，这显然是不可接受的。
• 业务逻辑正确性： 某些业务操作，例如创建订单，如果重复执行，可能会创建多个相同的订单，导致库存超卖等问题。
• 系统稳定性： 非幂等的接口在重试机制下，可能会对系统造成额外的压力，甚至导致雪崩效应。

以下是一些常见的需要保证幂等性的 API 接口场景：

场景	说明
支付接口	确保用户支付操作只执行一次，避免重复扣款。
创建订单接口	确保只创建一个订单，避免重复创建订单导致库存超卖。
更新库存接口	确保库存更新操作只执行一次，避免库存数据错误。
转账接口	确保转账操作只执行一次，避免重复转账。
删除数据接口	确保删除操作执行一次，多次请求删除同一数据，结果都应该是数据不存在，不会出现意外情况。
消息队列消费	消息队列消费者在消费消息时，如果消费失败，可能会进行重试，需要保证消息处理的幂等性，避免重复处理导致数据错误。

二、幂等性的实现方案：Token 机制

Token 机制是一种常见的实现幂等性的方案。其核心思想是：在客户端发起请求之前，服务器先生成一个唯一的 Token，将 Token 返回给客户端。客户端在发起实际请求时，需要将 Token 携带到服务器端。服务器端接收到请求后，首先验证 Token 是否存在，如果存在，则执行业务逻辑，并将 Token 删除；如果 Token 不存在，则表示该请求已经执行过，直接返回成功，避免重复执行。

下面是一个使用 Token 机制实现幂等性的示例代码（Java）：

import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

public class IdempotentToken {

    // 使用 ConcurrentHashMap 存储 Token，保证线程安全
    private static final ConcurrentHashMap<String, Boolean> tokenCache = new ConcurrentHashMap<>();

    /**
     * 生成 Token
     * @return
     */
    public static String generateToken() {
        String token = UUID.randomUUID().toString();
        // 将 Token 放入缓存，设置过期时间（可选）
        tokenCache.put(token, true);
        return token;
    }

    /**
     * 检查 Token 是否有效
     * @param token
     * @return
     */
    public static boolean checkToken(String token) {
        if (token == null || token.isEmpty()) {
            return false;
        }
        // 从缓存中获取 Token
        Boolean exists = tokenCache.get(token);
        if (exists != null && exists) {
            // 移除 Token，防止重复使用
            tokenCache.remove(token);
            return true;
        } else {
            return false;
        }
    }

    public static void main(String[] args) {
        // 模拟生成 Token
        String token = generateToken();
        System.out.println("Generated Token: " + token);

        // 模拟第一次请求，携带 Token
        boolean firstCheck = checkToken(token);
        System.out.println("First check Token: " + firstCheck); // 输出：true

        // 模拟第二次请求，携带相同的 Token
        boolean secondCheck = checkToken(token);
        System.out.println("Second check Token: " + secondCheck); // 输出：false

        // 模拟第三次请求，不携带 Token
        boolean thirdCheck = checkToken(null);
        System.out.println("Third check Token: " + thirdCheck); // 输出：false
    }
}

代码解释：

1. generateToken() 方法用于生成唯一的 Token，这里使用了 UUID。
2. checkToken() 方法用于检查 Token 是否有效。如果 Token 存在于缓存中，则将其从缓存中移除，并返回 true，表示 Token 有效；否则，返回 false，表示 Token 无效。
3. tokenCache 使用 ConcurrentHashMap 存储 Token，保证线程安全。
4. main方法模拟了token的生成和校验。

使用 Token 机制的流程如下：

1. 客户端请求服务器获取 Token。
2. 服务器生成 Token，并将其存储在缓存中（例如 Redis），设置过期时间。
3. 服务器将 Token 返回给客户端。
4. 客户端发起实际请求，携带 Token。
5. 服务器接收到请求后，首先验证 Token 是否存在于缓存中。
6. 如果 Token 存在，则执行业务逻辑，并将 Token 从缓存中删除。
7. 如果 Token 不存在，则表示该请求已经执行过，直接返回成功。

Token 机制的优点：

• 实现简单，易于理解。
• 可以有效防止重复提交。

Token 机制的缺点：

• 需要在服务器端存储 Token，增加了服务器端的存储压力。
• 需要考虑 Token 的过期时间，避免 Token 过期导致请求失败。
• 如果 Token 被窃取，可能会导致安全问题。

三、幂等性的实现方案：数据库锁

数据库锁是另一种常用的实现幂等性的方案。其核心思想是：在执行业务逻辑之前，先获取数据库锁，如果获取成功，则执行业务逻辑，并释放锁；如果获取失败，则表示该请求已经执行过，直接返回成功，避免重复执行。

数据库锁可以分为两种：

• 悲观锁： 在读取数据时，就认为其他事务可能会修改数据，因此需要先获取锁，才能进行操作。常见的悲观锁实现方式是 SELECT ... FOR UPDATE。
• 乐观锁： 在读取数据时，认为其他事务不会修改数据，因此不需要获取锁。在更新数据时，会检查数据是否被修改过，如果被修改过，则更新失败。常见的乐观锁实现方式是使用版本号或者时间戳。

下面是一个使用悲观锁实现幂等性的示例代码（Java + Spring + MyBatis）：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    @Autowired
    private OrderMapper orderMapper;

    /**
     * 创建订单
     * @param order
     * @return
     */
    @Transactional
    public boolean createOrder(Order order) {
        // 1. 查询订单是否存在，使用悲观锁
        Order existingOrder = orderMapper.selectOrderByIdForUpdate(order.getOrderId());

        // 2. 如果订单不存在，则创建订单
        if (existingOrder == null) {
            orderMapper.insertOrder(order);
            return true;
        } else {
            // 3. 订单已存在，直接返回成功
            return false;
        }
    }
}

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import com.example.demo.model.Order;

@Mapper
public interface OrderMapper {

    /**
     * 根据订单 ID 查询订单，使用悲观锁
     * @param orderId
     * @return
     */
    Order selectOrderByIdForUpdate(@Param("orderId") String orderId);

    /**
     * 插入订单
     * @param order
     * @return
     */
    int insertOrder(Order order);
}

<!-- OrderMapper.xml -->
<mapper namespace="com.example.demo.mapper.OrderMapper">
    <select id="selectOrderByIdForUpdate" resultType="com.example.demo.model.Order">
        SELECT * FROM orders WHERE order_id = #{orderId} FOR UPDATE
    </select>

    <insert id="insertOrder">
        INSERT INTO orders (order_id, product_name, quantity, price)
        VALUES (#{orderId}, #{productName}, #{quantity}, #{price})
    </insert>
</mapper>

代码解释：

1. OrderService.createOrder() 方法使用 @Transactional 注解，保证事务的一致性。
2. OrderMapper.selectOrderByIdForUpdate() 方法使用 SELECT ... FOR UPDATE 语句，获取订单的悲观锁。如果其他事务已经获取了该订单的锁，则当前事务会被阻塞，直到其他事务释放锁。
3. 如果订单不存在，则创建订单，并返回 true。
4. 如果订单已存在，则直接返回 false，表示该请求已经执行过。

下面是一个使用乐观锁实现幂等性的示例代码（Java + Spring + MyBatis）：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class ProductService {

    @Autowired
    private ProductMapper productMapper;

    /**
     * 更新产品库存
     * @param productId
     * @param quantity
     * @return
     */
    @Transactional
    public boolean updateProductStock(String productId, int quantity) {
        // 1. 查询产品信息
        Product product = productMapper.selectProductById(productId);

        // 2. 如果产品不存在，则返回失败
        if (product == null) {
            return false;
        }

        // 3. 更新产品库存，使用乐观锁
        int rows = productMapper.updateProductStock(productId, quantity, product.getVersion());

        // 4. 如果更新失败，则表示库存已被修改，返回失败
        if (rows == 0) {
            return false;
        }

        return true;
    }
}

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import com.example.demo.model.Product;

@Mapper
public interface ProductMapper {

    /**
     * 根据产品 ID 查询产品信息
     * @param productId
     * @return
     */
    Product selectProductById(@Param("productId") String productId);

    /**
     * 更新产品库存，使用乐观锁
     * @param productId
     * @param quantity
     * @param version
     * @return
     */
    int updateProductStock(@Param("productId") String productId, @Param("quantity") int quantity, @Param("version") int version);
}

<!-- ProductMapper.xml -->
<mapper namespace="com.example.demo.mapper.ProductMapper">
    <select id="selectProductById" resultType="com.example.demo.model.Product">
        SELECT * FROM products WHERE product_id = #{productId}
    </select>

    <update id="updateProductStock">
        UPDATE products SET stock = stock - #{quantity}, version = version + 1
        WHERE product_id = #{productId} AND version = #{version}
    </update>
</mapper>

代码解释：

1. ProductService.updateProductStock() 方法使用 @Transactional 注解，保证事务的一致性。
2. ProductMapper.selectProductById() 方法用于查询产品信息。
3. ProductMapper.updateProductStock() 方法使用乐观锁更新产品库存。WHERE product_id = #{productId} AND version = #{version} 语句保证只有在版本号未被修改的情况下，才能更新库存。
4. 如果更新失败，则表示库存已被修改，返回 false。

使用数据库锁的流程如下：

1. 客户端发起请求。
2. 服务器接收到请求后，获取数据库锁。
3. 如果获取锁成功，则执行业务逻辑，并释放锁。
4. 如果获取锁失败，则表示该请求已经执行过，直接返回成功。

数据库锁的优点：

• 可以保证数据的一致性。
• 不需要额外的存储空间。

数据库锁的缺点：

• 可能会导致死锁。
• 性能较低，尤其是在并发量较高的情况下。

四、选择合适的幂等性方案

在选择幂等性方案时，需要根据实际情况进行权衡。

• 如果 API 接口的并发量不高，且对数据一致性要求较高，可以使用数据库锁。
• 如果 API 接口的并发量较高，且对性能要求较高，可以使用 Token 机制。
• 对于某些简单的 API 接口，例如删除数据接口，可以直接使用 SQL 语句的 WHERE 条件来保证幂等性。例如，DELETE FROM table WHERE id = 123，无论执行多少次，结果都一样。

方案	优点	缺点	适用场景
Token	实现简单，易于理解，可以有效防止重复提交。	需要在服务器端存储 Token，增加了服务器端的存储压力；需要考虑 Token 的过期时间；如果 Token 被窃取，可能会导致安全问题。	API 接口的并发量较高，且对性能要求较高。
悲观锁	可以保证数据的一致性。	可能会导致死锁；性能较低，尤其是在并发量较高的情况下。	API 接口的并发量不高，且对数据一致性要求较高。
乐观锁	相比悲观锁，并发性能更高。	需要额外的版本号字段；如果并发冲突较多，可能会导致更新失败率较高。	API 接口的并发量较高，且对数据一致性要求较高，但允许一定的更新失败率。
SQL 约束	实现简单，不需要额外的代码。	只能用于某些简单的 API 接口，例如删除数据接口。	适用于简单的、可以使用 SQL 语句的 WHERE 条件来保证幂等性的 API 接口，例如删除数据接口。
唯一索引	通过数据库的唯一索引约束，保证在插入数据时，如果数据已存在，则插入失败。	只能用于插入数据操作。	适用于需要保证数据唯一性的插入操作，例如用户注册。

五、总结与思考

我们讨论了API接口幂等性的重要性，以及如何使用 Token 机制和数据库锁来实现幂等性。在实际应用中，需要根据具体的业务场景和技术架构，选择合适的幂等性方案。没有一种方案是万能的，只有最适合的。同时，需要注意幂等性方案的性能和安全性，避免引入新的问题。通过合理的设计和实现，可以保证 API 接口的幂等性，提高系统的稳定性和可靠性。

针对实际场景选择最适合的幂等方案

在实际开发中，根据业务特点和系统架构选择最合适的幂等性方案至关重要。

持续关注并优化幂等性方案

幂等性并非一劳永逸，需要持续关注并优化，以适应业务发展和系统变化。