TanStack Query 知识地图
TanStack Query 专题知识索引，覆盖核心概念、缓存管理、集成模式、错误处理、性能优化与工程实践。
#type / moc
#status / evergreen
#tech / dev / frontend
#resource / react
TanStack Query 知识地图
React 生态中最流行的服务端状态管理库，解决 API 数据的缓存、同步、失效与竞态问题。
入门
- TanStack Query 起源与概述 — 历史背景、核心定位、生态全景
- TanStack Query 服务端状态 — useQuery / useMutation / queryKey / staleTime 基础用法
- queryKey Factory 模式 — 结构化管理 queryKey，避免硬编码
缓存管理
- 缓存失效模式 — cancelQueries / setQueryData / removeQueries / invalidateQueries 四大 API
- gcTime vs staleTime 辨析 — 两个最容易混淆的时间参数
- placeholderData 与 keepPreviousData — 切换查询参数时避免 loading 闪烁
请求控制
- 请求取消与 AbortController — queryFn 的 signal 参数，防止组件卸载后的无效请求
- 错误处理与重试策略 — retry / retryDelay / 全局错误处理 / Error Boundary 集成
- 网络状态感知 — onlineManager、离线重试与网络恢复策略
高级查询模式
- Dependent 与 Parallel Queries — 依赖查询与并行查询
- select 与数据转换 — 在 cache 层面做数据转换，减少 re-render
- useInfiniteQuery 分页与无限滚动 — 分页加载、无限滚动、虚拟化集成
- Mutation 完整生命周期 — onMutate / onError / onSettled 全流程
集成模式
- 预取策略与 Suspense — prefetchQuery / useSuspenseQuery / 路由级预取
- Suspense 集成 — useSuspenseQuery / useSuspenseInfiniteQuery / Suspense Boundary
- 与 SSE 流式数据集成 — 流式场景下 Query cache 与 SSE 的协调
- DevTools 调试工具 — @tanstack/react-query-devtools 使用指南
实践与迁移
- QueryClient 配置策略 — 全局默认配置、Provider 放置、环境差异化
- 从 useState 迁移 — 四步增量迁移法
架构上下文
- 四层状态架构 — URL / Query / Streaming / UI 四层分工
- 派生状态模式 — 从 query data 推导状态
- Zustand 全局状态 — 客户端状态的分工
- 服务端状态与客户端状态的区分