企业官网建设流程全解析

NestJS RedisX的SWR与stale-if-error：让接口在缓存过期时依然丝滑

【免费下载链接】nestjs-redisxModular Redis toolkit for NestJS with plugin architecture - caching, locks, rate limiting, circuit breaker, pub/sub, idempotency, streams, metrics & tracing项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-redisx

缓存过期的那一刻，往往是接口最“卡顿”的时刻：大量请求同时打到数据库，响应变慢、超时、甚至雪崩。NestJS RedisX作为 NestJS 生态的模块化 Redis 工具包，内置了SWR（Stale-While-Revalidate，过期重建）与stale-if-error（错误时提供过期数据）两大缓存策略，让接口在缓存过期、甚至后端异常时依然能丝滑响应。本文将用最通俗的方式，带你一次看懂这两种缓存策略的原理、配置与最佳实践。

缓存过期为何让接口突然"卡顿"

传统的缓存流程很简单：缓存有数据就直接返回，没有数据就查数据库再写回。问题出在缓存刚好过期的瞬间——

• 数据库压力瞬间飙升：高并发下所有请求同时回源；
• 响应时间大幅波动：缓存命中时 1ms，回源时可能 1000ms；
• 极端情况引发缓存雪崩：大量 key 同时过期，数据库直接被压垮。

SWR 和 stale-if-error 正是针对这两个痛点设计的：一个解决“数据旧一点没关系”的场景，一个解决“数据源挂了怎么办”的场景。

SWR 是什么：过期后先返回旧数据，后台悄悄刷新

SWR 的全称是 Stale-While-Revalidate，直译就是“过期时先返回旧数据，同时后台重新验证”。它把缓存的生命周期从一段延长为三段：

在过期窗口内，用户几乎无感知：响应照常返回，NestJS RedisX 的 SWR 管理器会通过setImmediate()在后台非阻塞地执行刷新任务，同一 key 同时只允许一个刷新任务（自动去重），刷新成功后新旧数据无缝衔接。

核心实现位于 swr-manager.service.ts，其中createSwrEntry()负责计算staleAt与expiresAt时间戳，scheduleRevalidation()负责调度后台刷新任务。

开启 SWR 的最快配置方法

在 NestJS RedisX 中，只需在注册CachePlugin时开启一个开关，所有使用getOrSet()或@Cached的方法即可默认走 SWR 流程：

new CachePlugin({ swr: { enabled: true, // 全局开启 SWR defaultStaleTime: 60, // 默认过期窗口 60 秒 }, })

也可以只针对单个调用开启，灵活度很高，参考 swr-get-or-set.usage.ts：

return this.cache.getOrSet<User>( `user:${id}`, () => this.repository.findOne(id), { ttl: 300, // 新鲜 5 分钟 swr: { enabled: true, staleTime: 300 }, // 过期窗口再延长 5 分钟 } );

用装饰器同样生效，@Cached内部基于getOrSet()实现，SWR 能力完全保留：

@Cached({ key: 'user:{0}', ttl: 300, swr: { enabled: true, staleTime: 300 } }) async getUser(id: string): Promise<User> { ... }

stale-if-error：后端挂了，缓存还能"救场"

如果说 SWR 解决的是新鲜度问题，那么 stale-if-error 解决的就是可用性问题：当数据加载器（比如数据库查询）抛错失败时，是否允许返回最后一次成功缓存的值？

它和 SWR 是相互独立的开关，拥有独立的窗口。SWR 窗口结束后，值还会被保留一段时间（keepUntil = expiresAt + staleIfError.window），这段期间它对正常请求不可见——只有加载器抛错时，缓存才会兜底返回这个旧值。

一个完整的配置示例见 stale-if-error.setup.ts：

new CachePlugin({ staleIfError: { enabled: true, defaultWindow: 7 * 24 * 3600, // 后端持续故障时，最多兜底 7 天 shouldServe: (error) => !/404|410/.test(error.message), // 404 类错误不兜底 }, })

三个关键设计值得注意：

• 惰性、请求驱动：没有后台定时器，下次请求触发时才会重试加载器；
• window 必须是有限数字：避免 Redis 内存无限增长，非法配置会在启动时直接报错；
• 可观测：每次兜底返回都会输出 warn 日志并累加redisx_cache_stale_if_error_served_total指标，故障不会藏在“绿色缓存”背后。

SWR 与 stale-if-error 的时间线配合

把两个窗口放在同一条时间线上，关系一目了然：

staleAt = now + ttl # 新鲜 -> 过期（SWR 开始后台刷新） expiresAt = staleAt + staleTime # SWR 窗口结束 keepUntil = expiresAt + staleIfError.window # 仅用于错误兜底

• staleAt之前：直接返回新鲜数据；
• staleAt到expiresAt：返回旧数据 + 后台刷新（SWR 生效）；
• expiresAt到keepUntil：正常请求照常加载新数据，只有加载失败才兜底返回旧值（stale-if-error 生效）。

两者可以组合使用，并且与缓存插件的**请求合并（stampede 防护）**天然兼容：合并保护负责新鲜加载的并发去重，SWR 负责后台刷新，stale-if-error 负责故障兜底，三层各司其职。

最佳实践：什么场景该用、什么场景别用

推荐使用的场景：

千万别用的场景：

• 安全敏感数据（令牌、权限、认证状态）——必须永远新鲜；
• 库存、余额等强一致数据——旧值可能导致业务错误；
• 404/410 类“数据已永久消失”的错误——不要在shouldServe中放行，否则已删除的资源会被无限期地“复活”。

实用技巧：

• 先从较小的staleTime起步，根据监控逐步调大；
• 长时间故障（如半小时以上）建议配合 Circuit Breaker 熔断插件，让熔断器快速失败、缓存继续兜底，组合效果最佳；
• 详细的缓存状态与错误处理说明，可参考官方文档 swr.md。

小结

SWR 和 stale-if-error 是缓存系统中“高可用”与“高性能”的黄金组合：SWR 让接口在缓存过期时依旧秒回，stale-if-error 让接口在数据源故障时依然有值可用。NestJS RedisX 把它们做成了开箱即用的插件开关，配置几行即可生效，是优化接口响应、抵御缓存雪崩的利器。

【免费下载链接】nestjs-redisxModular Redis toolkit for NestJS with plugin architecture - caching, locks, rate limiting, circuit breaker, pub/sub, idempotency, streams, metrics & tracing项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-redisx