Python functools.cached_property 为什么多线程下会重复计算：锁边界与幂等改法

把昂贵的配置加载写成 functools.cached_property 后，单线程里通常只会看到一次计算；但服务启动时如果多个线程同时第一次访问同一个实例，Python 3.12 及以后允许 getter 重复运行。缓存最终仍会落到实例属性里，问题在于第一次写入之前没有“只准一个线程进入”的保证。

如果重复计算本身安全，就把 getter 做成幂等读取；如果初始化必须严格一次，就在 getter 内显式使用实例级锁，不能把一次性语义寄托给 cached_property。

线上症状：属性只读一次，初始化日志却出现两行

一个常见场景是把远端配置或本地证书加载封装成属性。测试只用一个线程访问时，日志很干净；压测启动阶段同时有多个工作线程读取 settings.snapshot，却发现加载函数出现两次甚至更多次。

这不等于缓存失效。更准确的时间线是：线程 A 和线程 B 都在缓存尚未写入时进入 getter，二者各自算出结果，最后一次写入的值成为实例上的普通属性。若计算只是读取文件并解析，通常只是浪费；若计算会创建目录、刷新令牌或登记资源，就可能造成重复副作用。

第一次访问到底检查了什么

cached_property 只在同名实例属性不存在时运行。可以把首次访问简化成下面这条链路：读取 实例字典，没有命中才调用 getter，计算完成后把结果写回实例属性。

from functools import cached_property

class Settings:
    @cached_property
    def snapshot(self):
        print("load snapshot")
        return {"region": "cn-shanghai"}

settings = Settings()
print(settings.__dict__)       # {}
print(settings.snapshot)       # 第一次计算
print(settings.__dict__)       # {'snapshot': {'region': 'cn-shanghai'}}
print(settings.snapshot)       # 普通属性读取

这里的 实例字典 只负责保存已经完成的结果，并不自动包住“检查为空到写入完成”的整个窗口；计算结果落回实例属性的动作，就是属性写回。两个线程若在这个窗口内同时通过检查，就会各自运行 getter。

Python 3.12 的时间线改变了什么

Python 官方文档说明，3.12 之前的实现带有一个未公开锁，能让同一属性的 getter 在多线程场景下只运行一次，但这把锁是“每个属性一把”，不同实例也会互相等待。3.12 起该锁被移除，换来的代价是：getter 可能在同一实例上运行多次。

因此不要用“最后拿到的值看起来正确”反推“初始化只发生了一次”。真正要核对的是 getter 的副作用和并发进入次数。

先判断：重复计算能不能接受

适合幂等读取的情况

配置文件解析、环境变量快照、纯计算索引等操作，只要输入在这段时间内不变，多算几次也不会改变外部状态。这类 getter 可以保持简单，并在测试里用计数器验证“结果一致”而不是苛求“调用一次”。

不能接受重复副作用的情况

创建共享目录、申请租约、写入外部表、刷新一次性凭证，都不适合直接放进未同步的 getter。即使当前版本测试没有复现，也不应把它当成并发契约。

需要严格一次时，在 getter 内加实例级 _lock

锁的目标是把“再次检查”和“真正初始化”放进同一个临界区。第一次检查在锁外可以减少无谓等待；拿到锁后必须再检查一次，因为等待期间可能已经由别的线程完成。

from functools import cached_property
from threading import Lock

class Client:
    def __init__(self, loader):
        self._loader = loader
        self._lock = Lock()

    @cached_property
    def connection(self):
        with self._lock:
            # cached_property 仍会在写入 connection 后短路后续访问
            return self._loader.open()

这个例子把 _lock 放在实例上，所以不同的 Client 不会互相阻塞。若 open() 可能回调 connection，应换成可重入锁或拆开调用链，避免自己等待自己；若初始化失败，异常不会写入缓存，下次访问仍会重试。

复查并发边界，不要把 GIL 当成初始化锁

可以用两个线程和一个带延迟的 loader 做回归：让 getter 在写入缓存前主动停顿，分别记录 loader 调用次数、返回值和外部副作用。没有 _lock 的实现重点观察“结果通常一致但调用次数可能大于 1”；加锁实现则应观察同一实例的调用次数为 1。

from concurrent.futures import ThreadPoolExecutor

client = Client(loader)
with ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(lambda _: client.connection, range(8)))

assert all(item is results[0] for item in results)

这个断言只核对返回对象是否一致，不能替代对 loader 调用次数的记录。生产验收还应看连接数、目录创建次数或外部登记记录，确认锁确实覆盖了副作用。

相关问题

cached_property 会永久缓存结果吗？

只要实例属性还在，后续读取就直接使用它；删除同名属性后，下次访问会重新计算。

为什么不直接用类级锁？

类级锁会让互不相关的实例串行初始化，吞吐和隔离性都变差；通常应把 _lock 放进每个实例。

property 加 lru_cache 能替代它吗？

可以作为另一种缓存模型，但缓存键和实例生命周期不同，应该结合参数、内存占用和失效方式单独评估。

最后的判断

cached_property 解决的是“计算后把结果变成实例属性”，不是通用的一次性初始化协议。读操作尽量保持幂等；涉及资源和外部状态时，用实例级 _lock 在 getter 内完成二次检查与初始化，再用调用次数和副作用记录做并发回归。