tRPC v10 到 v11 迁移指南：核心变更与升级要点-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00447/article/details/148325826

tRPC v10 到 v11 迁移指南：核心变更与升级要点

trpc trpc/trpc 是一个用于 Rust 语言编写的 RPC 框架，支持服务端和客户端的多种通信协议和数据格式。适合在分布式系统中实现服务间的通信。特点是提供了高效的通信协议、简单易用的 API 和良好的可扩展性。项目地址: https://gitcode.com/gh_mirrors/tr/trpc

前言

tRPC 作为现代 TypeScript 全栈开发的重要工具，其 v11 版本带来了一系列令人兴奋的新特性和改进。本文将从技术专家的角度，系统性地梳理从 v10 升级到 v11 的关键变化点，帮助开发者顺利完成迁移。

版本状态说明

当前 v11 版本处于稳定可用状态，适合在生产环境中使用。但需要注意的是，在正式发布 11.0.0 之前，API 仍可能发生小的破坏性变更。npm 上的包目前使用 next 标签发布。

安装与升级

升级到 v11 需要更新相关依赖包：

npm install @trpc/server@next @trpc/client@next @trpc/react-query@next @trpc/next@next @tanstack/react-query@latest @tanstack/react-query-devtools@latest

核心变更详解

1. 全新的 TanStack React Query 集成

v11 引入了全新的 TanStack React Query 集成方案，这是本次升级中最值得关注的改进之一。新集成提供了更简洁的 API 设计和更好的性能表现。

2. 服务器端终止订阅功能

现在可以从服务器端主动终止订阅连接，这为资源管理和连接控制提供了更大的灵活性：

const myRouter = router({
  sub: publicProcedure.subscription(async function* (opts) {
    for await (const data of on(ee, 'data', {
      signal: opts.signal,
    })) {
      const num = data[0] as number | undefined;
      if (num === undefined) {
        // 这将终止客户端订阅并触发 onComplete 回调
        return;
      }
      yield num;
    }
  }),
});

3. 路由懒加载支持

v11 新增了对路由懒加载的支持，这对于大型应用和代码分割场景特别有用。现在可以按需加载路由模块，减少初始加载时间。

4. 独立适配器的 basePath 支持

独立适配器现在支持 basePath 选项，可以方便地处理位于特定路径下的请求。

5. HTTP/2 服务器支持

新增了对 HTTP/2 服务器的原生支持，可以通过 createHTTP2Handler 和 createHTTPServer 函数创建 HTTP/2 服务器。

6. 嵌套数据中的 Promise 支持

httpBatchStreamLink 现在支持在嵌套数据结构中嵌入 Promise，使得复杂异步数据结构的处理更加灵活：

const router = router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(), // 直接嵌入 Promise
    };
  }),
});

7. TypeScript 版本要求提升

v11 要求 TypeScript 版本至少为 5.7.2。如果编辑器显示 any 类型，可能是因为编辑器没有使用项目中的 TypeScript 版本。

对于 VSCode 用户，建议在 .vscode/settings.json 中添加以下配置：

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

8. 服务器发送事件(SSE)支持

v11 引入了对 SSE 的原生支持，这意味着现在可以不需要 WebSocket 服务器就能实现实时更新。客户端还支持自动重连和恢复功能。

9. HTTP 流式响应支持

新增了通过 HTTP 流式传输查询和变更结果的能力。现在查询和变更解析器可以是 AsyncGenerator，支持 yield 操作或返回可延迟的 Promise。

10. 显式 Content-Type 检查

现在对 POST 请求的 Content-Type 头进行了显式检查。如果发送的 Content-Type 不匹配预期值，将返回 415 Unsupported Media Type 错误。

重要破坏性变更

1. 数据转换器(Transformer)位置变更

数据转换器现在需要在 links 数组中配置，而不是在初始化 tRPC 客户端时：

httpBatchLink({
  url: '/api/trpc',
  transformer: superjson, // 必须在此处添加
});

2. React Query 升级到 v5

tRPC v11 要求使用 TanStack React Query v5，请参考其官方迁移指南进行升级。

3. Node.js 版本要求提升

现在要求 Node.js 18 或更高版本，因为新增了对 FormData、File、Blob 和 ReadableStream 的支持。

4. 内部类型重构

重命名了一些内部类型，如 createTRPCProxyClient 改为 createTRPCClient，createProxySSGHelpers 改为 createSSGHelpers 等。

新增功能与改进

1. 重试链接(retryLink)

新增了 retryLink，可以配置失败操作的重试策略。

2. 双向无限查询

新增了对双向无限查询的支持，增强了分页功能。

3. 简化的路由定义

现在支持更简洁的路由定义方式：

const appRouter = router({
  // 简写形式创建子路由
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // 传统形式仍然可用
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});