API 重试与退避策略（指数退避、抖动、幂等键与错误分类）

# API 重试与退避策略（指数退避、抖动、幂等键与错误分类） ## 概述 合理的重试可提升成功率，但不当重试会导致雪崩。本文给出参数化退避与幂等保障。 ## 关键实践与参数 - 重试条件： - 网络错误、超时、`5xx`、`429`；避免对业务性 `4xx` 重试。 - 指数退避： - `base=100ms`、`factor=2`、`max=5 重试`；加入随机抖动 `±20%`。 - 幂等键： - 在请求头/体传递 `Idempotency-Key`，服务端以窗口（如 24h）去重。 - 上限与超时： - 设定单次请求超时（如 3s）与整体预算（如 10s）。 ## 示例（伪代码） ``` retry: attempts: 5 base_ms: 100 factor: 2 jitter_ratio: 0.2 retry_on: [5xx, 429, timeout, network] idempotency: key_header: Idempotency-Key window_hours: 24 ``` ## 验证方法 - 压测模拟限流与间歇性故障，观察重试分布与成功率。 - 日志标记幂等键命中；统计重复提交与窗口命中率。 - 监控尾延迟与错误比重，评估退避参数对稳定性的影响。 ## 注意事项 - 与网关限流协同；避免同步重试形成尖峰。 - 对非幂等操作必须要求幂等键；或通过锁/队列序列化。 - 客户端与服务端需要一致的超时与预算管理。