TanStack：从工具库到全栈框架的进化

TanStack 是一套为现代 Web 应用程序设计的高质量开源工具套件。迄今为止，其各个模块在 GitHub 上已累计获得超过 10 万颗星和 9500 名关注者。其核心优势在于将 Web 开发中最具挑战性的方面进行模块化和标准化，将它们提炼成一个全面且可用于生产环境的生态系统。

TanStack 的定位

TanStack 的目标不仅仅是成为一个便捷的工具库，它致力于解决现代全栈应用程序中固有的系统性复杂性。

它无缝地将以前分散的流程如路由、数据获取和服务器端渲染，整合成一个统一、连贯的工作流。当处理海量数据集或复杂的表单交互时，你会发现 TanStack 提供的是一个坚如磐石的基础，而不仅仅是一个捷径。它确保"高性能"和"高可靠性"不再是开发者的负担，而是融入到框架的 DNA 之中。

核心模块

为了实现其核心理念并解决 Web 开发中最持久的挑战，TanStack 打造了一套全面的专用工具模块。

TanStack Query

TanStack Query 是使用最广泛的模块，旨在解决全栈开发中最关键的数据流挑战。其标志性特点是"以缓存为中心的数据流"，使数据能够在各种组件之间无缝复用。通过专注于"服务器状态"管理，它将繁琐但高频的任务如获取、缓存、同步和失效转化为一套强大的声明式能力。

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

function UserProfile({ userId }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId], 
    queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
  });

  if (isLoading) return <div>loading...</div>;
  if (error) return <div>error: {error.message}</div>;

  return <div>hello, {data.name}</div>;
}

你所需要做的只是使用声明式的 queryKeys 定义你的数据需求。框架会抽象掉样板代码，如请求去重、缓存失效和自动重试，使你摆脱手动维护加载和错误状态的负担，从而将精力集中在真正重要的地方：业务逻辑。

与替代方案相比，TanStack Query 的核心优势在于将"服务器状态管理"作为一个独立领域进行专业化处理。它消除了像 Redux 这样的通用库所带来的繁琐样板代码和手动开销，同时系统性地解决了那些在手写 useEffect 实现中众所周知难以处理的棘手边界情况，如竞态条件、缓存和重试。其结果是开箱即用的高稳定性和可靠性。

TanStack Router

如果说 TanStack Query 高效稳定地处理数据流，那么 TanStack Router 就像是指挥家，在更高层面上编排 Query。因为路由器知道用户的目的地，它利用 loader 钩子在导航之前或期间发出数据获取指令。

在传统的开发模式中，路由器只负责切换组件，然后组件通过 useEffect 触发 Query。这常常导致"网络瀑布流"。

而使用 TanStack Router，只需将鼠标悬停在链接上就可以触发 Query 预取数据。然后路由器在数据准备好后一次性渲染完整页面，从而显著提升感知速度。

// 1. Define Query options (reusable logic)
const userQueryOptions = (id) => ({
  queryKey: ['user', id],
  queryFn: () => fetchUser(id),
});

// 2. Configure the loader at the route level
const userRoute = createRoute({
  path: '/user/$userId',
  // Key: Prefetch data before the route transition starts and store it in the Query cache
  loader: ({ params }) => queryClient.ensureQueryData(userQueryOptions(params.userId)),
  component: UserComponent,
});

function UserComponent() {
  const { userId } = userRoute.useParams();
  // Since data is already in the cache, it's read synchronously. 
  // No waterfalls, no secondary loading spinners.
  const { data } = useSuspenseQuery(userQueryOptions(userId));
  return <div>{data.name}</div>;
}

强强联合：TanStack Virtual + TanStack Table

TanStack Table 和 TanStack Virtual 的集成，本质上是"数据逻辑"与"渲染性能"之间的强大协同。

作为底层的逻辑引擎，TanStack Table 采用无头设计，专注于复杂的交互逻辑，如排序、筛选、分组和分页，而不限定具体的 UI 实现。

当处理数千行数据时，仅靠逻辑无法解决过多 DOM 节点造成的性能滞后。这时 TanStack Virtual 作为性能加速器登场。通过虚拟化，它确保只渲染用户视口内当前可见的行或单元格。

当两者结合时，Table 提供精确的行模型和状态管理，而 Virtual 以最高效的方式将这些数据喂给浏览器。这种协同在保留完整功能的同时，将渲染开销削减到最低，提供流畅且高性能的用户体验。

