

## 痛点开场

上篇我们把并发跑起来了——50 只股票从 12 秒压到 1.5 秒。

然后你周一早上到公司，跑一次全市场 5000 只的拉取——**跑到第 3800 只崩了**。

报错像这样：

```
HTTPServerError: 503 service unavailable
```

进程退出。剩下的 1200 只**一只没拉**。

你重新跑，又是 40 分钟。再崩在第 4200 只。再重跑……

**这不是策略问题，是工程问题**。

本文解决的就是：**怎么让脚本遇到 5xx / 超时时自动重试、遇到 4xx 直接跳过、既稳定又不浪费额度**。

## 本文你将得到什么

1. 三种拉取模式实测对比：无重试 / 无脑重试 / **异常分类重试**
2. `tenacity` 三个关键参数：`retry`/`stop`/`wait` 的正确写法
3. **异常分类铁律**：5xx 和超时可重试，4xx（特别是 400/401/403/404）重来也是白搭
4. `wait_exponential` 指数退避的正确配法（0.05/0.2 vs 0.3/2.0 的取舍）

## 一、为什么无脑重试是错的

直觉做法：拉一次失败就重试 3 次。

```python
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=0.3))
def fetch(code):
    return api.stock_history(code=code, ...)
```

看起来没问题，但有个**致命坑**：

- 服务端返回 **400（参数无效）** 或 **404（股票不存在）**——重试 100 次也是 400/404
- 服务端返回 **401（鉴权失败）** 或 **403（无权限）**——重试到过期也是 401/403
- 这些**重试毫无意义**，但每次重试**调用一次额度**

**真实生产事故**：某量化团队一个脚本对一只已退市的股票（代码写错）反复重试 50 次，浪费 50 次额度 + 阻塞主线程 25 秒。

**正确做法**：

> **只重试"服务端临时错"和"网络层错"**；其它错立即抛、不重试。

## 二、异常分类：与 HTTP 状态码同构

把异常按 HTTP 状态码分成三类：

| 类别 | 状态码 | 是否重试 | 原因 |
|---|---|---|---|
| **客户端错** | 400/401/403/404 | ❌ 否 | 参数/权限/资源问题，重试无意义 |
| **服务端错** | 500/502/503/504 | ✅ 是 | 临时性故障，几秒后自愈 |
| **网络层错** | 超时/DNS/连接重置 | ✅ 是 | 网络抖动，自动恢复 |

写成代码：

```python
class HTTPError(Exception):
    """所有 HTTP 错误的基类"""
    def __init__(self, status_code, msg=""):
        super().__init__(f"HTTP {status_code}: {msg}")
        self.status_code = status_code

class HTTPClientError(HTTPError):
    """4xx：客户端错，重试无意义"""

class HTTPServerError(HTTPError):
    """5xx：服务端临时错，值得重试"""

class NetworkError(HTTPError):
    """网络层异常，值得重试"""
```

这样在调用 `fetch_one` 时，**不同错走不同分支**：

```python
def fetch_one(code):
    r = api.stock_history(code=code, ...)
    if r.status_code == 200:
        return r.json()
    elif 400 <= r.status_code < 500:
        raise HTTPClientError(r.status_code)
    elif r.status_code >= 500:
        raise HTTPServerError(r.status_code)
    # 超时 / DNS 等由 requests 直接抛 ConnectionError
```

## 三、tenacity 三件套：`retry`/`stop`/`wait`

```python
from tenacity import (
    retry,
    retry_if_exception_type,
    stop_after_attempt,
    wait_exponential,
)

# 仅对 5xx/网络错重试，4xx 立即抛
@retry(
    retry=retry_if_exception_type((HTTPServerError, NetworkError)),
    stop=stop_after_attempt(3),       # 最多 3 次（含首次）
    wait=wait_exponential(multiplier=0.3, max=2.0),  # 指数退避
    reraise=True,                     # 用尽后原样抛（不要 RetryError 包装）
)
def fetch_with_retry(code):
    return fetch_one(code)
```

| 参数 | 作用 | 推荐值 |
|---|---|---|
| `retry=` | 重试**哪些**异常 | `retry_if_exception_type((HTTPServerError, NetworkError))` |
| `stop=` | 最多**几次** | `stop_after_attempt(3)` 或 `stop_after_delay(60)`（总时长限） |
| `wait=` | 几次**之间**等多久 | `wait_exponential(multiplier=0.3, max=2.0)` |
| `reraise=` | 用尽后**怎么抛** | `True`（抛原异常，便于上层分类处理） |

### 3.1 wait_exponential 的关键：multiplier 和 max

```python
wait_exponential(multiplier=0.3, max=2.0)
```

退避序列：**0.3s → 0.6s → 1.2s → 2.0s（第 4 次封顶 2.0s）**

为什么这么配？
- 第 1 次重试：0.3s（短暂让路）
- 第 2 次：0.6s（再等）
- 第 3 次：1.2s（明显让步）
- 后续：2.0s（封顶，不再无限等）

**反例**：`multiplier=1, max=10` —— 间隔太长，对用户不友好；服务端已恢复你还在等。

### 3.2 `stop_after_delay`：总时长兜底

如果担心一只股票卡死拖垮整个任务，可以加一个"总时长限制"：

```python
from tenacity import stop_after_delay

@retry(
    retry=retry_if_exception_type((HTTPServerError, NetworkError)),
    stop=(stop_after_attempt(3) | stop_after_delay(30)),  # 3 次**或** 30 秒
    wait=wait_exponential(multiplier=0.3, max=2.0),
    reraise=True,
)
```

## 四、实测对比（20 只样本 × 3 轮）

mock 一个会按概率返回 5xx / 超时 / 4xx 的"网络服务"，分别跑三种模式：

