tRPC服务端30分钟精通Routers、Procedures与Context的完整使用指南【免费下载链接】trpc♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpctRPC全称 TypeScript Remote Procedure Call是一个让开发者轻松构建端到端类型安全 API的开源框架口号是 Move Fast and Break Nothing。本文是面向新手的tRPC 服务端完整使用指南用 30 分钟带你吃透三大核心概念Routers路由、Procedures过程与Context上下文无需手写 REST 接口定义前后端类型自动推导从根源上消灭 接口字段对不上 的 bug 。为什么选择 tRPC一次搞懂它的定位传统后端开发流程是定义路由 → 手写请求/响应类型 → 前端再复制一份类型两边同步全靠自觉。tRPC 的思路完全不同服务端定义函数客户端直接 远程调用 同名函数参数和返回值类型由 TypeScript 自动推导支持 Express、Fastify、Next.js、AWS Lambda、Cloudflare Workers 等主流适配器一个框架同时覆盖Query 查询、Mutation 变更、Subscription 订阅三类场景想快速跑起来官方快速上手文档在 www/docs/main/quickstart.mdx官方定义 Router 的文档在 www/docs/server/routers.md。第一步初始化 tRPC每个应用只做一次tRPC 要求每个应用恰好初始化一次官方推荐使用initTRPC并在独立文件中导出可复用工具。核心代码如下import { initTRPC } from trpc/server; const t initTRPC.create(); export const router t.router; // 用于组织 API 目录 export const publicProcedure t.procedure; // 基础过程所有 API 的起点 注意这里导出的是router和publicProcedure而不是t本身——这是 tRPC 社区约定的base procedure 模式为后续派生protectedProcedure等命名过程留出空间。最小示例项目就是这么做的可以参考 examples/minimal/src/server/trpc.ts。需要传输特殊数据类型如 Date、BigInt时可以在此处挂载数据转换器transformer例如示例中使用的 superjsonexamples/minimal/src/shared/transformer.ts。第二步Routers 使用指南——像组织文件夹一样组织 APIRouter路由是 tRPC 的组织单元本质上是一个 键 → 过程/子路由 的映射对象。官方文档对 Router 的定义见 www/docs/server/routers.md。定义第一个 Routerimport { z } from zod; import { publicProcedure, router } from ./trpc; const appRouter router({ user: { list: publicProcedure.query(async () { return db.user.findMany(); }), byId: publicProcedure .input(z.string()) .query(async (opts) db.user.findById(opts.input)), create: publicProcedure .input(z.object({ name: z.string() })) .mutation(async (opts) db.user.create(opts.input)), }, }); // 关键导出 Router 的「类型」而非实例 export type AppRouter typeof appRouter;两个新手必知要点子路由可以直接写成内联对象如上例user: { ... }也可以显式调用router()两者等价官方称之为 inline sub-router导出AppRouter类型而不是实例客户端通过import type拿到完整类型且不会把服务端代码打进浏览器 bundle上面这段代码与官方最小示例 examples/minimal/src/server/index.ts 完全一致建议对照阅读。Router 的源码在哪里如果你想看router是如何递归解析 过程 子路由 的核心实现在 packages/server/src/unstable-core-do-not-import/router.ts其中RouterRecord类型定义了 每个键的值只能是过程或另一个路由记录 这条基本规则。第三步Procedures 完整清单——三种类型各适用什么场景Procedure过程是暴露给客户端的最小函数单元。tRPC 提供三种类型选择依据非常清晰 类型用途典型场景记忆口诀query只读获取数据查列表、查详情查数据用 querymutation写入/变更数据增删改、提交表单改数据用 mutationsubscription实时数据流WebSocket 推送、订阅更新要推送用 subscription官方 Procedures 文档含可复用过程、类型推导等进阶内容www/docs/server/procedures.md。三种过程的最小写法greeting: publicProcedure.query(() hello tRPC v11!), signGuestBook: publicProcedure.mutation(async (opts) { await opts.ctx.signGuestBook(); // mutation 里访问 Context return { message: goodbye! }; }),subscription走 WebSocket/流式通道独立成篇感兴趣可看 www/docs/server/subscriptions.md。输入参数验证配合 zod 一行搞定tRPC 过程支持链式调用.input(zodSchema)在函数执行前自动校验入参校验失败直接返回类型安全的错误服务端永远不必手动判断参数合法性。上面byId的z.string()就是例子。高级技巧可复用的 基础过程Base Procedures这是 tRPC 最高频的实战模式——给过程 套壳把鉴权逻辑写一次、到处复用export const protectedProcedure t.procedure.use((opts) { if (!opts.ctx.user?.email) { throw new TRPCError({ code: UNAUTHORIZED }); } return opts.next({ ctx: { user: opts.ctx.user } }); });use()是不可变构建器模式的一部分链上每一步都返回新的过程构建器且中间件可以通过opts.next({ ctx: ... })收窄上下文类型——上例执行后ctx.user在后续代码中自动变成非空类型IDE 零误报 ✨。官方组织成员鉴权的完整例子见 www/docs/server/procedures.md 的 Reusable Base Procedures 一节。第四步Context 上下文——所有过程共享的 请求说明书Context 是 tRPC 每个请求的共享数据容器认证信息、数据库连接、会话对象都放这里所有过程与中间件都能通过opts.ctx访问。Context 分两步设置定义类型每请求创建实例完整文档见 www/docs/server/context.md。4.1 定义 Context 类型在初始化时用.contextTContext()声明export async function createContext(opts: CreateHTTPContextOptions) { const token opts.req.headers[authorization]; const user token ? await verify(token) : null; // 解析会话 return { user }; } export type Context AwaitedReturnTypetypeof createContext; // 自动推导类型 const t initTRPC.contextContext().create();技巧用AwaitedReturnTypetypeof createContext从函数返回值推导类型避免手写类型与实现脱节。4.2 每请求创建 Context 实例createContext()需要传给适配器 handler每个请求调用一次同一批次请求中的多个过程共享同一份 Contextconst handler createHTTPHandler({ router: appRouter, createContext, // 交给 HTTP 适配器 });4.3 进阶Inner 与 Outer Context大型项目推荐把 Context 拆成两层Inner context内层不依赖请求的共享资源如数据库客户端。它永远可用还能方便你写集成测试和服务端调用Outer context外层依赖请求的对象如req、res和会话只在 HTTP 调用时可用官方建议 Context 类型从inner函数推导因为那才是过程中真正 永远可用 的部分。该模式的完整代码示例就在 www/docs/server/context.md。30 分钟速通路线把三个概念串成完整服务对照官方最小示例项目按此顺序走一遍即可全部掌握 ✅阶段做什么参考文件0-5 分钟安装trpc/servertrpc/client初始化initTRPCexamples/minimal/src/server/trpc.ts5-15 分钟用router()定义 Query/Mutation加 zod 输入校验examples/minimal/src/server/index.ts15-25 分钟定义createContext接入鉴权派生protectedProcedurewww/docs/server/context.md25-30 分钟导出AppRouter类型挂载到 HTTP 适配器启动服务www/docs/main/quickstart.mdx客户端只需import type { AppRouter }即可获得完整智能提示——这就是 tRPC 端到端类型安全 的闭环 。新手常见误区速查❌重复初始化一个应用只能initTRPC.create()一次多实例会引发类型混乱❌导出 router 实例给客户端只导出AppRouter类型防止服务端代码被打进前端❌在 query 里改数据凡是会变更状态的逻辑一律用mutation前端缓存策略依赖此区分❌手写 Context 类型优先用AwaitedReturnType...自动推导保证类型与实现一致总结掌握 tRPC 服务端只需记住这条主线initTRPC初始化一次 → 用router()组织 API 目录 → 用query/mutation/subscription三种过程编写逻辑 → 用Context承载请求级共享数据 → 导出AppRouter类型交给客户端。配合官方文档 www/docs/server/procedures.md、www/docs/server/routers.md 与 www/docs/server/context.md以及仓库 examples 目录下数十个真实场景示例Express、Next.js、Lambda、Nuxt 等30 分钟后你就能写出第一套前后端零摩擦的类型安全 API。【免费下载链接】trpc♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考