Python functools.lru_cache 的并发语义：缓存命中与重复计算边界

很多团队第一次给 Python 函数加上 @functools.lru_cache 时，会把“缓存是线程安全的”理解成“同一个参数只会计算一次”。这两个判断不是一回事：缓存内部的数据结构可以在并发更新时保持一致，但冷键的底层函数仍可能被多个线程同时执行。

先把“线程安全”拆成两个问题

官方文档对 lru_cache 的表述很精确：缓存是线程安全的，意味着底层数据结构在并发更新时保持一致；但如果另一个线程在第一次调用完成并写入缓存前发起同样的调用，被包装的函数可能执行不止一次。前者是容器一致性，后者是业务计算是否去重，不能混为一谈。

可以把一次请求分成三个真实节点：request A 进入 lru_cache，因为没有结果发生 cache miss，随后调用 slow_lookup。如果 request B 在结果写回前到达，它也可能看到同一个冷键并执行 slow_lookup。这条路径不会因为缓存结构安全就自动合并。

冷键并发时为什么会重复计算

from functools import lru_cache
from time import sleep

@lru_cache(maxsize=128)
def slow_lookup(user_id: int) -> str:
    sleep(0.2)
    return f"profile-{user_id}"

假设 request A 和 request B 几乎同时调用 slow_lookup(7)。在两次调用都尚未完成时，缓存里还没有参数 7 对应的结果，于是两个线程都可能执行函数体。随后某个结果先完成并进入缓存，后续请求才会稳定命中。

这通常不是数据损坏：如果函数是纯函数，两次结果相同，代价主要是重复的 CPU、I/O、连接或下游限流。但如果函数有副作用，例如扣库存、发送通知或写审计记录，就不应直接套缓存；官方文档也明确提醒缓存不适合带副作用的函数。

命中路径和未命中路径要分别验收

测试时不要只断言返回值相等，还要观察调用次数和缓存统计。连续调用同一个参数后，第二次通常应走 cache hit；并发冷启动则应允许底层函数出现重复执行。cache_info 能返回命中数、未命中数、最大容量和当前条目数，它适合用来确认测试是否真的覆盖了两条路径。

from functools import lru_cache

calls = 0

@lru_cache(maxsize=2)
def get_price(sku: str) -> int:
    global calls
    calls += 1
    return 199

get_price("A-17")
get_price("A-17")
print(get_price.cache_info())
print(calls)

这段验收关注的是关系而不是固定数字：相同参数的串行第二次调用应提高命中数，函数体调用次数不应随着每次读取线性增加。并发测试则要记录开始时间、结束时间和实际调用次数，不要把“命中数等于请求数”当作冷键阶段的硬性预期。

参数写法会改变缓存键

被缓存函数的参数必须可哈希，否则无法作为字典键保存。除此之外，位置参数与关键字参数的不同写法可能被视为不同调用，例如 f(a=1, b=2) 与 f(b=2, a=1) 可能占用两个缓存条目。若业务希望命中稳定，就在进入缓存函数前统一参数形状，不要让调用方随意混用位置和关键字写法。

from functools import lru_cache

@lru_cache(maxsize=16)
def render_page(page: int, size: int = 20) -> str:
    return f"page={page}&size={size}"

render_page(1, 20)
render_page(page=1, size=20)
print(render_page.cache_info())

这里的重点不是猜测某个版本的内部键构造，而是把调用约定固定下来并在目标 Python 版本实测。列表、字典等可变对象不能直接作为参数；可以先在边界层转换成稳定的元组或字符串，但转换规则必须成为接口契约的一部分。

何时需要在缓存外增加单飞协调

如果重复计算会造成明显的下游压力，业务可以在缓存外增加“同一冷键只允许一个任务执行”的协调机制，例如按规范化键维护 future 或锁，并让其他请求等待同一个结果。这个机制解决的是单飞语义，不是 lru_cache 自带能力；它还要处理异常传播、超时、取消和协调对象清理。

若函数只是昂贵但幂等的计算，允许少量冷启动重复往往更简单。若函数是外部写操作，则先移除缓存设计，改用幂等键、事务或显式去重。判断标准应是重复执行的业务后果，而不是看到“线程安全”三个字就默认存在全局互斥。

容量、失效和长期运行进程

maxsize 决定最多保留多少个最近使用的结果；长期运行的服务应根据真实键分布观察淘汰，而不是盲目设成无限缓存。配置、权限或价格发生变化时，要明确调用 cache_clear 的时机，并把失效事件纳入监控。缓存还会持有参数和返回值的引用，返回大型对象时要评估内存生命周期。

常见问题

lru_cache 能保证同一个冷键只执行一次吗？

不能。它保证缓存结构在并发访问下保持一致，但第一次结果写入前，底层函数可能被多个线程重复调用。

带副作用的函数可以直接加 lru_cache 吗？

不建议。缓存会跳过后续执行，冷键阶段也可能重复执行；写操作应使用幂等键、事务或显式去重。

如何判断缓存是否真的命中？

用稳定的参数做串行调用，再结合 cache_info 的命中与未命中变化观察；不要只根据返回值相等下结论。

一份可复用的验收清单

1. 先确认函数是幂等、可重复计算的纯函数，排除写操作和需要每次创建新可变对象的函数。
2. 用同一参数做串行两次调用，检查第二次的 cache hit 和 cache_info 变化。
3. 用两个并发请求模拟冷键，记录 request A、request B 与 slow_lookup 的时序，接受结果写回前可能发生重复计算。
4. 统一位置参数与关键字参数的入口形式，并为不可哈希输入设计明确的规范化方案。
5. 模拟配置变化后调用 cache_clear，确认下一次读取重新形成 cache miss。

functools.lru_cache 的边界可以浓缩成一句话：它让缓存容器在并发下保持可用，却不承诺冷键计算的全局单飞。把命中路径、重复计算、参数键和失效行为分别测出来，才能决定是否需要更强的业务协调层。