idempotency-patterns

用途

本技能面向需要保证操作可以安全重试而不产生意外副作用的场景，主要覆盖：构建支付或金融 API、实现 Webhook 处理器、处理来自队列的消息、创建变更类端点（POST、PUT、DELETE），以及构建具备至少一次投递特性的分布式系统。

主要能力

幂等键生成

提供 generate_idempotency_key 函数，依据实体 ID、动作和可选参数生成确定性的 32 位十六进制字符串。实现要点是先拼接 entity_id:action，当存在参数时使用 json.dumps(params, sort_keys=True) 保证输出稳定，最后取 hashlib.sha256(...).hexdigest()[:32]。

FastAPI 幂等中间件

IdempotencyMiddleware 类针对 POST/PUT/PATCH 方法处理 Idempotency-Key 请求头。其流程为：仅对变更方法生效；无幂等键则直接放行；以 idem:{request.url.path}:{idempotency_key} 作为缓存键查询 Redis；命中则返回缓存内容并带上响应头 X-Idempotent-Replayed: true；未命中则执行请求，并对 2xx 成功响应写入 Redis（setex，默认 TTL 86400 秒），随后返回该响应。

基于数据库的幂等

定义 ProcessedRequest 模型，字段包括 idempotency_key（主键）、endpoint、status_code、response_body、created_at、expires_at。idempotent_execute 函数先按幂等键查询，若已存在且未过期则返回已存结果并标记为回放；否则执行操作，并通过 insert(...).on_conflict_do_nothing() 写入结果以应对竞态，返回结果为 (response, status_code, was_replayed) 三元组。

事件消费者幂等

IdempotentConsumer.process 方法从事件中读取 idempotency_key，若缺失则直接处理（文档注明此为有风险行为）。有键时先走 Redis 快速路径，再查数据库慢路径（命中后回填 Redis 缓存）。处理阶段使用 db.begin_nested() 嵌套事务，先插入 ProcessedEvent 占位并 flush，再执行 handler，成功后将缓存写入 Redis；若插入触发 IntegrityError，说明其他进程已抢占该键，视为重复。

关键决策

文档给出的建议如下：键生成采用确定性哈希（相同输入始终得到相同键）；存储采用 Redis 加数据库（Redis 求速度，数据库求持久性）；TTL 为 24-72 小时（平衡存储与重放窗口）；锁策略采用数据库唯一约束（处理竞态条件）；响应缓存仅限 2xx 状态码（不缓存错误）。

反模式（文档标注为禁止）

不得使用非确定性键（如 str(uuid.uuid4()) 每次不同）；不得在键中包含时间戳；不得在没有锁的情况下执行先检查后操作（存在竞态）；金融操作不得跳过幂等性；不得缓存错误响应（错误应允许重试）。

能力细节中的能力关键词

key-generation：关键词为 idempotency key、hash、deterministic、deduplication key，解决如何生成幂等键、确定性键生成与键格式最佳实践。api-idempotency：关键词为 idempotency header、POST idempotent、retry safe、middleware，解决如何让 POST 端点幂等、实现 Idempotency-Key 请求头、缓存与回放响应。consumer-idempotency：关键词为 exactly-once、event deduplication、message idempotency，解决如何精确一次处理事件、去重队列消息、处理至少一次投递。

限制

上述为文档所载模式的说明，未提供具体版本、安装方式、收费、价格或性能基准等信息。

技能介绍

用途