React / 系统课时
使用 TanStack Query 查询数据
使用 TanStack Query 查询数据
本课用一个可直接运行的 React 18 示例完成服务端数据查询,并解释查询键、查询函数、缓存新鲜度与重新获取之间的关系。完成后,你能判断页面何时读取缓存、何时发起请求,以及如何用状态字段呈现加载过程。
学习目标
- 使用
queryKey和queryFn定义可缓存的异步查询 - 理解新鲜、过期与后台重新获取的区别
- 使用
staleTime、isPending和isFetching控制界面反馈
准备查询环境
在 React 18 TypeScript 项目中安装 TanStack Query,并确认依赖已经进入当前项目。
npm install @tanstack/react-query --silent && npm ls @tanstack/react-query预期输出
react-query-demo@<VERSION> <PATH>
└── @tanstack/react-query@<VERSION><VERSION> 和 <PATH> 会随项目与安装版本变化。应用入口还需要创建唯一的 QueryClient,再通过 QueryClientProvider 将缓存客户端提供给组件树。
编写完整查询示例
下面的入口文件使用本地异步函数模拟接口。查询条件 role 同时进入查询键和查询函数,因此“全部用户”与“管理员”会拥有两份独立缓存。查询键必须是顶层数组;查询函数依赖的可变参数也应包含在查询键中。:contentReference[oaicite:0]{index=0}
import { StrictMode, useState } from 'react';
import { createRoot } from 'react-dom/client';
import {
QueryClient,
QueryClientProvider,
useQuery,
} from '@tanstack/react-query';
type Role = 'all' | 'admin';
interface User {
id: number;
name: string;
role: 'admin' | 'member';
}
const queryClient = new QueryClient();
const serverUsers: User[] = [
{ id: 1, name: 'Ada', role: 'admin' },
{ id: 2, name: 'Lin', role: 'member' },
];
let requestCount = 0;
async function fetchUsers(role: Role) {
await new Promise((resolve) => setTimeout(resolve, 500));
requestCount += 1;
return {
items:
role === 'all'
? serverUsers
: serverUsers.filter((user) => user.role === role),
requestNo: requestCount,
};
}
function UserList() {
const [role, setRole] = useState<Role>('all');
const query = useQuery({
queryKey: ['users', { role }],
queryFn: () => fetchUsers(role),
staleTime: 30_000,
});
if (query.isPending) {
return <p>首次加载中...</p>;
}
if (query.isError) {
return <p>加载失败:{query.error.message}</p>;
}
return (
<main>
<h1>用户列表</h1>
<button type="button" onClick={() => setRole('all')}>
全部用户
</button>
<button type="button" onClick={() => setRole('admin')}>
仅管理员
</button>
<button type="button" onClick={() => query.refetch()}>
手动刷新
</button>
<p>
{query.isFetching ? '正在重新获取...' : '当前使用缓存或请求已完成'}
</p>
<p>最近一次请求编号:{query.data.requestNo}</p>
<ul>
{query.data.items.map((user) => (
<li key={user.id}>
{user.name} - {user.role}
</li>
))}
</ul>
</main>
);
}
createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<UserList />
</QueryClientProvider>
</StrictMode>,
);预期结果
首次进入页面时显示“首次加载中...”,约 500 毫秒后显示 2 名用户。
切换到“仅管理员”会为新查询键请求数据,并只显示 Ada。
30 秒内切回“全部用户”会优先读取对应缓存;点击“手动刷新”会立即重新执行查询函数。
请求编号为动态值,实际显示为 <N>。理解缓存与重新获取

staleTime: 30_000 表示数据在 30 秒内被视为新鲜。超过时间后,数据只是变为过期,并不会立刻从缓存删除;组件仍可先显示旧数据,再在符合条件时重新获取。官方默认策略会积极重新获取,设置合适的 staleTime 能减少短时间内的重复请求。:contentReference[oaicite:1]{index=1}
isPending 表示查询还没有可用数据,适合首次加载占位;isFetching 表示查询函数正在执行,也会覆盖已有数据时的后台刷新。把两者混为一个全屏加载状态,会导致后台刷新时页面闪烁。:contentReference[oaicite:2]{index=2}
检查关键边界
查询函数必须在失败时抛出错误或返回 rejected Promise,TanStack Query 才会进入错误状态。查询条件变化时,若变量没有进入 queryKey,不同条件可能错误地共享同一缓存。
不要把 staleTime 理解成“缓存存活时间”。它只控制数据多久保持新鲜;主动调用 refetch 或让相关查询失效,仍可提前发起请求。调试时可依次验证首次进入、切换条件、快速切回和手动刷新四种路径。