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

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

创建路由器

首先需要创建 router 来处理查询（queries）、变更（mutations）和订阅（subscriptions）。

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

router.ts

router.ts
ts
import * as trpc from '@trpc/server';
import { z } from 'zod';
type User = {
  id: string;
  name: string;
  bio?: string;
};
const users: Record<string, User> = {};
export const appRouter = trpc
  .router()
  .query('getUserById', {
    input: z.string(),
    async resolve({ input }) {
      return users[input]; // input type is string
    },
  })
  .mutation('createUser', {
    // validate input with Zod
    input: z.object({
      name: z.string().min(3),
      bio: z.string().max(142).optional(),
    }),
    async resolve({ input }) {
      const id = Date.now().toString();
      const user: User = { id, ...input };
      users[user.id] = user;
      return user;
    },
  });
// export type definition of API
export type AppRouter = typeof appRouter;

router.ts
ts
import * as trpc from '@trpc/server';
import { z } from 'zod';
type User = {
  id: string;
  name: string;
  bio?: string;
};
const users: Record<string, User> = {};
export const appRouter = trpc
  .router()
  .query('getUserById', {
    input: z.string(),
    async resolve({ input }) {
      return users[input]; // input type is string
    },
  })
  .mutation('createUser', {
    // validate input with Zod
    input: z.object({
      name: z.string().min(3),
      bio: z.string().max(142).optional(),
    }),
    async resolve({ input }) {
      const id = Date.now().toString();
      const user: User = { id, ...input };
      users[user.id] = user;
      return user;
    },
  });
// export type definition of API
export type AppRouter = typeof appRouter;

当路由文件变得过于庞大时，可将路由拆分为多个子路由（每个子路由在独立文件中实现），然后将其合并为统一的根路由 appRouter。

创建上下文

然后需要为每个请求创建 context。

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

context.ts

context.ts
ts
import { inferAsyncReturnType } from '@trpc/server';
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 = inferAsyncReturnType<typeof createContext>;

context.ts
ts
import { inferAsyncReturnType } from '@trpc/server';
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 = inferAsyncReturnType<typeof createContext>;

创建 Fastify 服务器

tRPC 内置了 Fastify 适配器。该适配器可将 tRPC 路由器转换为 Fastify 插件。为防止大型批量请求中出现错误，请确保将 Fastify 选项 maxParamLength 设置为适当值（如下所示）。

server.ts
ts
import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify';
import fastify from 'fastify';
import { createContext } from './context';
import { appRouter } from './router';
const server = fastify({
  maxParamLength: 5000,
});
server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: { router: appRouter, createContext },
});
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

server.ts
ts
import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify';
import fastify from 'fastify';
import { createContext } from './context';
import { appRouter } from './router';
const server = fastify({
  maxParamLength: 5000,
});
server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: { router: appRouter, createContext },
});
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

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

Endpoint	HTTP URI
getUser	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 插件支持 订阅。除上述步骤外，您只需安装此依赖项，在路由器中添加订阅，并在插件中启用 useWSS 选项。@fastify/websocket 要求的最低 Fastify 版本为 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
export const appRouter = trpc
  .router()
  // .query(...)
  // .mutation(...)
  .subscription('randomNumber', {
    resolve() {
      return new Subscription<{ randomNumber: number }>((emit) => {
        const timer = setInterval(() => {
          emit.data({ randomNumber: Math.random() });
        }, 1000);
        return () => {
          clearInterval(timer);
        };
      });
    },
  });

router.ts
ts
export const appRouter = trpc
  .router()
  // .query(...)
  // .mutation(...)
  .subscription('randomNumber', {
    resolve() {
      return new Subscription<{ randomNumber: number }>((emit) => {
        const timer = setInterval(() => {
          emit.data({ randomNumber: Math.random() });
        }, 1000);
        return () => {
          clearInterval(timer);
        };
      });
    },
  });

启用 useWSS 选项

server.ts
ts
server.register(fastifyTRPCPlugin, {
  useWSS: true,
  // ...
});

server.ts
ts
server.register(fastifyTRPCPlugin, {
  useWSS: true,
  // ...
});

现在您可以订阅 randomNumber 主题，每秒都会收到随机数 🚀。

Fastify 插件选项

name	type	optional	default	description
prefix	string	true	"/trpc"
useWSS	boolean	true	false
trpcOptions	NodeHTTPHandlerOptions	false	n/a