Python 重试库 Tenacity 核心用法与实战指南

2. 等待策略 (Wait)

决定两次重试之间的等待时间。

• wait_fixed(n): 固定等待 n 秒。
• wait_exponential(multiplier=1, min=1, max=10): 指数退避，默认从 1 秒开始，每次翻倍，最大不超过 10 秒。这是生产环境最常用的策略。
• wait_random(min, max): 在最小和最大值之间随机等待，用于避免'惊群效应'。

from tenacity import wait_exponential

@retry(wait=wait_exponential(multiplier=1, min=4, max=10))
def slow_operation():
    pass

3. 重试条件 (Retry)

决定哪些情况需要重试。

• retry_if_exception_type(exception): 仅当捕获到指定类型的异常时重试。
• retry_if_result(predicate): 根据函数的返回值决定是否重试。
• retry_unless_exception_type(exception): 除非捕获到指定异常才重试。

from tenacity import retry_if_exception_type

@retry(retry=retry_if_exception_type(IOError))
def open_file(path):
    # 仅 IOError 触发重试
    pass

高级用法与回调

1. 日志记录与监控

在重试过程中记录日志有助于排查问题。可以使用 before_sleep_log 或在 before_sleep 中自定义回调。

import logging
from tenacity import retry, wait_fixed, before_sleep_log

logger = logging.getLogger(__name__)

@retry(wait=wait_fixed(2), before_sleep=before_sleep_log(logger, logging.WARNING))
def risky_task():
    raise ConnectionError("Network error")

2. 基于返回值的重试

有时函数没有抛出异常，但返回结果不符合预期（例如 API 返回了错误码）。此时可使用 retry_if_result。

from tenacity import retry, retry_if_result

def is_success(result):
    return result.get('status') == 'OK'

@retry(retry=retry_if_result(lambda x: not is_success(x)), stop=stop_after_attempt(3))
def fetch_data():
    return {'status': 'FAIL'}

3. 实际场景：HTTP 请求重试

在实际开发中，Tenacity 常用于封装 HTTP 客户端。

import requests
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    reraise=True
)
def get_url(url):
    response = requests.get(url, timeout=5)
    response.raise_for_status()
    return response.json()

try:
    data = get_url("https://api.example.com/data")
except Exception as e:
    print(f"获取数据失败：{e}")

最佳实践

1. 避免无限重试：始终设置合理的 stop 策略，防止死循环消耗资源。
2. 指数退避：在生产环境中优先使用 wait_exponential，给服务端恢复时间。
3. 区分异常：不要对所有异常都重试，只针对可恢复的异常（如 NetworkError, Timeout）进行重试。
4. 幂等性检查：确保重试操作不会导致副作用（如重复扣款），必要时在业务层增加幂等控制。

总结

Tenacity 为 Python 应用提供了标准化的重试机制，极大地简化了容错代码的编写。通过灵活组合停止、等待和重试条件，开发者可以构建出适应不同网络环境和业务需求的稳健系统。掌握 Tenacity 的高级用法，能显著提升分布式系统的可用性。