TanStack Query（原 React Query）是一个面向 React 的异步服务端状态管理库，用于处理服务端数据的获取、缓存、同步与更新。它旨在消除手动数据请求的样板代码，并提供后台重新获取、乐观更新、分页与智能缓存管理等内置能力。
用途与适用场景
资料建议在以下情况使用 TanStack Query：从 REST API、GraphQL 或 tRPC 端点获取数据；需要自动后台重新获取与缓存失效；构建带轮询或 WebSocket 数据的实时仪表盘；实现无限滚动或分页；需要变更的乐观 UI 更新；管理复杂的服务端状态同步；需要缓存持久化的离线支持；构建数据频繁更新的应用。
它擅长的方面包括：服务端状态管理（API 数据、外部状态）、请求去重与缓存、stale-while-revalidate 模式、加载与错误状态管理、预取与提前加载、并行与依赖查询编排。
资料建议避免在以下情况使用：纯客户端状态（改用 Zustand、Jotai 或 Context）；表单状态管理（改用 React Hook Form、Formik）；无需缓存的简单一次性请求。
核心概念：服务端状态与客户端状态
资料区分了两类状态。服务端状态：远程持久化（数据库、API、云）；需要通过异步 API 获取与更新；可能与客户端不同步；可能被其他用户或系统更新；例如用户数据、文章、商品、设置。客户端状态：本地持久化（内存、localStorage）；可同步访问；完全由客户端控制；例如 UI 主题、弹窗开关、表单输入。资料明确指出 TanStack Query 管理服务端状态，客户端状态应使用 Zustand 或 Context。
查询键（Query Keys）
查询键唯一标识查询及其缓存数据。资料给出了字符串键（如 ['todos']）、数组键（推荐用于依赖项，如 ['todo', todoId]、['todos', { status: 'active', page: 1 }]）、嵌套数组（如 ['users', userId, 'posts', { sort: 'date' }]）等结构。匹配方式包括精确匹配（exact: true）、前缀匹配（['todos'] 可匹配 ['todos', 1] 等）以及 predicate 匹配。资料建议：使用层级结构的数组，如 ['resource', id, 'subresource']；将变量放在末尾，如 ['users', { filter, sort }]；跨组件保持一致顺序；复杂参数使用对象。
查询生命周期与缓存行为
生命周期为 FRESH → STALE → INACTIVE → GARBAGE COLLECTED。状态含义：Fresh 表示数据在 staleTime 内被视为最新；Stale 表示数据可能过期，将在触发时重新获取；Inactive 表示没有组件使用该查询；Garbage Collected 表示在 cacheTime 后被移出缓存。配置项包括 staleTime、gcTime、refetchOnWindowFocus、refetchOnReconnect、refetchInterval。自动缓存方面，多个组件使用相同查询键时，首个组件触发请求，第二个组件直接使用缓存；stale-while-revalidate 模式会立即显示缓存数据并在后台重新获取。
查询（Queries）
使用 useQuery 钩子，返回 data、error、isLoading、isFetching、isSuccess、isError、status、fetchStatus、refetch 等字段。查询函数模式包括：基础 fetch；在函数中解构 queryKey；使用 abort signal 实现取消（组件卸载或查询变为非活跃时自动取消）；Axios 模式。依赖查询通过 enabled 选项实现顺序或条件执行，例如先获取 user 再获取 projects。并行查询可手动声明多个 useQuery，或使用 useQueries 进行动态并行。占位与初始数据包括 placeholderData（不持久化到缓存，纯 UI）和 initialData（作为真实数据持久化到缓存）。
变更（Mutations）
使用 useMutation 钩子，支持 mutationFn、onSuccess、onError 等回调，以及 mutate、mutateAsync、data、error、isPending、isSuccess、isError、reset 等状态。缓存失效通过 queryClient.invalidateQueries 实现，可指定查询键、exact 精确匹配或 predicate 条件匹配。手动缓存更新使用 setQueryData，支持不可变更新（在列表中添加、移除、更新）。
乐观更新
基础模式包含 onMutate（取消发出中的重新获取、快照旧值、乐观更新缓存、返回上下文）、onError（回滚到快照）、onSettled（成功后始终重新获取）。资料还给出更复杂的乐观更新模式示例，包含取消多个查询、快照多个缓存、乐观更新列表与单项等步骤。原文在复杂示例的代码处被截断（结尾为“// O”），完整内容暂未提供。
使用方式与安装
安装命令：npm install @tanstack/react-query；开发工具（可选但推荐）：npm install @tanstack/react-query-devtools。基础设置通过 QueryClient 与 QueryClientProvider 包裹应用，并可配置 defaultOptions（如 staleTime、refetchOnWindowFocus），同时挂载 ReactQueryDevtools。
限制说明
资料未提供该技能的收费、价格、支持的框架版本范围、性能基准或其他平台信息，这些内容暂未提供。原文在复杂乐观更新示例处被截断，后续内容暂未提供。