blog.dopana

返回

在开发现代 React 应用时,前端工程师常常会遇到一个看似简单却极易产生冗余的问题:“接口已经返回过数据了,当用户切换页面或渲染其他组件时,还需要再次发起 API 请求吗?”

考虑一个常见的接口 GET /api/users/123。导航栏组件需要获取该用户的头像信息,个人主页卡片需要展示其昵称,而侧边栏的活动动态组件同样需要读取该用户的数据。

Header Component       ──→ GET /api/users/123
Profile Component      ──→ GET /api/users/123
ActivityFeed Component ──→ GET /api/users/123
text

在传统的 React 实践中,若仅使用 useEffect 配合 useState,每个组件在挂载(mount)时都会各自发起一次网络请求。这不仅造成大量重复请求与网络带宽浪费,还会导致界面频繁闪烁 Loading 骨架屏,无谓地增加了后端服务器的负载。

[!NOTE] TL;DR: @tanstack/react-query(原名 React Query)并不仅仅是 fetch() 或 axios 的封装层。从架构层面看,它是一个纯粹的 客户端服务端状态缓存系统(Client-side Server-State Cache),具备请求去重(deduplication)、后台自动重新验证、精准的生命周期管理(staleTime 与 gcTime),以及优雅的乐观更新(optimistic updates)。

1. 核心困境:手写缓存(DIY Cache)的技术泥潭#

为了避免重复发起网络请求,很多开发者的第一反应是自己在内存中维护一个 Map 缓存:

表面上看,这段代码干净利落。但随着业务复杂度的增加,这个简单的 Map 会迅速演变成一个难以维护的技术黑洞:

  • 缓存数据什么时候过期?(Stale 过期策略)
  • 什么时候应该在后台静默刷新?(窗口重新获得焦点、网络恢复)
  • 当用户在页面 A 更改了昵称,如何精准通知页面 B 和 C 更新视图?(Cache Invalidation)
  • 如何妥善处理断网时的 Loading、Error 状态与自动退避重试?
  • 用户在短时间内快速切换路由时,如何防止竞态问题(Race Condition)?
  • 离开页面后,内存中的对象如何被垃圾回收,避免内存泄漏?(Garbage Collection)
  • 如何优雅支持分页(Pagination)和无限滚动(Infinite Scroll)?

试图自行解决这些问题,无异于重新发明一套复杂的异步状态管理库。这正是 TanStack Query 大显身手的场景。

2. 心智模型(ELI5):服务端状态 vs. 客户端状态#

理解 TanStack Query 的第一步,是将前端应用中的状态清晰地划分为两大阵营。

远端后端架构React 前端应用服务端状态 (TanStack Query)客户端状态 (Zustand / useState)前端拥有完整控制权内存中暂存的只读快照界面主题: dark / light弹窗显示: true / false当前激活 Tab: 2用户个人资料历史订单列表购物车中的商品Database or REST Server

讲给 10 岁小朋友听的通俗解释(ELI5)#

  • 客户端状态(Client State): 就像你书桌上的个人涂鸦本。你想画什么、翻到哪一页、换哪支彩笔,完全由你说了算,外界没有任何人会干涉。例如:侧边栏展开还是折叠、当前选中的表单输入项。
  • 服务端状态(Server State): 就像你从公共图书馆借回家的图书。你手里拿到的仅仅是一份临时的快照(snapshot)。在图书馆总馆里,原作者可能已经发布了修订版本,或者其他借阅人已经更新了该书的借还状态,而你毫不知情。

[!WARNING] 前端并不真正拥有服务端状态。真实的数据源(Single Source of Truth)永远存储在后端数据库中。因此,客户端内存中的 API 数据,从接收完成的那一刻起,随时都面临着变旧(stale)的可能。

这也是为什么不建议把 API 数据无脑扔进 Redux 或 Zustand。Redux/Zustand 专为同步的客户端 UI 状态设计,而 TanStack Query 则是为了处理异步、共享、易过期的服务端状态而生的缓存中介。

3. TanStack Query 缓存的工作原理#

我们来看一个标准的基础示例。首先,在根组件中使用 QueryClientProvider 包裹应用:

App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { UserProfile } from './UserProfile'

const queryClient = new QueryClient()

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <UserProfile userId={123} />
    </QueryClientProvider>
  )
}
tsx

随后在业务组件中调用 useQuery:

queryKey 即缓存的唯一标识符#

TanStack Query 内部使用哈希序列化机制,将 queryKey 数组作为唯一主键管理缓存表:

