10分钟上手TanStack Query：React数据获取与缓存完整入门指南-编程实验室

10分钟上手TanStack Query：React数据获取与缓存完整入门指南

【免费下载链接】query🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query

TanStack Query（原 React Query）是一款面向 React、Vue、Svelte 等框架的强大异步状态管理与数据获取库，它能帮你轻松完成 React 数据获取、数据缓存、自动刷新和请求重试，彻底告别手写 loading、error、refetch 的繁琐代码。无论你是刚接触前端的新手，还是想优化现有项目的开发者，这篇文章都能在 10 分钟内带你跑通一个完整的 TanStack Query 应用 🚀

为什么选择 TanStack Query？React 数据获取的 5 大痛点

在传统 React 项目中，我们通常用useState+useEffect手写数据请求，每次都要重复处理：

痛点	手动管理	TanStack Query
加载状态（loading）	❌ 自己写	✅ 自动提供
错误处理（error）	❌ 自己写	✅ 自动提供
数据缓存	❌ 基本没有	✅ 按 queryKey 自动缓存
组件切换后数据丢失	❌ 重新请求	✅ 命中缓存秒开
窗口聚焦自动刷新	❌ 需手动实现	✅ 开箱即用
重复请求去重	❌ 容易重复发请求	✅ 自动去重合并

正如官方文档 overview.md 所说：服务端状态（Server State）与客户端状态完全不同——它持久化在远端、需要异步获取、可能随时被别人修改、也可能过期。TanStack Query 正是为解决这些"缓存、去重、后台更新、垃圾回收"问题而生的。

第一步：安装与初始化（最快 1 分钟）

安装非常简单，在项目中执行以下任一命令即可（兼容 React 18+ 与 React Native）：

npm i @tanstack/react-query

然后只需要 3 行代码完成初始化：创建一个QueryClient，并用QueryClientProvider包裹你的应用。完整步骤可参考官方安装指南 installation.md：

const queryClient = new QueryClient() <QueryClientProvider client={queryClient}> <App /> </QueryClientProvider>

💡 建议同时安装官方 ESLint 插件@tanstack/eslint-plugin-query，它能在编码时帮你捕获 queryKey 不一致等常见 bug。

核心概念一：queryKey——数据缓存的基石

TanStack Query 的所有缓存管理都围绕queryKey（查询键）展开。它必须是一个可序列化的数组，用于唯一标识一份数据：

useQuery({ queryKey: ['todos'], ... }) // 待办列表 useQuery({ queryKey: ['todo', 5], ... }) // 第 5 号待办 useQuery({ queryKey: ['todos', { page: 2 }], ... }) // 第 2 页

queryKey 会被确定性哈希：['todos', { page, status }]与['todos', { status, page }]被视为同一份缓存。这是"组件卸载后数据还在"的秘密所在。深入讲解请看 query-keys.md。

核心概念二：useQuery 获取与缓存数据

useQuery是 React 数据获取的核心 Hook。以官方示例 examples/react/simple/src/index.tsx 为例：

const { isPending, error, data, isFetching } = useQuery({ queryKey: ['repoData'], queryFn: () => fetch('https://api.github.com/repos/TanStack/query').then((res) => res.json()), })

就这么简单，你一次性获得了完整的请求生命周期：

isPending：数据尚未到达（加载中）
error：请求失败信息
data：缓存中的最新数据
isFetching：后台刷新中（此时旧数据仍然可用，界面不会闪烁）

缓存的魔法在于：当多个组件使用相同 queryKey 时，请求自动去重；当组件重新挂载时，优先展示缓存数据，并在后台静默刷新。这就是为什么你的页面"感觉更快了"。

核心概念三：Mutation 与缓存失效更新

查询（Query）是读数据，变更（Mutation）是写数据。修改数据后，通常需要让相关缓存失效并重新拉取，即Query Invalidation（查询失效）：

const mutation = useMutation({ mutationFn: postTodo, onSuccess: () => { // 让 todos 相关缓存失效，自动重新获取 queryClient.invalidateQueries({ queryKey: ['todos'] }) }, })

这三个概念（Queries、Mutations、Invalidation）构成了 React Query 核心功能的绝大部分，官方快速上手文档 quick-start.md 中有一个完整的 Todos 示例，非常值得动手跟练。

缓存机制揭秘：数据为什么会"自动保鲜"？

这是新手最常感好奇的部分 😄。TanStack Query 默认会在两种场景下自动后台刷新：

窗口重新聚焦（window-focus-refetching）：你切走标签页再切回来，数据悄悄更新；
缓存过期：每份缓存有staleTime（默认 0，即立刻视为过期），过期后只要被任何观察者访问就会触发刷新。

刷新遵循"乐观展示"原则：先显示旧数据，拿到新数据后无缝替换，用户几乎无感知。更多细节见 caching.md。

进阶技巧：3 个最常用的配置项

配置	作用	新手建议
`staleTime`	数据保持"新鲜"的毫秒数	列表类数据可设为`60 * 1000`，减少无效请求
`retry`	失败自动重试次数（默认 3 次）	弱网环境保持默认即可，体验极佳
`refetchOnWindowFocus`	窗口聚焦是否刷新	需要强实时性的页面保留默认

配合 React Query Devtools（开发工具面板），你可以可视化查看所有缓存、请求状态和网络流量，调试效率翻倍 🔍。

学习路径推荐：跟着官方示例走

本仓库提供了从入门到进阶的完整示例与文档，推荐按此顺序学习：

快速上手：docs/framework/react/quick-start.md —— 三大核心概念
简单示例源码：examples/react/simple/ —— 最小可运行 Demo
基础示例：examples/react/basic/ —— 完整应用结构
API 参考：docs/framework/react/reference/useQuery.md、docs/framework/react/reference/useMutation.md
核心包源码：packages/react-query/src/ —— 想深入原理时阅读
进阶指南：分页 paginated-queries.md、轮询 polling.md、乐观更新 optimistic-updates.md