blog.dopana

返回

聚焦 TanStack Query 在 React 中的简单理解与实际应用,特别是客户端缓存。

TL;DR: @tanstack/react-query 不只是一个调用 API 的库。它可以充当客户端 server-state 缓存,缓存 API 数据、避免重复请求、按需自动 refetch,并非常方便地管理 loading/error 状态。

问题:重复的 API 请求#

在构建 React 应用时,我们经常会遇到一个很普遍的问题:

API 已经返回数据了,下次还需要再调一次 API 吗?

比如一个页面有这样一个 API:

GET /api/users/123
text

如果组件 A 调用了这个 API,之后组件 B 也需要用户 123 的信息,传统做法可能导致两个组件都调 API。

组件AGET /api/users/123组件BGET /api/users/123

这就产生了多余的请求。

一种解法是自己造缓存:

cache.ts
const cache = new Map()
ts

但当应用变大,自己管理缓存很快就会变得复杂。

这时 TanStack Query 就派上用场了。

TanStack Query 是什么?#

TanStack Query(以前常被称为 React Query)是专门管理前端server state 的库。

React 用的包是:

terminal
npm install @tanstack/react-query
bash

关键在于:

TanStack Query 不单纯是一个 fetch() API 库。

它提供了一整套机制:

  • 拉取数据
  • 缓存数据
  • 请求去重
  • 数据 refetch
  • 请求重试
  • 管理 loading/error
  • 缓存失效
  • 乐观更新
  • 分页
  • 无限查询
  • 后台 refetch

Server State 和 Client State 有什么区别?#

这是理解 TanStack Query 最重要的概念。

Client State#

属于 UI/应用自身的状态。

例如:

ThemeToggle.tsx
const [isOpen, setIsOpen] = useState(false)
tsx

或者:

ThemeToggle.tsx
const [theme, setTheme] = useState("dark")
tsx

这些数据属于前端自己。

Server State#

来自后端的数据。

例如:

user.json
{
  "id": 123,
  "name": "John",
  "email": "john@example.com"
}
json

前端并不真正拥有这些数据。

后端才是数据源头。

APIServer(数据源头)TanStack QueryCache组件A组件B

TanStack Query 主要就是为解决这类状态而设计的。

[!NOTE] ELI5 一下:Client State 好比你家的电灯开关 —— 完全由你控制开和关。Server State 好比户外的天气 —— 你只能透过窗户(API)去”看”,并不拥有它,而且它随时可能变化。

不要把 TanStack Query 和 Redux 搞混#

一个简单的理解:

Redux/Zustand
    ↓
Client State

TanStack Query
    ↓
Server State
text

例如:

ui-store.ts
{
  sidebarOpen: true,
  theme: "dark"
}
ts

适合用 Zustand/Redux。

而:

server-state.ts
{
  users: [...],
  posts: [...],
  products: [...],
  profile: {...}
}
ts

如果数据来自 API,TanStack Query 通常更合适。

当然两种状态可以在一个应用中共存。

缓存是如何工作的?#

例如:

UserProfile.tsx
const { data } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
})
tsx

TanStack Query 用:

queryKey
ts

来确定缓存的是哪一份数据。

例如:

["user", 123]
text

和:

["user", 456]
text

是两个不同的缓存条目。

可以这样想象:

Query Cache

"user", 123
    ↓
{ id: 123, name: "John" }

"user", 456
    ↓
{ id: 456, name: "Alice" }

"posts", 123
    ↓
[ ... ]
text

[!TIP] 可以把 queryKey 想象成超市储物柜的号码:每个 key 只打开一个格子,存一份数据。key 不同 → 格子不同,永远不会混。

基础示例#

首先创建 QueryClient。

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

const queryClient = new QueryClient()

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

然后使用 query:

值得注意的是:

queryKey: ["user", userId]
ts

正是缓存的 identity。

[!NOTE] 从 TanStack Query v5 开始,初始加载状态是 isPending(取代 v4 的 isLoading),cacheTime 改名为 gcTime。本文示例使用 v5 API。

