从资损百万到零事故：Java 接口幂等设计的艺术与实践

在分布式系统中，最令人头疼的不是复杂的业务逻辑，而是那些看似偶然却反复出现的 "幽灵问题"—— 用户明明只点了一次支付，银行卡却被扣了两次；订单系统在重试后突然冒出两条相同的记录；库存明明足够，却因为消息重复消费变成了负数。这些问题的背后，几乎都指向同一个核心漏洞：接口缺乏幂等性设计。
本文将从真实资损案例出发，系统剖析幂等性的本质，详解 8 种主流解决方案的实现细节与适用场景，提供一套可落地的幂等性设计方法论。无论你是架构师还是开发工程师，都能从中获得实战级指导，让你的系统彻底告别 "重复提交" 带来的资损风险。
一、血的教训：3 个因幂等性失效导致的百万级资损案例
在深入技术细节前，先看几个真实发生的幂等性故障案例。这些案例并非个例，而是分布式系统中高频出现的 "隐形杀手"。
案例 1：电商支付双扣事件（直接损失 186 万）
某电商平台在 618 大促期间，由于支付接口未做幂等性处理，加上网关超时重试机制，导致 372 笔订单被重复扣款。其中最高一笔订单金额达 2.3 万元，用户投诉量激增 300%。技术团队紧急停服修复，花了 48 小时完成数据对账与退款，直接经济损失 186 万元，平台声誉严重受损，当月活跃用户下降 15%。
根因分析：支付接口未校验订单当前状态，仅通过 "订单号 + 用户 ID" 作为唯一标识，且未实现防重放机制。当网关因网络波动触发重试时，相同请求被多次执行，而支付系统未识别出重复请求。
案例 2：分布式消息重试导致库存超卖（间接损失 230 万）
某生鲜平台采用 "下单 - 扣库存 - 支付" 的分布式流程，使用 RabbitMQ 传递库存扣减消息。在一次秒杀活动中，某商品库存 1000 件，却因消息消费端超时触发重试机制，导致库存被多扣了 327 件。大量用户下单后无法发货，引发大规模投诉，平台不得不发放 200 元无门槛券安抚用户，间接损失 230 万元。
根因分析：库存扣减接口未做幂等性设计，同一条消息被重复消费时，执行了 "库存 = 库存 - 1" 的非幂等操作。虽然使用了分布式锁，但锁的粒度设计过大（商品级别而非订单级别），导致并发下锁失效。
案例 3：表单重复提交引发数据混乱（合规风险损失无法估量）
某银行的贷款申请系统，因前端未禁用提交按钮，加上后端未限制重复提交，导致 127 名用户生成了两份贷款申请记录。其中 3 笔贷款被重复审批通过，给银行造成坏账风险。更严重的是，重复数据触发了监管部门的合规检查，银行被责令整改，相关负责人被问责。
根因分析：表单提交接口未实现 Token 验证机制，且未对 "用户 ID + 申请日期" 做唯一约束，允许同一用户在短时间内提交多次相同请求。
这些案例揭示了一个残酷的现实：幂等性不是可选功能，而是分布式系统的生存底线。缺少幂等性保障的系统，就像在悬崖边行驶的汽车，随时可能坠入深渊。
二、彻底搞懂幂等性：从数学定义到工程实践
2.1 什么是接口幂等性？
幂等性（Idempotence）源于数学概念，在代数中表示 "f (f (x)) = f (x)" 的性质。在计算机领域，它被定义为：相同的请求被执行一次与执行多次的效果完全一致，不会对系统状态产生副作用。
用通俗的话讲：无论你调用接口 1 次还是 100 次，最终的结果都一样。比如 "查询余额" 接口天然幂等（多次查询结果相同），而 "转账" 接口若未做处理则非幂等（多次调用会重复扣钱）。
2.2 幂等性与相关概念的区别
很多开发者容易混淆幂等性、防重复提交、防重放攻击，这里用一张表明确区分：
概念 核心目标 实现层面 典型场景
幂等性 保证多次调用结果一致 后端接口 支付、库存扣减
防重复提交 防止前端多次发送相同请求 前端 + 后端 表单提交、按钮点击
防重放攻击 防止请求被恶意截取并重复发送 安全层 + 后端 登录认证、API 开放接口
关键结论：防重复提交和防重放攻击是保障幂等性的手段，但不能替代幂等性设计。即使前端做到了防重复提交，后端仍需实现幂等性 —— 因为请求可能通过 API 调试、恶意调用等渠道绕过前端限制。
2.3 哪些接口必须实现幂等性？
并非所有接口都需要幂等性设计，遵循 "写操作必做，读操作免做" 的原则：
必须实现的接口：
支付、转账、退款等涉及资金变动的接口
订单创建、状态更新等核心业务接口
库存扣减、余额修改等数据变更接口
分布式事务中的补偿、重试接口
消息消费端的处理接口
无需实现的接口：
纯查询接口（如 "查询订单详情"）
无状态的只读接口（如 "获取商品列表"）
三、接口不幂等的 7 大根源：从前端到后端的全链路分析
要设计出幂等的接口，必须先了解导致接口重复调用的根本原因。这些原因分布在从前端到后端的全链路中，任何一个环节都可能成为 "罪魁祸首"。
3.1 前端层面：用户操作与网络波动
用户误操作：用户快速点击按钮、页面未跳转时重复提交
网络延迟：请求已发送但响应未及时返回，用户误以为未提交
页面刷新 / 回退：表单提交后刷新页面，导致请求重发
前端框架缺陷：某些 UI 框架在特定场景下会自动重试失败的请求
3.2 后端层面：重试机制与分布式特性
服务调用超时重试：Feign、Dubbo 等框架默认的超时重试机制
分布式事务重试：TCC、SAGA 等模式中的补偿重试
消息中间件重试：RabbitMQ 的消息重投、Kafka 的消费者重试
负载均衡器重试：Nginx、Gateway 等在后端超时后的重试
数据库事务重试：乐观锁冲突时的业务层重试
3.3 网络层面：不可靠的传输特性
TCP 重传机制：网络丢包时 TCP 协议会自动重传数据包
代理服务器重试：反向代理在未收到响应时的重试
跨网通信延迟：跨地域、跨运营商通信时的延迟导致重试
了解这些根源后，我们能得出一个重要结论：在分布式系统中，重复调用是常态而非例外。与其寄希望于 "不会发生重复调用"，不如主动设计幂等性接口，从根本上解决问题。
四、8 种幂等性解决方案：从入门到精通的实战指南
根据业务场景的不同，幂等性解决方案各有侧重。以下 8 种方案覆盖了从简单到复杂的各种场景，包含完整代码实现与选型建议。
4.1 方案一：基于唯一请求 ID 的幂等设计（通用型）
核心思想：为每次请求生成唯一 ID（如 UUID），后端通过记录该 ID 是否已处理，来判断是否执行业务逻辑。
实现步骤：
客户端生成唯一请求 ID（requestId），随请求一起发送
服务端接收请求后，先检查 requestId 是否已处理
若未处理，执行业务逻辑，处理完成后记录 requestId
若已处理，直接返回上次处理结果
代码实现：

