一、引言与基础 (Introduction & Basics)

1.1 TanStack Query 概述

TanStack Query（前身为 React Query，v4 版本起更名）是一个强大的 异步状态管理库（Asynchronous State Management），专门用于简化获取、缓存、同步和更新服务器状态的过程（服务器状态是最常见的应用场景，但并非唯一用途）。服务器状态通常指那些需要从后端 API 获取并在前端进行管理的数据。

核心优势:

• 简化数据获取: TanStack Query 将复杂的数据获取逻辑（如加载状态、错误处理、重试）与 UI 组件解耦，开发者只需声明所需数据即可。
• 智能缓存管理: 内置强大的缓存机制，如 "stale-while-revalidate" 策略。它会优先展示缓存数据（提升感知速度），同时在后台检查并获取最新数据，优化用户体验和应用性能。
• 后台自动更新: 能够在后台静默地检查数据是否过期，并在合适的时机（如窗口重新聚焦、网络重连、固定时间间隔）自动更新，确保数据的相对新鲜度。
• 与框架无关: 其核心引擎 (@tanstack/query-core) 是一个独立的包，可以与 React, Solid, Vue, Svelte 等多种前端框架或原生 JavaScript 配合使用。
• 优秀的开发体验: 提供 TanStack Query DevTools，这是一个可视化工具，可以方便地检查查询状态、数据和缓存内容，极大地简化了调试过程。
• 减少样板代码: 自动化处理了传统数据获取中常见的加载、错误、缓存、同步等状态管理，使开发者能更专注于业务逻辑。

1.2 @tanstack/query-core：核心引擎

@tanstack/query-core 是 TanStack Query 的核心引擎，包含了所有与 UI 框架无关的基础逻辑和状态管理机制。你可以将其视为库的"大脑"——一个 headless（无头/与 UI 无关）的状态管理内核。

• 角色: 一个纯粹的、与界面无关的状态管理内核。"headless" 意味着它不包含任何 UI 渲染逻辑，只负责数据状态的管理，因此可以被任何前端框架适配和使用。
• 作用:
  • 实现了所有核心功能：管理数据请求 (Query)、数据修改操作 (Mutation)、缓存 (QueryCache, MutationCache)、状态更新、后台重新获取、垃圾回收等。
  • 是所有框架适配器（如 @tanstack/react-query, @tanstack/vue-query）的基础。这些适配器将 query-core 的能力与特定框架的响应式系统和生命周期相结合。

1.3 整体架构与核心模块

TanStack Query 采用了清晰的分层设计：

• 核心层 (@tanstack/query-core): 负责所有平台无关的底层逻辑和状态管理。
• 适配器层 (@tanstack/[framework]-query): 为特定前端框架（如 React, Vue）提供封装，将核心功能与框架的特性（如 Hooks, Composition API）集成，提供更符合框架习惯的 API。

@tanstack/query-core 主要由以下模块构成：

• QueryClient: 核心管理器。作为配置中心和 API 入口，管理全局配置及下属的 QueryCache 和 MutationCache 实例。通常在应用中创建单个实例。
• QueryCache: 查询缓存。负责存储和管理应用中所有的 Query 实例。
• MutationCache: 变更缓存。负责存储和管理应用中所有的 Mutation 实例。
• Query: 查询单元。代表一个独立的异步数据查询任务，包含其状态（status, fetchStatus）、数据、元数据以及获取数据的函数 (queryFn) 和配置。
• Mutation: 变更单元。代表一个独立的异步数据修改操作（如 POST, PUT, DELETE），包含其状态和执行逻辑 (mutationFn

下图展示了 TanStack Query 的核心组件如何协同工作，从用户界面的数据请求（通过适配器如 useQuery）到 QueryObserver 监听 Query 状态，再到 Query 通过 queryFn 从后端 API 获取数据，以及变更操作 (Mutation) 的流程：

• Retryer: 重试处理器。封装了处理查询或变更失败时的自动重试逻辑，支持配置重试次数和延迟。
• NotifyManager: 通知管理器。通过批处理（batching）优化状态更新通知，将短时间内的多个通知合并处理，减少不必要的重复渲染。
• FocusManager, OnlineManager: 环境状态管理器。分别监测浏览器窗口/标签页的焦点状态和网络的在线状态。当状态变化时（如窗口聚焦、网络恢复），可以触发数据的自动重新获取。

与前端框架的集成: query-core 通过适配器层与前端框架集成。例如，React 中的 useQuery Hook 内部会创建并管理一个 QueryObserver 实例。该 QueryObserver 订阅 query-core 中相应 Query 的状态变化。当 Query 状态更新时，QueryObserver 接收通知，计算新结果，并将这些结果传递给 React 组件，触发重新渲染。这种设计保证了核心逻辑的可重用性和框架无关性。

1.4 核心设计模式

TanStack Query 的实现中运用了多种经典设计模式：

• 观察者模式 (Observer Pattern): QueryObserver 是此模式的核心体现。Query 实例是被观察者（Subject），当其状态变化时，会通知所有订阅它的 QueryObserver（Observer）。QueryObserver 随后处理并通知最终的订阅者（如 UI 组件）。
• 发布-订阅模式 (Publish-Subscribe Pattern): 在缓存 (QueryCache, MutationCache) 和管理器 (NotifyManager, FocusManager, OnlineManager) 中广泛使用。组件或模块可以向某个中心（如 QueryCache 的事件系统）发布事件（如查询更新），而其他订阅了该事件的组件或模块则会收到通知，实现了模块间的解耦。NotifyManager 使用此模式调度和批量处理通知。
• 状态模式 (State Pattern): Query 和 Mutation 内部维护着复杂的状态机。例如，Query

1.5 query-core 源码结构

@tanstack/query-core 的主要源代码位于 packages/query-core/src/ 目录。了解核心文件的职责有助于深入理解其工作原理：

• queryClient.ts: 定义核心 QueryClient 类，是应用的入口点和配置中心，管理 QueryCache 和 MutationCache，并提供主要的 API 方法（如 fetchQuery, invalidateQueries, setQueryData 等）。
• queryCache.ts: 定义 QueryCache 类，负责管理所有 Query 实例的生命周期（创建、存储、查找、移除）和事件通知。
• mutationCache.ts: 定义 MutationCache 类，负责管理所有 Mutation 实例的生命周期和事件通知，并控制变更的执行顺序。
• query.ts: 定义 Query 类，代表一个独立的查询任务，包含其 queryKey

理解这些核心文件的职责，将有助于后续更深入地探索 TanStack Query 的源码。