React之react-query

react-query（现在正式名称是 TanStack Query）是一个用于 React 应用中的数据获取、缓存、同步和更新状态管理的库。它的目标是简化服务端数据的管理，让你专注于数据而不是状态处理逻辑。

一、它是用来干什么的？

传统情况下你会这样处理数据：

useEffect(() => {
  fetch("/api/data")
    .then(res => res.json())
    .then(data => setData(data))
    .catch(err => setError(err))
    .finally(() => setLoading(false))
}, []);

但是这样的方式有很多重复逻辑，比如加载状态、错误处理、缓存等。

而 react-query 做了这些事情：

• 自动处理 loading / error / success 状态
• 自动缓存数据（避免重复请求）
• 支持后台刷新（stale-while-revalidate）
• 支持分页、滚动加载、轮询
• 支持脱机状态（offline）恢复、窗口重新聚焦时自动刷新

二、怎么用？

1. 安装

npm install @tanstack/react-query

2. 初始化（根组件加个 Provider）

// main.tsx 或 app.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

< QueryClientProvider client={queryClient} >
  <App />
< /QueryClientProvider >

3. 基础用法

假设你有个 API：

const fetchUsers = async () => {
  const res = await fetch('/api/users');
  if (!res.ok) throw new Error('网络错误');
  return res.json();
};

使用 useQuery 获取数据

import { useQuery } from '@tanstack/react-query';

function UserList() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['users'],      // 缓存 key
    queryFn: fetchUsers       // 请求函数
  });

  if (isLoading) return <p>加载中...</p>;
  if (isError) return <p>错误：{error.message}</p>;

  return (
    <ul>
      {data.map(user => <li key={user.id}>{user.name}</li>)}
    </ul>
  );
}

4. 如何刷新 / 手动触发请求

const queryClient = useQueryClient();
queryClient.invalidateQueries({ queryKey: ['users'] }); // 让 ['users'] 重新请求

5. useMutation 提交数据（POST/PUT/DELETE）

import { useMutation, useQueryClient } from '@tanstack/react-query';

const addUser = async (user) => {
  const res = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(user),
    headers: { 'Content-Type': 'application/json' }
  });
  if (!res.ok) throw new Error('添加失败');
  return res.json();
};

function AddUserForm() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: addUser,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] }); // 添加成功后刷新用户列表
    }
  });

  const handleSubmit = () => {
    mutation.mutate({ name: '新用户' });
  };

  return (
    <button onClick={handleSubmit}>添加用户</button>
  );
}

三、常见功能（简要）

功能	用法
自动轮询	refetchInterval: 5000
窗口聚焦刷新	默认开启 refetchOnWindowFocus: true
设置缓存失效时间	staleTime: 60000
分页	使用 queryKey 带上页码
请求失败重试	默认开启，可配置 retry: 3
多数据并行加载	使用多个 useQuery
全局配置	QueryClient 中传 defaultOptions

四、总结一句话

React Query = useEffect + useState + fetch + loading/error 状态管理 + 缓存/刷新优化，帮你更优雅地处理服务端数据。