全栈类型安全：tRPC + Next.js 实战，前后端共享 TypeScript 类型，告别 API 文档

摘要:
前端还在苦等后端的 Swagger 文档？后端改了一个字段类型，前端运行时才报错？RESTful API 的“猜谜游戏”该结束了。tRPC (TypeScript Remote Procedure Call) 结合 Next.js，为您提供“端到端”的类型安全体验。本文将带您实战构建一个全栈应用，无需代码生成器，无需 JSON Schema，利用 TypeScript 的类型推断，实现前后端类型的“量子纠缠”。

1. 业务背景与技术痛点 (The Why)

1.1 “API 文档” 的信任危机

在传统的前后端分离架构中，我们通常使用 OpenAPI (Swagger) 或 GraphQL 来定义接口契约。但痛点显而易见：

• 文档漂移：后端改了代码，忘了更新文档。
• 代码生成的笨重：为了获得类型提示，前端必须运行openapi-generator生成几千行丑陋的 TS 代码。
• 运行时惊吓：文档写着返回string，实际返回了null，导致前端undefined is not a function白屏。

1.2 tRPC 的降维打击

tRPC 并不是一个新的协议（它基于 HTTP/JSON），而是一个TypeScript 类型的管道。
它的核心理念是：既然前后端都在一个 Monorepo 中（或共享类型库），为什么不能直接共享 TS 类型定义？

• 后端定义Router。
• 前端直接引入后端的AppRouter类型。
• IDE 自动补全，重构自动报错。

这种体验就像在写本地函数调用一样丝滑。

2. 核心原理图解 (The Visuals)

2.1 传统 REST vs tRPC 开发流

2.2 tRPC 请求生命周期

3. 实战代码：Next.js + tRPC (The How)

我们将构建一个简单的“用户管理”功能，展示从后端定义到前端调用的全过程。

3.1 后端：定义 Router (Server Side)

首先定义路由和输入验证（使用 Zod）。

// server/routers/user.tsimport{z}from'zod';import{procedure,router}from'../trpc';// 模拟数据库constusers=[{id:'1',name:'Alice',role:'ADMIN'},{id:'2',name:'Bob',role:'USER'},];exportconstuserRouter=router({// 定义一个 Query (GET)byId:procedure.input(z.object({id:z.string()}))// 运行时输入验证.query(({input})=>{constuser=users.find((u)=>u.id===input.id);returnuser;// 返回类型自动推断为 User | undefined}),// 定义一个 Mutation (POST)create:procedure.input(z.object({name:z.string(),role:z.enum(['ADMIN','USER'])})).mutation(({input})=>{constnewUser={id:Math.random().toString(),...input};users.push(newUser);returnnewUser;}),});

合并到主路由：

// server/routers/_app.tsimport{router}from'../trpc';import{userRouter}from'./user';exportconstappRouter=router({user:userRouter,// 命名空间});// 导出类型定义（注意：只导出类型，不导出代码！）exporttypeAppRouter=typeofappRouter;

3.2 前端：创建 Hooks (Client Side)

利用createTRPCNext创建强类型的 Hooks。

// utils/trpc.tsimport{httpBatchLink}from'@trpc/client';import{createTRPCNext}from'@trpc/next';importtype{AppRouter}from'../server/routers/_app';// 仅导入类型exportconsttrpc=createTRPCNext<AppRouter>({config(){return{links:[httpBatchLink({url:'http://localhost:3000/api/trpc',}),],};},});

3.3 前端：组件调用

见证奇迹的时刻：

// pages/index.tsx import { trpc } from '../utils/trpc'; export default function UserPage() { // 1. 输入参数 'id' 被 IDE 自动提示，且必须是 string const userQuery = trpc.user.byId.useQuery({ id: '1' }); // 2. Mutation 调用 const createUser = trpc.user.create.useMutation(); if (userQuery.isLoading) return <div>Loading...</div>; return ( <div> {/* 3. data 的属性 name, role 被自动提示 */} <h1>User: {userQuery.data?.name}</h1> <button onClick={() => { // 4. 参数被 Zod schema 约束，填错 IDE 报错 createUser.mutate({ name: 'Charlie', role: 'USER' }); }} > Create User </button> </div> ); }

