企业官网建设流程全解析

tRPC服务端30分钟精通：Routers、Procedures与Context的完整使用指南

【免费下载链接】trpc🧙‍♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpc

tRPC（全称 "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），例如示例中使用的 superjson：examples/minimal/src/shared/transformer.ts。

第二步：Routers 使用指南——像组织文件夹一样组织 API

Router（路由）是 tRPC 的组织单元，本质上是一个 "键 → 过程/子路由" 的映射对象。官方文档对 Router 的定义见 www/docs/server/routers.md。

定义第一个 Router

import { 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;

两个新手必知要点：

1. 子路由可以直接写成内联对象（如上例user: { ... }），也可以显式调用router()，两者等价，官方称之为 "inline sub-router"
2. 导出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 提供三种类型，选择依据非常清晰 📋：

官方 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 类型

在初始化时用.context<TContext>()声明：

export async function createContext(opts: CreateHTTPContextOptions) { const token = opts.req.headers['authorization']; const user = token ? await verify(token) : null; // 解析会话 return { user }; } export type Context = Awaited<ReturnType<typeof createContext>>; // 自动推导类型 const t = initTRPC.context<Context>().create();

技巧：用Awaited<ReturnType<typeof createContext>>从函数返回值推导类型，避免手写类型与实现脱节。

4.2 每请求创建 Context 实例

createContext()需要传给适配器 handler，每个请求调用一次，同一批次请求中的多个过程共享同一份 Context：

const 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 分钟速通路线：把三个概念串成完整服务

对照官方最小示例项目，按此顺序走一遍即可全部掌握 ✅

客户端只需import type { AppRouter }，即可获得完整智能提示——这就是 tRPC "端到端类型安全" 的闭环 🎉。

新手常见误区速查

• ❌重复初始化：一个应用只能initTRPC.create()一次，多实例会引发类型混乱
• ❌导出 router 实例给客户端：只导出AppRouter类型，防止服务端代码被打进前端
• ❌在 query 里改数据：凡是会变更状态的逻辑一律用mutation，前端缓存策略依赖此区分
• ❌手写 Context 类型：优先用Awaited<ReturnType<...>>自动推导，保证类型与实现一致

总结

掌握 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