10分钟上手TanStack QueryReact数据获取与缓存完整入门指南【免费下载链接】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/queryTanStack Query原 React Query是一款面向 React、Vue、Svelte 等框架的强大异步状态管理与数据获取库它能帮你轻松完成 React 数据获取、数据缓存、自动刷新和请求重试彻底告别手写 loading、error、refetch 的繁琐代码。无论你是刚接触前端的新手还是想优化现有项目的开发者这篇文章都能在 10 分钟内带你跑通一个完整的 TanStack Query 应用 为什么选择 TanStack QueryReact 数据获取的 5 大痛点在传统 React 项目中我们通常用useStateuseEffect手写数据请求每次都要重复处理痛点手动管理TanStack Query加载状态loading❌ 自己写✅ 自动提供错误处理error❌ 自己写✅ 自动提供数据缓存❌ 基本没有✅ 按 queryKey 自动缓存组件切换后数据丢失❌ 重新请求✅ 命中缓存秒开窗口聚焦自动刷新❌ 需手动实现✅ 开箱即用重复请求去重❌ 容易重复发请求✅ 自动去重合并正如官方文档 overview.md 所说服务端状态Server State与客户端状态完全不同——它持久化在远端、需要异步获取、可能随时被别人修改、也可能过期。TanStack Query 正是为解决这些缓存、去重、后台更新、垃圾回收问题而生的。第一步安装与初始化最快 1 分钟安装非常简单在项目中执行以下任一命令即可兼容 React 18 与 React Nativenpm i tanstack/react-query然后只需要 3 行代码完成初始化创建一个QueryClient并用QueryClientProvider包裹你的应用。完整步骤可参考官方安装指南 installation.mdconst 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常见问题 FAQQ1TanStack Query 会替换 Redux / Zustand 吗不会。它管理的是服务端状态客户端状态如表单、UI 开关仍建议用传统状态库官方在 does-this-replace-client-state.md 中有详细说明。Q2多个组件请求同一份数据会发多个请求吗不会。相同 queryKey 的并发请求会自动去重只发一个请求所有组件共享同一份缓存。Q3组件卸载后缓存会立刻被清掉吗不会。缓存默认在内存中保留gcTime默认 5 分钟组件短时间内切回来时直接命中缓存无需重新请求。总结10 分钟回顾npm i tanstack/react-queryQueryClientProvider完成初始化️ 用queryKey唯一标识数据它是缓存的基石useQuery一行搞定数据获取、缓存与自动刷新✏️useMutation invalidateQueries实现数据修改后的缓存同步 用staleTime、retry和 Devtools 打磨体验现在打开 examples/react/simple/跑通第一个查询吧——你离告别异步代码地狱只差 10 分钟 ⏱【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 10分钟上手TanStack Query：React数据获取与缓存完整入门指南
10分钟上手TanStack QueryReact数据获取与缓存完整入门指南【免费下载链接】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/queryTanStack Query原 React Query是一款面向 React、Vue、Svelte 等框架的强大异步状态管理与数据获取库它能帮你轻松完成 React 数据获取、数据缓存、自动刷新和请求重试彻底告别手写 loading、error、refetch 的繁琐代码。无论你是刚接触前端的新手还是想优化现有项目的开发者这篇文章都能在 10 分钟内带你跑通一个完整的 TanStack Query 应用 为什么选择 TanStack QueryReact 数据获取的 5 大痛点在传统 React 项目中我们通常用useStateuseEffect手写数据请求每次都要重复处理痛点手动管理TanStack Query加载状态loading❌ 自己写✅ 自动提供错误处理error❌ 自己写✅ 自动提供数据缓存❌ 基本没有✅ 按 queryKey 自动缓存组件切换后数据丢失❌ 重新请求✅ 命中缓存秒开窗口聚焦自动刷新❌ 需手动实现✅ 开箱即用重复请求去重❌ 容易重复发请求✅ 自动去重合并正如官方文档 overview.md 所说服务端状态Server State与客户端状态完全不同——它持久化在远端、需要异步获取、可能随时被别人修改、也可能过期。TanStack Query 正是为解决这些缓存、去重、后台更新、垃圾回收问题而生的。第一步安装与初始化最快 1 分钟安装非常简单在项目中执行以下任一命令即可兼容 React 18 与 React Nativenpm i tanstack/react-query然后只需要 3 行代码完成初始化创建一个QueryClient并用QueryClientProvider包裹你的应用。完整步骤可参考官方安装指南 installation.mdconst 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常见问题 FAQQ1TanStack Query 会替换 Redux / Zustand 吗不会。它管理的是服务端状态客户端状态如表单、UI 开关仍建议用传统状态库官方在 does-this-replace-client-state.md 中有详细说明。Q2多个组件请求同一份数据会发多个请求吗不会。相同 queryKey 的并发请求会自动去重只发一个请求所有组件共享同一份缓存。Q3组件卸载后缓存会立刻被清掉吗不会。缓存默认在内存中保留gcTime默认 5 分钟组件短时间内切回来时直接命中缓存无需重新请求。总结10 分钟回顾npm i tanstack/react-queryQueryClientProvider完成初始化️ 用queryKey唯一标识数据它是缓存的基石useQuery一行搞定数据获取、缓存与自动刷新✏️useMutation invalidateQueries实现数据修改后的缓存同步 用staleTime、retry和 Devtools 打磨体验现在打开 examples/react/simple/跑通第一个查询吧——你离告别异步代码地狱只差 10 分钟 ⏱【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考