用途:为 Litestar 应用配置响应缓存,涵盖路由级 cache 控制、应用级 ResponseCacheConfig、存储选择、TTL 策略与缓存键设计。
主要能力与用法: 路由级缓存模式支持 cache=True(沿用应用默认过期时间)、cache=<秒数> 指定 TTL,以及 CACHE_FOREVER(仅用于不可变或显式版本化资源)。应用级通过 ResponseCacheConfig 设置 default_expiration、存储选择与全局键/过滤行为。可为单个处理器设置 cache_key_builder=,按路径、查询参数、方法、租户、语言、认证范围、特性开关或请求头设计缓存键。cache_response_filter 用于在状态码确定后控制哪些响应写入缓存。多实例部署时需使用 Redis 等分布式存储共享缓存状态。
核心规则:只缓存可安全复用给等价请求的响应;可变数据优先使用短而明确的 TTL;cache=True 表示使用 ResponseCacheConfig.default_expiration,而非永久缓存;除非缓存键完整划分上下文,否则不得缓存个性化或权限范围响应;键构建器须确定性且跨进程稳定;Litestar 不为领域对象提供自动写侧失效,需自行设计。
适用场景与限制:适用于确定性、开销大且可安全重放的响应。避免缓存变更端点或非幂等工作流;注意 default_expiration=None 会使条目永久有效;多实例部署中不能假定共享缓存却仍用进程内存存储;CACHE_FOREVER 不应用于可变业务数据;cache_response_filter 不能替代良好的键设计。测试需覆盖命中、未命中与陈旧数据边界。更多细节参见官方文档 caching、ResponseCacheConfig 与 default_cache_key_builder 参考页。