5行代码搞定Python重试逻辑：Retrying库实战指南-优快云博客

5行代码搞定Python重试逻辑：Retrying库实战指南

你是否曾因网络波动导致API调用失败？是否为文件读写的偶发错误头疼不已？重试逻辑是提升程序健壮性的关键，但手动实现复杂的重试策略既耗时又容易出错。本文将带你全面掌握Retrying库，用最少的代码构建可靠的重试机制，解决90%的不稳定操作问题。读完本文你将学会：

3种停止策略精确控制重试终止条件
5种等待算法减少资源竞争
异常与返回值双重过滤实现智能重试
6个实战场景的完整代码模板

项目概述

Retrying是一个Apache 2.0许可的通用重试库，通过简洁的装饰器API为Python函数添加重试功能。其核心优势在于：

无需编写繁琐的循环和条件判断
支持多种停止条件和等待策略组合
可基于异常类型和返回值智能决策
兼容Python 2.6+和3.2+版本

# 核心原理演示
from retrying import retry

@retry(stop_max_attempt_number=3, wait_fixed=1000)
def unstable_operation():
    """带重试功能的不稳定操作"""
    # 业务逻辑代码
    pass

安装与环境准备

通过pip快速安装：

pip install retrying

如需源码安装，克隆仓库后执行 setup.py：

git clone https://gitcode.com/gh_mirrors/re/retrying
cd retrying
python setup.py install

核心功能解析

重试控制参数总览

参数类别	关键参数	作用描述	默认值
停止策略	stop_max_attempt_number	最大尝试次数	5
	stop_max_delay	最大重试总时长(毫秒)	100
等待策略	wait_fixed	固定等待时长(毫秒)	1000
	wait_random_min/max	随机等待范围(毫秒)	0/1000
	wait_exponential_multiplier	指数退避乘数(毫秒)	1
	wait_exponential_max	最大指数等待时长(毫秒)	1073741823
过滤条件	retry_on_exception	异常过滤函数/类型	永不重试
	retry_on_result	返回值过滤函数	永不重试
高级配置	wrap_exception	是否包装异常为RetryError	False
	wait_jitter_max	等待时间抖动最大值(毫秒)	0

停止策略详解

1. 基于尝试次数

@retry(stop_max_attempt_number=5)  # 最多尝试5次(含首次)
def limited_attempt_operation():
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

2. 基于时间限制

@retry(stop_max_delay=5000)  # 5秒后停止重试
def time_limited_operation():
    print("尝试执行...")
    raise TimeoutError("操作超时")

3. 自定义停止条件

def stop_after_10_failures(attempts, delay):
    """尝试10次或延迟超过3秒后停止"""
    return attempts >= 10 or delay >= 3000

@retry(stop_func=stop_after_10_failures)
def custom_stop_operation():
    print("尝试执行...")
    raise IOError("资源访问错误")

停止策略流程图：

mermaid

等待策略全解析

1. 固定等待

@retry(wait_fixed=2000)  # 每次重试间隔2秒
def fixed_delay_operation():
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

2. 随机等待

@retry(wait_random_min=1000, wait_random_max=3000)  # 随机等待1-3秒
def random_delay_operation():
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

3. 递增等待

@retry(
    wait_incrementing_start=1000,  # 初始等待1秒
    wait_incrementing_increment=500,  # 每次增加500毫秒
    wait_incrementing_max=5000  # 最大等待5秒
)
def incremental_delay_operation():
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

4. 指数退避等待

@retry(
    wait_exponential_multiplier=1000,  # 基数1秒
    wait_exponential_max=10000  # 最大等待10秒
)
def exponential_backoff_operation():
    """
    等待时间计算: 2^attempt_number * multiplier
    第1次: 2秒, 第2次:4秒, 第3次:8秒, 之后保持10秒
    """
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

5. 带抖动的指数退避

@retry(
    wait_exponential_multiplier=1000,
    wait_exponential_max=10000,
    wait_jitter_max=1000  # 随机增加0-1秒抖动
)
def jittered_backoff_operation():
    """在指数退避基础上增加随机抖动，避免重试风暴"""
    print("尝试执行...")
    raise ConnectionError("网络连接失败")

等待策略对比表：

策略类型	适用场景	优点	缺点
固定等待	稳定环境下的简单重试	实现简单，可预测	可能导致资源竞争
随机等待	分布式系统中的并发操作	减少冲突概率	总耗时不确定
递增等待	资源逐渐恢复的场景	平衡及时性和资源消耗	初始等待过短或后期等待过长
指数退避	远程服务调用	网络友好，自动适应恢复时间	配置复杂，短时间故障恢复慢
带抖动的指数退避	高并发分布式系统	避免重试风暴，网络友好	等待时间不确定性最大

智能过滤机制

1. 异常类型过滤

def retry_if_io_error(exception):
    """仅当发生IOError时重试"""
    return isinstance(exception, IOError)

