Python functools.cache与lru_cache按场景选择的参数清单

这两个装饰器的关键差别只有一句话：functools.cache 是无界缓存，适合结果空间稳定、可以随进程一直保留的纯函数；functools.lru_cache 可以设置容量上限和类型区分，适合长时间运行、输入持续变化的服务。不要只看“缓存命中”就决定，先估算键的数量、结果大小和失效方式。

官方文档：https://docs.python.org/3/library/functools.html

参数集合可控、无需淘汰就选 @cache；结果会不断增加或必须限制内存时选 @lru_cache(maxsize=...)。两者都只适合可重复计算的纯函数，不会自动感知数据库或文件变化。

先按结果空间选择装饰器

cache 等价于轻量的 lru_cache(maxsize=None)，不会淘汰旧项，调用关系简单，递归计算和固定枚举通常更合适。lru_cache 保留最近使用的结果；当访问模式会变化，或者服务进程的输入数量没有明确上限时，用它给内存留一道保险。

把参数整理成可缓存的输入

缓存键来自位置参数和关键字参数，因此参数必须可哈希。列表、字典、集合不能直接作为参数；可以在调用边界转换成元组、只读映射或稳定字符串。还要留意关键字顺序：语义相同但写成不同顺序的关键字调用，可能形成不同缓存项。

from functools import lru_cache

@lru_cache(maxsize=256, typed=True)
def price_rule(region: str, levels: tuple[str, ...]) -> str:
    # levels 用元组保证可哈希；函数只根据参数计算结果
    return f"{region}:{','.join(levels)}"

print(price_rule("east", ("vip", "new")))
print(price_rule.cache_parameters())  # 查看容量和 typed 配置
print(price_rule.cache_info())        # 查看命中、未命中和当前条目数

示例中的 levels 如果原始数据来自列表，应在进入缓存函数前完成规范化。不要缓存会修改全局变量、依赖当前时间、随机数或外部实时状态的函数；同一个参数必须能稳定对应同一个结果。

有限容量与无界记忆化的实际写法

需要控制内存时，把 maxsize 当成容量策略，而不是越大越好。命中率低且 currsize 经常接近上限，说明输入变化快，应该减少缓存成本或调整键；命中率高但结果对象很大，则要结合进程内存预算决定容量。

from functools import cache, lru_cache

@cache
def fibonacci(n: int) -> int:
    # 递归会反复访问相同 n，稳定整数结果适合无界缓存
    return n if n  str:
    # 只保留最近 64 个标签，避免长进程持续积累键
    return f"item-{item_id}"

render_label(7)
print(render_label.cache_info())
render_label.cache_clear()  # 数据规则变化或发布切换时主动失效

上线前的参数与失效清单

这类缓存是进程内存，不是共享缓存，也不会跨重启保留。方法缓存还会把 self 纳入键，实例可能因此被缓存引用保持更久。多线程下底层缓存结构保持一致，但同一个昂贵函数在首次并发调用期间仍可能被计算多次，所以不要把装饰器当作分布式锁。

• 结果依赖数据库、配置文件或权限时，设计明确的 cache_clear() 时机。
• 参数包含大对象时，先改成稳定的小键，避免缓存长期持有输入和返回值。
• 返回可变对象时不要让调用方原地修改共享结果，必要时返回不可变结构或复制。
• 先观察 cache_info() 的 hits、misses、maxsize、currsize，再决定是否调整容量。

常见问题

cache 能设置最大容量吗？不能直接设置；需要容量上限时改用 lru_cache(maxsize=...)。

lru_cache(maxsize=None) 和 cache 怎么选？行为目标相同，固定无界记忆化可用 cache 表达意图；需要统一管理参数或保留后续扩展空间时可显式写 lru_cache(maxsize=None)。