当第二个组件调用同一个 API#

假设组件 A 里有:

<UserProfile userId={123} />
tsx

之后组件 B 也用了:

<UserProfile userId={123} />
tsx

TanStack Query 知道:

["user", 123]
text

已经存在于 Query Cache 中。

因此组件 B 能立刻看到已有数据,而不是一片空白的 loading。

组件A先挂载Query Cache['user', 123]组件B后挂载API Request(仅在需要时)

这是 TanStack Query 的一大优势。

[!NOTE] 默认 staleTime 是 0,即缓存数据被立刻视为过期。组件 B 依然能瞬间看到旧数据(无 loading),同时 TanStack Query 在后台 refetch 更新 —— 这种模式叫 stale-while-revalidate。

请求去重#

一个很常见的场景:

组件A ─┐
       │
组件B ─┼──→ GET /api/user/123
       │
组件C ─┘
text

如果三个组件几乎同时挂载,你肯定不想发出:

GET /api/user/123
GET /api/user/123
GET /api/user/123
text

TanStack Query 有基于 query key 共享/去重请求的机制。

概念上:

组件AQuery Cache['user', 123]组件B组件C只发1次API请求

staleTime —— 数据多久之后算旧?#

这是一个非常重要的选项。

例如:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 60_000,
})
tsx

意思是数据被视为 60 秒内是新鲜的。

在这期间,如果别的组件使用:

["users"]
ts

TanStack Query 可以直接用当前缓存,而不是立刻 refetch。

例如:

00秒  API请求
     ↓
     缓存

10秒  组件B
     ↓
     用缓存

30秒  组件C
     ↓
     用缓存

60秒  缓存变旧
text

staleTime 不是缓存删除时间#

这是一个非常普遍的误解。

例如:

staleTime: 60_000
ts

并不是指:

60 秒后缓存被删除。

而是指:

60 秒后,数据被视为过期。

数据仍可能留在缓存里。

[!WARNING] 学 TanStack Query 时最常见的误解:staleTime 是”数据保鲜多久”,而不是”缓存存活多久”。staleTime 过期后数据只是被标记为旧 —— 下次使用时会后台 refetch,但缓存并不会被删除。

gcTime#

TanStack Query 还有:

gcTime
ts

以前常被称为:

cacheTime
text

它关系到不再被使用的数据在被垃圾回收前保留多久。

例如:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 60_000,
  gcTime: 5 * 60_000,
})
tsx

可以简单理解为:

staleTime
    ↓
数据多久之内算新鲜?

gcTime
    ↓
不活跃的缓存保留多久?
text

这是两个不同的概念。

[!NOTE] 默认值:staleTime 为 0(立刻过期),gcTime 为 5 分钟(最后一个组件卸载后,不活跃缓存保留 5 分钟)。新手遇到的大多数”奇怪”行为,都可以用这两个数字解释。

一个实际的配置#

例如商品 API:

ProductsList.tsx
const productsQuery = useQuery({
  queryKey: ["products"],
  queryFn: fetchProducts,
  staleTime: 5 * 60 * 1000,
  gcTime: 30 * 60 * 1000,
})
tsx

可以理解为:

5分钟
↓
数据视为新鲜

30分钟
↓
不活跃缓存可能被垃圾回收
text

这对很少变化的数据特别有用。

例如:

  • 国家列表
  • 分类
  • 学校列表
  • 配置
  • 商品目录
  • 主数据

[!TIP] 经验法则:数据越少变化,staleTime 越长。国家列表可以用 staleTime: Infinity;实时价格表则用几秒或 refetch interval。

缓存不等于数据永远最新#

这一点非常重要。

假设:

后端
  ↓
User name = "John"
text

前端缓存:

User name = "John"
text

之后服务端变了:

后端
  ↓
User name = "Mike"
text

前端缓存里可能还是:

John
text

所以客户端缓存永远存在 trade-off:

性能
    ↕
新鲜度
text

想减少 API 请求:

staleTime ↑
text

想数据频繁更新:

staleTime ↓
text

数据 refetch#

