C#怎么实现API的幂等性 API幂等性设计与实现方法

API幂等性需通过设计与代码逻辑共同保障，核心是确保同一请求多次执行产生相同副作用；C#中常用RequestId去重、业务字段唯一约束、状态机+版本号及统一过滤器实现。

API 幂等性不是靠框架自动实现的，而是靠设计 + 代码逻辑共同保障。核心思路是：**对同一请求（无论重试多少次），系统产生的副作用必须相同（比如数据库状态、业务结果一致）**。C# 中实现的关键在于识别“重复请求”并跳过重复处理。

用唯一请求标识（如 RequestId）做去重

客户端每次调用 API 时，带上一个全局唯一 ID（如 GUID），服务端在处理前先查这个 ID 是否已成功处理过。

• 把 RequestId + 处理结果（如 success / order_id / error_code）存入 Redis 或数据库，设置合理过期时间（例如 24 小时）
• 进入接口后，先查缓存/表：若存在且状态为 success，直接返回之前的结果，不执行业务逻辑
• 若不存在，加分布式锁（如 Redis Lock）防止并发重复写入，再执行业务，成功后写入幂等记录

基于业务字段做天然幂等（推荐用于创建类接口）

利用业务本身具备唯一性的字段，让重复请求因数据库唯一约束失败，从而避免重复插入。

• 例如创建订单，用「用户ID + 商户订单号」建联合唯一索引
• 接口中先尝试 INSERT，捕获唯一键冲突异常（SqlException 或 DbUpdateException），捕获后查出已有记录并返回
• 注意：不能只依赖异常兜底，要配合前置校验（如先 SELECT）提升响应速度和可读性

状态机 + 版本号控制更新类操作

对修改类操作（如支付回调、发货更新），仅允许状态按预设流程推进，并用版本号或时间戳防止旧请求覆盖新状态。

• 数据库表加 version 字段或 last_modified_time，UPDATE 语句带上 WHERE version = @oldVersion
• 更新后检查 RowsAffected == 0，说明已被其他请求抢先更新，直接返回成功（或当前最新状态）
• 关键状态变更（如 “待支付 → 已支付”）用状态机严格校验，非法流转直接拒绝

在 ASP.NET Core 中统一拦截与封装

避免每个接口重复写幂等逻辑，可通过 ActionFilter 或中间件提取共性。

• 自定义 IdempotentAttribute，配合 Filter 实现自动校验 RequestId
• 注入 IIdempotentStore（抽象存储层），支持 Redis / SQL Server 等多种后端，便于切换
• 对 GET、HEAD、OPTIONS 等天然幂等方法默认放行；对 POST/PUT/PATCH 方法按需启用

基本上就这些。幂等性不是银弹，要结合接口类型（创建 / 修改 / 查询）、数据一致性要求、性能瓶颈来选方案。简单场景用业务唯一键 + 异常捕获，复杂链路建议加 RequestId 全局追踪 + 状态机。不复杂但容易忽略的是：**日志记录、监控告警、以及客户端重试策略的配合**。