4. 源码级深度解析 (The Deep Dive)

tRPC 是如何做到“只导入类型就能产生运行时请求”的？核心在于TypeScript 的类型推断和JavaScript 的 Proxy。

4.1 类型推断的黑魔法 (InferType)

tRPC 利用了 TypeScript 的 Conditional Types 和 Generic Inference。

当我们写export type AppRouter = typeof appRouter时，TS 编译器从实现了query/mutation函数的运行代码中提取出了输入输出类型。

前端的createTRPCNext<AppRouter>接收了这个巨型类型对象。简化版的原理如下：

// 伪代码：tRPC 如何推断类型typeProcedure<Input,Output>={input:(input:Input)=>void;query:()=>Output;};// 提取 Input 类型typeInferInput<T>=TextendsProcedure<inferI,any>?I:never;// 提取 Output 类型typeInferOutput<T>=TextendsProcedure<any,inferO>?O:never;// useQuery 的类型定义大致如下typeUseQuery<T>=(input:InferInput<T>)=>{data:InferOutput<T>};

这使得前端得到的 hook 能够精确匹配后端的 Zod 校验和 Return 语句。

4.2 运行时代理 (Proxy)

你在前端调用的trpc.user.byId.useQuery，实际上并没有user或byId这些属性。这是一个Proxy (代理)。

// @trpc/client/src/createTRPCClient.tsfunctioncreateProxy(callback){returnnewProxy(()=>{},{get(_obj,name){// 当你访问 trpc.user.byId 时，它递归返回新的 Proxy// 并把路径 ['user', 'byId'] 存起来returncreateProxy((...args)=>{// ...});},apply(_1,_2,args){// 当你调用 .useQuery(args) 时// 最终将路径 parts 和 args 组装成 HTTP 请求// fetch('/api/trpc/user.byId?input=' + JSON.stringify(args))}});}

这个 Proxy 机制使得 tRPC 客户端极其轻量，因为它不需要为每个 API 生成实际的代码函数，只需要一个通用的 Proxy 处理器。

5. 生产环境避坑指南 (The Pitfalls)

坑一：Cold Start (冷启动) 与 Bundle Size

现象：AppRouter 变得巨大无比，包含了所有后端的 Zod 验证逻辑。
原因：如果在前端错误地导入了appRouter的值（runtime code），而不仅仅是类型(type AppRouter)，Webpack/Next.js 会把整个后端逻辑打包进前端 bundle。
检查：必须使用import type { AppRouter } ...。

坑二：Context 上下文丢失

现象：在createContext中获取不到 HTTP Headers（如 Cookie）。
原因：Next.js 的 Edge Runtime 或 Server Components 环境下，request 对象获取方式不同。
解法：根据部署环境（Node vs Edge），适配CreateNextContextOptions。

坑三：版本耦合 (Version Coupling)

现象：tRPC 强依赖前后端版本一致。
原因：前后端共享类型，意味着如果后端更新了类型但前端没重新 build，可能会出现类型错位（虽然 HTTP 层仍兼容 JSON）。
建议：tRPC 最适合 Monorepo。如果由于组织架构原因必须分库，请慎用 tRPC，或使用 git submodule 同步类型。

6. 竞品对比：tRPC vs GraphQL vs REST

总结

tRPC 是“Developer Experience First”(开发者体验优先) 的典范。它放弃了 API 的通用性（不适合提供给第三方调用），换取了内部开发极致的类型安全和迭代速度。

如果你的团队全栈使用 TypeScript，且前后端部署在一起（如 Next.js），那么请立刻尝试 tRPC。告别 Swagger，告别any，享受代码在指尖流动的快感。