Python lru_cache 缓存了旧配置怎么办：清理时机、缓存键与验证边界

线上配置中心刚把 timeout_seconds 从 3 改成 8，服务日志却连续几分钟打印旧值。代码里明明重新读取了配置文件，问题往往不是文件没写成功，而是 functools.lru_cache 还在把上一次函数调用的结果直接交回来。

只要缓存装饰器包住了“读取当前配置”的函数，外部配置发生变化后就必须明确触发失效；最稳妥的做法是把缓存边界收窄，并把刷新动作和新配置的校验绑定在一起。

配置文件已经变了，为什么函数还返回旧值

先看一个最小复现场景。假设服务把超时配置放在 settings.json，读取函数为了减少磁盘访问加了缓存：

import json
from functools import lru_cache
from pathlib import Path

SETTINGS_FILE = Path("settings.json")

@lru_cache(maxsize=1)
def load_settings():
    return json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))

print(load_settings()["timeout_seconds"])
SETTINGS_FILE.write_text('{"timeout_seconds": 8}', encoding="utf-8")
print(load_settings()["timeout_seconds"])
print(load_settings.cache_info())

两次输出可能都是 3，而 cache_info() 会显示第二次调用命中了缓存。装饰器只看到“参数还是空”，它不会主动检查 settings.json 的修改时间、文件内容或外部配置中心版本。

这里先别急着给文件加轮询逻辑。真正要理清的是：这个读取函数是否真的适合加缓存，以及谁负责通知它“旧结果已经不能复用了”。

先把缓存边界和刷新动作拆开

一个容易长期维护的写法，是让读取函数只负责“读取当前快照”，再提供一个明确的刷新入口。刷新入口先读新内容并做合法性校验，确认成功后再清理缓存：

import json
from functools import lru_cache
from pathlib import Path

SETTINGS_FILE = Path("settings.json")

def read_settings_file():
    data = json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
    timeout = data.get("timeout_seconds")
    if not isinstance(timeout, int) or not 1 

这段代码的关键不在“调用了一个清理方法”，而在于校验发生在清理之前。新文件损坏或数值越界时，read_settings_file() 会先抛出异常，旧缓存仍然保留，服务不会因为一次错误刷新直接丢掉可用配置。

按环境读取时，缓存键要表达真实边界

如果函数同时读取 dev、staging 和 prod 三套配置，就不要把环境名藏在全局变量里。把它作为入参，缓存才有机会区分不同环境的返回结果：

from functools import lru_cache

@lru_cache(maxsize=3)
def load_environment(name: str):
    path = CONFIG_ROOT / f"{name}.json"
    return read_and_validate(path)

load_environment("dev")
load_environment("prod")
print(load_environment.cache_info())

这时清理仍然有两种可选方案：配置批量发布时调用 load_environment.cache_clear()，一次清掉全部环境的缓存；只有某个环境变更时，可以把缓存改成显式字典，按环境名删除对应条目。不要为了“局部清理”强行依赖装饰器内部结构，lru_cache 没有公开的按键删除接口。

另一个要注意的边界是可变返回值。如果缓存返回一个字典，调用方修改字典内容会直接影响后续所有读取者。配置快照最好返回不可变结构，或者在边界处做一次拷贝：

from copy import deepcopy

def get_settings():
    return deepcopy(load_settings())

刷新后别只看一次返回值，检查命中状态和失败回退

验证缓存逻辑，至少要覆盖三种场景：首次读取是否未命中，重复读取是否命中，刷新后是否重新走读取逻辑。一个简单的测试用例就能把整条链路的行为验证清楚：

def test_refresh_replaces_cached_settings(tmp_path, monkeypatch):
    settings_path = tmp_path / "settings.json"
    settings_path.write_text('{"timeout_seconds": 3}', encoding="utf-8")
    monkeypatch.setattr("app.SETTINGS_FILE", settings_path)

    load_settings.cache_clear()
    assert load_settings()["timeout_seconds"] == 3
    first = load_settings.cache_info()
    assert first.misses == 1 and first.hits == 1

    settings_path.write_text('{"timeout_seconds": 8}', encoding="utf-8")
    refresh_settings()
    assert load_settings()["timeout_seconds"] == 8

    settings_path.write_text('{"timeout_seconds": 0}', encoding="utf-8")
    try:
        refresh_settings()
    except ValueError:
        pass
    assert load_settings()["timeout_seconds"] == 8

最后一条断言很重要：刷新失败后仍返回旧的合法值，说明旧快照没有被错误清空。生产日志还可以记录 cache_info() 的命中数、未命中数和当前配置版本，但不要把完整配置里的密钥、令牌或数据库密码写进日志。

几个很容易踩到的缓存误区

误区一：给函数加了 maxsize 就会自动感知文件变化

不会。maxsize 只限制缓存项数量，和文件、数据库或配置中心的版本没有任何关联。需要时间轮询时，应把轮询和刷新策略写在应用层，并为频率、失败和并发行为设定明确边界。

误区二：配置发布后直接 cache_clear，失败也没关系

如果清理后第一次读取新文件失败，服务可能从“继续使用旧配置”变成“没有可用配置”。更安全的顺序是先读取并校验，再替换快照；缓存只是加速层，不应该承担配置回退的逻辑。

误区三：在多线程刷新时把 cache_clear 当成事务操作

cache_clear() 不是配置发布事务。多个线程同时读取时，可能有人读到旧快照，有人触发新读取。若必须保证切换点完全一致，应在应用层用锁保护“校验、替换、发布版本”这一小段逻辑，并让调用方读取不可变快照。

相关问题：lru_cache 什么时候值得用

配置读取函数一定要加 lru_cache 吗？

不一定。配置文件本身很小、读取频率很低的场景，直接读取通常更简单。只有在读取成本明确、数据变化边界完全可管理时，缓存才值得加入。

怎么清掉 lru_cache？

通过被装饰函数公开的 cache_clear() 清空全部缓存项；用 cache_info() 查看命中、未命中和当前大小。

缓存函数可以返回字典吗？

可以，但不要把可变字典直接交给多个调用方共享。返回不可变对象或复制后的快照，更容易控制修改边界。

把配置刷新做成可复查的动作

lru_cache 适合缓存“相同参数对应的稳定结果”，不适合替代配置版本管理。落地时保留三个检查点：新配置先校验、刷新动作有明确入口、刷新后用命中统计和失败回退测试确认行为。这样遇到旧值问题时，排查重点会从“文件到底写没写进去”收敛到缓存边界、刷新时机和快照一致性。