bitzorcas
中 EN

Concept

幂等性

请求去重 — IdempotencyPipelineBehavior 配合 IMemoryCache 实现自动重复请求检测和缓存响应回放。

Last updated

BitzOrcas 通过 Mediator 管道中的 IdempotencyPipelineBehavior 提供自动请求幂等性。携带 Idempotency-Key 头的请求自动去重。

工作原理

携带 Idempotency-Key: "req-abc123" 的请求
       │
       ▼
IdempotencyPipelineBehavior
       │
       ├── 缓存中存在键？→ 立即返回缓存响应
       │
       └── 未找到键？→ 执行处理器 → 缓存结果 → 返回响应

接口

命令通过实现 IIdempotentRequest 选择加入：

public interface IIdempotentRequest
{
    string GetIdempotencyKey();
}


public record CreateNoteCommand(string Title, string Content)
    : IRequest<Result<Note>>, IIdempotentRequest
{
    public string GetIdempotencyKey() => $"{Title.GetHashCode()}";
}

Idempotency-Key 头

客户端将幂等键作为 HTTP 头发送：

POST /api/notes
Idempotency-Key: req-abc123
Content-Type: application/json


{"title": "Hello", "content": "World"}
  • 首次请求：处理器执行，结果缓存
  • 重复请求：立即返回缓存结果
  • 缓存 TTL：可配置（默认 5 分钟）

实现细节

  • 使用 IMemoryCache 进行单实例去重
  • 缓存键包含幂等键 + 租户上下文
  • 处理器结果被序列化并缓存以供回放
  • 与 IUnitOfWork 配合——缓存结果包含已提交的事务结果

当前限制

限制描述
单实例内存缓存不跨实例共享
内存压力无缓存大小限制——高吞吐系统需要有界缓存
无过期通知缓存结果持续存在直到 TTL 过期

生产路线图

对于生产多实例部署：

{
  "Idempotency": {
    "Backend": "Redis",
    "DefaultTtlSeconds": 300,
    "MaxCacheSize": 10000
  }
}

另见