# TanStack 查询（React Query）技巧 ## 总结 TanStack Query（以前称为 React Query）是一个强大的 React 异步状态管理库，可处理服务器状态获取、缓存、同步和更新。它消除了手动数据获取样板的需要，并提供后台重新获取、乐观更新、分页和智能缓存管理等内置功能。 ## 何时使用 **在以下情况下使用 TanStack 查询：** * 从 REST API、GraphQL 或 tRPC 端点获取数据 * 需要自动后台重新获取和缓存失效 * 使用轮询或 websocket 数据构建实时仪表板 * 实现无限滚动或分页 * 需要对突变进行乐观的 UI 更新 * 管理复杂的服务器状态同步 * 需要缓存持久化的离线支持 * 构建具有频繁数据更新的应用程序 **TanStack Query 擅长于：** * 服务器状态管理（API数据、外部状态） * 请求去重和缓存 * 重新验证时过时的模式 * 加载和错误状态管理 * 预取和预加载 * 并行和依赖查询编排 **避免 TanStack 查询：** * 纯客户端状态（使用 Zustand、Jotai 或 Context） * 表单状态管理（使用React Hook Form、Formik） * 简单的一次性获取，无需缓存 ## 快速入门 ### 安装 npm install @tanstack/react-query # DevTools（可选但推荐） npm install @tanstack/react-query-devtools ### 基本设置 // 应用程序/providers.tsx '使用客户端'；从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从'@tanstack/react-query-devtools'导入{ReactQueryDevtools}；从'react'导入{useState}；导出函数 Providers({ Children }: { Children: React.ReactNode }) { const [queryClient] = useState(() => new QueryClient({ 默认选项：{ 查询：{ staleTime: 60 * 1000, // 1 分钟 refetchOnWindowFocus：假， }, }, })); 返回（ {孩子} ）； } ### 第一个查询 // 组件/UserProfile.tsx 从'@tanstack/react-query'导入{useQuery}；界面用户{ id：号码；名称：字符串；电子邮件：字符串； } 函数 UserProfile({ userId }: { userId: 数字 }) { const { 数据，正在加载，错误 } = useQuery({ 查询键：['用户'，用户Id]， queryFn: async () => { const 响应 =等待 fetch(`/api/users/${userId}`); if (!response.ok) throw new Error('无法获取用户'); 返回response.json()作为Promise； }, }); if (isLoading) return

正在加载...

; if (error) return

错误: {error.message}

; 返回（

{数据.名称}

{数据.电子邮件}

）； } ### 第一次突变 // 组件/CreateUserForm.tsx 从 '@tanstack/react-query' 导入 { useMutation, useQueryClient }; 函数创建用户表单（）{ const queryClient = useQueryClient(); const 突变 = useMutation({ mutationFn: async (newUser: { name: string; email: string }) => { const 响应 = 等待 fetch('/api/users', { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 主体：JSON.stringify（newUser）， }); 返回response.json(); }, 成功：() => { // 无效并重新获取用户列表 queryClient.invalidateQueries({ queryKey: ['users'] }); }, }); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); 突变.突变({ 名称：formData.get('name') 作为字符串，电子邮件： formData.get('email') 作为字符串， }); }; 返回（

<输入名称=“名称”占位符=“名称”必需/> <按钮类型=“提交”禁用= {mutation.isPending}> {突变.isPending ? '创建...' : '创建用户'} {mutation.isError &&

错误：{mutation.error.message}

} ）； } ** ** ## 核心概念 ### 服务器状态与客户端状态 **服务器状态特征：** * 远程保存（数据库、API、云） * 需要异步 API 来获取/更新 * 可能与客户端不同步 * 可由其他用户/系统更新 * 示例：用户数据、帖子、产品、设置 **客户端状态特征：** * 本地持久化（内存、localStorage） * 同步访问 * 完全由客户控制 * 示例：UI 主题、模式打开/关闭、表单输入 **TanStack 查询管理服务器状态**。使用 Zustand/Context 作为客户端状态。 ### 查询键查询键唯一标识查询及其缓存的数据。 **关键结构：** // 字符串键（简单）查询键：['todos'] // 数组键（推荐用于依赖项）查询键：['todo', todoId] queryKey: ['todos', { status: 'active', page: 1 }] // 嵌套数组（复杂的层次结构） queryKey: ['用户', userId, '帖子', { sort: '日期' }] **关键匹配：** // 精确匹配 queryClient.invalidateQueries({ queryKey: ['todos', 1], 精确: true }); // 前缀匹配（使所有匹配无效） queryClient.invalidateQueries({ queryKey: ['todos'] }); // 匹配 ['todos', 1], ['todos', 2] 等 // 谓词匹配 queryClient.invalidateQueries({ 谓词: (query) => query.queryKey[0] === 'todos' && query.state.data?.status === 'draft' }); **最佳实践：** * 使用具有层次结构的数组：`['resource', id, 'subresource']` * 将变量放在末尾：`['users', { filter, sort }]` * 各组件的顺序一致 * 使用对象来获取复杂的参数 ### 查询生命周期新鲜 → 陈旧 → 不活跃 → 垃圾收集 ↓ ↓ ↓ ↓ 0ms staleTime 无观察者cacheTime **州：** * **新鲜** ：数据被认为是最新的（在“staleTime”内） * **Stale** ：数据可能已过时，将在触发时重新获取 * **非活动**：没有组件使用查询 * **垃圾收集** ：在 `cacheTime` 之后从缓存中删除 **配置：** 使用查询({ 查询键：['todos'], queryFn: fetchTodos, staleTime: 5 * 60 * 1000, // 5 分钟（数据新鲜） gcTime: 10 * 60 * 1000, // 10 分钟（缓存保留） refetchOnWindowFocus: true, // 当窗口重新获得焦点时重新获取 refetchOnReconnect: true, // 重新连接时重新获取 refetchInterval: 30000, // 每 30 秒轮询一次 }); ### 缓存行为 **自动缓存：** // 第一个组件 - 触发获取函数组件A() { const { data } = useQuery({ queryKey: ['user', 1], queryFn: fetchUser }); 返回

{data?.name}

; } // 第二个组件 - 立即使用缓存函数 ComponentB() { const { data } = useQuery({ queryKey: ['user', 1], queryFn: fetchUser }); 返回

{data?.email}