import { useReactTable, getCoreRowModel, flexRender } from '@tanstack/react-table';
import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualTable({ columns, data }) {
  const parentRef = React.useRef();

  // 1. Table handles logic: processing data models, sorting, filtering, etc.
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  });

  const { rows } = table.getRowModel();

  // 2. Virtual handles performance: calculating which rows should be rendered in the viewport
  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35, // Estimated row height
  });

  return (
    <div ref={parentRef} style={{ height: '500px', overflow: 'auto' }}>
      <div style={{ height: `${rowVirtualizer.getTotalSize()}px`, position: 'relative' }}>
        {rowVirtualizer.getVirtualItems().map((virtualRow) => {
          const row = rows[virtualRow.index];
          return (
            <div
              key={row.id}
              style={{
                position: 'absolute',
                top: 0,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              {/* 3. Render Table's logical data into the container provided by Virtual */}
              {row.getVisibleCells().map(cell => (
                <span key={cell.id}>
                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
                </span>
              ))}
            </div>
          );
        })}
      </div>
    </div>
  );
}

TanStack Start：全栈拼图

TanStack Start 的推出标志着 TanStack 从实用工具库集合演变为真正的全栈解决方案。它打破了各个模块之间的界限，提供了一条从路由定义、数据获取到 SSR 和客户端交互的路径。

简单来说，它是一个以 TanStack Router 为基础构建的全栈框架。通过深度利用 Router 的状态管理能力，标准化了 SSR、数据加载和导航工作流。开发者不再需要费力拼接各种库，他们可以拥抱"路由即数据边界"的理念。

框架对比

有关 TanStack 模块的更多信息，请访问 TanStack GitHub 仓库。

选型指南：从工具到集成

TanStack 的最大优势之一是其渐进式采用模型，允许开发者通过逐步迁移来增量集成其工具：

• 管理请求和缓存：从 TanStack Query 开始。
• 复杂表格是核心痛点：引入 TanStack Table（如果性能成为瓶颈，则添加 TanStack Virtual）。
• 扩展路由和数据加载：随着项目成熟和路由逻辑变得复杂，评估 TanStack Router。
• 新项目与统一架构：关注 TanStack Start，或使用 EdgeOne Pages 上的 Start 模板快速启动开发。

对于遗留项目，这种"先解决具体痛点，后集成"的策略通常比高风险的全面替换整个框架要稳定得多。

在 EdgeOne Pages 上部署

EdgeOne Pages 为 TanStack Start 全栈框架提供了强大的端到端部署支持。通过深度集成和优化，它有效解决了 SSR 实现、流式响应和路由重写规则等关键技术挑战。
借助预配置的 TanStack 模板，开发者可以在 EdgeOne Pages 上快速体验无缝集成的"开发到部署"工作流。

工作原理：适配原理

EdgeOne Pages 通过专用适配器 @edgeone/tanstack-start 实现 TanStack Start 的无缝平台适配和部署。该适配器是一个 Vite 插件，旨在将 TanStack Start 应用部署到 EdgeOne Pages 平台。它基于 @edgeone/vite-core 库构建，通过声明式配置为 TanStack Start 提供全框架支持。
核心特性

• 🔍 自动检测：自动识别 TanStack Start 项目（支持 React 和 SolidJS）。
• 📦 智能打包：利用 esbuild 结合 NFT（Node File Trace）进行高效的依赖追踪和服务器端代码打包。
• 🛣️ 路由解析：直接从 TanStack Router 自动解析路由配置。
• 🔌 胶水层适配：使用专用的 Server Wrapper 将框架输出与 EdgeOne Function 格式桥接。
• 🌐 边缘优化：生成严格符合 EdgeOne 平台规范的部署产物。

适配器执行工作流

• 静态资源迁移：将静态文件（HTML、CSS、JS 等）从 dist/client 复制到 .edgeone/assets/ 目录。
• 服务器端打包：使用 esbuild 将 dist/server 中的服务器端代码及其依赖打包成单个 handler.js。
• 胶水层生成：创建 Server Wrapper 代码，将框架内部的 fetch 处理程序适配为 EdgeOne Function 格式
• 路由配置解析：分析 routeTree.gen.ts 或路由目录以生成 meta.json，供平台用于智能路由分发。

您可以随时查阅我们的框架指南，获取针对您所选框架的最新兼容性信息和优化建议。