Python functools.lru_cache 缓存可变参数为什么不可哈希

functools.lru_cache 报 TypeError: unhashable type: 'list' 时，问题通常不在函数返回值，而在缓存键。lru_cache 需要把位置参数和关键字参数组合成可哈希的键；列表、字典这类可变对象不能直接参与字典查找。实用修复是：先按业务语义把输入规范化为 tuple、排序后的 tuple 或 frozenset，再让缓存函数只接收不可变参数。

为什么 list 传进 lru_cache 会报不可哈希

lru_cache 的缓存本质上要根据参数定位已有结果。官方文档明确要求位置参数和关键字参数可哈希，因为缓存内部需要类似字典键的查找。list 可以原地追加、删除或修改，修改后哈希值无法保持稳定，所以 Python 不允许它作为字典键。

from functools import lru_cache

@lru_cache(maxsize=128)
def total(items):
    # 这里尚未执行到函数体，参数就要先参与缓存键构造
    return sum(items)

total([1, 2, 3])  # TypeError: unhashable type: 'list'

这也解释了一个容易误判的现象：即使函数体只做 sum，仍然会报错；错误发生在缓存查找之前，而不是发生在求和逻辑里。

按结果语义选择参数规范化方式

你给被`functools.lru_cache`装饰的函数传入列表、字典这类可变参数时报错不可哈希，本质是lru_cache内部会把所有入参转成哈希值作为缓存键，而Python里可变对象默认没有实现哈希方法，自然没法生成唯一哈希值作为缓存索引。

直接把所有列表转成元组并不总是正确。关键问题是：列表顺序是否会改变函数结果？如果会改变，保留原顺序；如果不会改变，应该把等价输入规范化为同一个键。

from functools import lru_cache

@lru_cache(maxsize=256)
def sum_in_order(items):
    # tuple 保留输入顺序，适合顺序会影响结果的函数
    return sum(items)

@lru_cache(maxsize=256)
def sum_as_set(items):
    # frozenset 明确表示只关心去重后的元素集合
    return sum(items)

print(sum_in_order(tuple([1, 2, 3])))
print(sum_as_set(frozenset([3, 2, 1, 1])))

frozenset 不是“更高级的 tuple”，它改变了数据语义：重复项会被去掉。因此订单、路径、SQL 参数列表等场景通常要保留顺序；权限集合、标签集合等场景才可能适合无序规范化。

让公开 API 接收 list，但缓存层只接收不可变键

如果调用方已经使用列表，可以保留外层函数的接口，把转换动作放在边界处。这样缓存函数不会修改调用方的对象，也不会把规范化规则散落在多个调用点。

from functools import lru_cache

def get_total(items):
    # 公开接口兼容 list，缓存层只接收稳定的 tuple
    return _get_total_cached(tuple(items))

@lru_cache(maxsize=128)
def _get_total_cached(items):
    # 缓存函数只依赖不可变参数，便于重复调用
    return sum(items)

values = [4, 5, 6]
print(get_total(values))
print(get_total(values))
print(_get_total_cached.cache_info())

不要在缓存函数内部把输入列表改成元组再计算，也不要让缓存函数返回一个会被调用方持续修改的共享列表。缓存保存的是结果引用；如果结果必须可变，优先返回新对象，或缓存不可变结果后在外层复制。

用 cache_info 判断修复是否真的生效

能运行不等于缓存有效。cache_info() 会返回 hits、misses、maxsize 和 currsize。先用同一组规范化参数重复调用，再观察 hits 增加；如果每次都是 miss，通常是键构造不稳定、调用时关键字顺序不同，或函数本身的结果不适合缓存。

• 参数中仍含有嵌套 list、dict 时，外层转 tuple 仍然不够，需要递归规范化。
• maxsize=None 会让缓存无限增长，长时间运行的服务要谨慎。
• 带副作用、依赖当前时间、随机数或每次都要生成独立可变对象的函数，不适合用 lru_cache。
• 缓存保留参数和返回值引用，必要时使用 cache_clear() 释放旧条目。

相关问题

关键字参数顺序不同会共用一个缓存项吗？

不要默认它们一定共用。官方文档提示，不同的关键字参数排列可能形成不同缓存项；需要统一调用约定，或在外层先构造规范化参数。

把 list 改成 tuple 后还会报错吗？

如果 tuple 内部仍嵌套 list 或 dict，整体仍不可哈希。应把每一层都转换成稳定的不可变结构。

怎么清空 lru_cache？

调用被装饰函数的 cache_clear()，例如 _get_total_cached.cache_clear()；清空后下一次调用会重新计算。