; // 没有第二次获取！ } **重新验证时过时：** // 立即显示缓存数据，如果过时则在后台重新获取 const { 数据, isRefetching } = useQuery({ 查询键：['帖子']， queryFn: fetchPosts, staleTime: 60000, // 新鲜 1 分钟 }); // 立即从缓存中获取数据 // 如果发生后台重新获取，则 isRefetching = true ** ** ## 查询 ### useQuery Hook **基本语法：** 常量{ data, // 查询结果 error, // 如果失败则错误对象 isLoading, // 第一次加载（无缓存数据） isFetching, // 任何获取（包括背景） isSuccess, // 查询成功 isError, // 查询失败状态, // '待处理' | '错误'| ‘成功’ fetchStatus, // '正在获取' | '暂停' | “闲置” refetch, // 手动重新获取函数 } = useQuery({ 查询键: ['键'], queryFn: async () => { /* 获取逻辑 */ }, }); ### 查询函数模式 **基本获取：** const { 数据 } = useQuery({ 查询键：['用户']， queryFn: async () => { const 响应=await fetch('/api/users'); if (!response.ok) throw new Error('网络错误'); 返回response.json(); }, }); **函数中的查询键：** const { 数据 } = useQuery({ 查询键：['用户'，用户Id]， queryFn: async ({ queryKey }) => { const [_key, userId] = queryKey; const 响应 =等待 fetch(`/api/users/${userId}`); 返回response.json(); }, }); **中止信号（取消）：** const { 数据 } = useQuery({ 查询键：['todos'], queryFn: async ({ 信号 }) => { const response = wait fetch('/api/todos', { signal }); 返回response.json(); }, }); // 在卸载或查询变为非活动状态时自动取消 **Axios 模式：** 从 'axios' 导入 axios； const { 数据 } = useQuery({ queryKey: ['repos', 用户名], queryFn: ({ 信号 }) => axios.get(`/api/repos/${用户名}`, { signal }).then(res => res.data), }); ### 相关查询 **顺序查询：** // 在获取项目之前等待用户 const { 数据：用户 } = useQuery({ 查询键：['用户'，用户Id]， queryFn: () => fetchUser(userId), }); const { 数据：项目 } = useQuery({ queryKey: ['项目', 用户?.id], queryFn: () => fetchProjects(user!.id), enabled: !!user, // 仅当用户存在时运行 }); **条件查询：** const { 数据 } = useQuery({ queryKey: ['高级功能', userId], queryFn: fetchPremiumFeatures, enabled: user?.isPremium === true, // 仅获取高级用户 }); ### 并行查询 **手动并联：** 功能仪表板（）{ const users = useQuery({ queryKey: ['users'], queryFn: fetchUsers }); const posts = useQuery({ queryKey: ['posts'], queryFn: fetchPosts }); const 项目 = useQuery({ queryKey: ['projects'], queryFn: fetchProjects }); if (users.isLoading || posts.isLoading || items.isLoading) { 返回<旋转器/>; } return

/* 渲染仪表板 */

