用途:在网络不可靠、客户端可能重试的场景下,避免重复创建或重复扣款,并为关键写操作设计并发控制与重试策略。适用支付、扣减、转账、订单创建与审批、限流和重试设计。
主要能力:区分天然幂等(GET、PUT、DELETE)与非幂等(POST、PATCH)操作;提供 Idempotency-Key 模式(请求头携带客户端生成的 UUID,服务端按 (Idempotency-Key, endpoint) 检查是否已处理,已处理则返回上次响应,存储期限通常 24 小时,重试须复用同一 Key);业务去重键方案(如用 user_id + external_order_id 或 order_id 去重,实现双重防护);并发冲突处理(ETag/If-Match 乐观锁返回 409,version 字段数据库乐观锁,Redis SET NX EX 或 SELECT FOR UPDATE 悲观锁);重试策略(网络错误、5xx、429 可重试,4xx 和业务错误不重试,指数退避加抖动,最大 3~5 次,客户端须遵循 Retry-After,限流返回 X-RateLimit-* 头)。
使用方式:先识别需幂等的端点,再选择幂等机制并设计并发控制与重试策略,最后写入文档说明哪些端点支持或必须传 Idempotency-Key、重试与限流策略。配套模板为 templates/idempotency-retry-template.md。
限制与常见坑:Idempotency-Key 服务端不存储会造成伪幂等;不同操作复用同一 Key 会互相干扰;重试时生成新 Key 会失去幂等效果;限流不返回 Retry-After、5xx 不重试、无指数退避或无最大重试次数都会出问题。具体实现细节与平台支持情况暂未提供。