在 React 和 Next.js 中配置 tRPC

安装 @trpc/server 和 @trpc/client 这两个 tRPC 核心软件包。添加 @trpc/react-query 作为 React 钩子适配器，并添加 @tanstack/react-query 作为为这些钩子提供支持的对等依赖。

对于 Next.js API 路由集成，较新版本的 tRPC 不需要额外的适配器软件包。

创建 server/trpc.ts 文件，并调用 initTRPC.create() 获取 t 对象。将 t.router 导出为 router，将 t.procedure 导出为 publicProcedure，并将 t.mergeRouters 导出为实用工具。

initTRPC 工厂接受一个上下文类型泛型，用于定义每个过程的 ctx 参数中可用的数据。

您可以将 .input(zodSchema).query(handler) 或 .mutation(handler) 链接到 publicProcedure 上来定义过程。例如，对于一个简单的问候端点：publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name)。

Zod 模式同时为输入提供 TypeScript 类型和运行时验证。

使用 router() 函数创建 appRouter：router({ hello: helloHandler, users: usersRouter })。嵌套路由器可以让您将过程按领域（用户、文章、评论）组织到不同文件中。

导出 AppRouter 类型：export type AppRouter = typeof appRouter。客户端将导入的就是这个类型。

创建 app/api/trpc/[trpc]/route.ts（应用路由）或 pages/api/trpc/[trpc].ts（页面路由）。使用 @trpc/server/adapters/fetch 中的 fetchRequestHandler，通过这个单一的全匹配路由处理所有 tRPC 请求。

将路由器、createContext 函数以及请求和响应对象传递给 fetchRequestHandler。

创建 utils/trpc.ts 文件。调用 createTRPCReact<AppRouter>() 来创建具有类型的 trpc 客户端对象。该对象中的每个属性都对应路由器中的一个过程，并分别提供 React 查询钩子。

AppRouter 类型从您的服务器文件导入；TypeScript 会沿着导入链验证所有使用方式。

在应用布局或 _app.tsx 中，创建一个 QueryClient 实例，并使用 trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }) 创建一个 tRPC 客户端实例。

使用 trpc.Provider（传入 tRPC 客户端）和 QueryClientProvider 将组件树包裹起来。两个提供程序缺一不可。

在任意组件中：const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' })。这个钩子具有完整类型：data 是从 hello 过程推断出的返回类型，而输入对象会根据 Zod 模式进行类型检查。

传入错误的输入类型会导致 TypeScript 编译错误，而不是运行时错误。

要使 tRPC 正常工作，客户端必须能够从服务器文件导入类型。在 Next.js 项目中，服务器代码和客户端代码使用同一个 TypeScript 编译过程，因此导入可以直接生效。

在包含独立软件包的单仓库中，请在 tsconfig.json 中配置 TypeScript 项目引用或路径别名，使其指向服务器软件包。

tRPC 处理程序在服务器上运行（作为 Next.js API 路由或边缘函数）。tRPC 客户端在浏览器中运行。TypeScript 会在构建时处理类型级导入，而不会在浏览器中执行服务器代码。

客户端只会导入 AppRouter 类型，而不会导入实际实现，因此不会有服务器机密泄露到客户端软件包中。

启动 Next.js 开发服务器并打开浏览器控制台。trpc.hello.useQuery 调用应记录服务器响应。检查网络选项卡，查看发送到 /api/trpc/hello 的 HTTP 请求，以及作为查询参数批量传入的输入。

默认的 httpBatchLink 会将多个并发请求合并为一个 HTTP 调用，您可以在网络瀑布图中看到这一点。

哪个函数会初始化 tRPC 实例，并提供路由器和过程工厂？

安装 @trpc/server、@trpc/client、@trpc/react-query 和 @tanstack/react-query。使用 initTRPC.create() 初始化 tRPC，定义过程，并导出 AppRouter 类型。创建 Next.js API 全匹配路由，设置 TRPCProvider 和 QueryClientProvider，然后使用 trpc.procedureName.useQuery() 调用过程。

TypeScript 会在编译时强制检查完整的客户端—服务器契约，无需代码生成。