合理设置超时与重试是保障接口稳定的关键：连接超时设1~3秒、读取超时3~10秒；重试采用指数退避、限3~5次，仅针对5xx等临时错误；配合熔断降级、结构化日志与监控。
调用外部接口时，网络波动、服务端临时过载或限流都可能导致请求失败。合理设置超时与重试，是保障接口调用稳定性的关键，不是越多次重试越好，也不是超时越长越安全。
超时设置：分阶段控制更稳妥
单次请求应明确区分连接超时（connect timeout）和读取超时（read timeout）。连接超时建议设为1~3秒，防止卡在建连阶段；读取超时建议3~10秒，视接口预期响应时间而定。例如使用 requests 时可这样写：
-
requests.get(url, timeout=(2, 5))—— 前数为连接超时，后数为读取超时 - 避免只传单个数字（如
timeout=10），否则连接和读取共用同一时限，易掩盖真实问题 - 对高延迟但确定可用的接口（如某些政务API），可适度放宽读取超时，但需配合熔断机制
重试策略：带退避的有限重试
无条件重试可能加剧服务端压力，也容易触发限流。推荐使用指数退避（exponential backoff）+ 最大重试次数限制：
- 首次失败后等待 1 秒，第二次失败等 2 秒，第三次等 4 秒……每次翻倍，上限建议不超过 3~5 次
- 跳过明显不该重试的错误，如 400（参数错误）、401（鉴权失败）、404（资源不存在）
- 优先重试 5xx 服务端错误和部分 429（限流）、408（请求超时）等临时性状态码
- 可用 tenacity 库简化实现：
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10))
结合熔断与降级：避免雪崩效应
当某接口连续失败达到阈值（如 5 分钟内失败率超 50%），应自动熔断一段时间（如 60 秒），期间直接返回默认值或缓存结果，不发起真实调用：
立即学习“Python免费学习笔记（深入）”；
- 熔断器状态需线程安全，生产环境建议用 pybreaker 等成熟库管理
- 降级逻辑要轻量，避免引入新依赖或复杂计算
- 熔断恢复后，可先放行少量试探请求（half-open 状态），验证服务是否真正恢复
日志与可观测性：失败必须可追溯
每次重试、熔断、超时都应记录结构化日志，包含关键字段：
- 请求 URL、HTTP 方法、耗时、状态码、重试次数、异常类型
- 避免打印敏感参数（如 token、手机号），可用占位符脱敏
- 配合监控指标（如重试率、平均耗时、熔断触发次数），便于快速定位接口健康度拐点
