外部数据源不稳定的标准修复模式：HTTP重试 + 缓存兜底

问题背景

一个量化交易系统的宏观周期分析模块依赖外部学术机构发布的 GPR Index（地缘政治风险指数）Excel 文件。该文件由第三方研究者维护，托管在个人学术网站上，通过固定的 HTTPS URL 提供下载。

系统每天凌晨自动执行宏观数据采集管道，其中一个脚本负责下载 GPR Index 并生成风险评分。某次采集周期中，该步骤开始频繁超时失败：

Traceback (most recent call last):
  ...
urllib.error.URLError: <urlopen error timed out>

GPR 字段在 Dashboard 上显示为问号，宏观数据看板的地缘风险维度失去数据。

根因分析

排查发现：

1. 外部数据源本身不稳定：学术机构的网站没有 SLA 保障，带宽有限，高峰期响应缓慢
2. **原始代码是”裸调用”**：单次 HTTP 请求，30 秒超时，失败即崩溃

# 原始代码：一次请求，失败就抛异常
def download_gpr_data():
    req = urllib.request.Request(GPR_URL, headers={"User-Agent": "Mozilla/5.0"})
    resp = urllib.request.urlopen(req, timeout=30)
    data = resp.read()
    df = pd.read_excel(io.BytesIO(data), sheet_name="Sheet1")
    return df

3. 脚本异常导致整条管道中断：main() 函数直接调用 download_gpr_data()，异常向上冒泡，脚本以非零状态退出，定时任务标记为失败

这不是个例。任何依赖外部数据源的系统——行情 API、汇率接口、新闻 RSS、学术数据集——都会遇到同样的问题：你无法控制第三方的可用性。

修复方案：两层防护

第一层：HTTP 重试

网络请求失败的原因多种多样：瞬时拥塞、DNS 抖动、服务器临时过载。这些问题往往重试一次就好了。关键参数：

• 最大重试次数：3 次（太多会拖慢整个管道，太少覆盖不了瞬时故障）
• 重试间隔：5 秒（给目标服务器喘息时间）

GPR_MAX_RETRIES = 3
GPR_RETRY_DELAY = 5  # seconds between retries

def download_gpr_data():
    last_error = None
    for attempt in range(1, GPR_MAX_RETRIES + 1):
        try:
            req = urllib.request.Request(GPR_URL, headers={"User-Agent": "Mozilla/5.0"})
            resp = urllib.request.urlopen(req, timeout=30)
            data = resp.read()
            df = pd.read_excel(io.BytesIO(data), sheet_name="Sheet1")

            # 下载成功 → 立即保存缓存
            with open(GPR_CACHE_PATH, "wb") as f:
                f.write(data)
            return df
        except Exception as e:
            last_error = e
            print(f"  ⚠️ 下载失败（第{attempt}/{GPR_MAX_RETRIES}次）: {e}", file=sys.stderr)
            if attempt < GPR_MAX_RETRIES:
                time.sleep(GPR_RETRY_DELAY)

    # 所有重试均失败，进入第二层...

第二层：本地缓存兜底

GPR Index 是月度更新的学术数据集，一周前的数据和今天的数据几乎相同。即使在线下载彻底失败，用上次的缓存数据也完全够用。

关键设计：每次下载成功时，自动保存一份缓存到本地。

GPR_CACHE_PATH = os.path.join(DATA_DIR, ".gpr_cache.xls")

def _load_gpr_from_cache():
    """从本地缓存加载 GPR 数据"""
    if not os.path.exists(GPR_CACHE_PATH):
        return None
    try:
        df = pd.read_excel(GPR_CACHE_PATH, sheet_name="Sheet1")
        print(f"  ⚠️ 使用缓存数据: {GPR_CACHE_PATH}", file=sys.stderr)
        return df
    except Exception as e:
        print(f"  ⚠️ 缓存读取失败: {e}", file=sys.stderr)
        return None

在 download_gpr_data() 中，当所有重试都失败后，自动 fallback 到缓存：

# 所有重试均失败，尝试缓存兜底
print("  🔄 在线下载全部失败，尝试本地缓存...", file=sys.stderr)
cached_df = _load_gpr_from_cache()
if cached_df is not None:
    return cached_df

raise RuntimeError(f"GPR Index 下载失败且无可用缓存: {last_error}")

入口函数的优雅退出

即使两层防护都失效（在线下载失败 + 缓存不可用），也不应该让脚本崩溃。main() 函数捕获异常，保留上次生成的 JSON，本次跳过：

def main():
    try:
        df = download_gpr_data()
    except RuntimeError as e:
        print(f"\n❌ {e}", file=sys.stderr)
        print("   geopolitical_risk.json 保留上次结果，本次跳过。", file=sys.stderr)
        return  # 优雅退出，不抛异常

这样定时任务的状态始终是”成功”（exit code 0），不会触发告警系统的误报。

完整的数据流

在线下载（3次重试，间隔5s）
    ├── 成功 → 保存缓存 → 返回数据 ✓
    │
    └── 全部失败
            ↓
        加载本地缓存
            ├── 缓存存在 → 返回缓存数据 ✓（轻微过期，但可用）
            │
            └── 缓存不存在
                    ↓
                优雅退出，保留上次 JSON（不崩溃）

为什么不直接用 requests 库的 retry？

Python 生态有 requests + urllib3 内置的 Retry 适配器，或 tenacity 这样的重试库。为什么这里选择手写循环？

1. 依赖最小化：该脚本是宏观数据管道的一部分，运行在受限的 venv 环境中。手写 20 行代码 vs 引入一个新依赖，前者更简单
2. 缓存逻辑无法库化：重试可以用库，但”成功时缓存 + 失败时 fallback”是业务逻辑，手写更清晰
3. 可读性：整个 download_gpr_data() 函数从上到下读下来就是一个完整的故事——尝试→重试→缓存→退出，无需理解任何框架的配置语法

适用场景

这个”重试 + 缓存”模式适用于所有满足以下条件的场景：

条件	说明
数据非实时	缓存的数据可以”旧一点”（分钟级、小时级甚至天级延迟可接受）
外部不可控	数据源由第三方维护，没有 SLA
降级可接受	拿不到新数据时，用旧数据比”无数据”或”报错”更好

典型场景：

• 学术/官方数据集：央行汇率、统计局 CPI、学术机构研究数据
• 第三方 API：天气、汇率、新闻聚合
• RSS / 爬虫目标：博客、公告页

小结

外部数据源不稳定是系统工程中的常见问题。与其寄希望于第三方永远可用，不如在调用层做好防护。本文展示的两层防护模式——HTTP 重试 + 本地缓存兜底——是一个轻量、零依赖、可复用的标准修复方案。

核心原则只有一句：永远假设外部调用会失败，为失败设计 fallback。