Python functools.cache 与 lru_cache(maxsize=None) 的内存增长：命中率之外怎么做上限验收

接口刚上线时，函数缓存的命中率从 42% 涨到 96%，延迟也明显降了下来。两小时后，进程常驻内存却一直往上爬。问题不在缓存“没命中”，而在每一个新参数组合都可能成为一条永久记录。

functools.cache 和 lru_cache(maxsize=None) 都是无界缓存；如果参数空间持续增长，验收时必须同时看命中率、缓存条目数和进程内存，而不是只看响应时间。

先把“命中率很好”拆成三个指标

一个缓存是否健康，至少要同时回答三个问题：重复请求能不能命中，缓存里现在有多少项，以及这些项让进程多占了多少内存。cache_info() 能给出前两个证据，内存则可以用 tracemalloc 做一轮相对稳定的对比。

下面的示例故意把键设计成持续变化的字符串。它不是生产压测脚本，而是用来观察“misses 和 currsize 一起增长”这个边界。

from functools import cache

@cache
def normalize(key: str) -> str:
    return key.strip().lower()

for i in range(100_000):
    normalize(f"user-{i}")

print(normalize.cache_info())

如果结果接近 misses=100000、currsize=100000，说明每个键都被保留了。命中率并没有错，只是它没有告诉你这些缓存项是否还值得继续留在进程里。

两个写法的差别，关键在上限而不是名字

functools.cache 可以理解为 lru_cache(maxsize=None) 的轻量写法：没有淘汰上限，也不需要维护最近使用顺序。它适合参数集合天然有限、进程生命周期很短，或者你能明确控制清理时机的函数。

如果参数来自用户输入、租户编号、文件路径或外部查询条件，组合数通常不是固定集合。此时可以显式设置上限：

from functools import lru_cache

@lru_cache(maxsize=128)
def normalize(key: str) -> str:
    return key.strip().lower()

print(normalize.cache_info())
normalize.cache_clear()

maxsize=128 不是通用答案，它只是让内存风险变成可讨论、可压测的边界。设置过小会增加 misses，设置过大又会把问题推迟；要用真实参数分布和延迟目标一起决定。

用两条压测曲线找出增长拐点

测试不要只重复同一个键。准备两组输入：第一组在固定的 128 个键中循环，第二组每次生成新的键。前者用来确认命中收益，后者用来模拟用户标识或查询条件不断扩张的场景。

import tracemalloc

def measure(fn, keys):
    tracemalloc.start()
    for key in keys:
        fn(key)
    current, peak = tracemalloc.get_traced_memory()
    tracemalloc.stop()
    return current, peak, fn.cache_info()

fixed = [f"item-{i}" for i in range(128)] * 800
growing = [f"item-{i}" for i in range(100_000)]

print("fixed", measure(normalize, fixed))
normalize.cache_clear()
print("growing", measure(normalize, growing))

比较时关注趋势：固定键集合的 currsize 应该接近上限，新增键集合则会快速触顶并开始淘汰。若使用无界缓存，第二条曲线的条目数会随输入长度持续增加，这就是需要改设计的证据。

生产边界：什么时候该清理，什么时候不该缓存

缓存清理要跟业务生命周期绑定。配置热加载、测试隔离、租户切换这类场景，可以在变更完成后调用 cache_clear()，并在日志中记录清理前后的 currsize。如果函数结果依赖数据库内容，还要考虑数据更新后旧结果的有效期。

另一个边界是参数可控性。固定枚举、少量配置项适合函数缓存；搜索词、路径、时间范围和未归一化的字典对象容易形成高基数键。对这类输入，先做归一化、限长或改用带过期策略的专用缓存，往往比继续调高 maxsize 更稳。

常见问题

cache_info() 的 currsize 是不是当前缓存条数？

是，它表示当前缓存中保存的结果数量。对于无界缓存，它也可以作为增长告警的直接信号，但不能单独代表实际字节数。

设置 maxsize 后，命中率一定会下降吗？

不一定。只要工作集大部分时间落在上限内，命中率可能基本不变；只有热点集合频繁被淘汰时，misses 才会明显增加。

调用 cache_clear() 会影响正在执行的调用吗？

它清理的是已保存的缓存结果，不会替你取消已经开始的业务操作。需要把清理时机放在配置切换或任务边界，并用下一轮请求核对重新计算是否发生。

把验收标准写进压测记录

最后不要只留一句“命中率达到 96%”。至少记录固定键和增长键两组测试的 hits、misses、currsize、当前内存和峰值内存，并注明缓存是否在测试前清空。这样下一次改动 maxsize 时，才能知道是延迟收益换来了多少内存，而不是凭感觉保留一个无界缓存。