; } **useQueries（动态并行）：** 从'@tanstack/react-query'导入{useQueries}；函数 MultiUserProfiles({ userIds }: { userIds: number[] }) { 常量结果 = useQueries({ 查询： userIds.map(id => ({ 查询键：['用户'，id]， queryFn: () => fetchUser(id), 陈旧时间：60000， }））， }); const allLoaded = results.every(r => r.isSuccess); if (!allLoaded) 返回 ; 返回（

{结果.map((结果, i) => ( ))}

）； } ### 查询占位符 **占位符数据（即时 UI）：** const { 数据 } = useQuery({ 查询键：['todos'], queryFn: fetchTodos, placeholderData: [], // 加载时显示空数组 }); // 来自缓存的动态占位符 const { 数据 } = useQuery({ 查询键：['todo', id], queryFn: () => fetchTodo(id), 占位符数据：() => { // 使用缓存列表查找占位符返回查询客户端 .getQueryData(['todos']) ?.find(d => d.id === id); }, }); **初始数据（水合作用）：** const { 数据 } = useQuery({ 查询键：['todo', id], queryFn: () => fetchTodo(id), 初始数据：() => { 返回查询客户端 .getQueryData(['todos']) ?.find(d => d.id === id); }, 初始数据更新时间：() => queryClient.getQueryState(['todos'])?.dataUpdatedAt, }); **差异：** * `placeholderData`：不持久化到缓存，纯UI * `initialData`: 持久化缓存为真实数据 ** ** ## 突变 ### useMutation Hook **基本突变：** const 突变 = useMutation({ mutationFn: async (newTodo: Todo) => { const 响应 = 等待 fetch('/api/todos', { 方法：'POST'，正文：JSON.stringify(newTodo), }); 返回response.json(); }, onSuccess: (数据) => { console.log('创建：', data); }, onError: (错误) => { console.error('失败：', 错误); }, }); // 触发突变 mutate.mutate({ title: '新待办事项', done: false }); // 异步/等待变体尝试{ const data =等待mutate.mutateAsync(newTodo); 控制台.log(数据); } 捕获（错误）{ 控制台.错误（错误）； } **突变状态：** 常量{ mutate, // 触发函数 mutateAsync, // Promise 变体 data, // 成功变异的结果 error, // 突变失败导致的错误 isPending, // 正在进行突变 isSuccess, // 变异成功 isError, // 变异失败 reset, // 重置突变状态 } = useMutation({ /* ... */ }); ### 缓存失效 **变异后查询无效：** const 突变 = useMutation({ 突变Fn：createTodo，成功：() => { // 重新获取所有“todos”查询 queryClient.invalidateQueries({ queryKey: ['todos'] }); }, }); **多次无效：** const 突变 = useMutation({ 突变Fn：更新用户， onSuccess: (数据, 变量) => { // 使多个查询族无效 queryClient.invalidateQueries({ queryKey: ['user', Variables.id] }); queryClient.invalidateQueries({ queryKey: ['users'] }); queryClient.invalidateQueries({ queryKey: ['teams', data.teamId] }); }, }); **选择性失效：** // 只使特定查询无效 queryClient.invalidateQueries({ 查询键：['todos'], 精确：true，//仅['todos']，而不是['todos'，1] }); // 基于谓词的失效 queryClient.invalidateQueries({ 谓词：（查询）=> query.queryKey[0] === 'todos' && query.state.data?.status === '草稿', }); ### 手动缓存更新 **setQueryData（直接更新）：** const 突变 = useMutation({ 突变Fn：updateTodo， onSuccess: (updatedTodo) => { // 更新缓存中的特定待办事项 queryClient.setQueryData( ['todo', 更新的Todo.id], 更新待办事项）； // 更新列表中的待办事项 queryClient.setQueryData(['todos'], (旧: Todo[] = []) => 旧地图（待办事项 => todo.id === 更新的Todo.id ？更新待办事项：待办事项））； }, }); **不可变的更新：** // 添加到列表 queryClient.setQueryData(['todos'], (旧: Todo[] = []) => [...旧的，新的Todo] ）； // 从列表中删除 queryClient.setQueryData(['todos'], (旧: Todo[] = []) => old.filter(todo => todo.id !==deletedId) ）； // 更新列表 queryClient.setQueryData(['todos'], (旧: Todo[] = []) => old.map(todo => todo.id === id ? { ...todo, ...updates } : todo) ）； ** ** ## 乐观更新 ### 基本乐观更新 const 突变 = useMutation({ 突变Fn：updateTodo， // 变异执行之前 onMutate: 异步 (newTodo) => { // 取消传出重新获取等待 queryClient.cancelQueries({ queryKey: ['todos'] }); // 快照之前的值 const previousTodos = queryClient.getQueryData(['todos']); // 乐观更新缓存 queryClient.setQueryData(['todos'], (旧: Todo[] = []) => old.map(todo => todo.id === newTodo.id ? newTodo : todo) ）； // 返回带有快照的上下文返回 { 先前的待办事项 }; }, // 出错时回滚 onError: (err, newTodo, context) => { queryClient.setQueryData(['todos'], context?.previousTodos); }, // 成功或错误后始终重新获取已解决：() => { queryClient.invalidateQueries({ queryKey: ['todos'] }); }, }); ### 复杂的乐观更新模式界面待办事项{ id：号码；标题：字符串；完成：布尔值； } const useUpdateTodo = () => { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn: async (updatedTodo: Todo) => { const 响应 = 等待 fetch(`/api/todos/${updatedTodo.id}`, { 方法：'放置'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify(updatedTodo), }); if (!response.ok) throw new Error('更新失败'); 返回response.json(); }, onMutate: 异步 (updatedTodo) => { // 取消查询以防止竞争条件等待 queryClient.cancelQueries({ queryKey: ['todos'] }); 等待 queryClient.cancelQueries({ queryKey: ['todo', UpdatedTodo.id] }); // 快照当前状态 const previousTodos = queryClient.getQueryData(['todos']); const previousTodo = queryClient.getQueryData(['todo', UpdatedTodo.id]); // 乐观更新列表 if (前一个待办事项) { queryClient.setQueryData(['todos'], (old = []) => old.map(todo => todo.id === UpdatedTodo.id ? UpdatedTodo : todo) ）； } // 乐观地更新细节 queryClient.setQueryData(['todo',updatedTodo.id],updatedTodo); 返回 { previousTodos, previousTodo }; }, onError：（错误，updatedTodo，上下文）=> { // 出错时回滚 if (上下文?.previousTodos) { queryClient.setQueryData(['todos'], context.previousTodos); } if (上下文?.previousTodo) { queryClient.setQueryData(['todo',updatedTodo.id],context.previousTodo); } }, onSettled: (数据、错误、变量) => { // 始终重新获取以确保同步 queryClient.invalidateQueries({ queryKey: ['todos'] }); queryClient.invalidateQueries({ queryKey: ['todo', Variables.id] }); }, }); }; // 用法函数 TodoItem({ 待办事项 }: { 待办事项: 待办事项 }) { const updateTodo = useUpdateTodo(); 常量切换完成 = () => { updateTodo.mutate({ ...todo, done: !todo.done }); }; 返回（

<输入类型=“复选框” 检查= {todo.done} onChange={切换完成} 禁用={updateTodo.isPending} /> {todo.标题}

）； } ** ** ## 分页 ### useInfiniteQuery（无限滚动） **基本无限查询：** 从'@tanstack/react-query'导入{useInfiniteQuery}；接口帖子响应{ 帖子：帖子[]；下一个光标？：数字； } 函数 InfinitePosts() { 常量{ 数据，错误，获取下一页，有下一页， isFetchingNextPage, } = useInfiniteQuery({ 查询键：['帖子']， queryFn: async ({ pageParam = 0 }) => { const response = wait fetch(`/api/posts?cursor=${pageParam}`); 返回response.json()作为Promise; }, getNextPageParam: (lastPage) => lastPage.nextCursor, 初始页面参数: 0, }); 返回（

{data?.pages.map((页面, i) => ( {page.posts.map(帖子 => ( ))}

))} <按钮 onClick={() => fetchNextPage()} 禁用={!hasNextPage ||正在获取下一页} > {正在获取下一页？ “正在加载更多...” : 有下一页？ “加载更多” : '没有更多要加载的'} ）； } **双向分页：** 常量{ 数据，获取下一页，获取上一页，有下一页，有上一页， } = useInfiniteQuery({ 查询键：['帖子']， queryFn: async ({ pageParam = 0 }) => { const response = wait fetch(`/api/posts?cursor=${pageParam}`); 返回response.json(); }, getNextPageParam: (lastPage) => lastPage.nextCursor, getPreviousPageParam: (firstPage) => firstPage.prevCursor, 初始页面参数: 0, }); **带有交叉点观察器的无限滚动：** 从'@tanstack/react-query'导入{useInfiniteQuery}；从'react-intersection-observer'导入{useInView}；从'react'导入{useEffect}；函数 AutoLoadPosts() { const { ref, inView } = useInView(); 常量{ 数据，获取下一页，有下一页， isFetchingNextPage, } = useInfiniteQuery({ 查询键：['帖子']， queryFn: fetchPosts, getNextPageParam: (lastPage) => lastPage.nextCursor, 初始页面参数: 0, }); // 当哨兵进入视图时自动获取使用效果（（）=> { if (inView && hasNextPage) { 获取下一页（）； } }, [inView, hasNextPage, fetchNextPage]); 返回（

{data?.pages.map((页面, i) => ( {page.posts.map(post => )}

))} {/* 哨兵元素 */}

{isFetchingNextPage && }

）； } ### 传统分页 **基于页面的分页：** 函数分页帖子（）{ const [页面，setPage] = useState(1); const { 数据, isLoading } = useQuery({ queryKey: ['帖子', 页], queryFn: () => fetchPosts(页面), placeholderData: (previousData) => previousData, // 加载时保留以前的数据 }); 返回（

{正在加载？（ <旋转器/> ) : (

{data.posts.map(post => )}

)}

<按钮 onClick={() => setPage(old => Math.max(old - 1, 1))} 禁用={页=== 1} > 上一页第{页}页 <按钮 onClick={() => setPage(旧 => 旧 + 1)} 禁用={!data?.hasMore} > 下一步

