practical-react-query

React Query 指南

本技能为使用 React Query（TanStack Query）构建具备异步状态管理能力的现代 React 应用提供全面指导。

何时使用此技能

在需要以下方面的帮助时使用此技能：

• 设置和配置 React Query
• 数据获取、缓存和同步
• 变更和乐观更新
• 错误处理和重试策略
• TypeScript 集成
• 测试 React Query 代码
• 性能优化
• 高级模式和最佳实践

主题

根据需要阅读相关参考文件：

入门

主题	描述	文件
实用 React Query	核心概念、默认值、查询键、自定义钩子	01-practical-react-query.md
为什么使用 React Query	采用 React Query 的优势和原因	23-why-use.md
何时不需要	React Query 功能过剩时的简单替代方案	21-when-not-needed.md

核心概念

主题	描述	文件
查询键	用于缓存、重新获取和失效处理的键结构	08-query-keys.md
查询函数上下文	从查询键中提取参数	09-query-function-context.md
查询选项 API	代码组织和类型推断	24-query-options-api.md
状态管理器	将 React Query 用作异步状态管理器	11-state-manager.md

数据处理

主题	描述	文件
数据转换	在 queryFn、渲染或 select 中转换数据	02-data-transformations.md
占位数据和初始数据	预填充缓存，改善用户体验	10-placeholder-initial-data.md
填充缓存	预先填充查询缓存	18-seeding-cache.md
选择器	用于部分订阅的高级选择器模式	28-selectors.md

变更与更新

主题	描述	文件
变更	useMutation、乐观更新、失效处理	13-mutations.md
自动失效	自动查询失效模式	25-auto-invalidation.md
并发乐观更新	处理并发乐观更新	27-concurrent-optimistic.md

状态与错误处理

主题	描述	文件
状态检查	加载状态、后台错误	04-status-checks.md
错误处理	错误边界、重试策略	12-error-handling.md

性能

主题	描述	文件
渲染优化	notifyOnChangeProps、跟踪查询、结构共享	03-render-optimizations.md
无限查询	分页、无限滚动	26-infinite-queries.md

集成

主题	描述	文件
TypeScript	泛型、类型收窄、enabled 选项类型	06-typescript.md
类型安全	高级 TypeScript 模式	20-type-safe.md
React Router	数据加载、导航集成	17-react-router.md
React Context	与 React Context 结合使用	22-context.md
WebSockets	实时数据同步	07-websockets.md
表单	表单集成、处理表单状态	15-forms.md

高级

主题	描述	文件
内部机制	QueryClient、QueryCache、QueryObserver	19-internals.md
离线支持	持久化、离线变更	14-offline.md
测试	模拟网络请求、集成 MSW	05-testing.md
常见问题	常见问题解答	16-faqs.md

快速参考

基本查询

import { useQuery } from "@tanstack/react-query";

function Component() {
  const { data, isLoading, error } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodos,
  });
}

基本变更

import { useMutation, useQueryClient } from "@tanstack/react-query";

function Component() {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: addTodo,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["todos"] });
    },
  });
}

查询客户端设置

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  );
}