TanStack Query 可以在多种情况下 refetch。

例如用户回到浏览器标签页时:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  refetchOnWindowFocus: true,
})
tsx

概念:

用户离开标签页服务端数据变化用户回到标签页TanStack Query自动refetch

这让应用感觉数据永远是最新的,而开发者不用自己写事件监听。

[!NOTE] refetchOnWindowFocus 默认就是 true —— 容易让人吃惊的 “important defaults” 之一:切个标签页回来应用就自己调 API 了。如果在 DevTools 里看到”神秘”请求,很可能就是它。

缓存失效#

做 CRUD 时非常有用的功能。

例如:

GET /users
POST /users
text

创建用户后:

api.ts
await createUser(data)
ts

可以 invalidate:

UsersList.tsx
queryClient.invalidateQueries({
  queryKey: ["users"],
})
ts

TanStack Query 就知道查询:

["users"]
text

已经变旧,可以 refetch。

流程:

POST /users创建成功invalidate ['users']query变旧refetchUI更新

Mutation#

TanStack Query 也有 useMutation()。

CreateUser.tsx
const mutation = useMutation({
  mutationFn: createUser,
})
tsx

使用:

CreateUser.tsx
mutation.mutate({
  name: "John",
})
tsx

完整示例:

UsersList.tsx
const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: createUser,

  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ["users"],
    })
  },
})
tsx

这是很常见的模式:

MutationInvalidateRefetchUpdate UI

乐观更新#

更高级的功能是乐观更新(Optimistic Update)。

例如用户点击:

❤️ 点赞
text

与其:

点击
 ↓
API请求
 ↓
服务端响应
 ↓
更新UI
text

可以这样做:

点击
 ↓
立刻更新UI
 ↓
API请求
 ↓
成功 → 保持
失败 → 回滚
text

用户会觉得应用更快。

例如:

用户点击点赞10 → 11立刻更新POST /like成功 → 保持失败 → 回滚到10

这是手写缓存/状态管理会迅速变复杂的使用场景之一。

TanStack Query 会把缓存存到 LocalStorage 吗?#

默认:

不会。

Query cache 主要在内存里。

例如:

浏览器
   └─JavaScript内存
           └─TanStack Query Cache
text

刷新页面:

F5
 ↓
JavaScript内存丢失
 ↓
Query缓存丢失
text

如果想持久化缓存,TanStack Query 可以结合持久化机制,例如:

localStorage
IndexedDB
text

来打造持久缓存。

这适合想在刷新/离线后保留部分 server state 的应用。

TanStack Query 是 HTTP 缓存吗?#

不要把这两者混为一谈。

至少有两个不同的缓存层:

浏览器 / HTTP缓存
        ↓
HTTP响应缓存

TanStack Query
        ↓
应用层server-state缓存
text

例如:

React组件TanStack Query Cachefetch()浏览器HTTP缓存网络后端

TanStack Query 理解的是:

queryKey
staleTime
invalidation
mutation
query state
ts

而 HTTP 缓存基于 HTTP 机制,例如:

Cache-Control
ETag
Last-Modified
Age
text

两套系统可以协同工作。

和手写缓存对比#

不用 TanStack Query:

cache.ts
const cache = new Map()

async function getUser(id: number) {
  if (cache.has(id)) {
    return cache.get(id)
  }

  const data = await fetch(`/api/users/${id}`)
    .then(res => res.json())

  cache.set(id, data)

  return data
}
ts

初看很简单。

但之后你必须解决:

❓ 缓存多久?
❓ 何时过期?
❓ 何时refetch?
❓ 重试?
❓ Loading?
❓ Error?
❓ 去重?
❓ Mutation?
❓ 失效?
❓ 分页?
❓ 无限滚动?
❓ 乐观更新?
❓ 垃圾回收?
❓ 并发请求?
❓ 离线?
text

这时最初简单的 Map() 已经变成了一套完整的缓存系统。

TanStack Query 解决了其中大部分问题。

TanStack Query vs Zustand#

典型的 React 架构可以同时用两者:

React AppClient StateZustand — UI状态Server StateTanStack Query — API缓存

Zustand 示例:

ui-store.ts
{
  sidebarOpen: true,
  selectedTheme: "dark"
}
ts

TanStack Query:

server-state.ts
{
  users: [...],
  posts: [...],
  profile: {...}
}
ts

不必二选一。

TanStack Query vs SWR#

React/Next.js 中另一个流行的选择是 SWR。

两者的概念很相似:

React
 ├─TanStack Query
 └─SWR
text

都解决:

  • 拉取
  • 缓存
  • 重新验证
  • server state

TanStack Query 通常提供更完整的 query/mutation 体系和 server state 管理能力,而 SWR 的 API 相当精简。

所以如果应用中有大量:

CRUD
Mutation
分页
无限查询
乐观更新
缓存失效
复杂Server State
text

那么 TanStack Query 值得考虑。

什么时候该用 TanStack Query?#

TanStack Query 特别适合:

Dashboard
管理后台
电商
CRM
SaaS
社交网络
医疗应用
教育平台
text

特别是 API 很多的应用。

例如:

/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notifications
text

与其每个组件自己管理:

fetch
loading
error
cache
refetch
text

不如交给 TanStack Query 管理 server state。

什么时候不一定需要 TanStack Query?#

如果应用极其简单:

SimpleData.tsx
const [data, setData] = useState()

useEffect(() => {
  fetch("/api/data")
    .then(...)
}, [])
tsx

只有几个 API 请求,加一个库可能没什么收益。

同样,如果框架已经提供了很强的服务端数据获取/缓存机制,且应用主要用 server components,就要在引入客户端 query 库之前先考虑整体架构。

一个实际的架构#

对于大型 React SPA,可以这样组织:

src/
├─api/
│   ├─users.ts
│   ├─courses.ts
│   └─reports.ts
├─queries/
│   ├─users.ts
│   ├─courses.ts
│   └─reports.ts
├─components/
│   ├─UserList.tsx
│   └─CourseList.tsx
└─query-client.ts
text

例如:

queries/users.ts
// queries/users.ts

export const usersQuery = () => ({
  queryKey: ["users"],
  queryFn: fetchUsers,
})
ts

组件:

UserList.tsx
const { data, isPending } = useQuery(
  usersQuery()
)
tsx

这样 API 逻辑不会和 UI 混在一起。

一个重要的模式:Query Key#

使用 TanStack Query 时,应该设计结构化的 query key。

例如:

["users"]
ts
["users", userId]
ts
["users", { page: 1, search: "john" }]
ts

可以想象成:

users
├─users/123
├─users/456
└─users?page=1&search=john
text

query key 设计得越一致:

invalidateQueries()
ts

和缓存管理就越容易。

[!TIP] query key 按从通用到具体的层级设计:["users"] → ["users", id] → ["users", { page, search }]。这样 invalidateQueries({ queryKey: ["users"] }) 就能失效整棵子树 —— 就像删除整个文件夹,而不是逐个删文件。

一个完整的例子#

此时的流程很清晰:

ComponentuseQuery()Query CacheAPI → ServerMutationPOST /usersinvalidate ['users']refetchQuery Cache → UI updated

结论#

如果你的目标是 React 中 API 数据的客户端缓存,那么 @tanstack/react-query 非常值得考虑。

最需要记住的不是:

“TanStack Query 是 fetch API 库。”

而是:

TanStack Query 是 server state 管理与客户端缓存系统。

当应用 API 越来越多,开始出现这些问题时,它特别有用:

API请求重复
        +
缓存
        +
过期数据
        +
Refetch
        +
Mutation
        +
缓存失效
        +
乐观更新
text

与其用 useEffect + useState + Map 全部自己造,不如把 server-state 这部分交给 TanStack Query。

现代 React 架构可以简化为:

UI状态Zustand / useStateServer状态TanStack QueryHTTP缓存Browser / CDN持久数据Backend / Database

这也是避免把所有 API 数据无脑塞进 Redux/Zustand 的视角。

参考资料#