TanStack Query（Angular）是否替代全局状态管理：服务端状态与客户端状态的边界

TanStack Query 的定位是服务端状态（server-state）库，而非 Redux、MobX、Zustand 那样的客户端状态（client-state）管理工具。本篇以 Angular 生态（@tanstack/angular-query-experimental）为例，澄清它与全局状态管理器的真实关系：哪些异步样板代码可以被 injectQuery / injectMutation 取代、迁移后剩余的全局状态通常有多小，以及它明确不能替代的场景。

先厘清概念：服务端状态 vs 客户端状态

要回答“是否替代”，必须先区分两类状态：

• TanStack Query 是服务端状态库，负责管理浏览器与服务端之间的异步操作：请求缓存、加载/错误/成功状态、失效与重取（refetch）、窗口聚焦刷新、离线重试等；
• Redux、MobX、Zustand、NgRx 等是客户端状态库，它们可以存异步数据，但用于管理服务端数据时效率远不如专门的服务端状态工具。

基于这两点，官方文档（Angular 版文档入口，与 React 版原文 同源）给出的直接结论是：

TanStack Query 替代的是客户端状态管理器中用于管理缓存数据的那些样板代码和相关接线，把它们压缩成寥寥几行代码。

换句话说，它替代的不是状态管理器本身，而是“用状态管理器硬扛异步数据”所产生的那部分复杂度。

一个构造示例：迁移前后剩余的全局状态对比

文档中的构造示例展示了典型应用的全局状态。假设某个全局状态管理器里维护着：

const globalState = {
  projects,
  teams,
  tasks,
  users,
  themeMode,
  sidebarStatus,
}

其中 projects、teams、tasks、users 四类数据本质是服务端状态——它们来自接口、有缓存/失效/重取的生命周期，却混在了客户端状态管理器里。把这些资产迁移到 TanStack Query 之后，剩余的全局状态大致只剩：

const globalState = {
  themeMode,
  sidebarStatus,
}

对绝大多数应用而言，迁移完所有异步代码后，真正需要全局可访问的客户端状态通常非常小。

在 Angular 中这些样板代码具体指什么

文档列举了迁移后可以删掉的样板：连接层（Connectors）、Action Creators、中间件、Reducer、Loading/Error/Result 状态、Context。落到 Angular 的具体写法上，projects、tasks 这类数据从“store + effect + selector”的接线，变成几行 injectQuery / injectMutation 调用。以 tasks 为例（写法参照 Angular Quick Start 与 injectQuery API 参考）：

import { Component, Injectable, inject } from '@angular/core'
import { HttpClient } from '@angular/common/http'
import { lastValueFrom } from 'rxjs'
import {
  injectMutation,
  injectQuery,
  QueryClient,
} from '@tanstack/angular-query-experimental'

@Component({
  template: `
    <div>
      <button (click)="onAddTask()">Add Task</button>
      <ul>
        @for (task of query.data(); track task.title) {
          <li>{{ task.title }}</li>
        }
      </ul>
    </div>
  `,
})
export class TasksComponent {
  taskService = inject(TaskService)
  queryClient = inject(QueryClient)

  // 取代“selector 读 tasks + loading/error 状态”的一整套接线
  query = injectQuery(() => ({
    queryKey: ['tasks'],
    queryFn: () => this.taskService.getTasks(),
  }))

  // 取代“dispatch action -> middleware -> reducer -> 再触发请求”的链路
  mutation = injectMutation(() => ({
    mutationFn: (task: Task) => this.taskService.addTask(task),
    onSuccess: () => {
      this.queryClient.invalidateQueries({ queryKey: ['tasks'] })
    },
  }))

  onAddTask() {
    this.mutation.mutate({ title: 'Do Laundry' })
  }
}

@Injectable({ providedIn: 'root' })
export class TaskService {
  private http = inject(HttpClient)

  getTasks(): Promise<Task[]> {
    return lastValueFrom(
      this.http.get<Task[]>('https://jsonplaceholder.typicode.com/todos'),
    )
  }

  addTask(task: Task): Promise<Task> {
    return lastValueFrom(
      this.http.post<Task>('https://jsonplaceholder.typicode.com/todos', task),
    )
  }
}

这段代码背后是 @tanstack/angular-query-experimental 包的实际 API 面：从源码入口 packages/angular-query-experimental/src/index.ts 可以看到，它 re-export 了 @tanstack/query-core 的全部内容，并导出 injectQuery、injectMutation、injectQueryClient、provideTanStackQuery、queryFeature 等符号；缓存、重取、失效等核心机制全部来自 query-core 这一框架无关层。也就是说，上面被删掉的“Loading/Error/Result 状态”“失效重取”等逻辑，现在由 QueryClient 统一承担，而 injectQuery 返回的是可直接在模板中调用的信号（signal），无需手写任何状态切换代码。

需要强调的是前提条件：该包目前处于 experimental 阶段，minor 和 patch 版本都可能出现破坏性变更；生产环境建议锁定到 patch 级版本（见 Quick Start 的说明）。

剩下的全局状态还要不要状态管理器？

删掉上述接线后，自然会问：“为了这点小小的全局状态，还值得继续用客户端状态管理器吗？”文档的答复是：这取决于你自己（And that's up to you!）。

但有一条边界非常明确：

仍有一些场景，应用确实存在大量纯同步、纯客户端的状态（例如可视化设计器、音乐制作类应用），这种情况下你大概率仍然需要一个客户端状态管理器。此时要注意：TanStack Query 不是本地/客户端状态管理的替代品，不过它与大多数客户端状态管理器可以零冲突地共存使用。

判断口径可以归纳为两条：

1. 状态的来源是服务端（会过期、要重取、要失效、要乐观更新）→ 交给 TanStack Query，如示例中的 projects / teams / tasks / users；
2. 状态是纯客户端同步逻辑（UI 偏好、画布内选区、编辑缓冲区）→ 保留状态管理器或组件本地状态，如示例中的 themeMode / sidebarStatus。

小结

TanStack Query 的角色清晰且克制：移除应用中的异步接线与样板代码，用几行 injectQuery / injectMutation 调用取代它们。它不是 Redux/MobX 的替代品，而是与它们分层的协作关系——服务端状态归它管，剩下的少量纯客户端状态去留由团队自行权衡。若你的项目里大量异步数据正被塞进全局 store 并承担手写 loading/error 状态，这个迁移示例就是值得直接参照的起点；更多可运行示例可参考仓库中的 Angular 示例工程。