Python Resilience Patterns 是一套面向 Python 应用的容错与韧性实践,目标是让系统在瞬态失败、网络问题和服务中断时能够优雅处理,保持运行。
一、适用场景 资料列出以下使用时机:为外部服务调用添加重试逻辑;为网络操作实现超时;构建容错的微服务;处理限流和背压;创建基础设施装饰器;设计断路器。
二、核心概念
- 瞬态失败与永久失败:应重试瞬态错误(如网络超时、临时服务问题),不应重试永久错误(如凭证无效、错误请求)。
- 指数退避:在重试之间增加等待时间,避免压垮正在恢复的服务。
- 抖动(Jitter):为退避加入随机性,防止大量客户端同时重试造成“惊群”效应。
- 有界重试:对尝试次数和总时长都设上限,避免无限重试循环。
三、快速开始 示例使用 tenacity 的 retry、stop_after_attempt、wait_exponential_jitter 装饰器,对调用外部服务的函数设置最多 3 次尝试与指数退避加抖动。
四、基础模式 模式 1:使用 tenacity 的基础重试。资料建议生产级重试逻辑使用 tenacity 库;简单场景可考虑内置重试功能或轻量级自定义实现。示例定义 TRANSIENT_ERRORS 为 ConnectionError、TimeoutError、OSError,并组合 stop_after_attempt(5) 与 stop_after_delay(60),配合 wait_exponential_jitter。
模式 2:只重试合适的错误。资料明确列出永不重试的情形:ValueError、TypeError(属于 bug 而非瞬态问题)、AuthenticationError(无效凭证不会变有效)、HTTP 4xx(429 除外,客户端错误是永久的)。示例将可重试异常限定为 ConnectionError、TimeoutError、httpx.ConnectTimeout、httpx.ReadTimeout。
模式 3:按 HTTP 状态码重试。针对表示瞬态问题的状态码重试,示例将 RETRY_STATUS_CODES 设为 {429, 502, 503, 504},并使用 retry_if_result 判断响应是否可重试。
模式 4:组合异常与状态码重试。同时处理网络异常和 HTTP 状态码,示例合并 retry_if_exception_type 与 retry_if_result,并用 before_sleep_log 记录重试日志。
五、更多细节 资料说明更详细的章节(从“Advanced Patterns”开始)位于 references/details.md,当上方导航摘要不足时可阅读该文件。
六、最佳实践 只重试瞬态错误——不要重试 bug 或认证失败;使用指数退避——给服务恢复时间;加入抖动——防止同步重试的惊群效应;限制总时长——stop_after_attempt(5) | stop_after_delay(60);记录每次重试——静默重试会掩盖系统性问题;使用装饰器——让重试逻辑与业务逻辑分离;注入依赖——使基础设施可测试;处处设置超时——每次网络调用都需要超时;优雅失败——对非关键路径返回缓存或默认值;监控重试率——高重试率意味着底层问题。
七、限制 资料未提供该技能的具体安装命令、依赖版本要求、价格或收费方式、许可协议以及官方文档地址之外的运行环境要求,这些信息暂未提供。