）； } **预取下一页：** 函数分页帖子（）{ const queryClient = useQueryClient(); const [页面，setPage] = useState(1); const { 数据 } = useQuery({ queryKey: ['帖子', 页], queryFn: () => fetchPosts(页面), }); // 预取下一页使用效果（（）=> { 如果（数据？.hasMore）{ queryClient.prefetchQuery({ queryKey: ['帖子', 页数 + 1], queryFn: () => fetchPosts(页 + 1), }); } }, [数据, 页面, queryClient]); 返回（

{/* ... */}

）； } ** ** ## 缓存管理 ### 查询客户端方法 **getQueryData（读取缓存）：** const todos = queryClient.getQueryData(['todos']); const user = queryClient.getQueryData(['user', userId]); **setQueryData（写入缓存）：** queryClient.setQueryData(['用户', 1], newUser); // 更新函数 queryClient.setQueryData(['todos'], (old = []) => [...old, newTodo]); **invalidateQueries（标记陈旧+重新获取）：** // 使所有查询无效 queryClient.invalidateQueries(); // 通过键前缀无效 queryClient.invalidateQueries({ queryKey: ['todos'] }); // 仅精确匹配 queryClient.invalidateQueries({ queryKey: ['todos'], 精确: true }); // 具有重新获取控制 queryClient.invalidateQueries({ 查询键：['todos'], refetchType: 'active', // 'active' | refetchType: 'active', // 'active' | '不活跃' | '全部' | “无” }); **refetchQueries（立即重新获取）：** // 重新获取所有活动查询等待 queryClient.refetchQueries(); // 重新获取特定查询等待 queryClient.refetchQueries({ queryKey: ['todos'] }); // 使用过滤器重新获取等待 queryClient.refetchQueries({ 查询键：['todos'], type: 'active', // 仅重新获取活动查询 }); **removeQueries（从缓存中删除）：** // 删除所有查询 queryClient.removeQueries(); // 删除特定的 queryClient.removeQueries({ queryKey: ['todos', 1] }); // 使用谓词删除 queryClient.removeQueries({ 谓词：（查询）=> query.queryKey[0] === 'todos' && query.state.data?.isArchived === true, }); **resetQueries（重置为初始状态）：** // 重置所有查询 queryClient.resetQueries(); // 重置具体 queryClient.resetQueries({ queryKey: ['todos'] }); ### 缓存配置 **全局默认值：** const queryClient = 新的 QueryClient({ 默认选项：{ 查询：{ staleTime: 60 * 1000, // 1 分钟 gcTime: 5 * 60 * 1000, // 5分钟（以前的cacheTime） refetchOnWindowFocus：假， refetchOnReconnect：真，重试：3，重试延迟：尝试索引 => Math.min(1000 * 2 ** 尝试索引，30000), }, 突变：{ 重试：1， }, }, }); **每个查询配置：** 使用查询({ 查询键：['todos'], queryFn: fetchTodos, staleTime: Infinity, // 永不标记为过时 gcTime: Infinity, // 从不进行垃圾收集 refetchInterval: 5000, // 每5秒重新获取一次 refetchIntervalInBackground: false, // 当选项卡处于非活动状态时不重新获取 }); ### 缓存持久化 **保存到本地存储：** 从'@tanstack/react-query'导入{QueryClient}；从 '@tanstack/react-query-persist-client' 导入 { persistQueryClient } ；从 '@tanstack/query-sync-storage-persister' 导入 { createSyncStoragePersister }； const queryClient = 新的 QueryClient({ 默认选项：{ 查询：{ gcTime: 1000 * 60 * 60 * 24, // 24小时 }, }, }); const persister = createSyncStoragePersister({ 存储：window.localStorage， }); 持久查询客户端({ 查询客户端，坚持者, maxAge: 1000 * 60 * 60 * 24, // 24小时 }); **IndexedDB 持久化：** 从 '@tanstack/query-async-storage-persister' 导入 { createAsyncStoragePersister }；从 'idb-keyval' 导入 { get, set, del }; const persister = createAsyncStoragePersister({ 存储：{ getItem：async（key）=>等待get（key）， setItem：异步（键，值）=>等待设置（键，值），删除项目：异步（键）=>等待德尔（键）， }, }); ** ** ## 错误处理和重试 ### 错误处理 **查询错误边界：** 从'@tanstack/react-query'导入{QueryErrorResetBoundary}；从'react-error-boundary'导入{ErrorBoundary}；函数应用程序（）{ 返回（ <查询错误重置边界> {({重置}) => ( <错误边界 onReset={重置} FallbackRender={({ 错误，resetErrorBoundary }) => (

错误：{error.message}

)} > <组件/> )} ）； } // 组件向边界抛出错误函数组件() { const { 数据 } = useQuery({ 查询键：['用户']， queryFn：获取用户， throwOnError: true, // 将错误抛出到错误边界 }); 返回

{data.name}

; } **自定义错误类型：** 类 APIError 扩展错误 { 构造函数（消息：字符串，公共状态：数量，公共代码？：字符串）{ 超级（消息）； this.name = 'APIError'; } } const { 错误 } = useQuery({ 查询键：['用户']， queryFn: async () => { const 响应=await fetch('/api/user'); 如果（！response.ok）{ 抛出新的 APIError( '获取用户失败', 响应.状态, 等待响应.text() ）； } 返回response.json(); }, }); if (APIError 错误实例) { if (error.status === 404) return ; if (error.status === 401) return <未经授权/>; } ### 重试逻辑 **默认重试：** // 以指数退避重试 3 次使用查询({ 查询键：['数据']， queryFn：获取数据， retry: 3, // 重试次数重试延迟：尝试索引 => Math.min(1000 * 2 ** 尝试索引，30000), }); **有条件重试：** 使用查询({ 查询键：['数据']， queryFn：获取数据，重试：（失败计数，错误）=> { // 不要重试 404 if (错误实例APIError && error.status === 404) { 返回假； } // 对于其他错误最多重试 3 次返回失败计数<3； }, }); **突变重试：** 使用突变（{ 突变Fn：创建用户， retry: 2, // 重试突变（谨慎使用）重试延迟：1000， }); ### 网络状态检测 **在线/离线处理：** const queryClient = 新的 QueryClient({ 默认选项：{ 查询：{ networkMode: 'offlineFirst', // '在线' | '总是' | “离线优先” refetchOnReconnect：真， }, }, }); // 自定义在线/离线指示器函数在线状态（）{ const queryClient = useQueryClient(); const isOnline = useOnlineManager().isOnline(); 使用效果（（）=> { 如果（在线）{ queryClient.refetchQueries(); } }, [isOnline, queryClient]); 返回是否在线？ <在线图标/>：<离线图标/>； } ** ** ## SSR 和水合作用 ### Next.js 应用程序路由器 **服务器组件数据获取：** // 应用程序/用户/page.tsx 从'@tanstack/react-query'导入{脱水，HydrationBoundary，QueryClient}；从 './UsersList' 导入 { UsersList }；导出默认异步函数 UsersPage() { const queryClient = new QueryClient(); // 在服务器上预取等待 queryClient.prefetchQuery({ 查询键：['用户']， queryFn：获取用户， }); 返回（ <用户列表/> ）； } **客户端组件：** // 应用程序/用户/UsersList.tsx '使用客户端'；从'@tanstack/react-query'导入{useQuery}；导出函数 UsersList() { // 使用来自服务器的水合数据 const { 数据 } = useQuery({ 查询键：['用户']， queryFn：获取用户， }); 返回（

{user.name}

）； } ### Next.js 页面路由器 **获取服务器端属性：** 从“@tanstack/react-query”导入{脱水，QueryClient}；导出异步函数 getServerSideProps() { const queryClient = new QueryClient(); 等待 queryClient.prefetchQuery({ 查询键：['用户']， queryFn：获取用户， }); 返回{ 道具：{ 脱水状态：脱水（queryClient）， }, }; } 函数用户页面（）{ const { 数据 } = useQuery({ 查询键：['用户']， queryFn：获取用户， }); 返回

