Fastify 适配器

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

示例应用

要开始使用 Fastify 适配器，最好的方式是查看示例应用。

Description	Links
Fastify server with WebSocket Simple tRPC client in node	CodeSandbox Source

在 Fastify 中使用 tRPC

安装依赖

bash
yarn add @trpc/server fastify zod

bash
yarn add @trpc/server fastify zod

⚠️ Fastify 版本要求

tRPC v11 的 Fastify 适配器需要 Fastify v5+ 或更高版本。 使用 Fastify v4 可能导致请求返回空响应且不报错。

Zod 并非必需依赖，但下方示例路由中会使用到。

AI 代理

若您使用 AI 编程代理，请安装 tRPC 技能以优化代码生成效果：

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

创建路由器

首先需要创建路由来处理查询、变更和订阅操作。

下面提供了示例路由器，将其保存为 router.ts 文件：

router.ts

router.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
type User = {
  id: string;
  name: string;
  bio?: string;
};
 
const users: Record<string, User> = {};
 
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.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
type User = {
  id: string;
  name: string;
  bio?: string;
};
 
const users: Record<string, User> = {};
 
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;

若路由文件过大，可将其拆分为多个独立文件实现的子路由，然后合并为单一根路由 appRouter。

创建上下文

接着需要为每个请求创建上下文。

下面提供了示例上下文，将其保存为 context.ts 文件：

context.ts

context.ts
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<ReturnType<typeof createContext>>;

context.ts
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<ReturnType<typeof createContext>>;

创建 Fastify 服务器

tRPC 内置了 Fastify 适配器。该适配器可将 tRPC 路由器转换为 Fastify 插件。为避免大型批量请求出错，请确保按示例设置合适的 maxParamLength 选项。

技巧

由于 Fastify 插件系统和类型推断的限制，获取如 onError 等类型时可能存在困难。可添加 satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'] 辅助 TypeScript 获得正确类型。

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({
  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<AppRouter>['trpcOptions'],
});
 
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

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({
  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<AppRouter>['trpcOptions'],
});
 
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

现在你的端点已可通过 HTTP 访问！

Endpoint	HTTP URI
getUserById	GET http://localhost:3000/trpc/getUserById?input=INPUT where INPUT is a URI-encoded JSON string.
createUser	POST http://localhost:3000/trpc/createUser with req.body of type User

启用 WebSocket

Fastify 适配器通过 @fastify/websocket 插件支持 WebSocket。除了上述步骤外，你只需安装依赖、在路由中添加订阅，并在插件中启用 useWSS 选项即可。所需的最低 @fastify/websocket 版本为 3.11.0。

安装依赖

bash
yarn add @fastify/websocket

bash
yarn add @fastify/websocket

导入并注册 @fastify/websocket

ts
import ws from '@fastify/websocket';
 
server.register(ws);

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));
    }
  }),
});

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,
    // Enable heartbeat messages to keep connection open (disabled by default)
    keepAlive: {
      enabled: true,
      // server ping message interval in milliseconds
      pingMs: 30000,
      // connection is terminated if pong message is not received in this many milliseconds
      pongWaitMs: 5000,
    },
  },
});

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,
    // Enable heartbeat messages to keep connection open (disabled by default)
    keepAlive: {
      enabled: true,
      // server ping message interval in milliseconds
      pingMs: 30000,
      // connection is terminated if pong message is not received in this many milliseconds
      pongWaitMs: 5000,
    },
  },
});

现在你可以订阅 randomNumber 主题，并且每秒会收到一个随机数 🚀。

Fastify 插件选项

name	type	optional	default	description
prefix	string	true	"/trpc"	URL prefix for tRPC routes
useWSS	boolean	true	false	Enable WebSocket support via @fastify/websocket
trpcOptions	FastifyHandlerOptions<AppRouter, Request, Reply>	false	n/a	tRPC handler options including router, createContext, etc.