做全栈项目最难受的事情是什么我的答案不是写业务代码而是前后端之间那道“无形的墙”。REST API 要维护文档、字段一旦调整就要前后端同时改出了问题还得靠调试工具一遍遍手动试。t3code 这个项目最初就是冲着打破这堵墙去的。我给内部项目起了个代号叫 t3code本质上是围绕 T3 Stack 做的一次完整实践用 TypeScript 把前端、API、数据三层串成同一条类型链路前后端共用同一套类型定义改一个字段编译器直接帮你查出所有受影响的地方。这篇文章我打算把完整的技术选型、实现过程、踩过的坑都摊开讲一遍废话不多说直接进入正题。1. 为什么我把 t3code 定义为一次全栈类型安全的实验1.1 项目背景与要解决的三个核心问题t3code 并不是一个多复杂的业务产品最初想做的只是一个“笔记 团队协作”场景的全栈 Demo用来验证一件事现代 TypeScript 全栈开发到底能省掉多少沟通成本。以前做前后端分离的时候我经历过太多次“前端说字段不对后端说类型没错”的扯皮。后来改用自动化接口文档也只是把问题从口头争执变成了文档同步问题本质没变。于是我把 t3code 的目标定成三个前端调用后端接口时参数和返回值在编辑器里直接有类型提示不需要跳转看文档。数据库表结构变更后从 Schema 到 API 再到页面组件的类型自动联动不允许出现“手写类型对不上”这种情况。鉴权信息在整个调用链路上透明传递前端不需要手动管理每个接口的 Token 头。这三个问题看着都挺基础但传统项目里想同时做到需要非常苛刻的工程纪律。t3code 换了一条路——直接从框架层面解决。1.2 为什么选 T3 Stack 而不是传统前后端分离T3 Stack 这个名字可能有人第一次听说它不是一个“新技术框架”而是把几个成熟的 TypeScript 生态工具组合成了一个标准答案。核心成员只有四个Next.js、TypeScript、tRPC、Prisma加上 Tailwind CSS 负责样式。最大的特点在于“端到端类型安全”。传统前后端分离架构长这样前端 Vue/React 后端 Java/Go/Node 数据库。类型定义在前后端各写一份接口文档靠手写或代码生成联调阶段永远在修边界情况。T3 Stack 则把前后端放进同一个 Next.js 应用里后端能力通过 tRPC 暴露前端直接“导入”后端的 Router 类型来调用。数据库模型由 Prisma 定义而 Prisma 会把数据库表结构直接生成为 TypeScript 类型。所以从数据库到后端的业务函数、再到前端的组件数据绑定整条链路上的类型是天然同步的。我实际操作下来最大的感受是不是“类型完全消灭了 Bug”而是“类型把 Bug 出现的时间点提前到了编译阶段”。以前接口传参错误可能到运行时才暴露现在编辑器里直接提示省掉的可不只是排查时间还有团队成员之间来回确认的沟通成本。1.3 t3code 的项目结构与目录组织t3code 的整体目录结构沿用了 create-t3-app 的标准布局但我在后面自己加了不少约定。核心结构大概是t3code/ ├── app/ # Next.js App Router 页面目录 │ ├── api/ │ │ ├── auth/ # NextAuth 回调查询 │ │ └── trpc/ # tRPC HTTP 入口 │ ├── notes/ # 笔记列表与详情页 │ └── layout.tsx ├── prisma/ │ └── schema.prisma # 数据模型定义 ├── server/ │ ├── api/ │ │ ├── root.ts # tRPC 根 Router │ │ ├── routers/ # 各业务子 Router │ │ └── trpc.ts # tRPC 上下文与初始化逻辑 │ ├── auth.ts # NextAuth 配置 │ └── db.ts # Prisma Client 单例 └── app/utils/ └── api.ts # 前端 tRPC 客户端封装这套结构最妙的地方在于server/目录下的代码是前后端共用的而app/里只有页面组件。前端组件里 import 的api对象本质是一个强类型代理它并不直接访问数据库而是通过 HTTP 调/api/trpc这个 Next.js 路由转发到后端 Router。类型上却跟直接调用本地函数没有差别。2. t3code 技术选型拆解T3 Stack 的每一步都有原因2.1 Next.js App Router 作为应用骨架t3code 选 Next.js 而不是纯前端框架最关键的原因是它同时解决了“服务端渲染”和“API 挂载”两个问题。用 App Router 之后每个页面组件默认在服务端运行页面可以直接通过 tRPC 的服务端调用器caller读取数据渲染成完整的 HTML 再交给浏览器。这样首屏速度快SEO 也自然解决。App Router 的app/目录还带了一个额外的优势布局嵌套。比如 t3code 里的侧边栏导航、顶部的用户状态栏都可以放在app/layout.tsx或局部 layout 中页面切换时布局不重新加载只有内容区的 RSCReact Server Component更新。这种体验很接近以前服务端模板开发的直觉但保持了 React 的组件化开发体验。我个人建议新手直接选 App Router 而不是 Pages Router。虽然 Pages Router 更“经典”但 App Router 是当前 Next.js 的主流方向t3code 对接的许多新能力比如 RSC、服务端 Actions只有 App Router 才完整支持。如果已经在用 Pages Router 的老项目迁移成本确实高但新项目没有理由选旧方案。2.2 tRPC前后端类型同步的核心枢纽tRPC 可能是 T3 Stack 里最让人陌生的模块。它本质上是一个 RPC 框架让你像调用本地函数一样调用后端逻辑。不需要写 REST 路由不需要写 GraphQL Schema只需要在后端定义好一个 Router然后把类型导出给前端。tRPC 的工作流程我的理解是后端用procedure构建可复用的“处理器”每个处理器可以声明输入校验规则和业务逻辑。多个procedure组织成 RouterRouter 之间可以嵌套合并。前端拿到AppRouter类型后生成一个带类型推导的api客户端任意useQuery、useMutation调用都有类型约束。运行时会通过 HTTP POST 请求把调用名和参数传给/api/trpc路由返回结果自动序列化。tRPC 不是凭空发明的概念它本质上是在“框架层面”做了一件很多团队想做但没做成的事情把 TypeScript 类型当作前后端之间的接口契约。REST 的契约是 OpenAPI 文档GraphQL 的契约是 SchematRPC 的契约就是类型本身。因为类型属于代码编译期就存在所以永远不存在“文档过期”的问题。2.3 Prisma数据库表结构如何升级为类型保障数据层用的是 Prisma ORM。它比传统 ORM 更突出的一点是“Schema 优先”的工作方式你先在一个schema.prisma文件里把表和关系定义好然后执行npx prisma migrate生成数据库迁移文件再执行npx prisma generate生成类型安全的 Client。以 t3code 的笔记功能为例一个最简单的模型定义长这样model Note { id String id default(cuid()) title String content String? authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这个模型定义包含了几个关键信息主键用cuid()而不是自增 ID是为了分布式环境下生成 ID 不冲突author字段通过relation与用户表关联updatedAt在每次更新时自动刷新。这些约定一旦写入 SchemaPrisma Client 生成的所有查询接口都会带出对应类型。实际开发中我最喜欢的就是prisma studio这个工具执行npx prisma studio之后会打开一个本地图形界面可以直接查看、编辑数据库记录。排查数据问题的时候比手动写 SQL 快得多。2.4 Tailwind CSS 与样式方案的取舍样式方案选择了 Tailwind CSS这一点其实在 t3code 里争议不大。作为一个验证型的全栈项目Tailwind 最大优势是省心不需要维护 CSS 文件不需要想类名样式全部写在 HTML 上配合组件化开发非常顺畅。但有一个细节值得说Tailwind 的类名嵌套有时会让 JSX 显得很长尤其是复杂的页面组件。我的做法是将每个页面的区块拆分成独立组件Tailwind 负责原子样式组件负责结构复用。项目里我还会用clsx或tailwind-merge来拼接条件类名避免动态类名出现遗漏。如果将来的项目对主题切换有强需求我会考虑引入 CSS Variables 方案但这不属于 t3code 当前的必要条件。3. 实操记录从零搭建 t3code 的完整过程3.1 用 create-t3-app 初始化项目搭建 t3code 的第一步不是手动配置 Webpack 和 TypeScript而是直接使用官方脚手架create-t3-app。这是强烈推荐的方式它会帮你把 Next.js、TypeScript、tRPC、Prisma、NextAuth、Tailwind 全部串好省去大量新手最容易踩坑的“组合配置”环节。实际操作命令npm create t3-applatest t3code执行后会出现交互式选项我当时的选择是TypeScript开启Next.js 版本App RouterTailwind CSS开启Prisma开启NextAuth.js开启tRPC开启包管理器pnpm需要注意create-t3-app的版本更新较快不同版本的可选项会有细微差异但核心方向不会错。项目创建完毕后先执行pnpm install安装依赖然后pnpm dev就能看到默认页面。首次启动时如果提示数据库连接失败通常是 Prisma 还没执行迁移先不用着急排错。3.2 数据模型设计与迁移流程初始化完成后prisma/schema.prisma里只有一个空的示例模型。我设计 t3code 的表结构时从“笔记 用户”这个最小闭环入手User用户基础信息关联笔记和账户信息。Note笔记内容归属某个用户。Account 与 SessionNextAuth 的 OAuth 登录所需的标准表。新增模型后执行迁移命令npx prisma migrate dev --name init这个命令会做三件事创建迁移文件、应用到本地数据库、重新生成 Prisma Client。如果你用的是 PostgreSQL需要先把DATABASE_URL环境变量配置好例如DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/t3code?schemapublic我建议开发环境直接使用 SQLite 起步把DATABASE_URL指向本地文件DATABASE_URLfile:./db.sqlite这样零配置就能跑起来等需要模拟生产环境时再切换 PostgreSQL。切换时只需要改schema.prisma里的provider和DATABASE_URL然后重新迁移但注意两个数据库之间的一些类型差异比如枚举、Json 字段提前确认避免迁移报错。3.3 定义 tRPC Router 并打通前后端调用链路初始化生成的 tRPC 代码已经包含了基础上下文和根 Router。我添加一个笔记功能子 Router 作为示例// server/api/routers/note.ts import { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ~/server/api/trpc; export const noteRouter createTRPCRouter({ list: protectedProcedure .query(async ({ ctx }) { return ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional(), })) .mutation(async ({ ctx, input }) { return ctx.db.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });然后在根 Router 里合并// server/api/root.ts import { createTRPCRouter } from ~/server/api/trpc; import { noteRouter } from ~/server/api/routers/note; export const appRouter createTRPCRouter({ note: noteRouter, });前端的utils/api.ts会自动从appRouter类型推导出api对象。在客户端组件里调用方式非常直白use client; import { api } from ~/utils/api; export function NoteList() { const { data: notes, isLoading } api.note.list.useQuery(); if (isLoading) return div加载中.../div; return ( ul {notes?.map((note) li key{note.id}{note.title}/li)} /ul ); }这里的api.note.list和api.note.create都有完整的类型提示list不需要参数返回一个数组create必须传{ title, content }。一旦后端改了字段名前端直接编译报错这就是整条链路联通的直观效果。3.4 页面侧接入服务端渲染与客户端交互的组合t3code 的页面接入不是一刀切用useQuery而是分了两条路线服务端页面直接用 tRPC 的 caller 在 Server Component 里取数。比如笔记详情页这种读多写少的场景不需要客户端水合hydration等待直接渲染输出。// app/notes/[id]/page.tsx import { createCaller } from ~/server/api/root; import { createTRPCContext } from ~/server/api/trpc; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; export default async function NotePage({ params }: { params: { id: string } }) { const session await getServerSession(authOptions); const caller createCaller(await createTRPCContext({ headers: await headers() })); const note await caller.note.get({ id: params.id }); return pre{JSON.stringify(note, null, 2)}/pre; }客户端交互页面像创建笔记、实时编辑这类高频操作在 Client Component 里用api.note.create.useMutation()。提交成功后调用utils.invalidate()刷新列表不需要手动发事件或刷新页面。这两条路线并不是非此即彼可以混用。我实际项目中经常是一半服务端渲染打底一半客户端交互增强。过度使用useQuery会平白增加客户端请求次数而完全没有客户端交互又会丢掉即时反馈的体验。4. 部署、环境配置与安全实践4.1 部署与环境变量管理t3code 部署最省事的方式是使用 Vercel。在package.json里配置好构建脚本后把仓库导入平台会自动识别 Next.js 项目。关键是在平台控制面板里配置环境变量而不是放在代码仓库里DATABASE_URL指向生产数据库推荐用托管 PostgreSQL。NEXTAUTH_SECRET设置为足够长的随机字符串。NEXTAUTH_URL填写实际部署域名。如果使用邮箱或 OAuth 登录还需要配置对应服务商的密钥。我遇到过最典型的部署翻车场景是本地跑得好好的部署之后页面能开但登录一直失败最后发现是NEXTAUTH_SECRET没设置。这个变量在本地默认不会报错但生产模式下缺失会导致 NextAuth 直接拒绝 session 校验。4.2 数据访问与权限隔离tRPC 里区分publicProcedure和protectedProcedure是安全的一个关键分水岭。protectedProcedure在中间件里强制校验登录状态并把session.user注入到ctx中业务逻辑里可以直接用ctx.session.user.id作为数据归属条件。所有涉及用户私有数据的查询都必须用protectedProcedure否则任何人可以直接调用你的 API 拉取全部数据。另一个容易忽视的点是“多租户数据越权”。比如笔记详情查询如果只写db.note.findUnique({ where: { id } })攻击者只要遍历 ID 就能读取他人笔记。正确写法是db.note.findFirst({ where: { id: input.id, authorId: ctx.session.user.id }, });findFirst加上authorId条件从第一步就把越权风险挡掉了。这个习惯我在 t3code 里从最开始就强制自己执行。4.3 输入校验与异常处理tRPC 天然支持 Zod 校验每个 mutation 的输入都要用z.object({...})包裹。这不仅是“安全习惯”也是“类型来源”Zod 推导出的类型就是前端参数类型。比如const noteSchema z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string().max(10000).optional(), });前端调用时如果不满足规则tRPC 会自动返回校验错误不需要手写if (title )之类的分支判断。错误信息还能直接通过useMutation().error拿到。这块一开始可能觉得麻烦但是形成习惯之后接口健壮性提升非常明显。5. 踩坑记录t3code 开发过程中真实遇到的雷区5.1 Prisma Client 在开发模式下被反复实例化t3code 第一个遇见的坑来自 Next.js 的开发模式热重载。每改动一个文件Next.js 会重新执行模块代码如果没有处理单例Prisma Client 会被创建多次报出大量错误提示甚至导致数据库连接数暴涨。解决办法是使用全局单例模式// server/db.ts import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }这个代码的核心思路是开发环境中把实例挂到全局对象上避免每次热更新都新建生产环境中则不存在热重载问题可以放心新建。我把这个单例模式视为所有 Next.js Prisma 项目的标配。5.2 tRPC 版本升级带来的 API 变化t3code 开发期间正好赶上 tRPC 从 v10 升级到 v11踩坑最重的一次就在这里。v10 中的createReactQueryUtils在 v11 里变成了createCaller相关的新函数Router 的初始化方式也从initTRPC.create()改了不少细节。如果你使用旧教程的代码去匹配新版本编译报错会比较多。我的经验是遇到 tRPC 相关报错不要直接搜索引擎找旧答案先去官网看对应版本的 migration guide。create-t3-app 生成的项目版本一定是当时最新的跟着旧博客手动改依赖版本是最不值当的做法。现在我再看这类升级第一反应永远是查 changelog而不是对着报错胡乱尝试。5.3 NextAuth 与 App Router 的集成细节NextAuth 在 App Router 下有几种落地方式最容易踩坑的地方是 middleware。如果你打算用middleware.ts做路由守卫必须注意文件位置在src/middleware.ts或者项目根目录middleware.ts并且导出的方式是export { default } from next-auth/middleware;另外一个容易忽视的问题是App Router 中headers()和cookies()在 Next.js 15 之后变成了异步函数直接调用会报“Outside of request scope”之类的错误。正确写法是await headers()。t3code 里的 tRPC 上下文需要读取请求头里的 session cookie最初我忽略了 await 导致本地登录失效排查半天才意识到是版本特性变化。5.4 开发环境与生产环境的行为差异有几次 t3code 在开发环境一切正常部署到生产环境却出现诡异问题归纳起来有三类最常见现象原因解决方式登录后刷新丢失状态NEXTAUTH_SECRET未配置或与本地不一致生产环境显式配置强随机密钥数据库查询变慢开发环境数据量小没建索引Schema 中检查常用查询字段加indexAPI 请求 404NEXTAUTH_URL不匹配实际域名确认环境变量与正式域名完全一致生产环境和开发环境的差异很难通过本地完全复现我现在的流程是跑通功能后第一时间部署到 Staging 环境用真实的数据库和域名做一次完整验证再切生产。这一步省下的排查时间远超它本身消耗的时间。6. 后续扩展方向与我的真实体会6.1 t3code 的下一步计划t3code 目前只是把全栈类型安全这条路走通了但离“完善”还有不少距离。我接下来准备做三件事第一引入 WebSocket 或 SSE加入笔记实时同步能力。tRPC 在请求响应模式上做得很顺但实时推送不是它的强项需要切换到 Server-Sent Events 或者独立的消息通道。第二把服务端缓存加上。现在列表页每次刷新都直接查库笔记数量上来后响应时间逐渐变长。我计划在服务端 caller 外层加一层 Response Cache针对单个用户的笔记列表做短时间缓存。第三给 t3code 做一个可视化的数据看板用上prisma的聚合查询、tRPC 的 procedure 级 metrics加上 Next.js 自带性能分析把整个项目的状态可视化。这样既能验证 T3 Stack 在数据密集型场景的承受力也能顺手沉淀一套全栈项目的可观测性方案。6.2 关于类型安全说说我这几周的真实感受t3code 这套方案最打动我的不是“代码更少”或“性能更好”而是它把工程师的注意力从“接口协调”中彻底解放出来了。以前写后端要给别人留接口文档写前端要问别人拿 mock 数据现在类型系统就是唯一的真相来源。团队新人接手项目时不需要看几十页文档编辑器里的类型提示会一步步引导他把功能做出来。当然T3 Stack 不是银弹它更适合 TypeScript 全栈团队、中小型业务系统、以及产品原型阶段。如果你的团队里后端是 Java 或 Go那显然没法硬套如果项目有大量第三方系统需要对接REST 依然是边界上更稳妥的协议。但在你能完全掌控技术栈的项目里我强烈建议认真体验一次“类型全链路”的开发模式那种编译器替你挡住低级错误的踏实感值得试一次。
做全栈项目最难受的事情是什么我的答案不是写业务代码而是前后端之间那道“无形的墙”。REST API 要维护文档、字段一旦调整就要前后端同时改出了问题还得靠调试工具一遍遍手动试。t3code 这个项目最初就是冲着打破这堵墙去的。我给内部项目起了个代号叫 t3code本质上是围绕 T3 Stack 做的一次完整实践用 TypeScript 把前端、API、数据三层串成同一条类型链路前后端共用同一套类型定义改一个字段编译器直接帮你查出所有受影响的地方。这篇文章我打算把完整的技术选型、实现过程、踩过的坑都摊开讲一遍废话不多说直接进入正题。1. 为什么我把 t3code 定义为一次全栈类型安全的实验1.1 项目背景与要解决的三个核心问题t3code 并不是一个多复杂的业务产品最初想做的只是一个“笔记 团队协作”场景的全栈 Demo用来验证一件事现代 TypeScript 全栈开发到底能省掉多少沟通成本。以前做前后端分离的时候我经历过太多次“前端说字段不对后端说类型没错”的扯皮。后来改用自动化接口文档也只是把问题从口头争执变成了文档同步问题本质没变。于是我把 t3code 的目标定成三个前端调用后端接口时参数和返回值在编辑器里直接有类型提示不需要跳转看文档。数据库表结构变更后从 Schema 到 API 再到页面组件的类型自动联动不允许出现“手写类型对不上”这种情况。鉴权信息在整个调用链路上透明传递前端不需要手动管理每个接口的 Token 头。这三个问题看着都挺基础但传统项目里想同时做到需要非常苛刻的工程纪律。t3code 换了一条路——直接从框架层面解决。1.2 为什么选 T3 Stack 而不是传统前后端分离T3 Stack 这个名字可能有人第一次听说它不是一个“新技术框架”而是把几个成熟的 TypeScript 生态工具组合成了一个标准答案。核心成员只有四个Next.js、TypeScript、tRPC、Prisma加上 Tailwind CSS 负责样式。最大的特点在于“端到端类型安全”。传统前后端分离架构长这样前端 Vue/React 后端 Java/Go/Node 数据库。类型定义在前后端各写一份接口文档靠手写或代码生成联调阶段永远在修边界情况。T3 Stack 则把前后端放进同一个 Next.js 应用里后端能力通过 tRPC 暴露前端直接“导入”后端的 Router 类型来调用。数据库模型由 Prisma 定义而 Prisma 会把数据库表结构直接生成为 TypeScript 类型。所以从数据库到后端的业务函数、再到前端的组件数据绑定整条链路上的类型是天然同步的。我实际操作下来最大的感受是不是“类型完全消灭了 Bug”而是“类型把 Bug 出现的时间点提前到了编译阶段”。以前接口传参错误可能到运行时才暴露现在编辑器里直接提示省掉的可不只是排查时间还有团队成员之间来回确认的沟通成本。1.3 t3code 的项目结构与目录组织t3code 的整体目录结构沿用了 create-t3-app 的标准布局但我在后面自己加了不少约定。核心结构大概是t3code/ ├── app/ # Next.js App Router 页面目录 │ ├── api/ │ │ ├── auth/ # NextAuth 回调查询 │ │ └── trpc/ # tRPC HTTP 入口 │ ├── notes/ # 笔记列表与详情页 │ └── layout.tsx ├── prisma/ │ └── schema.prisma # 数据模型定义 ├── server/ │ ├── api/ │ │ ├── root.ts # tRPC 根 Router │ │ ├── routers/ # 各业务子 Router │ │ └── trpc.ts # tRPC 上下文与初始化逻辑 │ ├── auth.ts # NextAuth 配置 │ └── db.ts # Prisma Client 单例 └── app/utils/ └── api.ts # 前端 tRPC 客户端封装这套结构最妙的地方在于server/目录下的代码是前后端共用的而app/里只有页面组件。前端组件里 import 的api对象本质是一个强类型代理它并不直接访问数据库而是通过 HTTP 调/api/trpc这个 Next.js 路由转发到后端 Router。类型上却跟直接调用本地函数没有差别。2. t3code 技术选型拆解T3 Stack 的每一步都有原因2.1 Next.js App Router 作为应用骨架t3code 选 Next.js 而不是纯前端框架最关键的原因是它同时解决了“服务端渲染”和“API 挂载”两个问题。用 App Router 之后每个页面组件默认在服务端运行页面可以直接通过 tRPC 的服务端调用器caller读取数据渲染成完整的 HTML 再交给浏览器。这样首屏速度快SEO 也自然解决。App Router 的app/目录还带了一个额外的优势布局嵌套。比如 t3code 里的侧边栏导航、顶部的用户状态栏都可以放在app/layout.tsx或局部 layout 中页面切换时布局不重新加载只有内容区的 RSCReact Server Component更新。这种体验很接近以前服务端模板开发的直觉但保持了 React 的组件化开发体验。我个人建议新手直接选 App Router 而不是 Pages Router。虽然 Pages Router 更“经典”但 App Router 是当前 Next.js 的主流方向t3code 对接的许多新能力比如 RSC、服务端 Actions只有 App Router 才完整支持。如果已经在用 Pages Router 的老项目迁移成本确实高但新项目没有理由选旧方案。2.2 tRPC前后端类型同步的核心枢纽tRPC 可能是 T3 Stack 里最让人陌生的模块。它本质上是一个 RPC 框架让你像调用本地函数一样调用后端逻辑。不需要写 REST 路由不需要写 GraphQL Schema只需要在后端定义好一个 Router然后把类型导出给前端。tRPC 的工作流程我的理解是后端用procedure构建可复用的“处理器”每个处理器可以声明输入校验规则和业务逻辑。多个procedure组织成 RouterRouter 之间可以嵌套合并。前端拿到AppRouter类型后生成一个带类型推导的api客户端任意useQuery、useMutation调用都有类型约束。运行时会通过 HTTP POST 请求把调用名和参数传给/api/trpc路由返回结果自动序列化。tRPC 不是凭空发明的概念它本质上是在“框架层面”做了一件很多团队想做但没做成的事情把 TypeScript 类型当作前后端之间的接口契约。REST 的契约是 OpenAPI 文档GraphQL 的契约是 SchematRPC 的契约就是类型本身。因为类型属于代码编译期就存在所以永远不存在“文档过期”的问题。2.3 Prisma数据库表结构如何升级为类型保障数据层用的是 Prisma ORM。它比传统 ORM 更突出的一点是“Schema 优先”的工作方式你先在一个schema.prisma文件里把表和关系定义好然后执行npx prisma migrate生成数据库迁移文件再执行npx prisma generate生成类型安全的 Client。以 t3code 的笔记功能为例一个最简单的模型定义长这样model Note { id String id default(cuid()) title String content String? authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这个模型定义包含了几个关键信息主键用cuid()而不是自增 ID是为了分布式环境下生成 ID 不冲突author字段通过relation与用户表关联updatedAt在每次更新时自动刷新。这些约定一旦写入 SchemaPrisma Client 生成的所有查询接口都会带出对应类型。实际开发中我最喜欢的就是prisma studio这个工具执行npx prisma studio之后会打开一个本地图形界面可以直接查看、编辑数据库记录。排查数据问题的时候比手动写 SQL 快得多。2.4 Tailwind CSS 与样式方案的取舍样式方案选择了 Tailwind CSS这一点其实在 t3code 里争议不大。作为一个验证型的全栈项目Tailwind 最大优势是省心不需要维护 CSS 文件不需要想类名样式全部写在 HTML 上配合组件化开发非常顺畅。但有一个细节值得说Tailwind 的类名嵌套有时会让 JSX 显得很长尤其是复杂的页面组件。我的做法是将每个页面的区块拆分成独立组件Tailwind 负责原子样式组件负责结构复用。项目里我还会用clsx或tailwind-merge来拼接条件类名避免动态类名出现遗漏。如果将来的项目对主题切换有强需求我会考虑引入 CSS Variables 方案但这不属于 t3code 当前的必要条件。3. 实操记录从零搭建 t3code 的完整过程3.1 用 create-t3-app 初始化项目搭建 t3code 的第一步不是手动配置 Webpack 和 TypeScript而是直接使用官方脚手架create-t3-app。这是强烈推荐的方式它会帮你把 Next.js、TypeScript、tRPC、Prisma、NextAuth、Tailwind 全部串好省去大量新手最容易踩坑的“组合配置”环节。实际操作命令npm create t3-applatest t3code执行后会出现交互式选项我当时的选择是TypeScript开启Next.js 版本App RouterTailwind CSS开启Prisma开启NextAuth.js开启tRPC开启包管理器pnpm需要注意create-t3-app的版本更新较快不同版本的可选项会有细微差异但核心方向不会错。项目创建完毕后先执行pnpm install安装依赖然后pnpm dev就能看到默认页面。首次启动时如果提示数据库连接失败通常是 Prisma 还没执行迁移先不用着急排错。3.2 数据模型设计与迁移流程初始化完成后prisma/schema.prisma里只有一个空的示例模型。我设计 t3code 的表结构时从“笔记 用户”这个最小闭环入手User用户基础信息关联笔记和账户信息。Note笔记内容归属某个用户。Account 与 SessionNextAuth 的 OAuth 登录所需的标准表。新增模型后执行迁移命令npx prisma migrate dev --name init这个命令会做三件事创建迁移文件、应用到本地数据库、重新生成 Prisma Client。如果你用的是 PostgreSQL需要先把DATABASE_URL环境变量配置好例如DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/t3code?schemapublic我建议开发环境直接使用 SQLite 起步把DATABASE_URL指向本地文件DATABASE_URLfile:./db.sqlite这样零配置就能跑起来等需要模拟生产环境时再切换 PostgreSQL。切换时只需要改schema.prisma里的provider和DATABASE_URL然后重新迁移但注意两个数据库之间的一些类型差异比如枚举、Json 字段提前确认避免迁移报错。3.3 定义 tRPC Router 并打通前后端调用链路初始化生成的 tRPC 代码已经包含了基础上下文和根 Router。我添加一个笔记功能子 Router 作为示例// server/api/routers/note.ts import { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ~/server/api/trpc; export const noteRouter createTRPCRouter({ list: protectedProcedure .query(async ({ ctx }) { return ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional(), })) .mutation(async ({ ctx, input }) { return ctx.db.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });然后在根 Router 里合并// server/api/root.ts import { createTRPCRouter } from ~/server/api/trpc; import { noteRouter } from ~/server/api/routers/note; export const appRouter createTRPCRouter({ note: noteRouter, });前端的utils/api.ts会自动从appRouter类型推导出api对象。在客户端组件里调用方式非常直白use client; import { api } from ~/utils/api; export function NoteList() { const { data: notes, isLoading } api.note.list.useQuery(); if (isLoading) return div加载中.../div; return ( ul {notes?.map((note) li key{note.id}{note.title}/li)} /ul ); }这里的api.note.list和api.note.create都有完整的类型提示list不需要参数返回一个数组create必须传{ title, content }。一旦后端改了字段名前端直接编译报错这就是整条链路联通的直观效果。3.4 页面侧接入服务端渲染与客户端交互的组合t3code 的页面接入不是一刀切用useQuery而是分了两条路线服务端页面直接用 tRPC 的 caller 在 Server Component 里取数。比如笔记详情页这种读多写少的场景不需要客户端水合hydration等待直接渲染输出。// app/notes/[id]/page.tsx import { createCaller } from ~/server/api/root; import { createTRPCContext } from ~/server/api/trpc; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; export default async function NotePage({ params }: { params: { id: string } }) { const session await getServerSession(authOptions); const caller createCaller(await createTRPCContext({ headers: await headers() })); const note await caller.note.get({ id: params.id }); return pre{JSON.stringify(note, null, 2)}/pre; }客户端交互页面像创建笔记、实时编辑这类高频操作在 Client Component 里用api.note.create.useMutation()。提交成功后调用utils.invalidate()刷新列表不需要手动发事件或刷新页面。这两条路线并不是非此即彼可以混用。我实际项目中经常是一半服务端渲染打底一半客户端交互增强。过度使用useQuery会平白增加客户端请求次数而完全没有客户端交互又会丢掉即时反馈的体验。4. 部署、环境配置与安全实践4.1 部署与环境变量管理t3code 部署最省事的方式是使用 Vercel。在package.json里配置好构建脚本后把仓库导入平台会自动识别 Next.js 项目。关键是在平台控制面板里配置环境变量而不是放在代码仓库里DATABASE_URL指向生产数据库推荐用托管 PostgreSQL。NEXTAUTH_SECRET设置为足够长的随机字符串。NEXTAUTH_URL填写实际部署域名。如果使用邮箱或 OAuth 登录还需要配置对应服务商的密钥。我遇到过最典型的部署翻车场景是本地跑得好好的部署之后页面能开但登录一直失败最后发现是NEXTAUTH_SECRET没设置。这个变量在本地默认不会报错但生产模式下缺失会导致 NextAuth 直接拒绝 session 校验。4.2 数据访问与权限隔离tRPC 里区分publicProcedure和protectedProcedure是安全的一个关键分水岭。protectedProcedure在中间件里强制校验登录状态并把session.user注入到ctx中业务逻辑里可以直接用ctx.session.user.id作为数据归属条件。所有涉及用户私有数据的查询都必须用protectedProcedure否则任何人可以直接调用你的 API 拉取全部数据。另一个容易忽视的点是“多租户数据越权”。比如笔记详情查询如果只写db.note.findUnique({ where: { id } })攻击者只要遍历 ID 就能读取他人笔记。正确写法是db.note.findFirst({ where: { id: input.id, authorId: ctx.session.user.id }, });findFirst加上authorId条件从第一步就把越权风险挡掉了。这个习惯我在 t3code 里从最开始就强制自己执行。4.3 输入校验与异常处理tRPC 天然支持 Zod 校验每个 mutation 的输入都要用z.object({...})包裹。这不仅是“安全习惯”也是“类型来源”Zod 推导出的类型就是前端参数类型。比如const noteSchema z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string().max(10000).optional(), });前端调用时如果不满足规则tRPC 会自动返回校验错误不需要手写if (title )之类的分支判断。错误信息还能直接通过useMutation().error拿到。这块一开始可能觉得麻烦但是形成习惯之后接口健壮性提升非常明显。5. 踩坑记录t3code 开发过程中真实遇到的雷区5.1 Prisma Client 在开发模式下被反复实例化t3code 第一个遇见的坑来自 Next.js 的开发模式热重载。每改动一个文件Next.js 会重新执行模块代码如果没有处理单例Prisma Client 会被创建多次报出大量错误提示甚至导致数据库连接数暴涨。解决办法是使用全局单例模式// server/db.ts import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }这个代码的核心思路是开发环境中把实例挂到全局对象上避免每次热更新都新建生产环境中则不存在热重载问题可以放心新建。我把这个单例模式视为所有 Next.js Prisma 项目的标配。5.2 tRPC 版本升级带来的 API 变化t3code 开发期间正好赶上 tRPC 从 v10 升级到 v11踩坑最重的一次就在这里。v10 中的createReactQueryUtils在 v11 里变成了createCaller相关的新函数Router 的初始化方式也从initTRPC.create()改了不少细节。如果你使用旧教程的代码去匹配新版本编译报错会比较多。我的经验是遇到 tRPC 相关报错不要直接搜索引擎找旧答案先去官网看对应版本的 migration guide。create-t3-app 生成的项目版本一定是当时最新的跟着旧博客手动改依赖版本是最不值当的做法。现在我再看这类升级第一反应永远是查 changelog而不是对着报错胡乱尝试。5.3 NextAuth 与 App Router 的集成细节NextAuth 在 App Router 下有几种落地方式最容易踩坑的地方是 middleware。如果你打算用middleware.ts做路由守卫必须注意文件位置在src/middleware.ts或者项目根目录middleware.ts并且导出的方式是export { default } from next-auth/middleware;另外一个容易忽视的问题是App Router 中headers()和cookies()在 Next.js 15 之后变成了异步函数直接调用会报“Outside of request scope”之类的错误。正确写法是await headers()。t3code 里的 tRPC 上下文需要读取请求头里的 session cookie最初我忽略了 await 导致本地登录失效排查半天才意识到是版本特性变化。5.4 开发环境与生产环境的行为差异有几次 t3code 在开发环境一切正常部署到生产环境却出现诡异问题归纳起来有三类最常见现象原因解决方式登录后刷新丢失状态NEXTAUTH_SECRET未配置或与本地不一致生产环境显式配置强随机密钥数据库查询变慢开发环境数据量小没建索引Schema 中检查常用查询字段加indexAPI 请求 404NEXTAUTH_URL不匹配实际域名确认环境变量与正式域名完全一致生产环境和开发环境的差异很难通过本地完全复现我现在的流程是跑通功能后第一时间部署到 Staging 环境用真实的数据库和域名做一次完整验证再切生产。这一步省下的排查时间远超它本身消耗的时间。6. 后续扩展方向与我的真实体会6.1 t3code 的下一步计划t3code 目前只是把全栈类型安全这条路走通了但离“完善”还有不少距离。我接下来准备做三件事第一引入 WebSocket 或 SSE加入笔记实时同步能力。tRPC 在请求响应模式上做得很顺但实时推送不是它的强项需要切换到 Server-Sent Events 或者独立的消息通道。第二把服务端缓存加上。现在列表页每次刷新都直接查库笔记数量上来后响应时间逐渐变长。我计划在服务端 caller 外层加一层 Response Cache针对单个用户的笔记列表做短时间缓存。第三给 t3code 做一个可视化的数据看板用上prisma的聚合查询、tRPC 的 procedure 级 metrics加上 Next.js 自带性能分析把整个项目的状态可视化。这样既能验证 T3 Stack 在数据密集型场景的承受力也能顺手沉淀一套全栈项目的可观测性方案。6.2 关于类型安全说说我这几周的真实感受t3code 这套方案最打动我的不是“代码更少”或“性能更好”而是它把工程师的注意力从“接口协调”中彻底解放出来了。以前写后端要给别人留接口文档写前端要问别人拿 mock 数据现在类型系统就是唯一的真相来源。团队新人接手项目时不需要看几十页文档编辑器里的类型提示会一步步引导他把功能做出来。当然T3 Stack 不是银弹它更适合 TypeScript 全栈团队、中小型业务系统、以及产品原型阶段。如果你的团队里后端是 Java 或 Go那显然没法硬套如果项目有大量第三方系统需要对接REST 依然是边界上更稳妥的协议。但在你能完全掌控技术栈的项目里我强烈建议认真体验一次“类型全链路”的开发模式那种编译器替你挡住低级错误的踏实感值得试一次。
实现与优化)
