React / 系统课时

使用 TanStack Query 查询数据

使用 TanStack Query 查询数据

本课用一个可直接运行的 React 18 示例完成服务端数据查询,并解释查询键、查询函数、缓存新鲜度与重新获取之间的关系。完成后,你能判断页面何时读取缓存、何时发起请求,以及如何用状态字段呈现加载过程。

学习目标

  • 使用 queryKey 和 queryFn 定义可缓存的异步查询
  • 理解新鲜、过期与后台重新获取的区别
  • 使用 staleTime、isPending 和 isFetching 控制界面反馈

准备查询环境

在 React 18 TypeScript 项目中安装 TanStack Query,并确认依赖已经进入当前项目。

bash
npm install @tanstack/react-query --silent && npm ls @tanstack/react-query

预期输出

text
react-query-demo@<VERSION> <PATH>
└── @tanstack/react-query@<VERSION>

<VERSION> 和 <PATH> 会随项目与安装版本变化。应用入口还需要创建唯一的 QueryClient,再通过 QueryClientProvider 将缓存客户端提供给组件树。

编写完整查询示例

下面的入口文件使用本地异步函数模拟接口。查询条件 role 同时进入查询键和查询函数,因此“全部用户”与“管理员”会拥有两份独立缓存。查询键必须是顶层数组;查询函数依赖的可变参数也应包含在查询键中。:contentReference[oaicite:0]{index=0}

tsx
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>,
);

预期结果

text
首次进入页面时显示“首次加载中...”,约 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 或让相关查询失效,仍可提前发起请求。调试时可依次验证首次进入、切换条件、快速切回和手动刷新四种路径。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 TanStack Query 查询数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通