什么是幂等性

定义

**幂等性（Idempotency）**是指同一个操作执行一次和执行多次产生的结果是一致的。换句话说，无论重复执行多少次，系统的状态都不会发生额外的变化。

数学表达

在数学中，如果一个函数 f 满足以下条件，则称其为幂等函数：

f(f(x)) = f(x)

编程中的幂等性

在软件开发中，幂等性通常指：

1. API 层面：同一个请求发送多次，服务器资源和返回结果保持一致
2. 数据库层面：同一条 SQL 语句执行多次，数据状态不变
3. 消息队列层面：同一条消息被消费多次，业务处理结果一致

核心原则

1. 状态一致性

幂等操作的核心是确保系统状态的确定性：

// 非幂等操作：每次调用都会增加余额
public async Task<decimal> AddBalance(Guid userId, decimal amount)
{
    var user = await _dbContext.Users.FindAsync(userId);
    user.Balance += amount; // 重复调用会导致余额不断增加
    await _dbContext.SaveChangesAsync();
    return user.Balance;
}

// 幂等操作：设置余额为固定值
public async Task<decimal> SetBalance(Guid userId, decimal amount)
{
    var user = await _dbContext.Users.FindAsync(userId);
    user.Balance = amount; // 重复调用结果一致
    await _dbContext.SaveChangesAsync();
    return user.Balance;
}

2. 副作用可控

幂等操作允许有副作用，但副作用必须是可预测和可控的：

// 示例：更新用户最后登录时间
public async Task UpdateLastLogin(Guid userId)
{
    var user = await _dbContext.Users.FindAsync(userId);
    
    // 虽然每次调用都会更新时间，但最终状态是确定的
    // 都指向最后一次调用的时间戳
    user.LastLoginTime = DateTime.UtcNow;
    await _dbContext.SaveChangesAsync();
}

3. 返回值一致性

对于查询类操作，幂等性还要求返回值保持一致：

// GET 请求天然幂等：多次调用返回相同数据
[HttpGet("{id}")]
public async Task<ActionResult<User>> GetUser(Guid id)
{
    var user = await _dbContext.Users.FindAsync(id);
    return Ok(user); // 无论调用多少次，返回的用户信息一致
}

幂等性的层次

1. 读操作幂等

读取数据的操作天然是幂等的（不改变状态）：

// 查询用户列表 - 天然幂等
[HttpGet]
public async Task<ActionResult<IEnumerable<User>>> GetUsers()
{
    return Ok(await _dbContext.Users.ToListAsync());
}

2. 写操作幂等

修改数据的操作需要特殊设计才能保证幂等：

// 使用唯一索引保证订单创建的幂等性
public async Task<Order> CreateOrder(CreateOrderRequest request, string idempotencyKey)
{
    // 检查是否已存在相同的幂等键
    var existingOrder = await _dbContext.Orders
        .FirstOrDefaultAsync(o => o.IdempotencyKey == idempotencyKey);
    
    if (existingOrder != null)
    {
        // 返回已创建的订单，保证幂等
        return existingOrder;
    }
    
    // 创建新订单
    var order = new Order
    {
        IdempotencyKey = idempotencyKey,
        UserId = request.UserId,
        Amount = request.Amount,
        CreatedAt = DateTime.UtcNow
    };
    
    _dbContext.Orders.Add(order);
    await _dbContext.SaveChangesAsync();
    
    return order;
}

3. 删除操作幂等

删除操作应该容忍重复调用：

// 幂等的删除操作
public async Task DeleteUser(Guid userId)
{
    var user = await _dbContext.Users.FindAsync(userId);
    
    if (user == null)
    {
        // 用户不存在也视为成功（已经删除过了）
        return;
    }
    
    _dbContext.Users.Remove(user);
    await _dbContext.SaveChangesAsync();
}

幂等性与非幂等性对比

操作类型	示例	是否幂等	说明
查询用户	GET /users/123	✅ 是	不改变状态
更新邮箱	PUT /users/123/email	✅ 是	覆盖式更新
追加余额	POST /users/123/balance	❌ 否	累加式更新
删除资源	DELETE /orders/456	✅ 是	删除后再次删除无影响
创建订单	POST /orders	❌ 否	会创建多个订单
设置状态	PUT /orders/456/status	✅ 是	覆盖式更新

实际应用场景

场景 1：网络重试

// 客户端实现重试机制
public async Task<Order> CreateOrderWithRetry(CreateOrderRequest request)
{
    var maxRetries = 3;
    var idempotencyKey = Guid.NewGuid().ToString(); // 生成幂等键
    
    for (int i = 0; i < maxRetries; i++)
    {
        try
        {
            return await _apiClient.CreateOrder(request, idempotencyKey);
        }
        catch (TimeoutException)
        {
            // 超时后重试，服务端通过幂等键识别是同一请求
            if (i == maxRetries - 1) throw;
        }
    }
    
    throw new Exception("创建订单失败");
}

场景 2：消息队列去重

// 消费者端实现幂等性
public class OrderCreatedConsumer : IConsumer<OrderCreatedEvent>
{
    public async Task Consume(ConsumeContext<OrderCreatedEvent> context)
    {
        var messageId = context.MessageId.ToString();
        
        // 检查是否已处理过该消息
        if (await _processedMessages.ExistsAsync(messageId))
        {
            _logger.LogInformation("消息 {MessageId} 已处理，跳过", messageId);
            return;
        }
        
        // 处理业务逻辑
        await ProcessOrder(context.Message);
        
        // 记录已处理的消息
        await _processedMessages.AddAsync(messageId);
    }
}

总结

幂等性是构建可靠分布式系统的基石，它确保了：

1. 容错性：系统能够安全地重试失败的操作
2. 一致性：重复操作不会导致数据异常
3. 用户体验：避免因网络抖动或误操作导致的重复提交问题

在接下来的章节中，我们将深入探讨如何实现幂等性的各种技术方案。