进阶 trpc.io 2026-10-12 05:42:24 · 26 阅读
第3章 Fastify 适配器
版本:10.x
Fastify Adapter
示例应用
上手 Fastify adapter 最好的方式就是先看看示例应用。
说明 | 链接
Fastify WebSocket 服务器与 node 下的简易 tRPC 客户端 | CodeSandbox | 源码
如何在 Fastify 中使用 tRPC
安装依赖
bashyarn add @trpc/server fastify zod
bashyarn add @trpc/server fastify zod
Zod 不是必需依赖,但下面的示例 router 中用到了它。
创建 router
首先需要一个 router 来处理你的 queries、mutations 和 subscriptions。
下面是一个 router 示例,把它保存为 router.ts。
router.tsrouter.tstsimport { 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 APIexport type AppRouter = typeof appRouter;
router.tsrouter.tstsimport { 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 APIexport type AppRouter = typeof appRouter;
如果 router 文件变得太大,可以把它拆分成多个子 router,分别放在各自的文件里,然后合并成一个根 appRouter。
创建 context
接下来需要为每个请求创建一个 context。
下面是一个 context 示例,把它保存为 context.ts:
context.tscontext.tstsimport { 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>;
context.tscontext.tstsimport { 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 server
tRPC 内置了 Fastify adapter,可以把你的 tRPC router 转换成一个 Fastify 插件。为避免大批量请求时出错,请按示例所示,把 Fastify 的 maxParamLength 选项设置为一个合适的值。
提示由于 Fastify 插件系统和类型推断的限制,onError 等选项的类型标注可能有问题。可以加上 satisfies FastifyTRPCPluginOptions['trpcOptions'] 来帮助 TypeScript 推导出正确类型。
server.tstsimport { fastifyTRPCPlugin, FastifyTRPCPluginOptions,} from '@trpc/server/adapters/fastify';import fastify from 'fastify';import { createContext } from './context';import { appRouter, type AppRouter } from './router';const server = fastify({ 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); }})();
server.tstsimport { fastifyTRPCPlugin, FastifyTRPCPluginOptions,} from '@trpc/server/adapters/fastify';import fastify from 'fastify';import { createContext } from './context';import { appRouter, type AppRouter } from './router';const server = fastify({ 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); }})();
现在你的端点已经可以通过 HTTP 访问了!
端点HTTP URIgetUserGET http://localhost:3000/trpc/getUserById?input=INPUT
其中 INPUT 是一个 URI 编码的 JSON 字符串。POST http://localhost:3000/trpc/createUser
请求体 req.body 的类型为 User ## 如何启用订阅(WebSocket) Fastify 适配器通过 @fastify/websocket 插件支持订阅功能。除了上述步骤外,你只需安装该依赖项,在路由器中添加入口,并在插件配置中启用 useWSS 选项即可。使用 @fastify/websocket 所需的最低 Fastify 版本为 3.11.0。 ### 安装依赖 bash yarn add @fastify/websocket ### 导入并注册 @fastify/websocket ts import ws from '@fastify/websocket'; server.register(ws); ### 添加订阅 编辑前几步创建的 router.ts 文件,并添加以下代码: ts import { initTRPC } from '@trpc/server'; import { observable } from '@trpc/server/observable'; const t = initTRPC.create(); export const appRouter = t.router({ randomNumber: t.procedure.subscription(() => { return observable<{ randomNumber: number }>((emit) => { const timer = setInterval(() => { emit.next({ randomNumber: Math.random() }); }, 1000); return () => { clearInterval(timer); }; }); }), }); ### 启用 useWSS 选项 ts server.register(fastifyTRPCPlugin, { useWSS: true, // ... }); 没问题了,现在你可以订阅 randomNumber 主题,并每秒接收一个随机数 🚀。 ## Fastify 插件选项 | 名称 | 类型 | 是否可选 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | :--- | | prefix | string | 是 | "/trpc" | | | useWSS | boolean | 是 | false | | | trpcOptions | NodeHTTPHandlerOptions | 否 | n/a | |
其中 INPUT 是一个 URI 编码的 JSON 字符串。POST http://localhost:3000/trpc/createUser
请求体 req.body 的类型为 User ## 如何启用订阅(WebSocket) Fastify 适配器通过 @fastify/websocket 插件支持订阅功能。除了上述步骤外,你只需安装该依赖项,在路由器中添加入口,并在插件配置中启用 useWSS 选项即可。使用 @fastify/websocket 所需的最低 Fastify 版本为 3.11.0。 ### 安装依赖 bash yarn add @fastify/websocket ### 导入并注册 @fastify/websocket ts import ws from '@fastify/websocket'; server.register(ws); ### 添加订阅 编辑前几步创建的 router.ts 文件,并添加以下代码: ts import { initTRPC } from '@trpc/server'; import { observable } from '@trpc/server/observable'; const t = initTRPC.create(); export const appRouter = t.router({ randomNumber: t.procedure.subscription(() => { return observable<{ randomNumber: number }>((emit) => { const timer = setInterval(() => { emit.next({ randomNumber: Math.random() }); }, 1000); return () => { clearInterval(timer); }; }); }), }); ### 启用 useWSS 选项 ts server.register(fastifyTRPCPlugin, { useWSS: true, // ... }); 没问题了,现在你可以订阅 randomNumber 主题,并每秒接收一个随机数 🚀。 ## Fastify 插件选项 | 名称 | 类型 | 是否可选 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | :--- | | prefix | string | 是 | "/trpc" | | | useWSS | boolean | 是 | false | | | trpcOptions | NodeHTTPHandlerOptions | 否 | n/a | |