全新 TanStack React Query 集成方案正式发布

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

我们激动地宣布，全新的 TanStack React Query 集成方案已在 tRPC 的 next 版本中推出。相较于传统的 React Query 集成方案，新版方案更加简洁且更贴近 TanStack Query 原生范式。它选择直接采用 TanStack React Query 原生的 QueryOptions 和 MutationOptions 接口，而非通过封装 useQuery 和 useMutation 实现自定义客户端。

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
export function Greeting() {
  const trpc = useTRPC();
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
  // greetingQuery.data === 'Hello Jerry'
  // [...]
}

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
export function Greeting() {
  const trpc = useTRPC();
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
  // greetingQuery.data === 'Hello Jerry'
  // [...]
}

通过新版客户端，我们移除了常令新用户困惑的抽象层，转而提供更直接的 TanStack React Query 工作流。对于熟悉 TanStack 官方文档的开发者而言，这将带来即时的熟悉感。这也意味着我们无需过多 tRPC 文档来解释其原理——当然，我们仍准备了入门指南供您参考。

为何做出这一改变？

您可通过此链接查阅详细的原始 RFC 提案，以下是我们做出改变的核心原因：

• 简洁性：新版客户端更简洁且更契合 TanStack Query 原生范式，为 QueryKeys、QueryOptions 和 MutationOptions 等常用接口提供工厂方法。这降低了学习曲线，您可直接参考官方 TanStack Query 文档

• 熟悉度：新版客户端让已在其他场景使用 TanStack Query 的开发者倍感熟悉，避免因使用 tRPC 而被迫切换语法范式

• React 兼容性：传统集成方案实际违反了 Hook 规则，无法通过正确性检查，且会鼓励传递 Hook 作为 props 等破坏 React Compiler 的模式。新版客户端在这方面更符合 React 最佳实践

• 可维护性：版本同步始终是我们面临的挑战，尤其是当 TanStack Query 的 QueryClient 新增功能时。通过原生接口的精简接入层，我们既能更轻松地支持 React Query，也遵循了 TanStack 维护者推崇的最佳实践

• 社区反馈：传统客户端常为新用户制造理解障碍，但针对新版客户端的 RFC 提案获得了压倒性积极反馈，多数留言用户都期待使用此方案。当然目前并非所有用户都接受新版方案，因此我们将继续维护传统客户端

现有的 tRPC React Query 集成将如何发展？

它不会很快消失！我们承诺将长期维护传统方案，但不再为其增加重大新功能，并将其视为稳定版本。

我们仍建议新项目采用新版 TanStack React Query 集成方案，现有项目可考虑逐步迁移。

如何迁移？

虽然传统客户端将长期维护，但我们建议新项目直接采用新版方案，活跃项目可考虑渐进式迁移。

两个客户端相互兼容且可共存于同一应用，因此您可按自身节奏迁移。我们正在开发自动化迁移工具，并热切期待社区贡献！特别感谢 @reaper 目前为此工具做出的贡献！

👉 阅读迁移文档