@retry(retry_on_exception=retry_if_io_error)
def file_operation():
    """文件操作，仅IO错误时重试"""
    with open("unstable_file.txt", "r") as f:
        return f.read()

直接指定异常类型元组：

@retry(retry_on_exception=(IOError, ConnectionError))
def network_file_operation():
    """网络文件操作，IO和连接错误时重试"""
    # 实现代码

2. 返回值过滤

def retry_if_none(result):
    """结果为None时重试"""
    return result is None

@retry(retry_on_result=retry_if_none)
def data_fetcher():
    """数据获取，返回None时重试"""
    # 实现代码
    return None  # 模拟失败场景

3. 异常包装

@retry(
    retry_on_exception=(IOError,),
    wrap_exception=True  # 将原始异常包装为RetryError
)
def safe_operation():
    raise IOError("操作失败")

try:
    safe_operation()
except RetryError as e:
    print(f"最终失败: {e.last_attempt}")
    # 可访问原始异常: e.last_attempt.value

实战场景全解析

场景1：API调用重试

import requests
from retrying import retry

def retry_if_request_failure(exception):
    """HTTP 5xx错误或连接错误时重试"""
    return (isinstance(exception, (requests.ConnectionError, requests.Timeout)) or 
            (isinstance(exception, requests.HTTPError) and 
             500 <= exception.response.status_code < 600))

@retry(
    retry_on_exception=retry_if_request_failure,
    stop_max_attempt_number=5,
    wait_exponential_multiplier=1000,
    wait_exponential_max=10000
)
def call_unstable_api(url):
    """调用不稳定API，带指数退避重试"""
    response = requests.get(url, timeout=5)
    response.raise_for_status()  # 抛出HTTP错误
    return response.json()

# 使用示例
data = call_unstable_api("https://api.example.com/data")

场景2：数据库操作重试

import psycopg2
from retrying import retry

@retry(
    retry_on_exception=(psycopg2.OperationalError, psycopg2.InterfaceError),
    stop_max_attempt_number=3,
    wait_fixed=2000,
    before_attempts=lambda attempt: print(f"第{attempt}次尝试连接数据库")
)
def connect_to_database():
    """数据库连接，连接错误时重试"""
    return psycopg2.connect(
        dbname="mydb",
        user="user",
        password="pass",
        host="unstable-db.example.com"
    )

# 使用示例
conn = connect_to_database()

场景3：文件下载与校验

import hashlib
import requests
from retrying import retry

def validate_file(file_path, expected_hash):
    """验证文件哈希值"""
    sha256 = hashlib.sha256()
    with open(file_path, "rb") as f:
        for chunk in iter(lambda: f.read(4096), b""):
            sha256.update(chunk)
    return sha256.hexdigest() == expected_hash

