Python functools.lru_cache的缓存失效策略

functools.lru_cache 是 Python 中一个强大且易于使用的缓存装饰器。它通过“最近最少使用”（Least Recently Used, LRU）算法，自动存储函数的调用结果。当使用相同的参数再次调用时，它会立即返回缓存的结果，避免重复计算。理解它的缓存失效（即缓存数据何时被清除）策略，是正确、高效使用它的关键。

理解核心概念：LRU 算法

在深入失效策略前，必须先明白 LRU 的工作原理。它的核心思想是：当缓存空间不足时，优先移除“最长时间未被使用”的数据。

可以将它想象成一个固定大小的书架（maxsize）。每当你取出一本书（调用函数）时，会把它放回书架最显眼的位置（标记为“最近使用”）。当书架满了，你需要放入一本新书时，你就会把放在最里面、最久没动过的那本书（“最近最少使用”）拿走，为新书腾出空间。

缓存失效的触发场景

lru_cache 的缓存数据并非永久有效，它会在以下几种情况下被清除或“失效”。

1. 缓存容量满时的自动淘汰

这是 LRU 算法最核心的失效机制。当你通过 maxsize 参数设定了缓存大小后，一旦缓存条目数量达到上限，任何新的函数调用如果其结果尚未缓存，就会触发一次淘汰。

from functools import lru_cache

# 设置缓存最多存储 2 个结果
@lru_cache(maxsize=2)
def heavy_computation(n):
    print(f"Computing for {n}...")
    return n * n

# 初始调用，填充缓存
heavy_computation(1)  # 缓存: {1: 1}
heavy_computation(2)  # 缓存: {1: 1, 2: 4}

# 此时缓存已满 (maxsize=2)
# 调用一个新参数，触发 LRU 淘汰
heavy_computation(3)  # 最久未使用的是 key=1，被淘汰
# 缓存变为: {2: 4, 3: 9}
# 再次调用被移除的 key，将重新计算
heavy_computation(1)  # 会重新执行函数

淘汰策略：程序会比较缓存中所有条目的“最近使用时间”，移除那个被访问时间最早的键值对，为新结果腾出空间。

2. 函数参数变化

这是最直观的一种“失效”。lru_cache 以函数的参数值作为缓存的键（Key）。如果参数值发生变化，它自然就去查找新的键，旧键对应的缓存结果虽然可能还在（如果没被 LRU 淘汰），但不会被用于本次调用。

@lru_cache()
def get_user_info(user_id):
    print(f"Fetching info for user {user_id}...")
    return {"id": user_id, "name": f"User {user_id}"}

# 不同的参数 (user_id) 是不同的缓存键
get_user_info(1001) # 缓存: {1001: ...}
get_user_info(1002) # 缓存: {1001: ..., 1002: ...} (缓存增加了新条目)

3. 参数类型严格匹配

lru_cache 默认对参数进行精确匹配，包括类型。1 (int) 和 1.0 (float) 会被视为不同的键。typed 参数可以控制这一点。

@lru_cache(typed=False) # 默认
def multiply(a, b):
    return a * b

multiply(2, 3) # 缓存键: (2, 3)
multiply(2.0, 3.0) # 缓存键: (2.0, 3.0)，与上面不同，会重新计算

主动控制缓存失效

除了自动失效，你通常需要手动干预缓存。

1. 一次性清空所有缓存

使用装饰器返回的函数对象上的 cache_clear() 方法，可以立即移除所有缓存条目。这在你需要强制刷新所有数据时非常有用（例如，底层数据库更新了）。

@lru_cache(maxsize=128)
def expensive_query(query):
    print(f"Executing query: {query}")
    return f"Result for {query}"

# 首次调用，会计算并缓存
expensive_query("SELECT * FROM users")
# 第二次调用，直接返回缓存
expensive_query("SELECT * FROM users")

# 手动清空整个缓存
expensive_query.cache_clear()

# 再次调用，会重新计算
expensive_query("SELECT * FROM users")

2. 查看缓存状态

cache_info() 方法返回一个命名元组，包含 hits（缓存命中次数）、misses（缓存未命中次数）、maxsize（最大容量）和 currsize（当前缓存条目数）。这有助于你监控缓存的使用效果。

print(expensive_query.cache_info())
# CacheInfo(hits=1, misses=2, maxsize=128, currsize=2)

3. 通过“绕过”实现部分失效

lru_cache 没有提供“清除指定键”的直接方法。但你可以通过一种技巧来“失效”特定键的缓存：改变函数的调用方式，使其参数形式发生变化。

一个常见的场景是函数依赖了外部状态（如当前时间），但你希望它有时缓存，有时不缓存。

import time
from functools import lru_cache

@lru_cache(maxsize=32)
def get_market_price(stock_symbol, _timestamp=None):
    # 实际中，_timestamp 会用于区分不同时间点的调用
    print(f"Fetching price for {stock_symbol} at {_timestamp}")
    # 模拟返回一个价格
    return 100.0 + hash(stock_symbol) % 10

# 正常缓存调用
price = get_market_price("AAPL", _timestamp=int(time.time()) // 60) # 按分钟缓存
price = get_market_price("AAPL", _timestamp=int(time.time()) // 60) # 命中缓存

# 当你需要强制刷新某只股票的价格时
# “失效”策略：给 _timestamp 传入一个全新的值，例如精确到秒
new_price = get_market_price("AAPL", _timestamp=int(time.time()))
# 这将导致一个未命中的调用，并创建一个新的缓存条目 (AAPL, 新时间戳)
# 旧的条目 (AAPL, 旧时间戳) 如果未被LRU淘汰，仍然存在但不会再被新的相同方式调用访问到

最佳实践与注意事项

1. 缓存纯函数：最适合缓存的是纯函数——输出仅由输入决定，没有副作用。如果函数依赖全局变量、文件系统、网络等外部状态，缓存可能导致数据过期。
2. 谨慎设置 maxsize：maxsize=None 会创建一个无界缓存，可能消耗大量内存。根据你的函数调用频率和参数空间合理设置，例如 maxsize=256 或 maxsize=1024。
3. 注意可变参数：缓存键必须是可哈希的。列表、字典等可变对象不能直接作为参数传入。你可以考虑将其转换为元组或字符串。
4. 内存与性能权衡：缓存会占用内存。对于计算成本极低或结果数据量巨大的函数，缓存可能得不偿失。使用 cache_info() 评估命中率，低命中率说明缓存效果不佳。

# 错误示范：缓存了非纯函数
@lru_cache()
def get_current_time(): # 结果每次调用都不同，缓存毫无意义
    return time.time()

# 错误示范：缓存包含副作用的函数
@lru_cache()
def save_to_file(data, filename):
    with open(filename, 'w') as f:
        f.write(data)
    return True # 缓存后，不会再次执行写入操作！

通过理解这些缓存失效的机制和策略，你就可以像操控一个精密的工具一样使用 lru_cache，在提升程序性能的同时，避免陷入由缓存带来的数据一致性陷阱。