这段时间一直在整理手头的一个全栈项目陆陆续续写了不少代码也踩了不少坑。前几天把它归档的时候给这套基于 T3 Stack 的实践笔记起了个代号就叫 t3code。整个项目核心围绕一件事用 TypeScript 把前后端的类型安全真正打通让从前端调用后端接口这件事从“靠文档和约定”变成“编译器替你把关”。这套方案适合正在做中小型全栈应用、内部工具、或者想从零开始尝试类型安全开发模式的朋友。今天就把这套实践里的设计思路、关键步骤、踩坑记录和排查经验完整地梳理一下。1. 项目整体设计与思路拆解1.1 t3code 到底是什么先把这个事情说清楚。t3code 不是一个框架也不是什么新语言它是一套基于 T3 Stack 的工程实践。T3 Stack 是由 tRPC 作者 Theo 推动的组合方案核心成员包括 Next.js前端框架、TypeScript语言层、tRPCAPI 层、Prisma数据库 ORM、Tailwind CSS样式可选加入 NextAuth.js 做鉴权。这套组合最大的卖点是端到端类型安全从前端组件到后端数据库查询类型定义全程贯穿中途不会断掉。我最初选择这套组合很大程度上是受够了传统前后端分离模式下那种“接口文档写得挺好联调时全是意外”的状态。REST 接口虽然简单但前后端之间的契约完全靠人肉维护GraphQL 虽然把类型带进来了但 schema、resolver、前端 fragment 的管理成本又有点重。tRPC 的思路非常直接既然前后端都是 TypeScript那就让调用方直接获得被调用函数的类型签名不需要生成代码不需要额外声明路由文档天然就是类型安全的。t3code 这个项目里我实现了一个带账号体系的笔记收藏应用。用户登录后可以创建笔记、管理自己的收藏未登录用户可以浏览公开笔记列表。功能不算复杂但恰好能把 T3 Stack 各个核心环节串联起来。整个项目的目录结构也严格按照 T3 的推荐方式组织Next.js App Router 负责页面server 目录放 tRPC router 和 Prisma 客户端客户端组件通过 tRPC hooks 发起调用。1.2 技术选型背后的逻辑为什么是这套组合先说 Next.js。它既承担了页面渲染又承担了 API 服务。tRPC 的 HTTP 适配器可以挂载在 App Router 的路由处理器上这样后端逻辑不需要单独部署一套服务整个应用打包成一个整体扔到服务端就行。这个取舍对小团队和个人项目很友好部署成本低心智负担也小。再说 Prisma。它的价值主要体现在类型生成和迁移管理。定义一个Note模型运行prisma generate之后查询返回的每个字段都有精确的 TypeScript 类型。配合 tRPCPrisma 的返回类型可以直接穿透到前端数据库里查出来什么结构前端组件里就能拿到什么结构。这一点非常关键等于把类型安全的链条延伸到了数据库这一层。tRPC 在这套组合里是核心。它提供的不是 REST 风格的 URL 设计而是直接在服务端定义可调用函数前端以近乎调用本地函数的方式发起请求。这个模式有一个非常大的好处新增一个接口不需要去设计 URL、不需要写接口文档、不需要定义 DTO只需要写一个 procedure前端保存后立刻就能拿到类型提示。下面用一个表把这套组合和传统方案做个对比看完思路会更清楚维度REST 手写类型GraphQLtRPC T3类型安全靠手写 DTO 和接口文档易漂移schema 与 resolver 有类型但前端仍需维护 fragment前后端类型穿透无中间层文件开发效率每次加接口都要写客户端请求层需要维护 schema、resolver、codegen定义 router 后前端直接调用服务端部署通常单独部署单独部署与 Next.js 一起部署学习成本低中高中适合场景团队已有规范的外部接口复杂聚合查询、多端消费全栈单应用、内部工具、启动项目2. 从零搭建 T3 项目的关键步骤2.1 5分钟初始化一个 T3 项目T3 Stack 官方提供了脚手架create-t3-app这是整个项目起步最快的方式。执行下面的命令npx create-t3-applatest t3code过程中会有几个交互式选项我的选择是Next.js 采用 App Router 模式新项目推荐这里启用 TypeScript这是必须项启用 tRPC启用 Prisma启用 Tailwind CSS启用 NextAuth.js笔记应用需要用户体系启用 ESLint这里有个细节值得说脚手架默认把 tRPC 和 Prisma 都配好了server/api/trpc.ts文件里已经实现了createTRPCContext和createCaller不需要自己从零拼装。很多新手在这里容易犯的错是启动项目后看见一堆文件就盲目删改其实官方脚手架生成的结构已经非常合理先跑通一遍再说优化的事。初始化完成后直接运行npm run dev访问本机端口能看到一个默认页面。此时整个链路还没有数据需要先把数据库接进来。2.2 理解 t3code 项目结构脚手架生成的目录结构看起来复杂但核心只有几个位置搞清楚之后整个项目就通了大半app/Next.js 的页面和路由。app/page.tsx是首页app/api/trpc/[trpc]/route.ts是 tRPC 的 HTTP 入口。server/api/root.ts汇总所有子 router 的地方。每新增一个功能模块在这里挂载。server/api/routers/具体业务逻辑。server/api/trpc.tstRPC 实例、上下文、公共 procedure 的定义处。server/db.tsPrisma Client 单例。prisma/schema.prisma数据模型定义。需要特别注意的是trpc.ts文件。tRPC 的上下文类型会从这里一直穿透到所有 procedure 中。比如你想在路由里拿到当前登录用户就一定是在createTRPCContext里读取 session然后塞进 context。很多类型报错根源就是这里没接对。2.3 数据层建模Prisma Schema 设计要点以我的笔记应用为例先设计两个核心模型用户和笔记。用户模型可以直接用 NextAuth 的适配器扩展笔记模型单独定义。model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? accounts Account[] sessions Session[] notes Note[] } model Note { id String id default(cuid()) title String content String visibility Visibility default(PUBLIC) createdAt DateTime default(now()) updatedAt DateTime updatedAt author User relation(fields: [authorId], references: [id]) authorId String index([authorId]) } enum Visibility { PUBLIC PRIVATE }设计 schema 时有几个经验值得分享。第一主键一律用cuid()而不是自增 ID。自增 ID 的问题在于外部用户可以通过枚举 ID 遍历资源在公开场景下容易泄露数据规模。cuid 虽然长一点但既无序又带随机性对 Web 应用更稳妥。第二凡是经常按某个字段查询的都要显式建索引。像Note模型里index([authorId])用户中心里查“我写的笔记”是高频操作没有索引数据量一大基本就是全表扫描。第三visibility字段用 enum 而不是布尔值。虽然看起来多了一个概念但后续想扩展“仅好友可见”之类的状态时只需要在 enum 里加一个值改造成本远低于重构布尔逻辑。定义好 schema 后执行迁移npx prisma migrate dev --name init这一步会把schema.prisma的变化同步到数据库同时重新生成 Prisma Client 的类型定义。迁移完成后把DATABASE_URL配到.env里。本地开发我用 PostgreSQL部署到 Vercel 之后直接用平台的数据库连接串替换即可。3. 核心功能实现tRPC 路由与调用全流程3.1 定义第一个 tRPC Router输入输出校验T3 脚手架的server/api/root.ts中会预置一个postRouter示例我们可以在routers目录下新建自己的业务路由。以笔记功能为例先定义一个noteRouterimport { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const noteRouter createTRPCRouter({ listPublic: publicProcedure.query(async ({ ctx }) { return ctx.db.note.findMany({ where: { visibility: PUBLIC }, orderBy: { createdAt: desc }, include: { author: { select: { name: true } } }, }); }), listMine: protectedProcedure.query(async ({ ctx }) { return ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { updatedAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), visibility: z.enum([PUBLIC, PRIVATE]).default(PRIVATE), }) ) .mutation(async ({ ctx, input }) { return ctx.db.note.create({ data: { title: input.title, content: input.content, visibility: input.visibility, authorId: ctx.session.user.id, }, }); }), });这段代码里有两个 procedure 类型publicProcedure和protectedProcedure。它们都是在server/api/trpc.ts里基于中间件定义的。protectedProcedure会先检查 session没有登录直接抛UNAUTHORIZED错误后续代码根本不会执行。这个模式把鉴权从业务代码里剥离出来了非常干净。3.2 前端类型安全调用useQuery 与 useMutation服务端定义好 router 后前端的调用体验是整个 T3 最爽的部分。首先在app/_trpc/client.ts里创建类型化的 tRPC 客户端import { createTRPCReact } from trpc/react-query; import type { AppRouter } from /server/api/root; export const trpc createTRPCReactAppRouter();然后在根布局或局部页面挂载 provider。这里需要注意Next.js App Router 下provider 必须是客户端组件所以通常会单独抽一层TRPCProvideruse client; import { QueryClient, QueryClientProvider } from tanstack/react-query; import { httpBatchLink } from trpc/client; import { useState } from react; import { trpc } from ./client; export function TRPCProvider({ children }: { children: React.ReactNode }) { const [queryClient] useState(() new QueryClient()); const [trpcClient] useState(() trpc.createClient({ links: [httpBatchLink({ url: /api/trpc })], }) ); return ( trpc.Provider client{trpcClient} queryClient{queryClient} QueryClientProvider client{queryClient}{children}/QueryClientProvider /trpc.Provider ); }之后在任何客户端组件里调用笔记列表就变成这样use client; import { trpc } from /app/_trpc/client; export function NoteList() { const { data, isLoading, error } trpc.note.listPublic.useQuery(); if (isLoading) return p加载中.../p; if (error) return p出错了{error.message}/p; return ( ul {data?.map((note) ( li key{note.id} h2{note.title}/h2 p{note.content}/p span{note.author.name}/span /li ))} /ul ); }这里data的类型就是服务端 Prisma 查询返回的类型不需要前端再去手写一个Noteinterface。新增字段、改字段名编译器都会立即提醒前端哪里需要同步修改。这种体验一旦习惯了你就很难再回去对齐字段名靠猜的日子。创建笔记的 mutation 写法也很直观const utils trpc.useUtils(); trpc.note.create.useMutation({ onSuccess: () { utils.note.listPublic.invalidate(); }, });invalidate是 React Query 的缓存失效机制。mutation 成功后把列表标记为陈旧下次读取时自动重新拉取。这一步是保证数据一致性的关键很多页面改完数据不刷新都是因为在 mutation 成功后没有做 invalidate。3.3 鉴权与上下文让 session 流到数据库查询T3 上下文的设计是理解整套体系的关键一环。打开server/api/trpc.ts核心逻辑很清晰import { initTRPC, TRPCError } from trpc/server; import { getServerSession } from next-auth; import { db } from /server/db; import { authOptions } from /server/auth; export const createTRPCContext async () { const session await getServerSession(authOptions); return { db, session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: { ...ctx.session, user: ctx.session.user } } }); });createTRPCContext在每次请求进入时执行然后把db和session塞进所有 procedure 的ctx。protectedProcedure通过t.procedure.use()添加了一个中间件检查未登录直接抛UNAUTHORIZED。这个设计让业务路由里的代码非常干净比如查询“我的笔记”时不需要在路由里再判断“用户是否存在”因为能走到这里的人一定是已登录的。3.4 SSR 与缓存处理服务端组件里直接调 tRPCT3 的一个常见疑问是服务端渲染组件要不要也走 HTTP 请求正确答案是不用。App Router 模式下服务端组件可以用createCaller直接在 Node 环境里调用 router无需经过网络层import { createTRPCContext } from /server/api/trpc; import { appRouter } from /server/api/root; export default async function HomePage() { const ctx await createTRPCContext(); const caller appRouter.createCaller(ctx); const notes await caller.note.listPublic(); return ( main NoteList initialNotes{notes} / /main ); }这样做的好处是首屏数据在服务端就拿到了前端组件可以直接用初始数据渲染不会出现“先空白再闪现”的情况。同时类型依然全程贯通notes的变量类型会直接让你知道每个字段是什么。这里需要特别注意一点如果某个页面是纯静态的服务端调用 tRPC 查数据库会让页面变成动态渲染。需要根据业务场景决定全局性的内容可以用缓存或静态生成依赖用户登录态的数据建议保持动态渲染。4. 现场实录一个完整功能从设计到上线4.1 实现笔记创建的交互闭环第三节只展示了定义好的 router这一节把完整流程串起来。先说一个常见误区把整个页面都装进客户端组件。T3 的最佳实践类似“静态外壳 客户端交互岛”列表的外层布局可以在服务端渲染只有需要交互的表单、按钮、实时列表数据才标记为use client。创建笔记的表单我用一个客户端组件承载use client; import { useState } from react; import { trpc } from /app/_trpc/client; export function CreateNoteForm() { const [title, setTitle] useState(); const [content, setContent] useState(); const utils trpc.useUtils(); const createNote trpc.note.create.useMutation({ onSuccess: () { setTitle(); setContent(); utils.note.listMine.invalidate(); utils.note.listPublic.invalidate(); }, }); return ( form onSubmit{(e) { e.preventDefault(); createNote.mutate({ title, content, visibility: PUBLIC }); }} input value{title} onChange{(e) setTitle(e.target.value)} placeholder标题 required / textarea value{content} onChange{(e) setContent(e.target.value)} placeholder内容 required / button typesubmit disabled{createNote.isPending} {createNote.isPending ? 提交中... : 创建笔记} /button /form ); }这个组件里值得注意的细节是createNote.isPending。用 mutation 自带的 pending 状态去控制按钮的 loading比手动管理一个submitting状态变量要可靠得多还能避免按钮被重复点击。4.2 联调验证从 dev 到构建开发模式下前后端在同源环境下跑几乎没有跨域问题。当我把项目推到生产环境之前必须先执行一次完整的类型检查和构建npm run buildcreate-t3-app默认把tsc检查和next build绑在一起。这一步非常重要因为 tRPC 的类型贯穿是整个项目的价值所在一旦某个调用方与服务端类型对不上构建就会直接失败。在传统 REST 项目里这种错误往往要等到运行时才会暴露。部署到 Vercel 后我遇到了不少朋友也常见的问题本地npm run dev一切正常部署后app/api/trpc/[trpc]却返回 404。排查之后发现大多是 Next.js 版本更新后动态路由处理器需要显式声明运行环境。在route.ts文件头部加上一行即可export const dynamic force-dynamic;4.3 生产环境部署的注意事项生产环境和本地开发最大的差异有三个环境变量、数据库网络、Serverless 执行环境。环境变量是最容易踩的坑。DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL必须在 Vercel 的控制台里逐一配置而且NEXTAUTH_SECRET不能复用开发环境的默认值必须用openssl rand -base64 32生成一个新的随机串。数据库方面国内开发者如果使用海外数据库服务连接延时和连接数限制会成为瓶颈。Serverless 环境下函数的冷启动会创建新的 Prisma Client但 Prisma Client 本身是有全局连接池的建议在server/db.ts里用全局单例避免每次请求都新建连接import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const db globalForPrisma.prisma || new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;这个模式是 Prisma 官方推荐的能显著降低连接数耗尽的风险。部署后如果看到Too many connections或Connection pool timeout的报错先从这段代码入手排查。5. 常见问题与排查技巧实录5.1 tRPC 类型报错泛型丢失怎么办T3 项目里最常见的报错是前端调用时出现类似Property id does not exist on type never或Type undefined is not assignable to type string。这类问题的根源大多是ctx类型不对。我在调试过程中总结了一条排查路径先看server/api/trpc.ts里的createTRPCContext返回了什么再看 router 里ctx.db是否符合预期。如果ctx类型有问题所有下游 procedure 的返回类型都会被推断成错误或空类型。修复方法很简单确保initTRPC.contexttypeof createTRPCContext()用的是函数类型本身而不是返回类型。另外一个容易踩的坑是路由里用了any做输入输出。tRPC 的类型安全依赖显式声明输入 schema任何绕过 zod 校验的输入都会让返回推断退化成宽松类型。我的原则是路由的输入输出永远显式声明拒绝any。5.2 React Query 数据不刷新invalidate 的使用时机页面改了数据后列表不更新这是几乎每个用 tRPC 的人都会遇到的。原因很简单tRPC 的useQuery依赖 React Query 的缓存mutation 成功后没有主动失效缓存旧数据就一直躺在缓存里。我的习惯是在 mutation 的onSuccess回调里统一做invalidate。如果同一个 mutation 影响多个列表比如创建公开笔记既影响公开列表也影响我的列表就把相关的都 invalidate 一次。React Query 的invalidate不是暴力清空缓存而是标记为陈旧后再后台拉取用户体验非常自然。还有一种更精细的更新方式是直接用setData做乐观更新。比如给笔记加收藏可以先本地把 UI 切换成“已收藏”同时调 mutation失败再回滚。这个模式适合追求极致交互体验的场景。5.3 Prisma 在 Serverless 环境下的连接池问题部署到 Vercel 之后我遇到过一个印象深刻的错误页面偶发性报错提示PrismaClientInitializationError过几分钟后自己恢复。排查后确认是连接池耗尽。Serverless 函数并发是弹性伸缩的每个实例都可能创建数据库连接如果数据库连接数上限比较低就容易出现“瞬间冲垮”的情况。解决办法除了前面说的全局单例还有两条路一是把数据库连接池配置调大这取决于数据库服务商通常 PostgreSQL 都有connection_limit参数可调二是在 Prisma 的datasource里增加连接池超时和重试参数让瞬时失败不会直接变成 500 响应。datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DIRECT_URL) }directUrl与url分开配置是 Vercel 部署的常见实践url走连接池代理directUrl走直连。这个配置在流量不大时看不出区别一旦遇到并发尖峰差异非常明显。5.4 容易忽略的运行时错误清单我把这段时间遇到的高频问题整理成一个速查表方便日后排查现象可能原因排查方向前台调用报 404动态路由被静态化在app/api/trpc/[trpc]/route.ts加force-dynamicmutation 后数据不刷新缺少 invalidate检查onSuccess里的utils.xxx.invalidate()部署后登录态丢失NEXTAUTH_SECRET未更新用openssl rand -base64 32重新生成Prisma 报连接池超时并发连接过多使用全局单例配置directUrl类型推导变成nevercontext 类型不匹配检查initTRPC.contexttypeof ...()定义zod 校验不过但报错不明确输入类型与 schema 不一致严格检查前端传参前端与 schema 对齐6. 进阶扩展与工程化建议6.1 从 REST 迁移到 tRPC 的路径如果手头已经有一个 REST API 的后端想迁移到 tRPC我建议不要一次全部替换而是渐进式改造。保留现有的 REST 路由新增功能模块直接用 tRPC 写等一部分页面前端完成迁移后再把旧接口逐个下线。这样风险可以控制得很低也不会影响线上业务。迁移过程中有一个关键点原有 REST 接口的错误码和消息格式在 tRPC 里通过TRPCError的code字段映射。前端的拦截器需要同时兼容两种错误格式等旧接口完全下线后再统一收口。6.2 大型项目里的 router 组织策略t3code 目前只有一个note模块但真实项目不会这么简单。当业务模块变多root.ts里 import 的代码会越来越多我习惯按业务域拆分成多个子 routerroot.ts只做挂载不写业务逻辑import { createTRPCRouter } from ./trpc; import { noteRouter } from ./routers/note; import { userRouter } from ./routers/user; import { favoriteRouter } from ./routers/favorite; export const appRouter createTRPCRouter({ note: noteRouter, user: userRouter, favorite: favoriteRouter, });每个子 router 内部如果要再细分可以用命名空间比如noteRouter.create、noteRouter.list这样的层级。这样调用的语义非常清晰前端自然就是useNote.xxx.useQuery()的调用方式不用记任何 URL。6.3 测试策略直接在 Node 层打穿tRPC 带来的一个独特好处是测试变得很轻。因为业务逻辑都在 router 的 procedure 里测试时不需要启动 HTTP 服务直接创建 caller 调用即可const caller appRouter.createCaller({ db: testDb, session: { user: { id: test-id } }, }); const result await caller.note.create({ title: 测试标题, content: 测试内容, visibility: PUBLIC, });这样测试的速度非常快不需要 mock HTTP 层也不需要处理序列化直接调用函数。配合模拟数据库或者测试数据库实例可以覆盖绝大多数业务逻辑。前端组件层的测试再单独用 React Testing Library 处理两层测试职责分离维护成本很低。6.4 性能优化与缓存策略最后聊一下性能。tRPC 默认使用httpBatchLink它会把一个事件循环内的多个请求合并成一个 HTTP POST减少请求次数。这个机制对低流量的应用效果不明显但页面同时调用三五个 query 时网络开销能省一大截。缓存方面React Query 的staleTime参数值得认真配置。默认是 0意味着每次组件挂载都会重新请求。对变化不频繁的数据比如公开笔记列表可以调大const { data } trpc.note.listPublic.useQuery(undefined, { staleTime: 60_000, });这样一分钟内重复进入页面会直接走缓存点击体验会流畅很多。需要注意涉及用户隐私或实时性要求高的数据比如余额、订单状态staleTime不要调太大否则会出现显示滞后。我在实际使用中的体会是t3code 这套实践给自己带来的最大收益不是某个具体功能而是开发节奏的改变。以前写完接口还要写文档、定义类型、来回对字段名。现在改一个数据模型类型差错在编译期就暴露了。整理这个项目的过程里我把每一步踩过的坑都用注释留在代码里了比如为什么加索引、为什么用 cuid、为什么 invalidate 放在 onSuccess。这些看似细碎的点恰恰是文档里查不到、只有自己动手做一遍才能真正理解的。如果你也想转型到类型安全的全栈开发模式我建议别急着追求复杂架构就从一个小项目开始跑通 create-t3-app写出第一个带鉴权的 mutation然后逐步添加模块。等基础建立起来后你会发现自己对“前后端配合”这件事的理解会完全不一样。 
长河君 · 2026/10/26 23:34:12 · 阅读 1.2k T3 Stack 类型安全全栈开发实践：从原理到踩坑实录
这段时间一直在整理手头的一个全栈项目陆陆续续写了不少代码也踩了不少坑。前几天把它归档的时候给这套基于 T3 Stack 的实践笔记起了个代号就叫 t3code。整个项目核心围绕一件事用 TypeScript 把前后端的类型安全真正打通让从前端调用后端接口这件事从“靠文档和约定”变成“编译器替你把关”。这套方案适合正在做中小型全栈应用、内部工具、或者想从零开始尝试类型安全开发模式的朋友。今天就把这套实践里的设计思路、关键步骤、踩坑记录和排查经验完整地梳理一下。1. 项目整体设计与思路拆解1.1 t3code 到底是什么先把这个事情说清楚。t3code 不是一个框架也不是什么新语言它是一套基于 T3 Stack 的工程实践。T3 Stack 是由 tRPC 作者 Theo 推动的组合方案核心成员包括 Next.js前端框架、TypeScript语言层、tRPCAPI 层、Prisma数据库 ORM、Tailwind CSS样式可选加入 NextAuth.js 做鉴权。这套组合最大的卖点是端到端类型安全从前端组件到后端数据库查询类型定义全程贯穿中途不会断掉。我最初选择这套组合很大程度上是受够了传统前后端分离模式下那种“接口文档写得挺好联调时全是意外”的状态。REST 接口虽然简单但前后端之间的契约完全靠人肉维护GraphQL 虽然把类型带进来了但 schema、resolver、前端 fragment 的管理成本又有点重。tRPC 的思路非常直接既然前后端都是 TypeScript那就让调用方直接获得被调用函数的类型签名不需要生成代码不需要额外声明路由文档天然就是类型安全的。t3code 这个项目里我实现了一个带账号体系的笔记收藏应用。用户登录后可以创建笔记、管理自己的收藏未登录用户可以浏览公开笔记列表。功能不算复杂但恰好能把 T3 Stack 各个核心环节串联起来。整个项目的目录结构也严格按照 T3 的推荐方式组织Next.js App Router 负责页面server 目录放 tRPC router 和 Prisma 客户端客户端组件通过 tRPC hooks 发起调用。1.2 技术选型背后的逻辑为什么是这套组合先说 Next.js。它既承担了页面渲染又承担了 API 服务。tRPC 的 HTTP 适配器可以挂载在 App Router 的路由处理器上这样后端逻辑不需要单独部署一套服务整个应用打包成一个整体扔到服务端就行。这个取舍对小团队和个人项目很友好部署成本低心智负担也小。再说 Prisma。它的价值主要体现在类型生成和迁移管理。定义一个Note模型运行prisma generate之后查询返回的每个字段都有精确的 TypeScript 类型。配合 tRPCPrisma 的返回类型可以直接穿透到前端数据库里查出来什么结构前端组件里就能拿到什么结构。这一点非常关键等于把类型安全的链条延伸到了数据库这一层。tRPC 在这套组合里是核心。它提供的不是 REST 风格的 URL 设计而是直接在服务端定义可调用函数前端以近乎调用本地函数的方式发起请求。这个模式有一个非常大的好处新增一个接口不需要去设计 URL、不需要写接口文档、不需要定义 DTO只需要写一个 procedure前端保存后立刻就能拿到类型提示。下面用一个表把这套组合和传统方案做个对比看完思路会更清楚维度REST 手写类型GraphQLtRPC T3类型安全靠手写 DTO 和接口文档易漂移schema 与 resolver 有类型但前端仍需维护 fragment前后端类型穿透无中间层文件开发效率每次加接口都要写客户端请求层需要维护 schema、resolver、codegen定义 router 后前端直接调用服务端部署通常单独部署单独部署与 Next.js 一起部署学习成本低中高中适合场景团队已有规范的外部接口复杂聚合查询、多端消费全栈单应用、内部工具、启动项目2. 从零搭建 T3 项目的关键步骤2.1 5分钟初始化一个 T3 项目T3 Stack 官方提供了脚手架create-t3-app这是整个项目起步最快的方式。执行下面的命令npx create-t3-applatest t3code过程中会有几个交互式选项我的选择是Next.js 采用 App Router 模式新项目推荐这里启用 TypeScript这是必须项启用 tRPC启用 Prisma启用 Tailwind CSS启用 NextAuth.js笔记应用需要用户体系启用 ESLint这里有个细节值得说脚手架默认把 tRPC 和 Prisma 都配好了server/api/trpc.ts文件里已经实现了createTRPCContext和createCaller不需要自己从零拼装。很多新手在这里容易犯的错是启动项目后看见一堆文件就盲目删改其实官方脚手架生成的结构已经非常合理先跑通一遍再说优化的事。初始化完成后直接运行npm run dev访问本机端口能看到一个默认页面。此时整个链路还没有数据需要先把数据库接进来。2.2 理解 t3code 项目结构脚手架生成的目录结构看起来复杂但核心只有几个位置搞清楚之后整个项目就通了大半app/Next.js 的页面和路由。app/page.tsx是首页app/api/trpc/[trpc]/route.ts是 tRPC 的 HTTP 入口。server/api/root.ts汇总所有子 router 的地方。每新增一个功能模块在这里挂载。server/api/routers/具体业务逻辑。server/api/trpc.tstRPC 实例、上下文、公共 procedure 的定义处。server/db.tsPrisma Client 单例。prisma/schema.prisma数据模型定义。需要特别注意的是trpc.ts文件。tRPC 的上下文类型会从这里一直穿透到所有 procedure 中。比如你想在路由里拿到当前登录用户就一定是在createTRPCContext里读取 session然后塞进 context。很多类型报错根源就是这里没接对。2.3 数据层建模Prisma Schema 设计要点以我的笔记应用为例先设计两个核心模型用户和笔记。用户模型可以直接用 NextAuth 的适配器扩展笔记模型单独定义。model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? accounts Account[] sessions Session[] notes Note[] } model Note { id String id default(cuid()) title String content String visibility Visibility default(PUBLIC) createdAt DateTime default(now()) updatedAt DateTime updatedAt author User relation(fields: [authorId], references: [id]) authorId String index([authorId]) } enum Visibility { PUBLIC PRIVATE }设计 schema 时有几个经验值得分享。第一主键一律用cuid()而不是自增 ID。自增 ID 的问题在于外部用户可以通过枚举 ID 遍历资源在公开场景下容易泄露数据规模。cuid 虽然长一点但既无序又带随机性对 Web 应用更稳妥。第二凡是经常按某个字段查询的都要显式建索引。像Note模型里index([authorId])用户中心里查“我写的笔记”是高频操作没有索引数据量一大基本就是全表扫描。第三visibility字段用 enum 而不是布尔值。虽然看起来多了一个概念但后续想扩展“仅好友可见”之类的状态时只需要在 enum 里加一个值改造成本远低于重构布尔逻辑。定义好 schema 后执行迁移npx prisma migrate dev --name init这一步会把schema.prisma的变化同步到数据库同时重新生成 Prisma Client 的类型定义。迁移完成后把DATABASE_URL配到.env里。本地开发我用 PostgreSQL部署到 Vercel 之后直接用平台的数据库连接串替换即可。3. 核心功能实现tRPC 路由与调用全流程3.1 定义第一个 tRPC Router输入输出校验T3 脚手架的server/api/root.ts中会预置一个postRouter示例我们可以在routers目录下新建自己的业务路由。以笔记功能为例先定义一个noteRouterimport { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const noteRouter createTRPCRouter({ listPublic: publicProcedure.query(async ({ ctx }) { return ctx.db.note.findMany({ where: { visibility: PUBLIC }, orderBy: { createdAt: desc }, include: { author: { select: { name: true } } }, }); }), listMine: protectedProcedure.query(async ({ ctx }) { return ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { updatedAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), visibility: z.enum([PUBLIC, PRIVATE]).default(PRIVATE), }) ) .mutation(async ({ ctx, input }) { return ctx.db.note.create({ data: { title: input.title, content: input.content, visibility: input.visibility, authorId: ctx.session.user.id, }, }); }), });这段代码里有两个 procedure 类型publicProcedure和protectedProcedure。它们都是在server/api/trpc.ts里基于中间件定义的。protectedProcedure会先检查 session没有登录直接抛UNAUTHORIZED错误后续代码根本不会执行。这个模式把鉴权从业务代码里剥离出来了非常干净。3.2 前端类型安全调用useQuery 与 useMutation服务端定义好 router 后前端的调用体验是整个 T3 最爽的部分。首先在app/_trpc/client.ts里创建类型化的 tRPC 客户端import { createTRPCReact } from trpc/react-query; import type { AppRouter } from /server/api/root; export const trpc createTRPCReactAppRouter();然后在根布局或局部页面挂载 provider。这里需要注意Next.js App Router 下provider 必须是客户端组件所以通常会单独抽一层TRPCProvideruse client; import { QueryClient, QueryClientProvider } from tanstack/react-query; import { httpBatchLink } from trpc/client; import { useState } from react; import { trpc } from ./client; export function TRPCProvider({ children }: { children: React.ReactNode }) { const [queryClient] useState(() new QueryClient()); const [trpcClient] useState(() trpc.createClient({ links: [httpBatchLink({ url: /api/trpc })], }) ); return ( trpc.Provider client{trpcClient} queryClient{queryClient} QueryClientProvider client{queryClient}{children}/QueryClientProvider /trpc.Provider ); }之后在任何客户端组件里调用笔记列表就变成这样use client; import { trpc } from /app/_trpc/client; export function NoteList() { const { data, isLoading, error } trpc.note.listPublic.useQuery(); if (isLoading) return p加载中.../p; if (error) return p出错了{error.message}/p; return ( ul {data?.map((note) ( li key{note.id} h2{note.title}/h2 p{note.content}/p span{note.author.name}/span /li ))} /ul ); }这里data的类型就是服务端 Prisma 查询返回的类型不需要前端再去手写一个Noteinterface。新增字段、改字段名编译器都会立即提醒前端哪里需要同步修改。这种体验一旦习惯了你就很难再回去对齐字段名靠猜的日子。创建笔记的 mutation 写法也很直观const utils trpc.useUtils(); trpc.note.create.useMutation({ onSuccess: () { utils.note.listPublic.invalidate(); }, });invalidate是 React Query 的缓存失效机制。mutation 成功后把列表标记为陈旧下次读取时自动重新拉取。这一步是保证数据一致性的关键很多页面改完数据不刷新都是因为在 mutation 成功后没有做 invalidate。3.3 鉴权与上下文让 session 流到数据库查询T3 上下文的设计是理解整套体系的关键一环。打开server/api/trpc.ts核心逻辑很清晰import { initTRPC, TRPCError } from trpc/server; import { getServerSession } from next-auth; import { db } from /server/db; import { authOptions } from /server/auth; export const createTRPCContext async () { const session await getServerSession(authOptions); return { db, session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: { ...ctx.session, user: ctx.session.user } } }); });createTRPCContext在每次请求进入时执行然后把db和session塞进所有 procedure 的ctx。protectedProcedure通过t.procedure.use()添加了一个中间件检查未登录直接抛UNAUTHORIZED。这个设计让业务路由里的代码非常干净比如查询“我的笔记”时不需要在路由里再判断“用户是否存在”因为能走到这里的人一定是已登录的。3.4 SSR 与缓存处理服务端组件里直接调 tRPCT3 的一个常见疑问是服务端渲染组件要不要也走 HTTP 请求正确答案是不用。App Router 模式下服务端组件可以用createCaller直接在 Node 环境里调用 router无需经过网络层import { createTRPCContext } from /server/api/trpc; import { appRouter } from /server/api/root; export default async function HomePage() { const ctx await createTRPCContext(); const caller appRouter.createCaller(ctx); const notes await caller.note.listPublic(); return ( main NoteList initialNotes{notes} / /main ); }这样做的好处是首屏数据在服务端就拿到了前端组件可以直接用初始数据渲染不会出现“先空白再闪现”的情况。同时类型依然全程贯通notes的变量类型会直接让你知道每个字段是什么。这里需要特别注意一点如果某个页面是纯静态的服务端调用 tRPC 查数据库会让页面变成动态渲染。需要根据业务场景决定全局性的内容可以用缓存或静态生成依赖用户登录态的数据建议保持动态渲染。4. 现场实录一个完整功能从设计到上线4.1 实现笔记创建的交互闭环第三节只展示了定义好的 router这一节把完整流程串起来。先说一个常见误区把整个页面都装进客户端组件。T3 的最佳实践类似“静态外壳 客户端交互岛”列表的外层布局可以在服务端渲染只有需要交互的表单、按钮、实时列表数据才标记为use client。创建笔记的表单我用一个客户端组件承载use client; import { useState } from react; import { trpc } from /app/_trpc/client; export function CreateNoteForm() { const [title, setTitle] useState(); const [content, setContent] useState(); const utils trpc.useUtils(); const createNote trpc.note.create.useMutation({ onSuccess: () { setTitle(); setContent(); utils.note.listMine.invalidate(); utils.note.listPublic.invalidate(); }, }); return ( form onSubmit{(e) { e.preventDefault(); createNote.mutate({ title, content, visibility: PUBLIC }); }} input value{title} onChange{(e) setTitle(e.target.value)} placeholder标题 required / textarea value{content} onChange{(e) setContent(e.target.value)} placeholder内容 required / button typesubmit disabled{createNote.isPending} {createNote.isPending ? 提交中... : 创建笔记} /button /form ); }这个组件里值得注意的细节是createNote.isPending。用 mutation 自带的 pending 状态去控制按钮的 loading比手动管理一个submitting状态变量要可靠得多还能避免按钮被重复点击。4.2 联调验证从 dev 到构建开发模式下前后端在同源环境下跑几乎没有跨域问题。当我把项目推到生产环境之前必须先执行一次完整的类型检查和构建npm run buildcreate-t3-app默认把tsc检查和next build绑在一起。这一步非常重要因为 tRPC 的类型贯穿是整个项目的价值所在一旦某个调用方与服务端类型对不上构建就会直接失败。在传统 REST 项目里这种错误往往要等到运行时才会暴露。部署到 Vercel 后我遇到了不少朋友也常见的问题本地npm run dev一切正常部署后app/api/trpc/[trpc]却返回 404。排查之后发现大多是 Next.js 版本更新后动态路由处理器需要显式声明运行环境。在route.ts文件头部加上一行即可export const dynamic force-dynamic;4.3 生产环境部署的注意事项生产环境和本地开发最大的差异有三个环境变量、数据库网络、Serverless 执行环境。环境变量是最容易踩的坑。DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL必须在 Vercel 的控制台里逐一配置而且NEXTAUTH_SECRET不能复用开发环境的默认值必须用openssl rand -base64 32生成一个新的随机串。数据库方面国内开发者如果使用海外数据库服务连接延时和连接数限制会成为瓶颈。Serverless 环境下函数的冷启动会创建新的 Prisma Client但 Prisma Client 本身是有全局连接池的建议在server/db.ts里用全局单例避免每次请求都新建连接import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const db globalForPrisma.prisma || new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;这个模式是 Prisma 官方推荐的能显著降低连接数耗尽的风险。部署后如果看到Too many connections或Connection pool timeout的报错先从这段代码入手排查。5. 常见问题与排查技巧实录5.1 tRPC 类型报错泛型丢失怎么办T3 项目里最常见的报错是前端调用时出现类似Property id does not exist on type never或Type undefined is not assignable to type string。这类问题的根源大多是ctx类型不对。我在调试过程中总结了一条排查路径先看server/api/trpc.ts里的createTRPCContext返回了什么再看 router 里ctx.db是否符合预期。如果ctx类型有问题所有下游 procedure 的返回类型都会被推断成错误或空类型。修复方法很简单确保initTRPC.contexttypeof createTRPCContext()用的是函数类型本身而不是返回类型。另外一个容易踩的坑是路由里用了any做输入输出。tRPC 的类型安全依赖显式声明输入 schema任何绕过 zod 校验的输入都会让返回推断退化成宽松类型。我的原则是路由的输入输出永远显式声明拒绝any。5.2 React Query 数据不刷新invalidate 的使用时机页面改了数据后列表不更新这是几乎每个用 tRPC 的人都会遇到的。原因很简单tRPC 的useQuery依赖 React Query 的缓存mutation 成功后没有主动失效缓存旧数据就一直躺在缓存里。我的习惯是在 mutation 的onSuccess回调里统一做invalidate。如果同一个 mutation 影响多个列表比如创建公开笔记既影响公开列表也影响我的列表就把相关的都 invalidate 一次。React Query 的invalidate不是暴力清空缓存而是标记为陈旧后再后台拉取用户体验非常自然。还有一种更精细的更新方式是直接用setData做乐观更新。比如给笔记加收藏可以先本地把 UI 切换成“已收藏”同时调 mutation失败再回滚。这个模式适合追求极致交互体验的场景。5.3 Prisma 在 Serverless 环境下的连接池问题部署到 Vercel 之后我遇到过一个印象深刻的错误页面偶发性报错提示PrismaClientInitializationError过几分钟后自己恢复。排查后确认是连接池耗尽。Serverless 函数并发是弹性伸缩的每个实例都可能创建数据库连接如果数据库连接数上限比较低就容易出现“瞬间冲垮”的情况。解决办法除了前面说的全局单例还有两条路一是把数据库连接池配置调大这取决于数据库服务商通常 PostgreSQL 都有connection_limit参数可调二是在 Prisma 的datasource里增加连接池超时和重试参数让瞬时失败不会直接变成 500 响应。datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DIRECT_URL) }directUrl与url分开配置是 Vercel 部署的常见实践url走连接池代理directUrl走直连。这个配置在流量不大时看不出区别一旦遇到并发尖峰差异非常明显。5.4 容易忽略的运行时错误清单我把这段时间遇到的高频问题整理成一个速查表方便日后排查现象可能原因排查方向前台调用报 404动态路由被静态化在app/api/trpc/[trpc]/route.ts加force-dynamicmutation 后数据不刷新缺少 invalidate检查onSuccess里的utils.xxx.invalidate()部署后登录态丢失NEXTAUTH_SECRET未更新用openssl rand -base64 32重新生成Prisma 报连接池超时并发连接过多使用全局单例配置directUrl类型推导变成nevercontext 类型不匹配检查initTRPC.contexttypeof ...()定义zod 校验不过但报错不明确输入类型与 schema 不一致严格检查前端传参前端与 schema 对齐6. 进阶扩展与工程化建议6.1 从 REST 迁移到 tRPC 的路径如果手头已经有一个 REST API 的后端想迁移到 tRPC我建议不要一次全部替换而是渐进式改造。保留现有的 REST 路由新增功能模块直接用 tRPC 写等一部分页面前端完成迁移后再把旧接口逐个下线。这样风险可以控制得很低也不会影响线上业务。迁移过程中有一个关键点原有 REST 接口的错误码和消息格式在 tRPC 里通过TRPCError的code字段映射。前端的拦截器需要同时兼容两种错误格式等旧接口完全下线后再统一收口。6.2 大型项目里的 router 组织策略t3code 目前只有一个note模块但真实项目不会这么简单。当业务模块变多root.ts里 import 的代码会越来越多我习惯按业务域拆分成多个子 routerroot.ts只做挂载不写业务逻辑import { createTRPCRouter } from ./trpc; import { noteRouter } from ./routers/note; import { userRouter } from ./routers/user; import { favoriteRouter } from ./routers/favorite; export const appRouter createTRPCRouter({ note: noteRouter, user: userRouter, favorite: favoriteRouter, });每个子 router 内部如果要再细分可以用命名空间比如noteRouter.create、noteRouter.list这样的层级。这样调用的语义非常清晰前端自然就是useNote.xxx.useQuery()的调用方式不用记任何 URL。6.3 测试策略直接在 Node 层打穿tRPC 带来的一个独特好处是测试变得很轻。因为业务逻辑都在 router 的 procedure 里测试时不需要启动 HTTP 服务直接创建 caller 调用即可const caller appRouter.createCaller({ db: testDb, session: { user: { id: test-id } }, }); const result await caller.note.create({ title: 测试标题, content: 测试内容, visibility: PUBLIC, });这样测试的速度非常快不需要 mock HTTP 层也不需要处理序列化直接调用函数。配合模拟数据库或者测试数据库实例可以覆盖绝大多数业务逻辑。前端组件层的测试再单独用 React Testing Library 处理两层测试职责分离维护成本很低。6.4 性能优化与缓存策略最后聊一下性能。tRPC 默认使用httpBatchLink它会把一个事件循环内的多个请求合并成一个 HTTP POST减少请求次数。这个机制对低流量的应用效果不明显但页面同时调用三五个 query 时网络开销能省一大截。缓存方面React Query 的staleTime参数值得认真配置。默认是 0意味着每次组件挂载都会重新请求。对变化不频繁的数据比如公开笔记列表可以调大const { data } trpc.note.listPublic.useQuery(undefined, { staleTime: 60_000, });这样一分钟内重复进入页面会直接走缓存点击体验会流畅很多。需要注意涉及用户隐私或实时性要求高的数据比如余额、订单状态staleTime不要调太大否则会出现显示滞后。我在实际使用中的体会是t3code 这套实践给自己带来的最大收益不是某个具体功能而是开发节奏的改变。以前写完接口还要写文档、定义类型、来回对字段名。现在改一个数据模型类型差错在编译期就暴露了。整理这个项目的过程里我把每一步踩过的坑都用注释留在代码里了比如为什么加索引、为什么用 cuid、为什么 invalidate 放在 onSuccess。这些看似细碎的点恰恰是文档里查不到、只有自己动手做一遍才能真正理解的。如果你也想转型到类型安全的全栈开发模式我建议别急着追求复杂架构就从一个小项目开始跑通 create-t3-app写出第一个带鉴权的 mutation然后逐步添加模块。等基础建立起来后你会发现自己对“前后端配合”这件事的理解会完全不一样。