| 模式 | 成功率 | 总调用次数 | 耗时 | 关键差异 |
|---|---|---|---|---|
| A. **无重试**（遇错即停） | 18.5% | 6.7 | 0.00s | 第 1 只错就 break，剩 17 只根本不跑 |
| B. **无脑重试**（4xx 也重） | 98.5% | 28.3 | 0.51s | 看似成功率高，但 4xx 也重试浪费 8.7 次调用 |
| C. **分类重试**（仅 5xx+网络） | 91.5% | 26.7 | 0.42s | 4xx 直接抛，**省 1.6 次 API**、不浪费额度 |

**结论一目了然**：

- **C 比 B 省 5.6% 调用次数**（4xx 不重试），且成功率达 91.5%
- B 在表面"成功率最高"的幻象下，让 4xx 错也消耗额度——生产环境**只有 C 是对的**

> **核心铁律**：用 `retry_if_exception_type` **白名单**指定可重试异常，**不要省略 `retry=`**（默认是全部异常都重试）。

## 五、常见坑

### 5.1 漏写 `reraise=True`

```python
@retry(stop=stop_after_attempt(3))  # 默认 reraise=False
def fetch(...): ...
```

→ 用尽 3 次后会抛 `RetryError`，**原异常信息丢失**。务必加 `reraise=True`。

### 5.2 tenacity 与 `requests` 默认超时

```python
# requests 默认无超时，会卡死到你机器先崩
r = requests.get(url, timeout=None)  # 永远等

# 必须显式设
r = requests.get(url, timeout=(3.0, 10.0))  # (connect, read) 超时
```

否则连接卡住 → tenacity 等待 3 次 → 才能退出。**先设超时，才能让 tenacity 起作用**。

### 5.3 用 `@retry` 装饰并发任务

```python
@retry(...)
def fetch(code): ...

# 千万别这样：
with ThreadPoolExecutor(max_workers=5) as ex:
    for code in codes:
        ex.submit(fetch, code)
```

**坑**：tenacity 装饰器在并发线程中**会冲突地修改同一个 retry 状态对象**（早期版本是 module-level），高并发时出现 `RetryError` 串扰。

**正确做法**：把 retry 移进线程函数，或在每个 `fetch_one` 里手动实现退避，不装饰线程函数。

### 5.4 不要 `@retry` 装饰纯 CPU 函数

tenacity 内部用异常做重试判定。如果一个函数**不抛异常**就成功，retry 是空摆设；如果**每次抛不同异常**，retry 会陷入"老报错"循环。

### 5.5 重试预算：总时长不能超过用户的耐心

```python
# 危险组合：3 次重试 × 每次 5 分钟 = 15 分钟
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=60, max=300))

# 安全组合：3 次重试 × 每次 < 5 秒 = 总 < 15 秒
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=0.5, max=2))
```

## 六、工程建议

| 场景 | 推荐配置 |
|---|---|
| **服务端临时错**（5xx） | `retry=retry_if_exception_type(HTTPServerError)`，3 次，0.3s 起步 |
| **网络层错**（超时/连接失败） | `retry=retry_if_exception_type((NetworkError, ConnectionError))`，5 次，1s 起步 |
| **批量任务**（100+ 只） | `stop_after_attempt(3) \| stop_after_delay(60)` —— 总时长兜底 |
| **实时盯盘**（秒级） | `stop_after_attempt(2) \| stop_after_delay(5)` —— 不要久等 |
| **离线回测**（耗时无所谓） | `stop_after_attempt(5)` + `wait_exponential(multiplier=1, max=10)` —— 给服务端更宽容 |

**核心取舍**：
- 重试太多 → 浪费额度、拖慢任务
- 重试太少 → 一遇故障就崩

**经验值**：3 次重试 × 0.3s/0.6s/1.2s 退避 = 总 2.1 秒额外延迟，覆盖 90% 临时故障。

## 七、小结 + 下篇预告

**#05 一句话**：**网络抖动不可避免，但能用 tenacity + 异常分类把它变成可重试、可统计、可兜底的故障——而不是把整个任务扔掉**。

下篇（#06）我们解决一个相关但更隐蔽的问题：**进程崩了 / 电脑重启了 / 误关 SSH 导致任务中断，怎么从中断的位置续跑而不从头来**？我们会演示 checkpoint JSON + tqdm 进度条 + 重启自动续跑的完整工程链路。

## 免责声明

本文所有代码与数据仅用于量化工程方法演示，不构成任何投资建议，亦不构成收益承诺。投资有风险，决策需谨慎。

---

**下篇预告**：【Python量化系统工程化 #06】100只股票跑到一半进程崩了？进度条+JSON检查点+自动续跑不丢活

**参考代码**

代码与更多模板已在 GitHub 开放：`https://github.com/MaiRuiApi` 仓库 SDK 与配套文章（README 中获取 SDK 与接口文档）。


然后你周一早上到公司，跑一次全市场 5000 只的拉取——跑到第 3800 只崩了。

【Python量化系统工程化 #05】网络抖动一报错就全盘失败？用tenacity自动重试+指数退避

编程语言

后端

测试

本文解决批量股票数据拉取因5xx/超时中断的问题，通过tenacity异常分类重试策略，区分4xx不重试、5xx及网络错重试，配合指数退避，将成功率提升至91.5%，节省API额度，确保任务稳定完成。

代码解释

Python

GitHub

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【Python量化系统工程化 #05】网络抖动一报错就全盘失败？用tenacity自动重试+指数退避-腾讯云开发者社区-腾讯云

【Python量化系统工程化 #05】网络抖动一报错就全盘失败？用tenacity自动重试+指数退避

【Python量化系统工程化 #05】网络抖动一报错就全盘失败？用tenacity自动重试+指数退避

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