1. 数据库表设计（记录已处理的请求）
   sql
   CREATE TABLE idempotent_request (
   id bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
   request_id varchar(64) NOT NULL COMMENT '请求唯一标识',
   business_type varchar(32) NOT NULL COMMENT '业务类型（如PAY_ORDER）',
   business_id varchar(64) DEFAULT NULL COMMENT '业务ID（如订单号）',
   status tinyint(4) NOT NULL COMMENT '状态：0-处理中，1-成功，2-失败',
   response_data text COMMENT '响应数据',
   create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
   update_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   PRIMARY KEY (id),
   UNIQUE KEY uk_request_id (request_id) COMMENT '确保requestId唯一'
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT '幂等性请求记录表';
2. 幂等性处理工具类
   java
   运行
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.dao.DuplicateKeyException;
   import org.springframework.jdbc.core.JdbcTemplate;
   import org.springframework.stereotype.Component;

@Component
public class IdempotentHandler {
private static final Logger logger = LoggerFactory.getLogger(IdempotentHandler.class);
private final JdbcTemplate jdbcTemplate;

// 构造器注入（符合阿里巴巴规约）
public IdempotentHandler(JdbcTemplate jdbcTemplate) {
    this.jdbcTemplate = jdbcTemplate;
}

/**
 * 尝试获取幂等锁
 * @return true-首次处理，false-已处理
 */
public boolean tryAcquire(String requestId, String businessType, String businessId) {
    try {
        // 插入记录，利用唯一索引防止重复
        int rows = jdbcTemplate.update(
            "INSERT INTO idempotent_request (request_id, business_type, business_id, status, create_time, update_time) " +
            "VALUES (?, ?, ?, 0, NOW(), NOW())",
            requestId, businessType, businessId
        );
        return rows > 0;
    } catch (DuplicateKeyException e) {
        // 唯一索引冲突，说明已处理过
        logger.info("请求已处理，requestId={}, businessId={}", requestId, businessId);
        return false;
    } catch (Exception e) {
        logger.error("获取幂等锁失败，requestId={}", requestId, e);
        throw new RuntimeException("系统异常，请稍后重试");
    }
}

/**
 * 更新请求处理结果
 */
public void updateResult(String requestId, int status, String responseData) {
    jdbcTemplate.update(
        "UPDATE idempotent_request SET status = ?, response_data = ?, update_time = NOW() WHERE request_id = ?",
        status, responseData, requestId
    );
}

/**
 * 查询已处理的结果
 */
public String getResponseData(String requestId) {
    return jdbcTemplate.queryForObject(
        "SELECT response_data FROM idempotent_request WHERE request_id = ?",
        String.class, requestId
    );
}

}

1. 支付接口实现（核心业务）
   java
   运行
   import com.alibaba.fastjson.JSON;
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RestController;

import java.math.BigDecimal;

@RestController
public class PaymentController {
private static final Logger logger = LoggerFactory.getLogger(PaymentController.class);
private final IdempotentHandler idempotentHandler;
private final PaymentService paymentService;

public PaymentController(IdempotentHandler idempotentHandler, PaymentService paymentService) {
    this.idempotentHandler = idempotentHandler;
    this.paymentService = paymentService;
}

/**
 * 支付接口（幂等性实现）
 */
@PostMapping("/api/v1/pay")
public Result<PaymentResponse> pay(@RequestBody PaymentRequest request) {
    // 1. 参数校验（符合阿里巴巴规约：先校验参数）
    if (request.getRequestId() == null || request.getOrderId() == null || request.getAmount() == null) {
        return Result.fail("参数错误：requestId、orderId、amount不能为空");
    }

    try {
        // 2. 尝试获取幂等锁
        boolean isFirst = idempotentHandler.tryAcquire(
            request.getRequestId(), 
            "PAY_ORDER", 
            request.getOrderId()
        );

        // 3. 已处理过，直接返回缓存结果
        if (!isFirst) {
            String responseData = idempotentHandler.getResponseData(request.getRequestId());
            return Result.success(JSON.parseObject(responseData, PaymentResponse.class));
        }

        // 4. 首次处理，执行支付逻辑
        logger.info("开始处理支付，orderId={}, amount={}", request.getOrderId(), request.getAmount());
        PaymentResponse response = paymentService.processPayment(
            request.getOrderId(), 
            request.getUserId(), 
            request.getAmount()
        );

        // 5. 更新处理结果
        idempotentHandler.updateResult(
            request.getRequestId(), 
            1, // 处理成功
            JSON.toJSONString(response)
        );

        return Result.success(response);
    } catch (Exception e) {
        logger.error("支付处理失败，orderId={}", request.getOrderId(), e);
        // 更新失败状态
        idempotentHandler.updateResult(
            request.getRequestId(), 
            2, // 处理失败
            e.getMessage()
        );
        return Result.fail("支付失败：" + e.getMessage());
    }
}

// 请求与响应对象（内部类）
public static class PaymentRequest {
    private String requestId; // 唯一请求ID
    private String orderId;   // 订单号
    private String userId;    // 用户ID
    private BigDecimal amount;// 支付金额
    // getter和setter省略
}

public static class PaymentResponse {
    private String orderId;
    private String payStatus; // SUCCESS/FAIL
    private String tradeNo;   // 交易号
    // getter和setter省略
}

}
优缺点与适用场景：
优点：实现简单，适用范围广，能应对大多数重复请求场景
缺点：需要额外存储请求记录，增加数据库开销；依赖前后端配合传递 requestId
适用场景：支付接口、订单创建、退款申请等核心业务接口（推荐作为首选方案）
4.2 方案二：基于乐观锁的幂等设计（高并发场景）
核心思想：通过版本号（version）控制数据更新，只有当版本号匹配时才允许更新，避免并发下的重复操作。
实现原理：
数据表中增加version字段（初始值 0）
查询数据时获取当前版本号
更新数据时，条件中包含版本号，且更新后版本号 + 1
若更新影响行数为 0，说明版本号已变化（被其他线程更新），则更新失败
代码实现（库存扣减为例）：

1. 库存表设计
   sql
   CREATE TABLE product_stock (
   id bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
   product_id varchar(64) NOT NULL COMMENT '商品ID',
   stock int(11) NOT NULL COMMENT '库存数量',
   version int(11) NOT NULL DEFAULT 0 COMMENT '版本号，用于乐观锁',
   update_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   PRIMARY KEY (id),
   UNIQUE KEY uk_product_id (product_id)
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT '商品库存表';
2. 库存服务实现
   java
   运行
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.jdbc.core.JdbcTemplate;
   import org.springframework.stereotype.Service;
   import org.springframework.transaction.annotation.Transactional;

@Service
public class StockService {
private static final Logger logger = LoggerFactory.getLogger(StockService.class);
private final JdbcTemplate jdbcTemplate;

public StockService(JdbcTemplate jdbcTemplate) {
    this.jdbcTemplate = jdbcTemplate;
}

/**
 * 扣减库存（乐观锁实现幂等）
 * @return 是否成功
 */
@Transactional(rollbackFor = Exception.class)
public boolean deductStock(String productId, int quantity) {
    // 1. 查询当前库存和版本号
    StockInfo stockInfo = jdbcTemplate.queryForObject(
        "SELECT stock, version FROM product_stock WHERE product_id = ?",
        (rs, rowNum) -> new StockInfo(
            rs.getInt("stock"),
            rs.getInt("version")
        ),
        productId
    );

    // 2. 校验库存是否充足
    if (stockInfo.stock() < quantity) {
        logger.warn("库存不足，productId={}, 需求={}, 库存={}", productId, quantity, stockInfo.stock());
        return false;
    }

    // 3. 乐观锁更新：只有版本号匹配时才更新
    int rows = jdbcTemplate.update(
        "UPDATE product_stock SET stock = stock - ?, version = version + 1, update_time = NOW() " +
        "WHERE product_id = ? AND version = ?",
        quantity, productId, stockInfo.version()
    );

    // 4. 判断更新是否成功
    if (rows > 0) {
        logger.info("库存扣减成功，productId={}, 扣减数量={}, 剩余库存={}",
                    productId, quantity, stockInfo.stock() - quantity);
        return true;
    } else {
        logger.warn("库存扣减失败（版本号不匹配），productId={}, 当前版本={}",
                    productId, stockInfo.version());
        return false;
    }
}

// 记录库存和版本号的记录类（JDK17 record特性）
private record StockInfo(int stock, int version) {}

}

1. 调用方实现（带重试机制）
   java
   运行
   @Service
   public class OrderService {
   private static final Logger logger = LoggerFactory.getLogger(OrderService.class);
   private final StockService stockService;

   public OrderService(StockService stockService) {

    this.stockService = stockService;
   

   }

   /**

   • 创建订单时扣减库存（带重试）
     */
     public boolean createOrder(String orderId, String productId, int quantity) {
     // 最多重试3次（避免无限重试）
     int maxRetry = 3;
     int retryCount = 0;

     while (retryCount < maxRetry) {

      try {
          boolean success = stockService.deductStock(productId, quantity);
          if (success) {
              // 扣减成功，继续创建订单逻辑
              logger.info("订单创建成功，orderId={}", orderId);
              return true;
          }
          // 扣减失败，重试
          retryCount++;
          logger.info("订单创建失败，准备重试，orderId={}, 重试次数={}", orderId, retryCount);
          // 短暂休眠，避免频繁重试（指数退避策略）
          Thread.sleep(100 * (1 << retryCount));
      } catch (Exception e) {
          logger.error("创建订单异常，orderId={}", orderId, e);
          return false;
      }
     

     }

     logger.error("订单创建失败，超过最大重试次数，orderId={}", orderId);
     return false;
     }
     }
     优缺点与适用场景：
     优点：无锁竞争，性能极佳；适合高并发场景
     缺点：需要额外的版本号字段；可能需要重试机制配合；不适合写冲突频繁的场景
     适用场景：库存扣减、余额更新、商品数量修改等高频更新操作
     4.3 方案三：基于悲观锁的幂等设计（强一致性场景）
     核心思想：通过排他锁确保同一时间只有一个请求能处理资源，避免并发导致的重复操作。
     实现原理：
     使用数据库行锁（SELECT ... FOR UPDATE）或分布式锁（Redis/ZooKeeper）
     处理请求前先获取锁，处理完成后释放锁
     其他请求需等待锁释放后才能处理，确保操作的原子性
     代码实现（订单状态更新为例）：

2. 订单表设计
   sql
   CREATE TABLE order_info (
   id bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
   order_id varchar(64) NOT NULL COMMENT '订单号',
   user_id varchar(64) NOT NULL COMMENT '用户ID',
   status varchar(32) NOT NULL COMMENT '状态：PENDING-待支付，PAID-已支付，CANCELED-已取消',
   create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
   update_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   PRIMARY KEY (id),
   UNIQUE KEY uk_order_id (order_id)
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT '订单信息表';
3. 基于数据库行锁的实现
   java
   运行
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.jdbc.core.JdbcTemplate;
   import org.springframework.stereotype.Service;
   import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderStatusService {
private static final Logger logger = LoggerFactory.getLogger(OrderStatusService.class);
private final JdbcTemplate jdbcTemplate;

public OrderStatusService(JdbcTemplate jdbcTemplate) {
    this.jdbcTemplate = jdbcTemplate;
}

/**
 * 更新订单状态（悲观锁实现幂等）
 */
@Transactional(rollbackFor = Exception.class)
public boolean updateOrderStatus(String orderId, String fromStatus, String toStatus) {
    // 1. 查询订单并加行锁（FOR UPDATE）
    logger.info("尝试更新订单状态，orderId={}, from={}, to={}", orderId, fromStatus, toStatus);
    Integer count = jdbcTemplate.queryForObject(
        "SELECT COUNT(1) FROM order_info WHERE order_id = ? AND status = ? FOR UPDATE",
        Integer.class,
        orderId, fromStatus
    );

    // 2. 检查订单是否存在且状态匹配
    if (count == null || count == 0) {
        logger.warn("订单状态不匹配或不存在，orderId={}, 当前状态不是{}", orderId, fromStatus);
        return false;
    }

    // 3. 更新订单状态
    int rows = jdbcTemplate.update(
        "UPDATE order_info SET status = ?, update_time = NOW() WHERE order_id = ?",
        toStatus, orderId
    );

    logger.info("订单状态更新完成，orderId={}, 结果={}", orderId, rows > 0 ? "成功" : "失败");
    return rows > 0;
}

}

1. 基于 Redis 分布式锁的实现（适合跨服务场景）
   java
   运行
   import org.redisson.api.RLock;
   import org.redisson.api.RedissonClient;
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.stereotype.Component;

import java.util.concurrent.TimeUnit;

@Component
public class RedisLockHandler {
private static final Logger logger = LoggerFactory.getLogger(RedisLockHandler.class);
private final RedissonClient redissonClient;

public RedisLockHandler(RedissonClient redissonClient) {
    this.redissonClient = redissonClient;
}

/**
 * 执行带锁的任务
 */
public <T> T executeWithLock(String lockKey, long waitTime, long leaseTime, 
                            TimeUnit unit, LockTask<T> task) {
    RLock lock = redissonClient.getLock(lockKey);
    boolean locked = false;
    try {
        // 尝试获取锁
        locked = lock.tryLock(waitTime, leaseTime, unit);
        if (locked) {
            // 获取锁成功，执行任务
            return task.execute();
        } else {
            logger.warn("获取锁失败，lockKey={}", lockKey);
            throw new RuntimeException("系统繁忙，请稍后重试");
        }
    } catch (InterruptedException e) {
        logger.error("获取锁被中断，lockKey={}", lockKey, e);
        Thread.currentThread().interrupt();
        throw new RuntimeException("系统异常，请稍后重试");
    } finally {
        // 释放锁（确保只释放当前线程持有的锁）
        if (locked && lock.isHeldByCurrentThread()) {
            lock.unlock();
            logger.debug("释放锁成功，lockKey={}", lockKey);
        }
    }
}

// 函数式接口：带返回值的锁内任务
@FunctionalInterface
public interface LockTask<T> {
    T execute();
}

}
优缺点与适用场景：
优点：能严格保证数据一致性；适合写冲突频繁的场景
缺点：存在锁竞争，性能较低；可能导致死锁；分布式锁实现复杂
适用场景：订单状态更新、支付结果确认、库存调整等核心流程
4.4 方案四：基于状态机的幂等设计（状态流转场景）
核心思想：将业务对象的状态流转定义为有限状态机，只有符合状态转换规则的请求才被允许执行。
实现原理：
定义业务对象的所有可能状态（如订单的 "待支付"、"已支付"）
定义状态之间的合法转换规则（如 "待支付"→"已支付"）
处理请求时，校验当前状态是否允许转换到目标状态，只有符合规则才执行更新
代码实现（订单状态机为例）：

1. 订单状态枚举（状态机定义）
   java
   运行
   import java.util.Arrays;
   import java.util.HashSet;
   import java.util.Set;

/**

• 订单状态枚举（状态机定义）
  */
  public enum OrderStatus {
  // 初始状态：待支付
  PENDING_PAY("待支付", new String[]{"PAID", "CANCELED"}),
  // 已支付
  PAID("已支付", new String[]{"SHIPPED", "REFUNDED"}),
  // 已发货
  SHIPPED("已发货", new String[]{"RECEIVED"}),
  // 已收货
  RECEIVED("已收货", new String[]{"COMPLETED", "REFUNDED"}),
  // 已完成
  COMPLETED("已完成", new String[]{}),
  // 已取消
  CANCELED("已取消", new String[]{}),
  // 已退款
  REFUNDED("已退款", new String[]{});

  private final String desc;
  // 允许转换到的目标状态
  private final Set allowedTransitions;

  OrderStatus(String desc, String[] allowed) {

   this.desc = desc;
   this.allowedTransitions = new HashSet<>(Arrays.asList(allowed));
  

  }

  /**

  • 检查是否允许转换到目标状态
    */
    public boolean canTransitionTo(OrderStatus target) {
    return allowedTransitions.contains(target.name());
    }

    public String getDesc() {
    return desc;
    }
    }

    1. 订单状态服务（基于状态机）
       java
       运行
       import org.slf4j.Logger;
       import org.slf4j.LoggerFactory;
       import org.springframework.jdbc.core.JdbcTemplate;
       import org.springframework.stereotype.Service;
       import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderStateMachineService {
private static final Logger logger = LoggerFactory.getLogger(OrderStateMachineService.class);
private final JdbcTemplate jdbcTemplate;

public OrderStateMachineService(JdbcTemplate jdbcTemplate) {
    this.jdbcTemplate = jdbcTemplate;
}

/**
 * 基于状态机更新订单状态
 */
@Transactional(rollbackFor = Exception.class)
public boolean updateStatusWithStateMachine(String orderId, OrderStatus targetStatus) {
    // 1. 查询当前订单状态
    String currentStatusStr = jdbcTemplate.queryForObject(
        "SELECT status FROM order_info WHERE order_id = ?",
        String.class,
        orderId
    );
    OrderStatus currentStatus = OrderStatus.valueOf(currentStatusStr);
    logger.info("更新订单状态，orderId={}, 当前状态={}, 目标状态={}",
                orderId, currentStatus.getDesc(), targetStatus.getDesc());

    // 2. 校验状态转换是否合法
    if (!currentStatus.canTransitionTo(targetStatus)) {
        logger.error("订单状态转换不合法，orderId={}, 不允许从{}转换到{}",
                    orderId, currentStatus.getDesc(), targetStatus.getDesc());
        return false;
    }

    // 3. 执行更新
    int rows = jdbcTemplate.update(
        "UPDATE order_info SET status = ?, update_time = NOW() WHERE order_id = ?",
        targetStatus.name(), orderId
    );

    logger.info("订单状态更新结果，orderId={}, 成功={}", orderId, rows > 0);
    return rows > 0;
}

}
优缺点与适用场景：
优点：状态转换规则清晰，可维护性强；能有效防止非法状态变更
缺点：前期设计成本高；不适合状态频繁变更的业务
适用场景：订单系统、工作流系统、状态流转清晰的业务对象
4.5 方案五至方案八：其他场景的幂等设计方案
限于篇幅，以下四种方案简要介绍核心实现与适用场景，完整代码可参考前文风格自行扩展：
方案五：基于 Token 的幂等设计（前端表单场景）
核心流程：前端先获取 Token → 提交时携带 Token → 后端验证 Token 有效性并立即失效
实现要点：Token 需绑定用户 ID，设置合理过期时间（如 30 分钟），使用 Redis 存储
适用场景：用户表单提交、评论发布、报名登记等前端交互场景
方案六：基于数据库唯一索引的幂等设计（插入场景）
核心流程：为业务唯一标识（如订单号）创建唯一索引 → 插入时捕获 DuplicateKeyException → 视为重复请求处理
实现要点：唯一标识需业务上保证唯一性（如 "用户 ID + 商品 ID + 日期"）
适用场景：订单创建、用户注册、记录生成等插入操作
方案七：基于分布式事务的幂等设计（跨服务场景）
核心流程：TCC 模式中为 Try/Confirm/Cancel 阶段设计幂等性 → 通过事务 ID 确保重复调用安全
实现要点：每个阶段需独立实现幂等，Confirm/Cancel 需支持空补偿
适用场景：分布式事务、跨服务调用场景
方案八：基于本地缓存的幂等设计（高频读场景）
核心流程：使用 Caffeine 本地缓存记录已处理的请求 ID → 内存校验避免数据库访问
实现要点：设置合理的缓存过期时间，避免内存溢出
适用场景：高频读、低并发写的接口（如商品详情查询计数）
五、幂等性设计的最佳实践与避坑指南
掌握了各种方案后，还需要了解实际开发中的最佳实践，避免踩坑。
5.1 方案选型的黄金法则
优先使用唯一请求 ID：通用型方案，适合 90% 以上的场景
高并发写用乐观锁：库存、余额等高频更新场景
强一致性用悲观锁：订单状态、支付结果等核心流程
状态流转用状态机：订单、工单等有明确状态的业务对象
前端交互用 Token：表单提交、按钮点击等场景
5.2 避坑指南：90% 的人会犯的 5 个错误
错误：依赖前端防重复提交
正确做法：前端防重只是体验优化，后端必须实现幂等性
错误：唯一标识设计不合理
正确做法：唯一标识需满足 "业务唯一性"，如 "订单号" 而非 "用户 ID"
错误：忽略异常情况下的幂等性
正确做法：需考虑 "处理中" 状态的超时处理，避免请求永久阻塞
错误：重试机制设计不当
正确做法：重试次数有限制（如 3 次），使用指数退避策略，避免雪崩
错误：分布式锁未设置过期时间
正确做法：必须设置锁过期时间，避免服务宕机导致死锁
六、总结：幂等性设计的本质与价值
幂等性设计的本质，是通过技术手段屏蔽分布式系统的不确定性，确保业务数据的一致性。它不是可有可无的优化，而是系统稳定性的基石。
从本文介绍的 8 种方案中，你会发现一个共性：幂等性的核心是 "唯一性"—— 唯一请求 ID、唯一业务标识、唯一版本号、唯一状态转换规则。抓住 "唯一性" 这个核心，就能在各种场景中设计出可靠的幂等方案。
最后，记住一句话：在分布式系统中，重复调用是常态。与其祈祷不发生，不如主动设计幂等性。当你的系统能从容应对各种重复调用时，才能真正称得上是一个健壮的分布式系统。