Python functools.cached_property 删除属性后如何强制刷新缓存

如果一个昂贵的派生值用 functools.cached_property 保存，而实例里的原始配置已经改变，最直接的刷新方式不是重新给装饰器赋值，而是删除该实例上的同名属性：del obj.value。下一次读取 obj.value 时，Python 会再次执行被装饰的方法并把新结果写回实例。

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

cached_property 的缓存实际放在实例上

cached_property 和普通 property 的关键区别，是第一次读取后会把结果写入实例字典。后续读取优先拿到这个普通属性，因此原方法不会再次运行；删除同名属性后，描述符才重新获得机会。

最小刷新写法：删除后再读取

下面的例子把配置版本放进实例，并用一个计数器观察派生属性何时重新计算。第一次访问会生成结果，第二次访问直接复用；修改配置后删除缓存，再访问才会得到新值。

from functools import cached_property


class Report:
    def __init__(self, version: int) -> None:
        self.version = version
        self.build_count = 0

    @cached_property
    def summary(self) -> str:
        # 只在缓存不存在时执行，模拟一次昂贵的派生计算。
        self.build_count += 1
        return f"配置版本={self.version}"

    def refresh_summary(self) -> None:
        # 缓存可能尚未生成，避免用 del 直接触发 KeyError。
        self.__dict__.pop("summary", None)


report = Report(1)
print(report.summary)       # 第一次读取：配置版本=1
print(report.summary)       # 命中实例属性，不会再次计算
report.version = 2
report.refresh_summary()
print(report.summary)       # 删除后重新计算：配置版本=2
print(report.build_count)   # 2

如果你能确定属性已经计算过，也可以直接写 del report.summary。封装成 refresh_summary() 的好处是把“哪个派生值需要失效”写成显式业务动作，并用 pop(..., None) 兼容尚未访问过缓存的实例。

为什么重新赋值不能替代失效

实例属性允许普通写入，所以 report.summary = "手工值" 会把缓存替换成手工值，但不会让原来的计算方法重新执行。若目标是根据新配置重新生成结果，应先修改源数据，再删除同名缓存；不要把新的派生结果直接写回后又期待装饰器自动接管。

# 修改源数据后，使派生属性回到“按需计算”状态。
report.version = 3
del report.summary

# 下一次读取才会进入 cached_property 方法。
fresh_summary = report.summary
print(fresh_summary)

三个容易忽略的边界

实例必须有可变的 __dict__。官方文档说明，使用没有包含 __dict__ 的 __slots__ 类时，cached_property 无法写入缓存。需要节省实例空间时，可以改用 @property 叠加 @lru_cache，但那已经是另一种缓存模型。

删除只影响一个实例。del report.summary 不会清理同类其它对象，也不会删除类上的描述符。批量刷新时应遍历明确的对象集合，并把源配置更新和缓存失效放在同一个业务操作里。

并发访问可能重复计算。Python 3.12 起，cached_property 不再带有此前的未文档化属性级锁；多个线程同时首次读取时，getter 可能运行多次，最后一次结果写入缓存。若计算有副作用或必须只执行一次，应在 getter 内部或访问外部自行加锁。

不要把它和 lru_cache 的清理方式混用

cached_property 缓存的是某个实例的同名属性，失效动作是删除实例属性；lru_cache 缓存的是函数参数组合，失效动作通常是调用包装函数提供的 cache_clear()。下面的代码只用于对比两种对象，不建议为了同一个问题同时叠加两层缓存。

from functools import lru_cache


@lru_cache(maxsize=128)
def load_label(version: int) -> str:
    # 参数不变时复用结果；清理的是函数缓存，不是某个实例属性。
    return f"版本标签={version}"


print(load_label(1))
load_label.cache_clear()  # 清除所有参数组合的缓存。
print(load_label(1))

刷新动作的速查表

常见问题

删除 cached_property 后会删除类方法吗？

不会。删除的是实例上的缓存值，类上的描述符仍然存在，下一次读取会再次调用它。

可以直接给 cached_property 赋新值吗？

可以，实例允许写入同名属性；但这属于手工覆盖缓存，不会触发原方法重新计算。

为什么第一次读取时会报没有 __dict__？

通常是实例使用了不含 __dict__ 的 __slots__，或对象类型不提供可变实例字典。此时应重新评估缓存方式。

多线程下 del 再读取能保证只计算一次吗？

不能。删除与读取之间仍可能发生并发访问；需要单次计算语义时，应由业务代码提供合适的锁。

记住一条规则即可：cached_property 的刷新对象是实例属性，修改源数据后删除它，下一次读取自然会重新计算；只有当缓存对象变成函数参数、实例没有可变字典或并发要求更严格时，才需要换用其它设计。