tRPC 解决的问题

当您使用 TypeScript 构建 REST API 时，服务端会定义响应结构。客户端必须手动创建匹配的 TypeScript 类型。随着 API 演进，这些类型会逐渐发生漂移；由于类型定义位于不同的软件包中，编译器无法捕获这种不匹配。

服务端重命名字段后，客户端就会出现一个静默的运行时错误。

GraphQL 可以通过 graphql-codegen 之类的工具从模式生成 TypeScript 类型，从而解决类型漂移问题。这种方式效果很好，但也会增加复杂性：需要单独的查询语言（GraphQL SDL）、构建流程中的代码生成步骤，以及模式管理工具。

对于已经投入使用 GraphQL 的团队，代码生成是正确的选择。对于希望获得类型安全、却不想承担 GraphQL 额外开销的团队，tRPC 提供了另一种方案。

tRPC 的方法简单得近乎彻底：在服务端将 API 过程定义为 TypeScript 函数，导出路由器类型，然后在客户端导入该类型。不需要代码生成，也不需要单独的模式语言。

TypeScript 编译器本身会在构建时强制检查客户端与服务端之间的契约。

tRPC 要求服务端和客户端通过 TypeScript 导入共享类型。在单仓库中，这种方式非常自然；Turborepo、Nx 和 pnpm workspaces 都允许服务端和客户端作为相互导入的独立软件包存在。

如果后端和前端完全分离，您需要将路由器类型发布为共享软件包。虽然这会增加一个发布步骤，但仍然不需要代码生成。

在服务端，您需要定义路由器并导出其类型：export type AppRouter = typeof appRouter。在客户端，您导入该类型并创建类型化客户端：createTRPCReact()。客户端可以准确知道有哪些过程，以及这些过程的输入和输出类型。

如果在服务端重命名某个过程，客户端会立即显示 TypeScript 错误。

由于 tRPC 直接使用 TypeScript 的类型系统，您的编辑器会在客户端为过程名称、输入结构和返回类型提供完整的自动补全。重命名过程属于 TypeScript 重命名重构，而不是在整个代码库中手动搜索并替换。

在实际使用中，这种开发者体验的改进是 tRPC 最受好评的特性。

默认情况下，tRPC 使用 HTTP 作为传输方式。每次过程调用都是一个 HTTP 请求。tRPC 也支持使用 WebSockets 进行订阅。传输方式属于实现细节；无论使用哪种传输方式，客户端 API 都完全相同。

您还可以使用 REST 适配器，将 tRPC 过程公开为传统 REST 端点，以兼容非 tRPC 客户端。

tRPC 可以作为中间件用于 Express、Fastify 和 Hono。在 Next.js 中，它可以通过 API 路由处理程序进行集成。create-t3-app 起始模板（T3 Stack）将 tRPC、Prisma、NextAuth 和 Tailwind 组合成一个全栈 Next.js 模板。

T3 Stack 是最受欢迎的 tRPC 起点，并展示了适用于生产环境的模式。

另一种类型安全的 REST 方案是定义 Zod 模式，自动生成 OpenAPI 规范，再根据该规范生成 TypeScript 类型。这样可以提供一份非 TypeScript 客户端也能使用的 API 契约。

tRPC 更简单，但仅限 TypeScript。OpenAPI + Zod 会增加复杂性，却能生成公开的 API 契约。对于内部 TypeScript 到 TypeScript 的通信，请选择 tRPC；对于公开 API，请选择 OpenAPI。

当您需要供第三方使用的公开 API、使用其他语言编写的移动客户端，或需要稳定版本化契约的合作伙伴时，tRPC 不能替代 REST。它专门适用于拥有全栈类型安全的 TypeScript 单仓库。

理解这一适用范围，可以避免在 REST 或 GraphQL 更合适的场景中采用 tRPC。

运行 npm create t3-app@latest 会搭建一个预先配置好 Next.js、tRPC、Prisma、NextAuth.js、Tailwind CSS 和 TypeScript 的项目。生成的代码展示了路由器结构、上下文创建和客户端设置。

研究这个脚手架是了解 tRPC 各个组成部分如何在真实应用中协同工作的最快途径。

tRPC 通过直接导入路由器的 TypeScript 类型来共享类型，从而消除代码生成，解决 TypeScript 客户端与服务器之间的类型漂移问题。它适用于单仓库，并能与 Next.js、Express、Fastify 和 Hono 集成。T3 Stack（create-t3-app）是标准的生产级入门项目。

tRPC 仅支持 TypeScript，最适合内部全栈应用，而不适合公共 API。