{/* ... */}

; } 导出默认的UsersPage； **_app.tsx 设置：** // 页面/_app.tsx 从'react'导入{useState}；从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider, HydrationBoundary }; 导出默认函数 App({ Component, pageProps }) { const [queryClient] = useState(() => new QueryClient()); 返回（ <组件{...pageProps} /> ）； } ### 流式 SSR **悬念整合：** 从'@tanstack/react-query'导入{useSuspenseQuery}；函数 UserProfile({ userId }: { userId: 数字 }) { const { 数据 } = useSuspenseQuery({ 查询键：['用户'，用户Id]， queryFn: () => fetchUser(userId), }); // 不需要加载状态 - Suspense 可以处理它返回

{data.name}

; } // 在父组件中 <悬念回退={}> <用户配置文件 userId={1} /> ** ** ## 集成模式 ### tRPC 集成 **设置：** // utils/trpc.ts 从'@trpc/react-query'导入{createTRPCReact}；从 '@/server/routers/_app' 导入类型 { AppRouter }；导出 const trpc = createTRPCReact(); **提供者：** // 应用程序/providers.tsx '使用客户端'；从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从'@trpc/client'导入{httpBatchLink}；从'react'导入{useState}；从 '@/utils/trpc' 导入 { trpc }；导出函数 Providers({ Children }: { Children: React.ReactNode }) { const [queryClient] = useState(() => new QueryClient()); const [trpcClient] = useState(() => trpc.createClient({ 链接：[ httpBatchLink({ url: '/api/trpc', }), ], }) ）；返回（ {孩子} ）； } **用途：** 函数用户配置文件（）{ // 查询 const { 数据 } = trpc.user.getById.useQuery({ id: 1 }); // 变异 const utils = trpc.useUtils(); const 突变 = trpc.user.create.useMutation({ 成功：() => { utils.user.list.invalidate(); }, }); 返回

{data?.name}

