必须显式设置@lru_cache的maxsize参数，避免内存无限增长；缓存值为强引用，慎缓存大型对象；参数须可哈希，不可变类型需手动转换；多线程下cache_clear()需加锁防护。
缓存未设置最大容量会持续吃光内存
Python 的 @lru_cache 默认不限制缓存条目数，只要参数组合不同，就一直往缓存字典里塞。一旦函数被高频调用、且参数变化多（比如传入时间戳、UUID、用户 ID），缓存会无限增长，最终触发 MemoryError 或拖慢整个进程。
实操建议：
- 务必显式指定
maxsize参数，例如@lru_cache(maxsize=128)；设为None表示无限制，等同于自埋地雷 - 若不确定合理大小，先用
@lru_cache(maxsize=1)测试——只缓存最后一次调用，观察性能是否可接受 - 对纯计算型函数（如数值递归），
maxsize=128通常够用；对带业务上下文的函数（如get_user_profile(user_id)），需按预期并发用户量反推上限
缓存对象本身持有引用导致无法 GC
@lru_cache 内部用弱引用管理键，但值是强引用。如果缓存的返回值是大型对象（如 pandas DataFrame、numpy array、长字符串或嵌套 dict），这些对象会一直驻留内存，即使外部已无其他引用。
常见错误现象：
立即学习“Python免费学习笔记（深入）”；
- 反复调用同一函数后，
psutil.Process().memory_info().rss持续上涨 -
gc.collect()后内存不下降，说明对象仍被缓存强持有
解决思路：
- 避免缓存大对象本身，改缓存其轻量标识（如文件路径、数据库主键、哈希值），再按需加载
- 用
functools.lru_cache时，确保被装饰函数返回值尽可能“小”；若必须返回大数据，考虑用functools.cache（Python 3.9+）配合手动清理逻辑 - 必要时调用
func.cache_clear()主动清空，比如在批处理循环末尾或内存告警时
可变参数（如 list/dict）直接导致缓存失效或崩溃
@lru_cache 要求所有参数可哈希，而 list、dict、set 默认不可哈希。若函数签名含这类参数，运行时会抛出 TypeError: unhashable type，而不是静默跳过缓存。
使用场景中容易忽略的点：
- 看似传的是 tuple，实则内部含 list（如
(1, [2, 3])）→ 依然报错 - 用
**kwargs接收参数，其中某个值是 dict → 缓存键构造失败 - 误以为
json.dumps(data, sort_keys=True)能当缓存键用，但没意识到这增加了序列化开销和哈希碰撞风险
稳妥做法：
- 强制转换：把
list改成tuple，dict改成frozenset(dict.items())，并在函数文档里注明“仅接受不可变参数” - 改用基于内容的缓存方案，如
joblib.Memory或自定义装饰器，对可变结构做稳定哈希（如hashlib.md5(pickle.dumps(obj)).hexdigest()），但要注意 pickle 安全性和性能代价
多线程下 cache_clear() 不是原子操作
多个线程同时调用 func.cache_clear() 可能引发竞态：一个线程刚清空缓存，另一个线程立刻命中旧缓存条目，或两个线程同时重建缓存造成重复计算。
这不是 bug，而是设计使然——lru_cache 本身线程安全（读写缓存键值是加锁的），但 cache_clear() 是“清空 + 重置计数器”，中间存在窗口期。
应对方式：
- 避免在热路径频繁调用
cache_clear()；优先用maxsize控制自然淘汰 - 若必须动态清空，用外部锁包裹：
with clear_lock: func.cache_clear() - 对高并发服务，考虑换用线程隔离缓存，如每个线程绑定独立的
functools.lru_cache(maxsize=...)实例（通过threading.local管理）
最危险的不是缓存没生效，而是它悄悄活着——占着内存、拦着 GC、还假装自己很高效。检查每个 @lru_cache 装饰器时，顺手敲两行：func.cache_info() 看命中率，sys.getsizeof(func.cache_parameters)（需自行估算）估体积，比等 OOM 更省事。