['user', 123]  ──→ 缓存记录 A: { id: 123, name: 'John' }
['user', 456]  ──→ 缓存记录 B: { id: 456, name: 'Alice' }
['posts', 123] ──→ 缓存记录 C: [ ... ]
text

当组件树中处于两个互不相干层级的组件同时传入 ['user', 123] 调用 useQuery 时,TanStack Query 会立即命中同一个缓存槽位,实现数据的秒级复用。

4. 请求去重机制(Request Deduplication)#

来看一个非常典型的应用场景:在同一个仪表盘页面中,3 个独立的子组件几乎在同一瞬间挂载,且都需要读取当前用户的数据:

3 个子组件同时挂载后端 API 服务后端 API 服务TanStack Query 缓存层TanStack Query 缓存层useQueryuseQueryuseQuery仅发送 1 次网络请求返回响应 JSON并发分发给所有订阅组件渲染视图渲染视图渲染视图顶部头像组件侧边栏资料卡片中心仪表盘主体queryKey: ['user', 123]去重引擎 (复用单一 Promise)GET /api/users/123

若没有去重机制,浏览器将向后端发送 3 个一模一样的 HTTP GET 请求。TanStack Query 能够智能捕获相同 queryKey 的正在进行中(in-flight)请求,将其合并为一个单一的网络 Promise。在数据返回时,一键同步分发给所有订阅者,杜绝资源浪费。

5. staleTime vs. gcTime:彻底破除新手第一误区#

这是大多数初学者接触 TanStack Query 时最容易混淆的两个核心参数。

配置项历史旧称真实含义默认值
staleTimestaleTime数据在被视作“新鲜”(Fresh)的存活时间;超出该时间后进入“过期陈旧”(Stale)状态0 毫秒
gcTimecacheTime当没有组件再订阅该数据(Inactive)后,它在客户端内存(RAM)中保留多久才会被垃圾回收清除5 * 60 * 1000(5分钟)
00秒: 接口数据拉取完成 ──────→ 数据状态为 Fresh(新鲜)
     │
     │  (在 staleTime 内: 任何组件挂载均直接使用内存缓存,绝不触发请求)
     ▼
60秒: staleTime 倒计时结束 ──→ 数据状态转为 Stale(但仍驻留在缓存中!)
     │
     │  (用户切换路由,所有订阅 ['users'] 的组件全部卸载)
     ▼
70秒: 查询标记为 Inactive ───→ gcTime 垃圾回收倒计时启动(5分钟)
     │
     ▼
370秒: gcTime 倒计时结束 ────→ 数据正式从 JavaScript 堆内存中被清除
text

[!TIP] 黄金法则: 设置 staleTime: 60000 绝对不意味着 60 秒后缓存会被删除!它仅仅表示 60 秒后数据被判定为“陈旧”。TanStack Query 遵循 Stale-While-Revalidate 理念:当下一次访问发生时,即便数据已经陈旧,也会立刻将旧数据渲染上屏避免白屏等待,同时在后台静默发起网络请求拉取最新数据予以平滑替换。

针对静态基础数据的推荐配置#

对于更新频率极低的主数据(如国家列表、角色权限列表、通用字典):

queries/categories.ts
export const categoriesQueryOptions = {
  queryKey: ['categories'],
  queryFn: fetchCategories,
  staleTime: 10 * 60 * 1000, // 10分钟内均视为新鲜数据
  gcTime: 60 * 60 * 1000,    // 组件卸载后在内存中保留60分钟
}
typescript

6. 核心权衡:性能 vs. 实时性#

客户端缓存始终是一场经典的权衡:

性能极致(网络请求极少)       ◄───────────►       实时性极致(数据绝对最新)
       高 staleTime                                       staleTime = 0
text

如果后端在数据库中将用户名由 "John" 修改为 "Mike",而前端设置了 staleTime: 10分钟,客户端将继续展示 "John",直到时间耗尽或触发了同步机制。

为了在不侵入业务逻辑的前提下保持数据贴近实时,TanStack Query 提供了开箱即用的后台静默重新验证能力:

  • refetchOnWindowFocus(默认 true): 当用户从其他浏览器标签页切换回当前页面时,自动静默刷新陈旧数据。
  • refetchOnReconnect(默认 true): 设备断网重新连接后,自动触发重新拉取。
  • refetchOnMount(默认 true): 组件挂载时,若缓存已处于 stale 状态,自动发起后台静默校验。

7. 数据变更与缓存主动失效(Mutation & Invalidation)#

