SyZero.Idempotency 1.2.0

.NET 9.0 This package targets .NET 9.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package SyZero.Idempotency --version 1.2.0
                    


                    

                
NuGet\Install-Package SyZero.Idempotency -Version 1.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="SyZero.Idempotency" Version="1.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="SyZero.Idempotency" Version="1.2.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="SyZero.Idempotency" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add SyZero.Idempotency --version 1.2.0
                    


                    

                
#r "nuget: SyZero.Idempotency, 1.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package SyZero.Idempotency@1.2.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=SyZero.Idempotency&version=1.2.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=SyZero.Idempotency&version=1.2.0
                    


                            Install as a Cake Tool

SyZero.Idempotency

ASP.NET Core 幂等性中间件 + 存储抽象。基于 Idempotency-Key 请求头复用之前的响应，保证同一 key 的重复请求只执行一次业务逻辑。

📦 安装

dotnet add package SyZero.Idempotency

✨ 特性

  • 🛡️ 基于 Idempotency-Key 头：业界通用约定（Stripe / GitHub / RFC 草案）。
  • 🔄 响应快照复用：首次成功响应缓存到 IIdempotencyStore，后续请求直接回放。
  • ⚡ 并发占位：首请求落地后立即占位，避免双发请求都执行业务。
  • 🔌 可插拔存储：默认 MemoryIdempotencyStore（单实例 / 测试）；多实例可换 Redis / 数据库实现。
  • 🎯 方法过滤：默认仅对 POST / PUT / PATCH / DELETE 生效，GET / HEAD 默认幂等不拦截。

🚀 快速开始

1. 注册服务

builder.Services.AddSyZeroIdempotency(builder.Configuration);
// 或：builder.Services.AddSyZeroIdempotency(configure: o => o.ExpirationSeconds = 600);

2. 启用中间件

app.UseRouting();
app.UseSyZeroIdempotency(); // 建议放在路由之后、终结点之前
app.MapControllers();

3. 客户端调用

POST /api/orders
Content-Type: application/json
Idempotency-Key: 5d1a3f08-...-uuid

{ "productId": 1, "quantity": 2 }

同一个 Idempotency-Key 在过期窗口内重复发送，会直接复用第一次的响应（状态码 / Body / ContentType）。

⚙️ 配置项

{
  "SyZeroIdempotency": {
    "HeaderName": "Idempotency-Key",
    "ExpirationSeconds": 86400,
    "InflightRejectionStatusCode": 409,
    "Methods": [ "POST", "PUT", "PATCH", "DELETE" ]
  }
}
字段 默认 说明
HeaderName Idempotency-Key 客户端携带幂等 key 的请求头
ExpirationSeconds 86400 key 的存活时间（秒），过期后允许重新执行
InflightRejectionStatusCode 409 首请求仍在处理时并发请求返回的状态码
Methods POST/PUT/PATCH/DELETE 命中的 HTTP 方法（不区分大小写）

🧩 自定义存储

实现 IIdempotencyStore 接口：

public class RedisIdempotencyStore : IIdempotencyStore { /* SET NX 实现 */ }

builder.Services.AddSingleton<IIdempotencyStore, RedisIdempotencyStore>();
builder.Services.AddSyZeroIdempotency();

⚠️ 注意

  • 默认 MemoryIdempotencyStore 仅适合单实例；多实例必须替换为 Redis / 数据库实现。
  • 中间件会缓冲整个响应体（MemoryStream），对大响应可能有内存压力，可在业务侧避免对大响应使用幂等 key。
  • 仅缓存 2xx / 4xx 响应，5xx 响应不缓存（允许后续重试）。
Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on SyZero.Idempotency:

Package Downloads
SyZero.Redis

SyZero-Redis

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
10.0.0 94 10/23/2026
9.1.0 79 10/22/2026
1.2.0 74 10/22/2026
1.2.0-dev.1 47 10/22/2026