SuperAPI AI 工具集

api-idempotency-retry

编程与开发

查看项目

更新于 10-16 08:44

技能介绍

用途:为公开 API 同时设计服务端幂等键与客户端重试行为,使重试写入安全。资料强调,只做其中一半会留下保证缺口。

主要能力:识别不可安全重试的端点;设计客户端生成、按调用方(account_id, idempotency_key)作用域的键契约;设置重放窗口(约 24 小时)与清理阈值(约 72 小时);用数据库唯一约束、条件写 OCC 或行锁加 SERIALIZABLE 原子认领键;设计缺失、进行中、已完成三态响应语义;编写客户端重试指引与 SDK 默认值。

使用方式:先提出澄清问题(协议、非幂等端点、存储类型、是否调用外部不可回滚系统、SDK 语言、最长重试链、交付期限)。重试仅针对 429(遵守 Retry-After)、502、503、504、连接超时等明确允许的错误,退避需带抖动,默认 full jitter。

适用场景:需要让第三方集成方从文档自行编写重试循环的 REST/gRPC 公开 API。

限制:Idempotency-Key 头没有已批准标准,语义需自行设计并记录;不可重试读取超时且无幂等键的非幂等操作;裸 Redis SETNX 锁不足以作为认领机制。错误响应格式等由 api-error-design 处理,此处不重新设计。