分布式環境下的接口冪等性保障：Spring Boot 實踐與方案對比

作者：一安 2025-09-02 07:16:37

開發前端

冪等性（Idempotence）是一個數學與計算機學概念，指的是無論對同一操作執行多少次，其結果都是相同的。對于接口而言，即使用戶重復提交相同的請求，接口最終產生的效果也與單次提交一致。

前言

隨著業務的快速發展，分布式系統已成為企業級應用的主流架構。然而，分布式環境下的網絡延遲、服務重試、負載均衡等因素，都可能導致接口被重復調用。如果接口不具備冪等性，可能會引發數據不一致、重復創建資源、資金重復扣減等嚴重問題。

冪等性定義

冪等性（Idempotence）是一個數學與計算機學概念，指的是無論對同一操作執行多少次，其結果都是相同的。對于接口而言，即使用戶重復提交相同的請求，接口最終產生的效果也與單次提交一致。

為什么需要冪等性

在分布式系統中，以下場景可能導致請求重復：

網絡抖動導致客戶端重試
前端表單重復提交
服務間調用超時重試
負載均衡環境下的請求重定向
分布式事務中的補償機制

常見的冪等性解決方案

圖片

基于數據庫的方案

唯一主鍵

利用數據庫主鍵的唯一性約束，確保重復請求無法插入重復數據。

適用場景：訂單創建、用戶注冊等需要唯一標識的場景。

樂觀鎖

通過版本號機制實現，更新數據時檢查版本號，只有版本號匹配才允許更新。

UPDATE orders SET status = 1, version = version + 1 WHERE id = 123 AND version = 0

悲觀鎖

利用數據庫的行鎖機制，在事務中鎖定記錄，防止并發修改。

SELECT * FROM orders WHERE id = 123 FOR UPDATE

基于令牌 (Token) 的方案

客戶端請求獲取令牌
服務端生成全局唯一令牌并返回
客戶端攜帶令牌發起業務請求
服務端驗證令牌有效性，執行業務邏輯，標記令牌已使用

適用場景：表單提交、支付請求等需要防止重復提交的場景。

基于分布式鎖的方案

利用Redis、ZooKeeper等組件實現分布式鎖，確保同一時間只有一個請求能執行關鍵業務邏輯。

適用場景：庫存扣減、秒殺等并發控制嚴格的場景。

基于狀態機的方案

通過定義清晰的狀態流轉規則，確保重復請求無法改變最終狀態。

例如，訂單狀態流轉：創建 → 支付中 → 已支付 → 已完成，不允許從已支付直接回到支付中狀態。

適用場景：有明確狀態流轉的業務，如訂單、工單等。

基于冪等設計的 API

遵循RESTful設計原則，合理使用HTTP方法：

GET：天生冪等，只查詢數據
PUT：應設計為冪等，用于全量更新
DELETE：應設計為冪等，刪除資源
POST：通常不冪等，用于創建資源

冪等性實現

基于數據庫唯一約束的實現

創建訂單實體類，使用業務唯一標識作為聯合唯一約束：

@Entity
@Table(name = "orders", 
       uniqueConstraints = {@UniqueConstraint(columnNames = {"user_id", "order_no"})})
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "user_id")
    private Long userId;
    
    @Column(name = "order_no")
    private String orderNo;
    
    private BigDecimal amount;
    
    private String status;
    
    @Version
    private Integer version;
}

在Service層處理訂單創建，捕獲唯一約束異常：

@Service
@Transactional
public class OrderService {
    
    @Autowired
    private OrderRepository orderRepository;
    
    public Order createOrder(Order order) {
        try {
            return orderRepository.save(order);
        } catch (DataIntegrityViolationException e) {
            // 捕獲唯一約束異常，查詢已存在的訂單
            return orderRepository.findByUserIdAndOrderNo(order.getUserId(), order.getOrderNo())
                    .orElseThrow(() -> new RuntimeException("訂單創建失敗"));
        }
    }
}

基于令牌的實現

創建令牌工具類：

@Component
public class TokenUtil {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
    
    // 生成令牌
    public String generateToken(String keyPrefix, long expireSeconds) {
        String token = UUID.randomUUID().toString();
        String key = keyPrefix + ":" + token;
        redisTemplate.opsForValue().set(key, "0", expireSeconds, TimeUnit.SECONDS);
        return token;
    }
    
    // 驗證令牌
    public boolean validateToken(String keyPrefix, String token) {
        String key = keyPrefix + ":" + token;
        // 使用Redis的setIfAbsent實現原子操作
        return redisTemplate.opsForValue().setIfAbsent(key, "1", 5, TimeUnit.MINUTES);
    }
}

創建令牌控制器：

@RestController
@RequestMapping("/api/token")
public class TokenController {
    
    @Autowired
    private TokenUtil tokenUtil;
    
    @GetMapping("/generate")
    public String generateToken() {
        // 為支付場景生成令牌，有效期30分鐘
        return tokenUtil.generateToken("payment", 1800);
    }
}

支付接口實現：

@RestController
@RequestMapping("/api/payment")
public class PaymentController {
    
    @Autowired
    private PaymentService paymentService;
    
    @Autowired
    private TokenUtil tokenUtil;
    
    @PostMapping
    public ResponseEntity<?> processPayment(@RequestHeader("X-Idempotency-Token") String token,
                                           @RequestBody PaymentRequest request) {
        // 驗證令牌
        boolean isValid = tokenUtil.validateToken("payment", token);
        if (!isValid) {
            return ResponseEntity.badRequest().body("重復請求");
        }
        
        // 處理支付邏輯
        PaymentResult result = paymentService.processPayment(request);
        return ResponseEntity.ok(result);
    }
}

基于 Redis 分布式鎖的實現

