在分布式系统里，网络抖动、网关重试或用户误触都会导致同一个WebAPI被多次调用。如果接口不具备幂等性，重复请求就可能造成重复扣款、重复下单或重复发送通知。C#开发者在构建WebAPI时，需要通过合理的架构设计，让重复调用产生与单次调用一致的结果，且不引发额外业务副作用。
什么是接口幂等性
幂等（Idempotency）原本是数学概念，表示一个操作多次执行所产生的效果与一次执行相同。放到WebAPI场景中，就是客户端使用同样的参数重复请求某个接口，服务端无论收到一次还是十次，最终业务状态只变更一次。比如订单创建接口，第一次调用生成订单A，后续相同参数的调用不能生成订单B，而应返回订单A的信息。
需要注意的是，幂等并不等于“返回内容完全一致”。在查询接口中，每次返回最新数据是正常的；而在写接口中，幂等关注的是“是否产生了额外的状态修改”。C# WebAPI通常面对的是后者，即通过POST、PUT等操作修改资源，必须防止重复写。
基于唯一请求标识的Token方案
最常用的C#幂等实现是引入客户端唯一标识（Idempotency-Key）。客户端在发起请求前先获取或本地生成UUID，随请求头发送到服务端。服务端以该Key作为主键，在分布式缓存如Redis中记录处理状态。若缓存已存在且状态为完成，则直接返回首次结果，不再执行业务逻辑。
下面示例展示了一个简单的幂等过滤器，利用ASP.NET Core的ActionFilter结合Redis判断请求是否重复：
using Microsoft.AspNetCore.Mvc.Filters;
using StackExchange.Redis;
using System;
using System.Threading.Tasks;
public class IdempotencyFilter : IAsyncActionFilter
{
private readonly IDatabase _redis;
public IdempotencyFilter(IConnectionMultiplexer mux)
{
_redis = mux.GetDatabase();
}
public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
{
// 从请求头获取幂等键
if (!context.HttpContext.Request.Headers.TryGetValue("Idempotency-Key", out var key))
{
context.HttpContext.Response.StatusCode = 400;
await context.HttpContext.Response.WriteAsync("缺少Idempotency-Key头");
return;
}
string redisKey = "idemp:" + key.ToString();
// 尝试占用键，过期时间十分钟
bool locked = await _redis.StringSetAsync(redisKey, "processing", TimeSpan.FromMinutes(10), When.NotExists);
if (!locked)
{
// 已存在说明重复请求
string cached = await _redis.StringGetAsync(redisKey);
if (cached == "done")
{
context.HttpContext.Response.StatusCode = 200;
await context.HttpContext.Response.WriteAsync("重复请求，已忽略");
return;
}
}
var result = await next();
// 处理完成后标记完成
await _redis.StringSetAsync(redisKey, "done", TimeSpan.FromMinutes(10));
}
}
该方案的优点是对业务代码侵入小，通过过滤器统一拦截。缺点在于Redis不可用时会降级失效，因此需要配合降级策略，例如本地内存缓存或数据库唯一约束兜底。另外，Key的过期时间要大于客户端最大重试窗口，否则可能误放重复请求。
利用数据库唯一约束兜底
当业务数据写入关系型数据库时，可以设计一张幂等记录表，或者以业务唯一键建立唯一索引。C#中使用Entity Framework Core时，可将请求标识存为列并加唯一索引，重复插入会抛出DbUpdateException，捕获后返回首次结果即可。
示例代码如下，展示如何在插入订单前先插入幂等记录：
using Microsoft.EntityFrameworkCore;
using System;
using System.Threading.Tasks;
public class AppDbContext : DbContext
{
public DbSet<IdempotencyRecord> Records { get; set; }
public DbSet<Order> Orders { get; set; }
}
public class IdempotencyRecord
{
public string Key { get; set; }
public string OrderId { get; set; }
}
public class OrderService
{
private readonly AppDbContext _db;
public OrderService(AppDbContext db) { _db = db; }
public async Task<string> CreateOrderAsync(string idemKey, string product)
{
// 尝试插入幂等记录
var rec = new IdempotencyRecord { Key = idemKey };
_db.Records.Add(rec);
try
{
await _db.SaveChangesAsync();
}
catch (DbUpdateException)
{
// 唯一约束冲突，说明已处理
var old = await _db.Records.FirstAsync(r => r.Key == idemKey);
return old.OrderId;
}
// 正常创建订单
var order = new Order { Product = product };
_db.Orders.Add(order);
await _db.SaveChangesAsync();
rec.OrderId = order.Id;
await _db.SaveChangesAsync();
return order.Id;
}
}
这种方式的强项是利用数据库事务保证一致性，即使缓存层失败也不会重复写。但它的局限是增加了一次数据库往返，高并发下唯一约束冲突会带来一定性能损耗。实践中常将Redis前置过滤与数据库唯一索引结合，形成双层防护。
并发场景下的处理要点
在极高并发时，两个相同Key的请求可能同时通过“是否存在”的检查，再并行执行业务。C#中可使用分布式锁（如Redis的RedLock）或数据库悲观锁来串行化。另一种轻量做法是利用UPSERT语义，在写入业务表时以唯一键冲突作为幂等信号。
此外，幂等设计要与前端重试机制配合。前端应在收到可重试状态码（如网络错误、429、503）时才携带原Key重试，而非所有错误都重试，避免将真正失败的请求误判为重复处理。服务端日志也应记录Key与处理结果，方便排查争议。
总结设计选型
小型系统可仅用数据库唯一约束；中大型WebAPI建议采用“Redis幂等过滤器+数据库唯一索引”组合。C#开发者应把幂等逻辑抽象为通用组件，通过特性或中间件挂载，降低业务侵入。最终目标是无论网络如何重试，用户权益与系统数据都保持准确一致。
C#WebAPIidempotency修改时间：2026-08-05 04:45:28