进阶 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 等
其中 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