創建分布式鎖工具類：

@Component
public class RedisLockUtil {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
    
    private static final String LOCK_PREFIX = "lock:";
    private static final long DEFAULT_EXPIRE = 30000; // 默認鎖過期時間30秒
    
    // 獲取鎖
    public boolean tryLock(String key, long expireMillis) {
        String lockKey = LOCK_PREFIX + key;
        String value = UUID.randomUUID().toString();
        
        Boolean success = redisTemplate.opsForValue().setIfAbsent(lockKey, value, expireMillis, TimeUnit.MILLISECONDS);
        return Boolean.TRUE.equals(success);
    }
    
    public boolean tryLock(String key) {
        return tryLock(key, DEFAULT_EXPIRE);
    }
    
    // 釋放鎖
    public void unlock(String key) {
        String lockKey = LOCK_PREFIX + key;
        redisTemplate.delete(lockKey);
    }
}

在庫存服務中使用分布式鎖：

@Service
public class InventoryService {
    
    @Autowired
    private InventoryRepository inventoryRepository;
    
    @Autowired
    private RedisLockUtil redisLockUtil;
    
    @Transactional
    public boolean deductStock(Long productId, int quantity) {
        String lockKey = "product:" + productId;
        
        try {
            // 獲取鎖
            boolean locked = redisLockUtil.tryLock(lockKey, 5000);
            if (!locked) {
                throw new RuntimeException("獲取鎖失敗，請重試");
            }
            
            // 查詢庫存
            Inventory inventory = inventoryRepository.findByProductId(productId)
                    .orElseThrow(() -> new RuntimeException("商品不存在"));
            
            // 檢查庫存是否充足
            if (inventory.getStock() < quantity) {
                throw new RuntimeException("庫存不足");
            }
            
            // 扣減庫存
            inventory.setStock(inventory.getStock() - quantity);
            inventoryRepository.save(inventory);
            returntrue;
        } finally {
            // 釋放鎖
            redisLockUtil.unlock(lockKey);
        }
    }
}

基于 AOP 的冪等性注解實現

創建冪等性注解：

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
    // 冪等鍵前綴
    String prefix() default "";
    
    // 過期時間(秒)
    int expire() default 300;
    
    // 冪等鍵的表達式，支持SpEL
    String key() default "";
}

實現AOP切面：

@Aspect
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class IdempotentAspect {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
    
    @Pointcut("@annotation(idempotent)")
    public void pointcut(Idempotent idempotent) {}
    
    @Around("pointcut(idempotent)")
    public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable {
        // 解析SpEL表達式獲取冪等鍵
        String key = generateKey(joinPoint, idempotent);
        
        // 嘗試設置緩存
        Boolean success = redisTemplate.opsForValue().setIfAbsent(key, "1", 
                idempotent.expire(), TimeUnit.SECONDS);
        
        if (Boolean.TRUE.equals(success)) {
            // 第一次請求，執行目標方法
            return joinPoint.proceed();
        } else {
            // 重復請求，返回默認結果或拋出異常
            throw new RuntimeException("不允許重復請求");
        }
    }
    
    // 生成冪等鍵
    private String generateKey(ProceedingJoinPoint joinPoint, Idempotent idempotent) {
        String prefix = idempotent.prefix();
        String keyExpression = idempotent.key();
        
        if (StringUtils.isEmpty(keyExpression)) {
            // 如果沒有指定key，使用方法簽名作為默認key
            return prefix + ":" + joinPoint.getSignature().toLongString();
        }
        
        // 解析SpEL表達式
        MethodSignature methodSignature = (MethodSignature) joinPoint.getSignature();
        EvaluationContext context = new StandardEvaluationContext();
        Object[] args = joinPoint.getArgs();
        String[] parameterNames = methodSignature.getParameterNames();
        
        for (int i = 0; i < args.length; i++) {
            context.setVariable(parameterNames[i], args[i]);
        }
        
        SpelExpressionParser parser = new SpelExpressionParser();
        Expression expression = parser.parseExpression(keyExpression);
        String key = expression.getValue(context, String.class);
        
        return prefix + ":" + key;
    }
}

使用冪等性注解：

@RestController
@RequestMapping("/api/order")
public class OrderApiController {
    
    @Autowired
    private OrderService orderService;
    
    @PostMapping
    @Idempotent(prefix = "order", key = "#request.orderNo", expire = 300)
    public ResponseEntity<Order> createOrder(@RequestBody OrderRequest request) {
        Order order = new Order();
        order.setUserId(request.getUserId());
        order.setOrderNo(request.getOrderNo());
        order.setAmount(request.getAmount());
        order.setStatus("CREATED");
        
        Order savedOrder = orderService.createOrder(order);
        return ResponseEntity.ok(savedOrder);
    }
}

各方案對比與適用場景

方案	優點	缺點	適用場景
唯一主鍵	實現簡單，依賴數據庫自身特性	僅適用于插入場景，需要提前生成唯一標識	訂單創建、用戶注冊
樂觀鎖	性能好，并發高	存在重試成本，需要版本字段	庫存更新、狀態變更
悲觀鎖	數據一致性高	并發性能差，可能導致死鎖	數據一致性要求高，低并發場景
令牌機制	適用范圍廣，不侵入業務	需要額外的令牌生成和驗證步驟	表單提交、支付請求
分布式鎖	靈活性高，可控制鎖粒度	實現復雜，存在鎖超時、死鎖風險	秒殺、庫存扣減
狀態機	業務語義清晰	僅適用于有明確狀態流轉的業務	訂單流程、工單系統
RESTful 設計	符合 HTTP 規范，無額外開銷	適用場景有限	查詢、全量更新、刪除操作

責任編輯：武曉燕來源：一安未來

分布式接口查詢