TanStack Query 知识地图

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

TanStack Query 主要管理的是服务端事实在客户端的 cache/projection 与同步生命周期，而不是新的 durable truth。

最重要的判断：queryKey 表达远程数据身份；stale 表达 freshness；setQueryData / invalidateQueries 的选择取决于客户端掌握了多少 authoritative evidence。

---

入门

• TanStack Query 起源与概述 — 历史背景、核心定位、生态全景
• TanStack Query 服务端状态 — ownership、query identity、useQuery/useMutation、stale/fetching 核心心智模型
• queryKey Factory 模式 — 结构化管理 queryKey，避免 identity 缺失与缓存串台

---

缓存管理

• 缓存失效模式 — cancelQueries / setQueryData / removeQueries / invalidateQueries，以及 409 stale conflict 后的同步策略
• 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 server projection 与 ActiveTurn/runtime projection 的边界，以及 terminal reconciliation
• DevTools 调试工具 — @tanstack/react-query-devtools 使用指南

---

实践与迁移

• QueryClient 配置策略 — 全局默认配置、Provider 放置、环境差异化
• 从 useState 迁移 — 四步增量迁移法

---

架构上下文

• 四层状态架构 — URL / Query / Streaming / UI 层，与 server durable authority 的关系
• 派生状态模式 — 从 query data 推导状态
• Zustand 全局状态 — Shared client state container 与 server projection 的 ownership 分工
• 服务端状态与客户端状态的区分 — 先判断 owner/authority，再选择容器
• Durable SSE Recovery with after_seq — streaming transport 断线后如何用 run-aware cursor 恢复

---

60 秒复习

queryKey   = 远程数据身份/cache address
queryFn    = 如何取得它
QueryCache = server state 的客户端 projection
staleTime  = freshness policy，不是 truth policy
isFetching = 当前正在同步，不等于没有 data

完整 authoritative mutation response
→ setQueryData 可行

不知道完整后果 / 409 stale revision
→ invalidate + refetch

---

Related notes

• 前端工程化 MOC
• React MOC