当需要对数据进行增删改(POST、PUT、DELETE)操作时,应使用 useMutation 搭配 queryClient.invalidateQueries。

POST api users200 SuccessinvalidateQueries1. 用户点击新建用户2. useMutation3. 后端持久化至数据库4. onSuccess 回调5. 将 users 查询标记为 stale6. 触发后台自动重新拉取7. 页面视图响应式更新

标准生产级实现范例:

8. 极致用户体验:乐观更新(Optimistic Updates)#

在点赞、收藏或勾选代办事项等高频交互中,若必须等待后端耗时 300ms–1s 响应后才更新 UI,界面操作会产生明显的迟滞感。

乐观更新(Optimistic Updates)的核心思路是:假设请求一定会成功,立刻先修改客户端内存缓存以刷新 UI,同时在后台异步发起 API 请求;若网络请求发生异常,系统将自动回滚(rollback)到修改前的快照状态:

9. 深度辨析:TanStack Query vs. 浏览器 HTTP 缓存#

许多人常常产生疑问:“浏览器本身已经支持带有 Cache-Control 和 ETag 的 HTTP 缓存,为什么我们还需要 TanStack Query?”

事实上,它们处于两个完全独立的架构分层:

1. 应用层 (React 内存)3. 基础设施网络层3. 基础设施网络层2. 浏览器网络层 (HTTP 协议栈)2. 浏览器网络层 (HTTP 协议栈)useQueryCache Miss or RevalidateCache MissForward304 or 200 OKJSON 数据触发响应式重渲染React 组件TanStack Query 缓存fetch() / XMLHttpRequest浏览器 HTTP 缓存 (ETag,max-age)CDN 边缘缓存节点后端 API 服务 / 数据库
维度对比TanStack Query浏览器 HTTP 缓存
存储介质JavaScript 堆内存(RAM)浏览器磁盘 / 内存缓存
组件生命周期感知深度绑定 React 挂载、卸载及焦点状态仅感知 URL、HTTP 方法和请求头
视图响应式更新数据变更自动触发 React 重新渲染与 DOM 渲染完全脱节
并发请求去重共享进行中的单一 Promise若并发触发,可能发送多个物理连接
乐观更新与精准回滚提供完备的原生支持完全不支持

两者相辅相成:HTTP 缓存负责在网络传输层面减少字节开销(如利用 304 Not Modified),而 TanStack Query 则负责在应用视图层面提供极致流畅、无感知的交互体验。

10. 大型项目工程化:Query Key Factory 模式#

在大型工程项目中,如果到处散落着像 ['users', id, 'posts'] 这样的字面量数组,极易因拼写疏忽导致缓存无法命中或错误失效。

采用 Query Key Factory 模式可以实现集中化类型安全管理:

queries/userKeys.ts
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: { page: number; search?: string }) =>
    [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: number) => [...userKeys.details(), id] as const,
}
typescript

借助清晰的树状结构:

  • 失效该模块的所有缓存:queryClient.invalidateQueries({ queryKey: userKeys.all })
  • 仅失效列表而保留单条详情:queryClient.invalidateQueries({ queryKey: userKeys.lists() })
  • 精确订阅特定详情:queryKey: userKeys.detail(userId)

11. 何时推荐使用,何时不需要?#

极力推荐使用的场景:#

  • 管理后台(Admin Dashboard)、SaaS 软件、CRM、电商平台。
  • 具有复杂联动关系、多视图共享相同实体数据的 Web 应用。
  • 基于 React + Vite 或 Next.js(Client Components)构建的单页应用(SPA)。

可以不必引入的场景:#

  • 仅有一个联系表单需要提交的纯静态展示官网。
  • 全面拥抱 Next.js App Router 纯 React Server Components(RSC)架构,且数据获取与缓存完全由服务端框架全权代管的系统。

12. 总结#

TanStack Query 的核心价值远不止于“简化 API 请求”,它是一套在客户端管理与调度异步服务端状态的缓存中枢。

只要掌握好以下四大支柱:

  1. 客户端状态(Zustand/useState)与 服务端状态(TanStack Query)的清晰解耦
  2. 基于 queryKey 的确定性缓存寻址
  3. 精确区分 staleTime(保鲜期)与 gcTime(垃圾回收期)
  4. Mutation ➔ Invalidate ➔ Refetch 的闭环更新链路

你就能从繁琐的异步数据处理中彻底解脱出来,编写出既健壮又极速的高品质 React 应用程序。

参考资料#