在 Python 的日常开发中，functools.lru_cache 是一个极为常用的装饰器，它通过缓存函数返回值来显著提升程序性能，尤其适用于计算密集型或重复调用的场景。然而，不少初学者甚至经验丰富的开发者，在尝试将列表（list）作为函数参数传递给被 lru_cache 装饰的函数时，会遭遇一个令人困惑的 TypeError：unhashable type: 'list'。这一错误看似简单，背后却涉及 Python 核心的哈希机制与可变对象的设计哲学。本文将从错误现象出发，深入剖析原因，并提供可行的解决方案。

错误重现：列表参数引发的“血案”

先看一段典型的出问题代码：

from functools import lru_cache

@lru_cache(maxsize=128)
def compute(data: list) -> int:
    return sum(data)

result = compute([1, 2, 3])  # 抛出 TypeError: unhashable type: 'list'

当调用 compute([1, 2, 3]) 时，Python 立即抛出 TypeError，指出列表是不可哈希类型。同样的问题也会出现在字典、集合等可变容器上。但若将参数改为元组 (1, 2, 3)，则一切正常。这是为什么呢？

根源探析：哈希与缓存的底层契约

lru_cache 的实现依赖于一个字典（dict）来存储调用参数与返回值的映射。字典的键必须是可哈希的（hashable），因为字典通过哈希表实现 O(1) 的查找性能。Python 中，一个对象可哈希的必要条件是：

  1. 实现了 __hash__() 方法。
  2. 实现了 __eq__() 方法，用于解决哈希冲突。
  3. 在其生命周期内，哈希值保持不变——这通常要求对象是不可变的。

列表是一种可变对象，它的内容可以随时被修改（如 list.append、list[0]=x 等）。为了保证哈希值的一致性，Python 的设计者明智地让列表类型不实现 __hash__() 方法（实际上 list.__hash__ 被设为 None）。因此，当 lru_cache 试图将列表参数作为字典的键时，Python 就会抛出 TypeError。

这一设计并非 Python 的缺陷，而是深思熟虑的权衡。假如列表是可哈希的，那么当列表内容在函数调用之间被意外修改时，缓存就会返回错误的结果，导致难以追踪的 bug。例如：

@lru_cache
def func(lst):
    return sum(lst)

data = [1, 2, 3]
result1 = func(data)  # 缓存 (1,2,3) -> 6
data.append(4)
result2 = func(data)  # 缓存 (1,2,3,4) -> 10，但旧缓存依然存在且错误

这种“诡谲”的行为显然不符合缓存缓存的预期——缓存应该保证相同的输入产生相同的输出，而可变对象无法提供这种保证。

多层影响：不只是 lru_cache

实际上，任何依赖哈希表的 Python 机制都会对列表参数报同样的错，例如将列表作为字典的键、放入集合，或使用 hash() 函数。lru_cache 只是其中最常见的一个触发场景。此外，functools.cache（Python 3.9 引入的等价装饰器）以及 functools.cached_property 等也遵循同样的规则。

解决方案：三种优雅的应对策略

面对列表参数无法被缓存的问题，开发者有以下几种常见的解决思路：

1. 将列表转换为元组

最直接的方案：在调用函数之前，将列表强制转换为不可变的元组。由于元组是不可哈希的——等等，元组可哈希吗？准确地说，元组只有当其所有元素都是可哈希时才是可哈希的。但对于包含字符串、数字等简单元素的元组，没有问题。因此可以改写：

@lru_cache
def compute(data: tuple) -> int:
    return sum(data)

result = compute(tuple([1, 2, 3]))  # 正常

如果函数逻辑需要接受列表，可以在函数内部将参数转换为元组，但装饰器参数必须是元组。这种方法的缺点是需要修改调用代码或函数签名，不太透明。

2. 使用 functools._make_key 自定义键（谨慎方案）

Python 内部提供了一个未公开的函数 functools._make_key，用于将参数转换为可哈希的键。但该函数是私有实现，不推荐在生产代码中直接使用，因为未来版本可能更改。更稳妥的做法是自行编写一个包装函数，将参数转为规范化形式。

3. 重写缓存逻辑：使用 dict 或 cachetools

如果需要更灵活的缓存策略（例如允许可变对象作为键），可以放弃 lru_cache，改用 cachetools 库中的 TTLCache 或 LRUCache，并在键生成函数中调用 id() 或转成不可变类型。但要注意，使用 id() 会导致缓存基于对象引用而非内容，容易造成内存泄漏或逻辑错误。

4. 利用 functools.singledispatch 避免问题

如果函数需要处理多种类型，可以考虑使用 functools.singledispatch 实现泛型函数，对列表参数单独做一个不缓存的分支。

最佳实践：编码习惯与工具辅助

最佳的应对策略是预防胜于治疗：在编写需要缓存的函数时，主动使用不可变参数。如果函数天然需要处理列表，可以在定义时声明参数为 tuple，并在调用处显式转换。许多开源项目（如 NumPy 的 @numpy.vectorize）也遵循这一设计原则。

此外，使用类型检查工具（如 mypy、Pylint）可以静态检测到此类错误。Pylint 的 unhashable-dict-key 警告虽针对字典，但对 lru_cache 同样有提示意义。

结语

functools.lru_cache 对列表参数抛出 TypeError，并非 Python 的疏忽，而是对“不可变对象才能参与哈希”这一基础规则的坚守。理解这一机制，不仅能帮助我们写出更健壮的缓存代码，更能加深对 Python 对象模型与哈希表设计背后权衡的认知。下次当你遇到相似的错误时，不妨静下心来，将列表替换为元组，或许就能立刻迎刃而解。毕竟，在 Python 的世界里，拥抱不可变性就是拥抱了安全与确定性。