幂等性怎么实现？

wen python案例 2026-07-18 3

从原理到实践的权威指南

目录导读

什么是幂等性？——核心概念与误区澄清
为什么需要幂等性？——业务场景与风险分析
幂等性实现的六大核心方案
常见问题与解决方案（Q&A）
最佳实践与避坑指南

什么是幂等性？——核心概念与误区澄清

幂等性（Idempotence） 是指任意多次执行同一个操作所产生的影响，与一次执行产生的影响完全相同，在分布式系统和API设计中,这是一个至关重要的特性。

幂等性怎么实现？

关键误区澄清：

❌ 幂等 ≠ 同一结果：幂等关注的是系统状态的变化，而不是返回值必须相同，例如第一次创建资源返回201，后续重试返回200,只要资源未被重复创建即可。
❌ 幂等 ≠ 无副作用：幂等操作可以有副作用,但重复执行不应产生额外的副作用。

典型幂等操作举例：

DELETE /users/123  // 无论执行几次，用户123最终都被删除
PUT /users/123     // 多次更新相同数据，结果一致
GET /users/123     // 多次读取，不改变状态

为什么需要幂等性？——业务场景与风险分析

在现实系统中，网络超时、客户端重试、消息重复投递是常态,不实现幂等性将导致以下灾难：

场景	非幂等后果	幂等解决方案
支付扣款重试	用户被重复扣款	按支付订单号去重
订单创建重试	生成多个重复订单	按业务单号+唯一索引
库存扣减重试	库存超卖	乐观锁+版本号
短信发送重试	用户收到N条相同短信	结合token校验

真实案例： 某电商系统因未实现订单幂等性，双十一期间网络抖动导致同一订单被创建3次，直接损失数十万，这个案例说明——幂等性是系统的防弹衣，不是可有可无的装饰。

幂等性实现的六大核心方案

1 数据库唯一约束（最基础方案）

原理： 利用数据库主键或唯一索引的约束,重复插入时抛出异常。

CREATE TABLE `payment` (
  `order_id` VARCHAR(64) PRIMARY KEY,  -- 业务单号做主键
  `amount` DECIMAL(10,2) NOT NULL
);
-- 重复插入时，数据库直接报错，不会产生两条记录
INSERT INTO payment VALUES('ORDER2025001', 99.99);

2 令牌与去重表（高并发首选）

原理： 客户端携带全局唯一ID（Token），服务端用去重表+分布式锁保证只处理一次。

实现步骤：

客户端请求时，生成UUID作为Token
服务端收到请求，先去Redis检查Token是否存在
若存在则直接返回结果（幂等处理），若不存在则将Token存入Redis并执行实际业务
业务完成后，保留Token（设置过期时间）

代码示例：

def process_payment(token, order_data):
    # 使用SET NX命令实现分布式锁
    if not redis.setnx(f"idempotent:{token}", "processing"):
        return {"code": 200, "msg": "请求已处理", "data": redis.get(f"result:{token}")}
    try:
        result = do_payment(order_data)
        redis.setex(f"result:{token}", 3600, result)
        return result
    except:
        redis.delete(f"idempotent:{token}")
        raise

3 乐观锁与版本号（防重复更新）

原理： 更新时带上版本号,只有版本号匹配时才能更新成功。

UPDATE product 
SET stock = stock - 1, version = version + 1 
WHERE id = 100 AND version = 5;
-- 检查受影响行数，若为0则说明版本号已变更，表示请求已处理过

4 状态机（业务流程控制）

原理： 定义业务的固定流转方向,只有符合状态路径才能执行。

状态机示例（订单状态）：

PENDING -> PROCESSING -> DELIVERED -> COMPLETED
                              |             |
                              v             v
                            CANCELED      REFUNDED

当订单已处于COMPLETED状态时，再次调用支付接口会直接返回成功（幂等）
不允许从COMPLETED跳转到CANCELED

5 全局唯一ID + 去重队列（消息场景）

原理： 消息中间件中，每条消息携带业务ID,消费端基于ID去重。

RabbitMQ实现：

{
  "messageId": "UUID-123456",
  "bizData": { "orderId": "ORDER2025001" }
}

消费端：检查Redis中是否已存在该messageId,存在则忽略。

6 幂等性设计模式（框架层面）

Spring Boot实现幂等性注解：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
    String tokenKey();  // 请求头中携带的token
    long expireTime() default 3600;
}
// AOP拦截器
@Aspect
public class IdempotentAspect {
    @Around("@annotation(idempotent)")
    public Object handleIdempotent(ProceedingJoinPoint pjp, Idempotent idempotent) {
        String token = getTokenFromRequest();
        String key = "idempotent:" + token;
        if (redis.hasKey(key)) {
            return redis.get("result:" + token);
        }
        Object result = pjp.proceed();
        redis.setex(key, idempotent.expireTime(), "processed");
        redis.setex("result:" + token, idempotent.expireTime(), result);
        return result;
    }
}