Python weakref.WeakValueDictionary 怎样避免缓存持有对象引用

我在给对象做内存缓存时遇到过一个很容易被忽略的现象：缓存命中率看起来不错，但对象数量一直不降。原因通常不是垃圾回收失灵，而是缓存字典本身还保留着对象的强引用。

如果缓存只需要“对象还活着时帮我复用一次”，而不应该因为缓存的存在阻止对象回收，可以使用 weakref.WeakValueDictionary。它把值保存为弱引用：业务代码不再持有对象时，缓存项也会随对象消失。这个语义适合对象复用缓存，但不等同于带容量、带过期时间的通用缓存。

普通字典为什么会让缓存对象一直活着

先把缓存和业务对象的关系画清楚。下面的普通字典把对象直接存为值，只要字典还在，字典就会持有这个对象的强引用。

class Document:
    # 文档对象包含解析后的内容，实例可能比较大
    def __init__(self, name: str, text: str):
        self.name = name
        self.text = text


strong_cache = {}
document = Document("guide.md", "...大量文本...")
strong_cache[document.name] = document

# 即使业务变量删除，strong_cache 仍然持有对象
del document

这里删除的只是变量名，不是对象本身。只要 strong_cache["guide.md"] 还指向实例，垃圾回收器就不能把这个实例当成“没有强引用”的对象。普通字典不是错误，它适合希望缓存明确保留对象的场景；问题在于不能把它误认为弱缓存。

用 WeakValueDictionary 保存不会强行保活的对象

WeakValueDictionary 的接口接近字典，最小改动就是把容器换掉。值对象需要是支持弱引用的自定义实例，键仍然可以是字符串或其他普通键。

import weakref


class Document:
    # 普通 Python 类实例默认支持弱引用
    def __init__(self, name: str, text: str):
        self.name = name
        self.text = text


document_cache = weakref.WeakValueDictionary[str, Document]()

def load_document(name: str) -> Document:
    # 缓存没有对象时才构造；调用方拿到的局部变量是强引用
    document = document_cache.get(name)
    if document is None:
        document = Document(name, f"content of {name}")
        document_cache[name] = document
    return document


first = load_document("guide.md")
second = load_document("guide.md")
print(first is second)  # 业务引用仍在，通常得到 True

在 first 和 second 仍然存在时，两个变量都是对象的强引用，因此第二次查找可以复用同一个实例。把对象放进弱值字典不会马上把它清掉；弱引用只是“不阻止回收”，不是“主动回收”。

缓存命中和对象回收是两种不同结果

弱值缓存最容易让人误解的地方是：它的失效不是由 TTL 定时器决定，而是由对象是否还存在强引用决定。业务代码释放最后一个强引用后，对应条目可能在后续垃圾回收过程中消失。

import gc
import weakref


class ImageModel:
    # 这个对象代表解码后的模型或图片，不应被缓存单独保活
    def __init__(self, key: str):
        self.key = key


cache = weakref.WeakValueDictionary[str, ImageModel]()
model = ImageModel("avatar:42")
cache[model.key] = model
print("命中:", cache.get("avatar:42") is model)

# 删除业务侧最后一个强引用；缓存不再承担保活职责
del model
gc.collect()
print("仍在缓存:", "avatar:42" in cache)

第二个输出不能被当成稳定的业务承诺：不同实现和回收时机下，条目消失的时间可能不同。工程代码应该把“缓存拿不到”当作正常分支，重新加载对象，而不是依赖某一次立即回收。

哪些对象能放进去，哪些对象会报 TypeError

弱值字典不是任何对象都能接收。普通 Python 类实例通常支持弱引用，但一些内置类型不能直接作为弱引用目标。

import weakref


class SlotDocument:
    # slots 类要显式保留 __weakref__ 槽位
    __slots__ = ("name", "__weakref__")

    def __init__(self, name: str):
        self.name = name


cache = weakref.WeakValueDictionary[str, SlotDocument]()
item = SlotDocument("guide.md")
cache[item.name] = item

# 没有 __weakref__ 时，这一步会抛出 TypeError
print(cache[item.name].name)

如果对象不能弱引用，错误应当促使我们重新检查缓存语义，而不是为了“让代码跑起来”把对象包装成一层又一层的容器。包装后仍要确认包装对象的生命周期确实符合需求。

把弱值缓存放进工程时的四个边界

1. 把它当作可丢失缓存。每次读取都要接受缺失并具备重建或回源路径。
2. 不要把弱值缓存当作容量控制。它没有按大小淘汰、按时间过期或命中率保证；需要这些能力时要使用明确的缓存策略。
3. 避免在缓存值内部反向持有关键强引用。如果其他全局结构仍然强引用同一对象，弱值字典自然不会让它变得可回收。
4. 先确认对象类型。自定义类、slots、扩展类型的弱引用支持不同，不能只看字典接口是否相似。

我更愿意把 WeakValueDictionary 用在“对象已经由业务拥有，缓存只是为了减少重复查找或重复构造”的位置。例如对象注册表、解析结果的临时索引、由其他组件负责生命周期的实例映射。对于必须稳定命中、需要控制内存上限或要求数据始终存在的缓存，应该选有明确生命周期的方案。

相关问题

WeakValueDictionary 会按时间自动过期吗？

不会。它关注的是对象是否仍有其他强引用，不提供 TTL 语义。需要按时间过期时，应增加独立的过期策略或使用支持 TTL 的缓存组件。

缓存里还有键，为什么取值却是空的？

弱值对象可能已经被回收，条目会在清理过程中消失。读取时使用 get() 并处理 None，不要把键存在当成值一定存在。

把 list 放入 WeakValueDictionary 为什么失败？

内置 list 不能直接被弱引用。可以定义一个支持弱引用的自定义包装类，但要先确认包装层不会改变实际生命周期需求。

普通 dict 和 WeakValueDictionary 应该怎么选？

需要缓存负责保留对象时选普通字典或带策略的缓存；对象由业务侧负责拥有、缓存只做可丢失复用时，才考虑 WeakValueDictionary。