TL;DR： 缓存失效是缓存领域最难解决的问题。TanStack Query 提供了丰富的失效 API：
invalidateQueries支持查询过滤器匹配、refetchQueries立即刷新、removeQueries进行垃圾回收、setQueryData实现精准更新。本文涵盖六种常见 SaaS 场景的失效模式。
引言
TanStack Query 的缓存是一个键值存储，键即查询键结构。失效是指将缓存数据标记为过期，并可选择重新获取。核心在于：数据变更时，精准判断需要失效哪些查询。
精准失效
const queryClient = useQueryClient()
// 让所有 product 查询失效
queryClient.invalidateQueries({ queryKey: ['products'] })
// 让单个 product 失效
queryClient.invalidateQueries({ queryKey: ['product', productId] })
// 带过滤条件的失效
queryClient.invalidateQueries({
queryKey: ['products'],
predicate: (query) => query.queryKey.includes('active'),
})
Mutation 响应式失效
export function useCreateProduct() {
const queryClient = useQueryClient()
return useMutation({
mutationFn: createProductFn,
onSuccess: (newProduct) => {
// 更新单个 product 缓存
queryClient.setQueryData(['product', newProduct.id], newProduct)
// 让列表失效
queryClient.invalidateQueries({ queryKey: ['products'] })
// 让相关计数失效
queryClient.invalidateQueries({ queryKey: ['dashboard', 'stats'] })
},
})
}
失效策略矩阵
| 模式 | 方法 | 适用场景 | 成本 |
|---|---|---|---|
| 全量失效 | invalidateQueries | 创建/删除后 | 中（重新获取） |
| 精准更新 | setQueryData | 更新后 | 低（无网络请求） |
| 乐观更新 + 回滚 | onMutate + onError | 即时 UI | 中 |
| 定向重取 | refetchQueries | 可接受数据过期 | 中 |
| 移除 + 懒加载 | removeQueries | 用户登出 | 低 |
| 定时后台刷新 | refetchInterval | 仪表盘 | 持续 |
结语
TanStack Query 中的高效缓存管理，核心在于根据每次 mutation 类型选择恰当的失效策略。列表类 mutation → 失效；单体项 mutation → setQueryData；即时 UI → 乐观更新加回滚。
关于即时 UI 反馈的实战演练，参见 TanStack Query: 乐观更新。若应用需要在离线环境下运行，离线支持 介绍了持久化模式。实时数据同步方面，WebSocket 实时数据 可与 Server-Sent Events 集成，边缘缓存策略指南 则涵盖了与 TanStack Query 客户端缓存互补的 CDN 层缓存策略。