第6章 tRPC 独立适配器详解
Version: 10.xStandalone Adapter(独立适配器)
tRPC 的 Standalone Adapter 是让新项目最快跑起来的方式,非常适合本地开发以及基于服务器的生产环境。它本质上就是对标准 Node.js HTTP Server 的一层封装,保留了常用的 tRPC 相关配置项。
如果你已有 Express、Fastify 或 Next.js 等现有 API 部署,想把 tRPC 集成进去,请查看各自的适配器文档。同样,如果你倾向于部署在 serverless 或边缘计算环境,也有 AWS Lambda、Fetch 等适配器可供选择。
还有一种很常见的做法:当生产环境的适配器在本地难以运行时,可以让应用保留两个入口——本地开发用 Standalone Adapter,部署时换用其他适配器。
示例应用 描述链接 Standalone tRPC ServerStackBlitz源码 带 CORS 处理的 Standalone tRPC ServerStackBlitz源码
搭建 Standalone tRPC Server
1. 实现 App Router
先实现你的 tRPC router,例如:
appRouter.tstsimport { initTRPC } from '@trpc/server';import { z } from 'zod';export const t = initTRPC.create();export const appRouter = t.router({ getUser: t.procedure.input(z.string()).query((opts) => { return { id: opts.input, name: 'Bilbo' }; }), createUser: t.procedure .input(z.object({ name: z.string().min(5) })) .mutation(async (opts) => { // use your ORM of choice return await UserModel.create({ data: opts.input, }); }),});// export type definition of APIexport type AppRouter = typeof appRouter;
更多信息请参考 quickstart 指南。
2. 使用 Standalone adapter
Standalone adapter 会启动一个简单的 Node.js HTTP 服务器。
server.tstsimport { initTRPC } from '@trpc/server';import { createHTTPServer } from '@trpc/server/adapters/standalone';import { appRouter } from './appRouter.ts';createHTTPServer({ router: appRouter, createContext() { console.log('context 3'); return {}; },}).listen(2022);
处理 CORS 与 OPTIONS 请求
默认情况下,standalone 服务器不会响应 HTTP OPTIONS 请求,也不会设置任何 CORS 头。
如果你的部署环境(比如本地开发)无法替你处理这些问题,就需要自己处理。
1. 安装 cors
可以借助流行的 cors 包自行添加支持:
bashyarn add corsyarn add -D @types/cors
关于该包的完整配置方式,请查阅其文档。
2. 配置 Standalone 服务器
下面的示例对任意请求都放开了 CORS,这在开发环境很方便,但在生产环境中应该配置得更严格。
server.tstsimport { initTRPC } from '@trpc/server';import { createHTTPServer } from '@trpc/server/adapters/standalone';import cors from 'cors';createHTTPServer({ middleware: cors(), router: appRouter, createContext() { console.log('context 3'); return {}; },}).listen(3333);
middleware 选项接受任何形似 connect/Node.js 中间件的函数,因此用途不只是处理 CORS。不过它的定位只是一个简单的"逃生舱口",本身不支持组合多个中间件。如果你有这个需求,可以选择:
- 换用中间件支持更完善的适配器,比如 Express adapter - 使用 connect 之类的方案来组合中间件 - 基于自定义 http server 扩展 Standalone 的 createHTTPHandler(见下文)
更进一步
如果 createHTTPServer 无法满足需求,还可以用 standalone adapter 的 createHTTPHandler 函数配合自己的 HTTP Server。例如:
server.tstsimport { createServer } from 'http';import { initTRPC } from '@trpc/server';import { createHTTPHandler } from '@trpc/server/adapters/standalone';const handler = createHTTPHandler({ router: appRouter, createContext() { return {}; },});createServer((req, res) => { / * Handle the request however you like, * just call the tRPC handler when you're ready */ handler(req, res);}).listen(3333);