基于Python functools.lru_cache实现函数结果缓存与淘汰观测

本文由Gemini辅助撰写，示例代码已在Linux Python 3环境执行验证。

在后端任务处理与高频纯计算场景中，针对无副作用的确定性函数进行结果复用是降低计算开销的常用手段。Python标准库内置的 functools.lru_cache 装饰器提供了开箱即用的最近最少使用（Least Recently Used, LRU）内存缓存实现。通过合理设置容量上限与监控缓存运行指标，开发者可以在不引入外部中间件的前提下，有效抑制重复密集运算带来的 CPU 资源浪费。

核心机制与指标观测方法

functools.lru_cache 本质上是一个用 C 语言或高效 Python 字典结构封装的闭包包装器。它通过函数的入参（位置参数与关键字参数组合构成的键值）建立映射字典，并维护一个双向链表记录访问热度。

其核心功能和观测属性包括：

1. 命中与未命中计算：首次调用特定参数组合时执行原函数，产生未命中（misses + 1）并将返回值载入缓存；后续相同入参调用直接返回缓存引用，触发命中（hits + 1）。
2. 定长淘汰（Eviction）：当缓存元素数量达到 maxsize 且产生新的未命中记录时，装饰器会自动淘汰链表末尾最久未被访问（Least Recently Used）的条目。
3. 状态诊断与重置：修饰后的包装函数提供 cache_info() 方法，返回一个包含 hits、misses、maxsize 和 currsize 的命名元组；同时提供 cache_clear() 用于显式释放缓存与清空计数器。

验证代码与执行流程

以下代码演示了定长 LRU 缓存的初始化、重复命中、满载逐出检测以及显式清空过程：

import functools

call_count = 0


@functools.lru_cache(maxsize=3)
def compute_square(n: int) -> int:
    global call_count
    call_count += 1
    return n * n


# 首次调用触发未命中计算
assert compute_square(2) == 4
assert compute_square(3) == 9
assert compute_square(4) == 16
assert call_count == 3

# 重复调用触发缓存命中，计算次数不增加
assert compute_square(2) == 4
assert compute_square(3) == 9
assert call_count == 3

info = compute_square.cache_info()
assert info.hits == 2
assert info.misses == 3
assert info.maxsize == 3
assert info.currsize == 3

# 当前缓存访问顺序为 [4, 2, 3]，写入 5 时淘汰最久未访问的 4
assert compute_square(5) == 25
assert call_count == 4

info_after = compute_square.cache_info()
assert info_after.currsize == 3
assert info_after.misses == 4

# 验证 4 确已被逐出缓存，再次调用重新计算
assert compute_square(4) == 16
assert call_count == 5

# 重置缓存状态并验证计数清零
compute_square.cache_clear()
info_cleared = compute_square.cache_info()
assert info_cleared.hits == 0
assert info_cleared.misses == 0
assert info_cleared.currsize == 0

print("MATERIAL_OK")

运行流程剖析

在上述代码中：

1. 装饰器设定 maxsize=3。前三次分别计算 2、3、4 的平方，函数执行 3 次，misses 增至 3，currsize 达到满额 3。
2. 随后再次访问 2 和 3，未进入函数体内部，call_count 保持为 3，hits 增至 2。此时由于 2 和 3 被再次读取，缓存内部的 LRU 热度顺序更新，4 成为最久未被访问的项。
3. 当传入参数 5 时，触发新一轮计算（misses 变为 4），原先处于链表尾端的 4 被逐出，currsize 依然维持在 3。
4. 再次请求参数 4 时，由于该键已被逐出，系统必须重新执行函数计算平方，call_count 增至 5。
5. 调用 cache_clear() 后，所有缓存键值对被丢弃，currsize、hits 与 misses 全部归零。

核心约束与排查要点

在生产服务中使用 lru_cache 时，必须严格注意以下架构边界与潜在陷阱：

1. 入参可哈希约束（Hashable）：
   lru_cache 依赖参数构建哈希字典键。如果被修饰函数的参数包含 list、dict、set 等可变容器，运行时会立即抛出 TypeError: unhashable type。排查时应检查参数类型，若必须传递复合结构，应改用 tuple 或冻结数据结构（如 frozenset）。

2. 进程隔离与生命周期：
   缓存属于进程私有内存，无法跨多进程（如 Gunicorn / Celery 预分叉模型）共享。各 worker 进程拥有彼此隔离的缓存空间，因此多进程环境下指标统计相互独立，不能替代分布式缓存中间件。

3. 缺乏自动过期（TTL）机制：
   标准库的 lru_cache 仅依据容量和访问次序淘汰，不包含基于时间戳的生存期（TTL）。若函数依赖外部动态数据源，长久运行可能导致脏读，必须在外部数据变更时显式调用 .cache_clear() 重置。

4. 内存占用与对象常驻：
   缓存会强引用函数的入参和返回值，阻碍垃圾回收器回收大对象。若 maxsize=None，缓存将无限制膨胀，极易引发内存泄漏。

官方文档参考：
Python 3 官方文档（对应模块与章节）