; } ### 使用 Axios 的 REST API **API客户端：** // lib/api-client.ts 从 'axios' 导入 axios；导出 const apiClient = axios.create({ 基本URL：process.env.NEXT_PUBLIC_API_URL，标题：{ '内容类型'：'应用程序/json'， }, }); // 请求拦截器 apiClient.interceptors.request.use(config => { const token = localStorage.getItem('token'); 如果（令牌）{ config.headers.Authorization = `承载${token}`; } 返回配置； }); // 响应拦截器 apiClient.interceptors.response.use( 响应=>响应，错误=> { if (error.response?.status === 401) { // 处理未授权的情况 window.location.href = '/登录'; } 返回 Promise.reject(错误); } ）； **查询挂钩：** // 钩子/useUsers.ts 从 '@tanstack/react-query' 导入 { useQuery, useMutation, useQueryClient }; 从 '@/lib/api-client' 导入 { apiClient }；导出函数 useUsers() { 返回 useQuery({ 查询键：['用户']， queryFn: async ({ 信号 }) => { const { data } = wait apiClient.get('/users', { signal }); 返回数据； }, }); } 导出函数 useUser(id: number) { 返回 useQuery({ 查询键：['用户'，id]， queryFn: async ({ 信号 }) => { const { data } = wait apiClient.get(`/users/${id}`, { signal }); 返回数据； }, 启用：！！id， }); } 导出函数 useCreateUser() { const queryClient = useQueryClient(); 返回 useMutation({ 突变Fn：（新用户：新用户）=> apiClient.post('/users', newUser).then(res => res.data), 成功：() => { queryClient.invalidateQueries({ queryKey: ['users'] }); }, }); } ### GraphQL 集成 **Apollo 客户端替代方案：** 从'@tanstack/react-query'导入{useQuery}；从'graphql-request'导入{request，gql}； const 端点 = 'https://api.example.com/graphql'; const GET_USERS = gql` 查询获取用户{ 用户{ 编号姓名电子邮件 } } `; 函数 useUsers() { 返回 useQuery({ 查询键：['用户']， queryFn: async () => 请求(端点, GET_USERS), }); } // 带变量常量 GET_USER = gql` 查询 GetUser($id: ID!) { 用户（id：$id）{ 编号姓名电子邮件 } } `; 函数 useUser(id: 字符串) { 返回 useQuery({ 查询键：['用户'，id]， queryFn: async () => 请求(端点, GET_USER, { id }), }); } ### Zu 代表全局状态 **组合模式：** // 商店/useAuthStore.ts 从“zustand”导入{创建}；接口 AuthState { 标记：字符串|无效的; setToken: (令牌: string | null) => void; 注销：() => 无效； } 导出 const useAuthStore = create((set) => ({ 令牌：localStorage.getItem('令牌'), 设置令牌：（令牌）=> { 如果（令牌）{ localStorage.setItem('令牌', 令牌); } 否则{ localStorage.removeItem('token'); } 设置（{令牌}）； }, 注销：() => { localStorage.removeItem('token'); 设置（{令牌：空}）； }, })); // 钩子/useAuthenticatedQuery.ts 从'@tanstack/react-query'导入{useQuery}；从 '@/store/useAuthStore' 导入 { useAuthStore }；导出函数 useAuthenticatedQuery() { const token = useAuthStore(state => state.token); 返回 useQuery({ queryKey: ['个人资料', 令牌], queryFn: async () => { const 响应 = 等待 fetch('/api/profile', { headers: { 授权: `Bearer ${token}` }, }); 返回response.json(); }, 启用：！！令牌， }); } ** ** ## TypeScript 模式 ### 类型查询 **通用查询挂钩：** 界面用户{ id：号码；名称：字符串；电子邮件：字符串； } // 显式输入 const { 数据 } = useQuery<用户, 错误>({ 查询键：['用户'，id]， queryFn: async () => { const 响应 =等待 fetch(`/api/users/${id}`); 返回response.json(); // TypeScript 推断返回类型 }, }); // 数据是用户 |未定义 // 错误是错误 |空 **类型安全的查询键：** // 定义查询键的类型常量用户密钥 = { all: ['users'] 作为 const，列表： () => [...userKeys.all, 'list'] as const, 列表：（过滤器：UserFilters）=> [...userKeys.lists（），过滤器] as const，详细信息： () => [...userKeys.all, 'detail'] as const, 详细信息： (id: number) => [...userKeys.details(), id] as const， }; // 具有完全类型安全性的用法 const { 数据 } = useQuery({ queryKey: userKeys.detail(userId), queryFn: () => fetchUser(userId), }); // 自动完成无效 queryClient.invalidateQueries({ queryKey: userKeys.lists() }); **自定义挂钩类型：** 界面用户{ id：号码；名称：字符串；电子邮件：字符串； } 接口 UseUserOptions { 启用？：布尔值； onSuccess?: (用户: 用户) => void; } 函数 useUser(id: 数字, 选项?: UseUserOptions) { 返回 useQuery({ 查询键：['用户'，id]， queryFn: async (): Promise => { const 响应 =等待 fetch(`/api/users/${id}`); if (!response.ok) throw new Error('无法获取用户'); 返回response.json(); }, 启用：选项？.启用， // 类型安全回调 onSuccess：选项？.onSuccess， }); } // 用法 const { 数据 } = useUser(1, { 启用：真， onSuccess: (用户) => { console.log(用户名); // TypeScript 知道用户是 User }, }); ### 类型突变接口创建用户有效负载{ 名称：字符串；电子邮件：字符串； } 界面用户{ id：号码；名称：字符串；电子邮件：字符串； } 函数 useCreateUser() { 返回 useMutation<用户，错误，CreateUserPayload>({ mutationFn：异步（有效负载）=> { const 响应 = 等待 fetch('/api/users', { 方法：'POST'，正文：JSON.stringify（有效负载）， }); 返回response.json(); }, onSuccess: (数据) => { // 数据是用户 console.log('已创建用户：', data.name); }, onError: (错误) => { // 错误就是错误 console.error('失败：', error.message); }, }); } // 用法 const 突变 = useCreateUser(); mutate.mutate({ name: 'John', email: 'john@example.com' }); ### 查询客户端输入从'@tanstack/react-query'导入{QueryClient}； // 类型安全的查询客户端方法 const user = queryClient.getQueryData(['user', 1]); queryClient.setQueryData<用户>(['用户', 1], (旧) => { // 旧的是用户 |未定义 if (!old) 返回旧的； return { ...old, name: '更新' }; }); // 类型安全失效 queryClient.invalidateQueries<用户>({ 查询键：['用户']，谓词：（查询）=> { // query.state.data 是 User |未定义返回query.state.data?.isActive === true; }, }); ** ** ## 测试 ### 设置测试环境 **测试工具：** // 测试/utils.tsx 从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从'@testing-library/react'导入{渲染}；从'react'导入{ReactNode}；导出函数 createTestQueryClient() { 返回新的 QueryClient({ 默认选项：{ 查询：{ retry: false, // 不要在测试中重试失败的查询 gcTime：无穷大， }, }, 记录器：{ 日志：控制台.log，警告：控制台.警告， error: () => {}, // 测试中静默错误 }, }); } 导出函数 renderWithClient(ui: ReactNode) { const testQueryClient = createTestQueryClient(); 返回渲染（ {用户界面} ）； } ### 测试查询 **基本查询测试：** // 用户配置文件.test.tsx 从'@/test/utils'导入{renderWithClient}；从 '@testing-library/react' 导入 { screen, waitFor }; 从“msw”导入{rest}；从'msw/node'导入{setupServer}；从 './UserProfile' 导入 { UserProfile }；常量服务器 = setupServer( rest.get('/api/users/1', (req, res, ctx) => { 返回资源（ ctx.json({ 编号: 1, 名称：“约翰·多伊”，电子邮件：'john@example.com'， }) ）； }) ）； beforeAll(() => server.listen()); afterEach(() => server.resetHandlers()); afterAll(() => server.close()); test('显示用户个人资料', async () => { renderWithClient(); Expect(screen.getByText('正在加载...')).toBeInTheDocument(); 等待 waitFor(() => { Expect(screen.getByText('John Doe')).toBeInTheDocument(); }); }); test('处理获取错误', async () => { 服务器.使用( rest.get('/api/users/1', (req, res, ctx) => { 返回 res(ctx.status(500)); }) ）； renderWithClient(); 等待 waitFor(() => { 期望(screen.getByText(/error/i)).toBeInTheDocument(); }); }); ### 测试突变 // 创建用户表单.test.tsx 从'@/test/utils'导入{renderWithClient}；从 '@testing-library/react' 导入 { screen, waitFor }; 从'@testing-library/user-event'导入userEvent；从“msw”导入{rest}；从'msw/node'导入{setupServer}；从 './CreateUserForm' 导入 { CreateUserForm }；常量服务器 = setupServer( rest.post('/api/users', async (req, res, ctx) => { const body =等待req.json(); 返回资源（ ctx.json({ 编号: 1, ...身体， }) ）； }) ）； beforeAll(() => server.listen()); afterEach(() => server.resetHandlers()); afterAll(() => server.close()); test('创建用户成功', async () => { const user = userEvent.setup(); renderWithClient(); 等待 user.type(screen.getByPlaceholderText('姓名'), '约翰·多伊'); 等待 user.type(screen.getByPlaceholderText('电子邮件'), 'john@example.com'); 等待 user.click(screen.getByRole('button', { name: /create/i })); 等待 waitFor(() => { Expect(screen.getByText(/创建成功/i)).toBeInTheDocument(); }); }); ### 使用模拟数据进行测试 **水合物查询数据：** test('使用初始数据渲染', () => { const testQueryClient = createTestQueryClient(); // 预填充缓存 testQueryClient.setQueryData(['用户', 1], { 编号: 1, 名称：“约翰·多伊”，电子邮件：'john@example.com'， }); 渲染（ <用户配置文件 userId={1} /> ）； // 数据立即可用（无加载状态） Expect(screen.getByText('John Doe')).toBeInTheDocument(); }); ### 测试自定义挂钩 // useUser.test.ts 从 '@testing-library/react' 导入 { renderHook, waitFor }; 从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从“msw”导入{rest}；从'msw/node'导入{setupServer}；从 './useUser' 导入 { useUser } ；常量服务器 = setupServer( rest.get('/api/users/:id', (req, res, ctx) => { return res(ctx.json({ id: 1, name: 'John Doe' })); }) ）； beforeAll(() => server.listen()); afterEach(() => server.resetHandlers()); afterAll(() => server.close()); test('获取用户数据', async () => { const queryClient = new QueryClient(); const 包装器 = ({ 孩子 }: { 孩子: React.ReactNode }) => ( {children} ）； const { 结果 } = renderHook(() => useUser(1), { 包装器 }); 等待 waitFor(() => 期望(result.current.isSuccess).toBe(true)); Expect(result.current.data).toEqual({ id: 1, name: 'John Doe' }); }); ** ** ## 性能优化 ### 查询重复数据删除 **自动重复数据删除：** // 多个组件请求相同的数据 - 只有一个网络请求功能仪表板（）{ 返回（

