TanStack Query 实践指南一、TanStack 核心工具与安装配置核心库组成 TanStack

一、TanStack 核心工具与安装配置

核心库组成
TanStack 是由 React Query 创始人开发的工具集，主要包含：
- TanStack Query（原 React Query）：数据获取与状态管理，支持缓存、自动分页、乐观更新等。
- TanStack Router：React Router 的替代方案，支持 TypeScript 和灵活的路由配置。
- TanStack Virtual/Table：虚拟化长列表和复杂表格管理，优化渲染性能。
- TanStack DB：与 ElectricSQL 合作推出的数据库工具，支持实时查询和事务。

安装与初始化

npm install @tanstack/react-query @tanstack/react-query-devtools

在 React 应用入口文件（如 index.tsx）中配置 QueryClientProvider：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();
root.render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

开发时可集成 react-query-devtools 进行调试。

二、数据获取与状态管理

基础数据查询（useQuery）

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

export default function PostPage() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['post', '123'],
    queryFn: () => fetchPost('123'),
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{data.title}</div>;
}

缓存机制：通过 queryKey 唯一标识请求，自动缓存响应数据。
状态管理：内置 isLoading、isError、isSuccess 等状态，简化 UI 条件渲染。

无限滚动与分页（useInfiniteQuery）

import { useInfiniteQuery } from '@tanstack/react-query';
import { fetchPhotos } from './api';

export default function PhotoFeed() {
  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
    queryKey: ['photos'],
    queryFn: ({ pageParam = 1 }) => fetchPhotos(pageParam),
    getNextPageParam: (lastPage) => lastPage.nextPage,
    initialPageParam: 1,
  });

  return (
    <div>
      {data?.pages.map((page) => (
        <div key={page.id}>{/* 渲染单页数据 */}</div>
      ))}
      {hasNextPage && <button onClick={fetchNextPage}>加载更多</button>}
    </div>
  );
}

自动分页：通过 getNextPageParam 动态获取下一页参数。
滚动加载：结合 onScroll 事件实现无限滚动。

三、数据变更与突变（`useMutation`）

基础用法

import { useMutation } from '@tanstack/react-query';
import { updatePost } from './api';

export default function PostEditor() {
  const mutation = useMutation(updatePost);

  const onSubmit = (formData) => {
    mutation.mutate(formData);
  };

  if (mutation.isLoading) return <div>提交中...</div>;
  if (mutation.isError) return <div>错误: {mutation.error.message}</div>;

  return <form onSubmit={onSubmit}>{/* 表单内容 */}</form>;
}

乐观更新：默认启用乐观 UI 更新，提升交互流畅度。
错误重试：通过 mutation.retry() 实现自动重试。

与路由结合
在动态路由中根据参数触发突变：

const { id } = useParams();
const { data } = useQuery({ queryKey: ['post', id], queryFn: fetchPost });
const mutation = useMutation(updatePost, {
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['post', id] }),
});

四、性能优化与高级技巧

缓存策略
- 手动更新缓存：通过 queryClient.setQueryData 直接修改缓存数据。
- 缓存失效：使用 invalidateQueries 强制刷新特定或全局缓存。

虚拟化长列表
使用 TanStack Virtual 优化大数据渲染：

import { createVirtual } from '@tanstack/react-virtual';

const virtual = createVirtual({
  data: largeArray,
  estimateSize: 50,
});

return (
  <div style={{ height: '500px', overflow: 'auto' }}>
    {virtual.scrollTo(100).render()}
  </div>
);

按需渲染：仅渲染视口内元素，减少 DOM 节点数量。

表格与复杂数据
结合 TanStack Table 实现高级表格功能：
```
import { createTable } from '@tanstack/react-table';

const table = createTable()
  .setColumns(columns)
  .setData(data);
```
- 功能支持：列排序、固定、分页、筛选等。

五、生态整合与最佳实践

与框架集成
- React Router：替代或补充路由逻辑，支持 TypeScript 类型安全。
- Next.js：结合服务端渲染（SSR）优化数据预取。
代码组织建议
- 分离查询函数：将 queryFn 抽离为独立模块，提升可维护性。
- 错误边界：结合 React Error Boundary 捕获异步错误。
调试工具
- React Query DevTools：实时监控查询状态、缓存和突变记录。

六、最新动态与扩展

TanStack DB：2025 年推出的新库，支持实时数据同步和事务，适合复杂应用。
API 统一化：未来可能将多个工具函数合并为 query() 和 infiniteQuery()，简化 API。

通过以上指南，您可以快速掌握 TanStack 的核心功能与实践方法。如需深入特定场景（如全栈集成或性能调优），建议参考官方网页及社区案例。

TanStack Query​​ 实践指南

一、TanStack 核心工具与安装配置

二、数据获取与状态管理

三、数据变更与突变（useMutation）

四、性能优化与高级技巧

五、生态整合与最佳实践

六、最新动态与扩展

TanStack Query 实践指南

三、数据变更与突变（`useMutation`）