Python functools.lru_cache自动缓存应用小结

我们来对 Python 中 functools.lru_cache的自动缓存应用做一个清晰的小结。

functools.lru_cache是 Python 内置的一个非常强大的装饰器，用于为函数添加最近最少使用 (Least Recently Used, LRU) 缓存。它能自动缓存函数的返回值，当再次以相同的参数调用该函数时，直接从缓存中返回结果，从而避免重复计算，极大提升性能。

一、核心作用与适用场景

1. 核心作用

性能提升：将函数的时间复杂度从 O(n) 降低到 O(1)（对于缓存命中），尤其适用于计算密集型、递归或 I/O 等待型函数。
自动管理：自动处理缓存的存储、检索和淘汰，无需手动编写缓存逻辑。
线程安全：在 CPython 中，对于 CPU 密集型任务，它是线程安全的。

2. 适用场景

纯函数：函数的输出只依赖于输入参数，且没有副作用（如修改全局变量、进行 I/O 操作）。相同的参数必须总是返回相同的结果。
计算成本高：函数执行时间较长，但参数组合有限，重复使用率高。
递归函数：经典用例，如斐波那契数列、树/图的遍历。
数据库或API查询：对于相同的查询条件，在短时间内返回相同的结果。（注意：对于可能变化的数据，需要谨慎使用或设置过期时间）。

不适用场景

函数有副作用：如打印、写文件、修改状态等。缓存会导致副作用不发生。
参数不可哈希：如列表、字典等可变类型。需要使用不可变类型（如元组、frozenset）或自定义 __hash__方法。
结果集巨大：缓存本身会占用内存，如果返回值非常大且种类繁多，可能导致内存耗尽。
数据实时性要求极高：缓存的数据可能不是最新的。

二、基本使用方法

1. 引入与装饰

import functools

@functools.lru_cache(maxsize=None)
def my_function(args):
    # ... 耗时计算 ...
    return result

2. 关键参数

maxsize：指定缓存的最大条目数。
- maxsize=None：缓存无限增长（慎用，有内存溢出风险）。
- maxsize=N：一个正整数，缓存最多 N 个结果。当缓存满时，会淘汰最久未使用的条目。
typed：默认为 False。如果设为 True，不同类型的参数将分别缓存。例如，f(3)和 f(3.0)会被视为不同调用并被分别缓存。

三、应用示例

示例 1：加速斐波那契数列计算

没有缓存的递归斐波那契数列是指数级复杂度的，计算 fib(30)都非常慢。

import functools

@functools.lru_cache(maxsize=None) # 无限缓存
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 第一次计算会比较慢
print(fibonacci(35)) # 9227465
# 第二次计算瞬间完成，因为所有中间结果都被缓存了
print(fibonacci(35)) # 9227465 (从缓存读取)

示例 2：缓存带参数的数据库查询模拟

假设我们有一个模拟的、耗时的数据库查询函数。

import functools
import time

# 模拟一个耗时的数据库查询
def mock_database_query(query, delay_time=0.5):
    time.sleep(delay_time) # 模拟I/O延迟
    return f"Result for query: '{query}'"

# 使用 lru_cache 包装
@functools.lru_cache(maxsize=128)
def cached_query(query):
    return mock_database_query(query)

# 第一次调用，耗时 ~0.5秒
start = time.time()
print(cached_query("SELECT * FROM users"))
end = time.time()
print(f"First call took: {end - start:.2f}s")

# 第二次用相同参数调用，耗时 ~0.0秒
start = time.time()
print(cached_query("SELECT * FROM users"))
end = time.time()
print(f"Second call took: {end - start:.2f}s")

四、高级管理与监控

lru_cache装饰器将一个可调用对象包装后，会返回一个带有额外方法的函数对象。我们可以利用这些方法来管理和监控缓存。

.cache_info()：返回一个命名元组，显示缓存的统计信息。
- hits：缓存命中的次数。
- misses：缓存未命中的次数（即函数实际执行的次数）。
- maxsize：缓存的最大容量。
- currsize：当前缓存中的条目数。
.cache_clear()：清空缓存。

@functools.lru_cache(maxsize=2) # 故意设置一个小的maxsize用于演示
def add(a, b):
    print(f"Calculating {a} + {b}")
    return a + b

print(add(1, 2)) # 计算， misses=1
print(add(1, 2)) # 缓存命中， hits=1
print(add(2, 3)) # 计算， misses=2
print(add(3, 4)) # 计算， misses=3。此时缓存已满 (maxsize=2)，会淘汰最久未使用的 (1,2)
print(add(1, 2)) # 再次计算！因为 (1,2) 已被淘汰， misses=4

# 查看统计信息
print(add.cache_info())
# 输出：CacheInfo(hits=1, misses=4, maxsize=2, currsize=2)

# 清空缓存
add.cache_clear()
print(add.cache_info())
# 输出：CacheInfo(hits=0, misses=0, maxsize=2, currsize=0)

五、注意事项与陷阱

参数必须可哈希：这是最常见的错误。如果传递列表或字典，会引发 TypeError。 @functools.lru_cache() def func(lst): return sum(lst) func([1, 2, 3]) # TypeError: unhashable type: 'list'解决方案：转换为元组 func(tuple(my_list))或使用其他可哈希的结构。
内存使用：使用 maxsize=None时要极其小心，对于被频繁调用且参数组合无限的函数，会导致内存无限增长直至崩溃。
隐藏的性能问题：过度使用缓存可能掩盖代码中的性能瓶颈，或者导致你认为某个计算很快，但实际上它只是在使用缓存。
不适用于所有函数：如前所述，对于有副作用或依赖外部状态的函数的函数，使用缓存会导致逻辑错误。

总结

特性	描述	建议
用途	缓存纯函数的返回值，提升性能。	优先考虑用于计算密集型、递归函数。
核心参数	`maxsize`控制缓存大小，`None`为无限。	根据场景设置合理的 `maxsize`，避免内存问题。
管理工具	`.cache_info()`监控，`.cache_clear()`清空。	利用这些方法进行调试和性能分析。
首要原则	被装饰的函数必须是纯函数。	确保输出只依赖于输入，且无副作用。
常见陷阱	参数为不可哈希类型。	使用元组等不可变类型作为参数。