{/* 触发获取 */} {/* 使用缓存 */} {/* 使用缓存 */}

）； } ### 预取 **悬停预取：** 函数 UserLink({ userId }: { userId: 数字 }) { const queryClient = useQueryClient(); const prefetchUser = () => { queryClient.prefetchQuery({ 查询键：['用户'，用户Id]， queryFn: () => fetchUser(userId), 陈旧时间：60000， }); }; 返回（ <链接 href={`/users/${userId}`} onMouseEnter={prefetchUser} onFocus={prefetchUser} > 查看用户）； } **路由预取：** // Next.js 应用程序路由器从'@tanstack/react-query'导入{QueryClient，HydrationBoundary，脱水}；导出默认异步函数 UserPage({ params }: { params: { id: string } }) { const queryClient = new QueryClient(); // 预取用户数据等待 queryClient.prefetchQuery({ queryKey: ['用户', params.id], queryFn: () => fetchUser(params.id), }); // 预取相关数据等待 queryClient.prefetchQuery({ queryKey: ['用户帖子', params.id], queryFn: () => fetchUserPosts(params.id), }); 返回（ <用户配置文件 userId={params.id} /> ）； } ### 选择和转换数据 **记忆化选择器：** // 仅当所选数据发生变化时重新渲染函数 TodoList({ 过滤器 }: { 过滤器: '全部' | '完成' | '待处理' }) { const { 数据：filteredTodos } = useQuery({ 查询键：['todos'], queryFn: fetchTodos, 选择：（待办事项）=> { // 仅当待办事项更改时运行 if (filter === 'done') return todos.filter(t => t.done); if (filter === 'pending') return todos.filter(t => !t.done); 返回待办事项； }, }); // 组件仅在filteredTodos改变时重新渲染返回（

{todo.title}

