进阶 trpc.io 2026-10-12 05:42:24 · 33 阅读

第9章 Fastify Adapter 适配器

# 第9章 Fastify Adapter 版本:11.xFastify Adapter ## 示例应用 入门 Fastify adapter 最好的方式是先看看示例应用。 | 描述 | 链接 | | --- | --- | | 带 WebSocket 的 Fastify 服务器 | CodeSandbox | | Node 中的简易 tRPC 客户端 | 源码 | ## 如何在 Fastify 中使用 tRPC ### 安装依赖 ```bash yarn add @trpc/server fastify zod ``` ⚠️ Fastify 版本要求 tRPC v11 的 Fastify adapter 需要 Fastify v5 及以上版本。使用 Fastify v4 可能导致请求返回空响应且不报错。 Zod 并非必需依赖,但下面的示例 router 中会用到。 ### AI Agents 如果你使用 AI 编程助手,可以安装 tRPC skills 以获得更好的代码生成效果: ```bash npx @tanstack/intent@latest install ``` ### 创建 router 首先需要一个 router 来处理你的 queries、mutations 和 subscriptions。下面是一个示例 router,把它保存到名为 `router.ts` 的文件中。 ```ts router.ts import { initTRPC } from '@trpc/server'; import { z } from 'zod'; type User = { id: string; name: string; bio?: string; }; const users: Record = {}; export const t = initTRPC.create(); export const appRouter = t.router({ getUserById: t.procedure.input(z.string()).query((opts) => { return users[opts.input]; // input type is string }), createUser: t.procedure .input( z.object({ name: z.string().min(3), bio: z.string().max(142).optional(), }), ) .mutation((opts) => { const id = Date.now().toString(); const user: User = { id, ...opts.input }; users[user.id] = user; return user; }), }); // export type definition of API export type AppRouter = typeof appRouter; ``` 如果你的 router 文件变得太大,可以把它拆分成多个子 router,各自放在独立文件中,然后再合并到一个根 `appRouter` 中。 ### 创建 context 接下来需要创建一个 context,它会为每个请求生成。下面是一个示例 context,保存到名为 `context.ts` 的文件中: ```ts context.ts import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify'; export function createContext({ req, res }: CreateFastifyContextOptions) { const user = { name: req.headers.username ?? 'anonymous' }; return { req, res, user }; } export type Context = Awaited>; ``` ### 创建 Fastify 服务器 tRPC 内置了 Fastify adapter,可以把你的 tRPC router 转换成一个 Fastify plugin。为避免大批量请求出错,请确保按下面的示例把 Fastify 的 `maxParamLength` 选项设置为一个合适的值。 tip 由于 Fastify plugin 系统和类型推断的限制,某些配置(例如 `onError`)的类型可能无法正确推断。你可以加上 `satisfies FastifyTRPCPluginOptions['trpcOptions']` 来帮助 TypeScript 获得正确的类型。 ```ts server.ts import { fastifyTRPCPlugin, FastifyTRPCPluginOptions, } from '@trpc/server/adapters/fastify'; import fastify from 'fastify'; import { createContext } from './context'; import { appRouter, type AppRouter } from './router'; const server = fastify({ routerOptions: { maxParamLength: 5000, }, }); server.register(fastifyTRPCPlugin, { prefix: '/trpc', trpcOptions: { router: appRouter, createContext, onError({ path, error }) { // report to error monitoring console.error(`Error in tRPC handler on path '${path}':`, error); }, } satisfies FastifyTRPCPluginOptions['trpcOptions'], }); (async () => { try { await server.listen({ port: 3000 }); } catch (err) { server.log.error(err); process.exit(1); } })(); ``` 现在你的 endpoints 已经可以通过 HTTP 访问了! | Endpoint | HTTP URI | | --- | --- | | getUserById | `GET http://localhost:3000/trpc/getUserById?input=INPUT` |

其中 INPUT 是一个 URI 编码的 JSON 字符串。向 createUser 端点发送 POST 请求至 http://localhost:3000/trpc/createUser。

req.body 的类型为 User 启用 WebSockets​ Fastify adapter 通过 @fastify/websocket 插件支持 WebSockets。除了上述步骤,只需安装依赖项、在路由中添加订阅并启用插件的 useWSS 选项。@fastify/websocket 最低版本要求为 3.11.0。 安装依赖项​ bash yarn add @fastify/websocket 导入并注册 @fastify/websocket​ ts import ws from '@fastify/websocket'; server.register(ws); 添加订阅​ 编辑前几步创建的 router.ts 文件,并添加以下代码: router.ts ts import { initTRPC } from '@trpc/server'; const t = initTRPC.create(); export const appRouter = t.router({ randomNumber: t.procedure.subscription(async function* () { while (true) { yield { randomNumber: Math.random() }; await new Promise((resolve) => setTimeout(resolve, 1000)); } }), }); 启用 useWSS 选项​ server.ts ts import { fastifyTRPCPlugin, FastifyTRPCPluginOptions, } from '@trpc/server/adapters/fastify'; import fastify from 'fastify'; import { createContext } from './context'; import { appRouter, type AppRouter } from './router'; const server = fastify(); server.register(fastifyTRPCPlugin, { useWSS: true, trpcOptions: { router: appRouter, createContext, // 启用心跳消息以保持连接开放(默认禁用) keepAlive: { enabled: true, // 服务器 ping 消息间隔(毫秒) pingMs: 30000, // 若在此毫秒数内未收到 pong 消息,则终止连接 pongWaitMs: 5000, }, }, }); 现在你可以订阅 randomNumber 主题,并且每秒会收到一个随机数 🚀。 Fastify 插件选项​ 名称 类型 可选 默认值 描述 prefix string 是 "/trpc" tRPC 路由的 URL 前缀 useWSS boolean 是 false 通过 @fastify/websocket 启用 WebSocket 支持 trpcOptions FastifyHandlerOptions 否 / tRPC 处理器选项,包括 router、createContext 等

评论 (0)