@retry(
    retry_on_result=lambda result: not result,  # 验证失败时重试
    stop_max_attempt_number=3,
    wait_fixed=5000
)
def download_and_validate(url, file_path, expected_hash):
    """下载文件并验证，失败则重试"""
    # 下载文件
    response = requests.get(url, stream=True)
    with open(file_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    
    # 验证文件
    return validate_file(file_path, expected_hash)

# 使用示例
download_success = download_and_validate(
    "https://example.com/large_file.iso",
    "local_file.iso",
    "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
)

场景4：分布式锁获取

import redis
from retrying import retry

class DistributedLock:
    @retry(
        stop_max_attempt_number=10,
        wait_exponential_multiplier=100,  # 指数退避，初始100ms
        wait_exponential_max=1000
    )
    def acquire(self, lock_key, timeout=30):
        """获取分布式锁，失败时重试"""
        r = redis.Redis(host="redis-server", port=6379)
        # 使用Redis SET NX EX命令尝试获取锁
        result = r.set(lock_key, "locked", nx=True, ex=timeout)
        if not result:
            raise RuntimeError("未能获取锁")
        return True

# 使用示例
lock = DistributedLock()
if lock.acquire("critical_resource_lock"):
    try:
        # 执行临界区操作
    finally:
        # 释放锁
        r.delete("critical_resource_lock")

场景5：带前置清理的重试

import tempfile
import os
from retrying import retry

def cleanup_temp_files(attempt_number):
    """重试前清理临时文件"""
    temp_dir = tempfile.gettempdir()
    for f in os.listdir(temp_dir):
        if f.startswith("retry_demo_"):
            try:
                os.remove(os.path.join(temp_dir, f))
                print(f"清理临时文件: {f}")
            except Exception as e:
                print(f"清理失败: {e}")

@retry(
    stop_max_attempt_number=3,
    wait_fixed=2000,
    before_attempts=cleanup_temp_files  # 每次尝试前执行清理
)
def temp_file_operation():
    """临时文件操作，失败前清理环境"""
    # 创建临时文件并执行操作
    with tempfile.NamedTemporaryFile(prefix="retry_demo_", delete=False) as f:
        f.write(b"some data")
    
    # 模拟随机失败
    if random.random() < 0.5:
        raise IOError("临时文件操作失败")

场景6：组合策略实现复杂重试

from retrying import retry
import random
import time

def should_retry(exception):
    """自定义异常过滤"""
    return isinstance(exception, (ConnectionError, TimeoutError))

def custom_wait(attempts, delay):
    """自定义等待策略：前3次快速重试，之后指数退避"""
    if attempts < 3:
        return 1000  # 前3次等待1秒
    else:
        return min(2 ** (attempts - 3) * 1000, 10000)  # 之后指数退避，最大10秒

def log_attempt(attempt_number):
    """记录重试日志"""
    print(f"=== 第{attempt_number}次尝试 ===")

@retry(
    retry_on_exception=should_retry,
    stop_max_attempt_number=8,
    stop_max_delay=60000,  # 1分钟超时
    wait_func=custom_wait,
    before_attempts=log_attempt,
    after_attempts=lambda attempt: print(f"尝试{attempt}完成")
)
def complex_operation():
    """组合多种策略的复杂操作"""
    # 模拟不稳定操作
    if random.random() < 0.7:  # 70%概率失败
        if random.random() < 0.5:
            raise ConnectionError("连接失败")
        else:
            raise TimeoutError("操作超时")
    return "成功结果"

# 使用示例
result = complex_operation()

最佳实践与性能优化

关键配置建议

合理设置停止条件：
- 网络操作：建议stop_max_attempt_number=3-5次
- 资源密集型操作：减少重试次数，增加等待时间
- 关键业务：可适当增加次数，但设置stop_max_delay防止无限阻塞
选择合适的等待策略：
- 内部服务：固定等待或短递增等待
- 外部API：指数退避等待（推荐multiplier=1000, max=10000）
- 高并发场景：必须添加抖动（wait_jitter_max=1000）
精确异常过滤：
- 避免使用过于宽泛的异常类型（如直接捕获Exception）
- 区分可恢复异常（如超时）和不可恢复异常（如认证失败）

性能优化技巧

# 1. 减少重试开销 - 只重试必要部分
def critical_operation():
    # 非重试部分 - 只执行一次
    preparation()
    
    # 重试部分 - 仅不稳定操作
    @retry(stop_max_attempt_number=3)
    def unstable_part():
        return perform_unstable_action()
    
    return unstable_part()

# 2. 使用缓存避免重复计算
from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_calculation(param):
    # 计算逻辑
    return result

@retry
def operation_with_cache():
    # 缓存结果不会被重试影响
    return expensive_calculation(123)

常见问题解决方案

重试风暴问题：
- 添加随机抖动（wait_jitter_max）
- 使用指数退避而非固定等待
- 实现断路器模式（结合tenacity等库）
资源泄露风险：
- 使用before_attempts清理前次失败资源
- 采用上下文管理器确保资源释放

性能监控：

import time

def monitor_retry(attempt_number):
    """监控重试性能"""
    if attempt_number > 1:  # 首次尝试不记录
        print(f"重试监控: 第{attempt_number}次尝试 at {time.ctime()}")

@retry(before_attempts=monitor_retry)
def monitored_operation():
    # 实现代码

版本演进与特性对比

版本	发布日期	关键特性
1.0.0	2013-01-21	基础功能，Apache许可
1.2.0	2014-05-04	自动推断停止/等待类型，异常传播改进
1.3.0	2014-09-30	添加six依赖，移除内嵌代码
1.3.3	2014-12-14	修复six版本依赖问题

与其他重试库对比：

特性/库	Retrying	Tenacity	Decorator
活跃维护	停止(2014后)	活跃	停止
Python 3支持	有限	完全支持	有限
装饰器API	简单	灵活	简单	异步支持	无	原生支持	无
依赖	six	无	无
学习曲线	平缓	中等	平缓

总结与未来展望

Retrying库通过简洁的API设计，让开发者能够轻松为Python程序添加健壮的重试逻辑。其核心价值在于：

大幅减少模板代码，专注业务逻辑
灵活的参数组合满足各种场景需求
成熟稳定，经过生产环境验证

尽管项目已停止活跃开发，但其核心功能在大多数场景下仍能满足需求。对于更复杂的场景，可关注Tenacity等现代重试库，它们提供了异步支持、类型注解等高级特性。

扩展学习路径：

结合断路器模式提升系统弹性
实现分布式追踪监控重试行为
构建自适应重试策略（基于成功率动态调整参数）

掌握重试逻辑不仅是提升代码健壮性的技巧，更是培养系统思维的重要一步。希望本文能帮助你构建更可靠的Python应用！

如果你觉得本文有价值，请点赞收藏，关注获取更多Python实战指南。下期预告：《分布式系统中的故障恢复模式》

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考