）； } **昂贵的计算：** const { 数据：sortedUsers } = useQuery({ 查询键：['用户']， queryFn：获取用户，选择：（用户）=> { // 重排序仅在用户更改时运行返回用户 .slice() .sort((a, b) => a.name.localeCompare(b.name)); }, }); ### 结构共享 **自动结构共享：** // TanStack Query 自动进行结构共享 const { 数据 } = useQuery({ 查询键：['todos'], queryFn: fetchTodos, StructureSharing: true, // 默认 }); // 如果重新获取返回相同的数据结构， // 即使获取完成，组件也不会重新渲染 **自定义结构共享：** 从'@tanstack/react-query'导入{replaceEqualDeep}； const { 数据 } = useQuery({ 查询键：['数据']， queryFn：获取数据，结构共享：（旧数据，新数据）=> { // 自定义比较逻辑返回replaceEqualDeep(oldData, newData); }, }); ### 查询取消 **中止传输中的请求：** const { 数据，重新获取 } = useQuery({ queryKey: ['搜索', searchTerm], queryFn: async ({ 信号 }) => { const 响应 = 等待 fetch(`/api/search?q=${searchTerm}`, { signal, // 传递中止信号 }); 返回response.json(); }, }); // 当searchTerm改变时，之前的请求自动取消 **手动取消：** const queryClient = useQueryClient(); // 取消所有查询 queryClient.cancelQueries(); // 取消特定查询 queryClient.cancelQueries({ queryKey: ['todos'] }); ** ** ## 最佳实践和常见模式 ### 查询关键工厂 **集中查询键：** // lib/query-keys.ts 导出常量查询键 = { 用户：{ all: ['users'] 作为 const，列表： () => [...queryKeys.users.all, 'list'] as const, 列表：（过滤器：UserFilters）=> [...queryKeys.users.lists（），过滤器] as const，详细信息： () => [...queryKeys.users.all, 'detail'] as const, 详细信息： (id: number) => [...queryKeys.users.details(), id] as const, }, 帖子：{ all: ['posts'] 作为 const，列表：() => [...queryKeys.posts.all, 'list'] as const, 列表：（过滤器：PostFilters）=> [...queryKeys.posts.lists（），过滤器] as const，详细信息： () => [...queryKeys.posts.all, 'detail'] as const, 详细信息： (id: number) => [...queryKeys.posts.details(), id] as const, }, }; // 用法 const { 数据 } = useQuery({ queryKey: queryKeys.users.detail(userId), queryFn: () => fetchUser(userId), }); // 使所有用户列表无效 queryClient.invalidateQueries({ queryKey: queryKeys.users.lists() }); ### 自定义钩子图案 **资源挂钩工厂：** // lib/create-resource-hooks.ts 从 '@tanstack/react-query' 导入 { useQuery, useMutation, useQueryClient }; 导出函数 createResourceHooks, UpdateT = Partial>( 资源名称：字符串，应用程序编程接口：{ getAll: () => Promise; getOne: (id: string | number) => Promise; 创建：（数据：CreateT）=> Promise；更新：（id：字符串|数字，数据：UpdateT）=> Promise ；删除：（id：字符串|数字）=> Promise ； } ）{ 常量键 = { all: [resourceName] as const, 列表： () => [...keys.all, 'list'] as const, 详细信息： () => [...keys.all, 'detail'] as const, 详细信息：(id: string | number) => [...keys.details(), id] as const, }; 返回{ 使用列表：() => 使用查询({ 查询键：keys.lists(), queryFn: api.getAll, }), useDetail: (id: 字符串 | 数字) => 使用查询({ 查询键：keys.detail(id), queryFn: () => api.getOne(id), 启用：！！id， }), 使用创建：() => { const queryClient = useQueryClient(); 返回 useMutation({ 突变Fn：api.create，成功：() => { queryClient.invalidateQueries({ queryKey:keys.lists() }); }, }); }, 使用更新：() => { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn: ({ id, data }: { id: string | number; data: UpdateT }) => api.update(id, 数据), onSuccess: (_, { id }) => { queryClient.invalidateQueries({ queryKey:keys.detail(id) }); queryClient.invalidateQueries({ queryKey:keys.lists() }); }, }); }, 使用删除：() => { const queryClient = useQueryClient(); 返回 useMutation({ 突变Fn：api.delete，成功：() => { queryClient.invalidateQueries({ queryKey:keys.lists() }); }, }); }, }; } // 用法 const userHooks = createResourceHooks('users', userApi); 函数用户列表（）{ const { 数据：用户 } = userHooks.useList(); const createUser = userHooks.useCreate(); const deleteUser = userHooks.useDelete(); 返回（

{用户？.map(用户=>(

{用户名}

))}

）； } ### 错误处理模式 **集中错误处理程序：** // lib/query-client.ts 从'@tanstack/react-query'导入{QueryClient}；从“sonner”导入{toast}；导出 const queryClient = 新 QueryClient({ 默认选项：{ 查询：{ onError: (错误) => { if (APIError 错误实例) { toast.error(`错误：${error.message}`); } }, }, 突变：{ onError: (错误) => { toast.error(`保存失败：${error.message}`); }, }, }, }); ### 从 SWR 迁移 **SWR 到 TanStack 查询：** // 之前 (SWR) 从 'swr' 导入 useSWR；函数配置文件（）{ const { 数据、错误、变异 } = useSWR('/api/user', fetcher); 如果（错误）返回

错误

； if (!data) return

正在加载...

; 返回

{data.name}

; } // 之后（TanStack 查询）从 '@tanstack/react-query' 导入 { useQuery, useQueryClient }; 函数配置文件（）{ const { 数据，错误，正在加载 } = useQuery({ 查询键：['/api/user'], queryFn: () => fetcher('/api/user'), }); const queryClient = useQueryClient(); const invalidate = () => queryClient.invalidateQueries({ queryKey: ['/api/user'] }); 如果（错误）返回

错误

； if (isLoading) return

正在加载...

; 返回

{data.name}

; } **比较：** * `useSWR(key, fetcher)` → `useQuery({ queryKey: [key], queryFn: fetcher })` * `mutate()` → `queryClient.invalidateQueries()` * `!data` 加载 → `isLoading` * `useSWRConfig()` → `useQueryClient()` ** ** ## 开发工具 **设置开发工具：** 从'@tanstack/react-query-devtools'导入{ReactQueryDevtools}；函数应用程序（）{ 返回（ <你的应用程序/> ）； } **生产版本：** // DevTools 会自动排除在生产版本中 // 不需要条件渲染 **开发工具功能：** * 查看所有查询及其状态 * 检查查询数据和错误 * 手动触发重新获取 * 使查询无效 * 查看查询时间线 * 监控缓存大小 * 调试网络瀑布 ** ** ## 常见陷阱 **❌ 不要在组件内部创建 QueryClient：** // 错误 - 在每次渲染时创建新客户端函数应用程序（）{ const queryClient = new QueryClient(); // ❌ 返回 ...; } // 正确 - 稳定的客户端实例函数应用程序（）{ const [queryClient] = useState(() => new QueryClient()); // ✅ 返回 ...; } **❌不要在没有检查的情况下在渲染中使用查询数据：** // 错误 - 数据可能未定义函数用户配置文件（）{ const { data } = useQuery({ queryKey: ['user'], queryFn: fetchUser }); 返回

{data.name}

; // ❌ 如果数据未定义则崩溃 } // 正确 - 处理加载状态函数用户配置文件（）{ const { data, isLoading } = useQuery({ queryKey: ['user'], queryFn: fetchUser }); if (isLoading) 返回 ; // ✅ 返回

{data.name}

; } **❌不要忘记查询键是依赖项：** // 错误 - 查询键中缺少依赖项函数 UserPosts({ userId, filter }: Props) { const { 数据 } = useQuery({ queryKey: ['posts'], // ❌ 缺少 userId 和过滤器 queryFn: () => fetchUserPosts(userId, 过滤器), }); } // 正确 - key 中的所有依赖项函数 UserPosts({ userId, filter }: Props) { const { 数据 } = useQuery({ queryKey: ['posts', userId, filter], // ✅ queryFn: () => fetchUserPosts(userId, 过滤器), }); } **❌不要直接改变查询数据：** // 错误 - 改变缓存数据 const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos }); data.push(newTodo); // ❌ 直接改变缓存 // 正确 - 使用 setQueryData queryClient.setQueryData(['todos'], (old = []) => [...old, newTodo]); // ✅ ** ** ## 总结 TanStack Query 是 React 应用程序中服务器状态管理的行业标准解决方案。使用它进行 API 数据获取、缓存、同步和实时更新。它消除了手动状态管理样板，并提供了强大的功能，例如自动后台重新获取、乐观更新、分页和智能缓存管理。 **要点：** * 使用`useQuery`通过自动缓存获取数据 * 使用`useMutation`进行创建/更新/删除操作 * 查询键是缓存管理的基础 * 突变后使查询无效以保持 UI 同步 * 利用乐观更新获得即时 UI 反馈 * 使用 `useInfiniteQuery` 进行分页和无限滚动 * 与 Zustand 结合进行客户端状态管理 * 与 tRPC、REST 和 GraphQL 无缝集成 * 使用 TypeScript 输入所有内容以实现完整的类型安全 * 使用 MSW 进行测试以进行真实的 API 模拟 **渐进式加载模式：** * **入口点**：快速启动和基本设置 * **中级**：查询、突变和缓存管理 * **高级**：乐观更新、SSR、集成和性能如需其他资源，请访问[官方文档]()。 ## 相关技能使用 Tanstack Query 时，这些技能可以增强您的工作流程： * **react** ：用于集成 TanStack Query 的 React 钩子和模式 * **nextjs** ：使用 Next.js 应用程序路由器和服务器组件进行 TanStack 查询 * **zustand** ：补充客户端状态管理（混合状态一起使用） * **测试驱动开发** ：测试查询、突变和缓存行为 [如果部署在您的捆绑包中，则可以获取这些技能的完整文档]

坦斯塔克查询

包含技能