T3全栈实践：从数据库到UI的类型安全开发

如果你最近在逛 Next.js 或者 TypeScript 相关的内容，“t3”这个前缀应该不算陌生。t3code 是我给最近一个全栈练习项目起的代号，名字直接源于 create-t3-app 那一套组合：Next.js、TypeScript、Tailwind CSS、tRPC，再加上 Prisma 和 NextAuth.js 处理数据和登录。项目本身是一个带后台的内容发布站，功能不算复杂，但要求从数据库到页面按钮全部由 TypeScript 一条链路贯穿。从脚手架初始化到最终部署上线，我花了大概两周，中间踩了不少文档上没有明着写的坑。这篇文章就是把整个 t3code 的搭建过程、关键链路和选型逻辑原样捋一遍。如果你也在观望要不要上手 T3 这套东西，或者刚 create-t3-app 完不知道下一步怎么串起来，这篇文章应该能帮你省不少时间。

1. 我为什么在 t3code 里押注 T3 全栈组合

1.1 t3code 到底要解决什么问题

t3code 要做的其实是一个很常见的内容站：用户注册登录、管理员发文章、前台列表展示和详情阅读。换成我以前的做法，大概率是“Next.js 写前端 + Express 写 API + MySQL 存数据”，前端再手写一堆接口类型定义。这种经典分家方案不是不能跑，但做久了有一个非常烦的体验——类型不同步。

后端接口把返回结构改了，前端不会第一时间知道，往往要等到联调或者测试跑完才暴露问题。时间一长，大量精力都消耗在“对齐接口约定”上，而非业务本身。所以 t3code 的核心诉求不是功能多炫酷，而是“一套类型走到底”：数据库表长什么样、API 返回什么、前端拿到的数据长什么样，这三者在编译期就必须一致，不允许出现“明明文档说返回字符串，运行时却给我一个对象”这种破事。这也是 T3 全栈组合最打动我的地方。

1.2 T3 这套组合的核心逻辑：把类型安全当成第一优先级

T3 栈不是某个公司推出的框架，而是围绕 TypeScript 组织起来的一套实践集合。它有一个很"强硬"的约定：能用编译器推导类型的地方，就不用运行时猜；能同构同步的，就不手写双份定义。具体到 t3code 项目里，这条链路长这样：

• Next.js：负责页面渲染和部分服务端能力，t3code 用的是 App Router 模式；
• tRPC：替代传统 REST，让前端像调用本地函数一样调用后端函数，类型自动推导；
• Prisma：ORM 层，通过 schema 定义数据库表，自动生成全量的 TypeScript 类型；
• NextAuth.js：处理登录认证，和 Next.js 服务端会话深度集成；
• Tailwind CSS：负责样式，效率和一致性都高，create-t3-app 默认集成，省去配置成本。

拿 t3code 最核心的场景举例：Prisma schema 里定义了 Post 模型，tRPC 里写一个 getPost procedure，然后我在前端代码里输入post.title，编辑器立刻会给出正确的类型提示。整条链路里没有手写的 DTO、interface、类型守卫，这在传统“前端 + 后端 + 中间协议”模式里几乎是不可想象的。

那是不是所有项目都应该无脑上 T3？我的判断是不一定。如果你的服务端逻辑大部分不是 Node.js 生态，团队主力语言是 Java、Python，那“全 TypeScript”这个优势会被明显冲淡。如果项目涉及复杂权限模型、跨系统大量接口对接，REST 的可观测性和文档生态依然更成熟。我在立项 t3code 之前犹豫过这一点，最后是因为它本身是单人主导、业务边界清晰，才决定用这整套方案。

1.3 一套组合拳能不能成立，关键看边界是否清晰

在 t3code 里我体会到一件事：T3 全栈的舒适区，是“一个人或者一个小团队，用一套语言，做一个边界明确的产品”。一旦超出一个应用本身，比如要对接十几个外部服务、跨部门分工明确、前后端团队人员结构固定，T3 的优势反而会被协作成本抵消。所以这套组合不是银弹，而是针对特定场景的极优解。

2. 搭骨架：create-t3-app 初始化与目录结构里的设计意图

2.1 初始化命令与选项取舍

创建 t3code 本身没什么技术含量，一条命令的事：

pnpm create t3-app@latest

真正的决策发生在交互式选项里。create-t3-app 会让你勾选需要的模块。我当时的勾选情况如下：

• Tailwind CSS：必选，写样式效率高，而且脚手架已经配好；
• Prisma：必选，数据模型全靠它；
• tRPC：必选，这是核心数据链路；
• NextAuth.js：必选，内容站绕不开登录；
• ESLint + Prettier：必选，代码风格从第一天统一；
• Playwright：不选，前期优先验证核心链路，E2E 测试等页面稳定了再补；
• Docker：不选，本地开发环境不用容器，部署走托管平台也不需要。

为什么不要 Playwright？t3code 前期最重要的是把 tRPC、Prisma、NextAuth 这条主链路跑通，测试工具链一开始拉得太重反而会拖慢节奏。等核心功能稳定后补 E2E 是完全来得及的，我后面确实也打算补。

生成后展示的项目结构大致是这样的：

src/ ├── app/ │ ├── page.tsx │ ├── layout.tsx │ └── api/ │ └── auth/[...nextauth]/ ├── server/ │ ├── api/ │ │ ├── root.ts │ │ └── routers/ │ ├── auth.ts │ └── db.ts ├── trpc/ │ ├── server.ts │ ├── client.ts │ └── react.tsx └── styles/

很多第一次接触 create-t3-app 的人会困惑：为什么src/trpc和src/server要分开？在 t3code 里我实际体会到了这套划分的价值。src/server是纯服务端世界，可以安全地访问数据库、环境变量、鉴权信息；src/trpc是暴露给前端的边界，router 定义会被组件直接引用。边界一旦清晰，后面写业务代码就不会出现"在页面组件里直接 import Prisma client"这种坏味道——那不是不能跑，而是把不该泄漏的实现细节暴露给了前端。

2.2 一个容易被忽略的协作坑：包管理器一致性

create-t3-app 生成项目时，会根据你当前使用的包管理器来生成 lock 文件。我自己用 pnpm，但有一次在另一台机器上用 npm install，结果node_modules和 lock 文件对不上，命令行里疯狂提示冲突，最离谱的一次连依赖版本都产生了差异。团队协作时，这个问题会被放大。

建议在项目 README 的第一行写明包管理器版本和 Node 版本。t3code 的经验是：这种小细节看着不起眼，但一旦出问题，排查成本比写代码高得多。统一环境是投入产出比最高的第一步。

2.3 数据模型设计：给 t3code 定一套清楚的结构

内容站的数据关系天然清晰：用户、文章、标签。t3code 的 Prisma schema 里核心是 User 和 Post：

model User { id String @id @default(cuid()) name String? email String? @unique image String? passwordHash String? posts Post[] accounts Account[] sessions Session[] } model Post { id String @id @default(cuid()) title String content String @db.MediumText published Boolean @default(false) authorId String author User @relation(fields: [authorId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

主键这里我特意选了cuid()而不是自增Int。原因有两个：一是分布式环境下 cuid 不需要查数据库自增序列，冲突概率低；二是内容站的文章链接如果带自增 id，容易被爬虫批量枚举，cuid 能提高一点信息安全性。代价是索引稍微大一点，但对 t3code 这种量级的站点完全不是问题。

schema 改动之后，开发环境用npx prisma migrate dev生成迁移文件并更新数据库，这个命令是把 schema 变更和 migration 历史绑在一起的关键步骤，后面部署章节我会专门说为什么生产环境不能靠它。

3. 数据链路：tRPC + Prisma 从数据库到 UI 的类型同构

3.1 tRPC 的一句话工作原理

用一句话概括 tRPC：让前端像调用本地函数一样调用后端函数，并且通过 TypeScript 类型推导，把后端入参出参的类型直接带到前端。它不是 REST，也不是 GraphQL，本质上是一个基于 HTTP 的远程过程调用方案。

生活化类比一下：你给同事发消息说“帮我把 112 号文章的内容拿过来”，同事干完活直接把文章文本发给你。整个过程你不需要预先查通讯录确认他工号，也不需要约定一个“统一的邮件模板”，你们俩天然拥有同一套认知。tRPC 就是把这种默契类型化了——路由名就是函数路径，入参就是函数参数，返回值就是函数返回值。

3.2 从 Prisma 到 tRPC 的完整链路

以 t3code 的文章列表页为例，服务端 router 定义在src/server/api/routers/post.ts：

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "@/server/api/trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure .input( z.object({ page: z.number().default(1), pageSize: z.number().default(10), }) ) .query(async ({ ctx, input }) => { const posts = await ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: "desc" }, skip: (input.page - 1) * input.pageSize, take: input.pageSize, select: { id: true, title: true, createdAt: true, author: { select: { name: true }, }, }, }); return posts; }), detail: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) => { return ctx.db.post.findUnique({ where: { id: input.id }, include: { author: { select: { name: true } }, }, }); }), });

这里的ctx.db是服务端注入的 Prisma client，前端永远不需要关心数据库在哪里连接、连接串是什么。前端组件里调用list是这样写的：

import { api } from "@/trpc/react"; export function PostList() { const { data, isLoading } = api.post.list.useQuery({ page: 1, pageSize: 10, }); if (isLoading) return <div>加载中...</div>; return ( <ul> {data?.map((post) => ( <li key={post.id}> <h2>{post.title}</h2> <span>{post.author.name}</span> </li> ))} </ul> ); }

注意api.post.list.useQuery里的post.list不是魔法字符串，它对应后端路由路径，类型是全量推导的。如果后端list的返回结构变了，前端代码这里会直接编译报错。这种“改一端，另一端立刻红”的体验，就是类型同构的实际价值。

3.3 zod 在输入校验里扮演的角色

create-t3-app 默认集成 zod，procedure 的 input 声明用 zod schema 完成。它做的事情是“运行时校验 + 编译期类型推导”二合一。t3code 早期我犯过一个低级错误：detail的 input 没加 zod 校验，前端传了一个 undefined 进去，TypeScript 编译期没拦到（因为参数类型是 string），但运行时就崩了。补上z.string()之后，编译器立刻能拦住非法调用。

建议所有 procedure 都写 input 校验，哪怕是空对象z.object({}).optional()也写上。这不是为了炫技，而是让你明确知道这个 procedure 的入参边界在哪。

3.4 mutation 和缓存失效：发布文章的正确姿势

内容站肯定有“创建文章”这个动作。t3code 里对应的 mutation 写法是：

createPost: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(10), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }),

前端调用时，最容易被忽略的是缓存失效：

const utils = api.useUtils(); const createMutation = api.post.createPost.useMutation({ onSuccess: async () => { await utils.post.list.invalidate(); }, });

为什么要主动invalidate？因为 React Query 会缓存列表查询结果。发布完文章，缓存不会自动知道数据库变了。第一次在 t3code 里写发布功能时我忘了这步，数据库里明明多了文章，前端列表死活不刷新，我还以为是后端写入失败。排查半天，罪魁祸首就是缺了一次缓存失效。这个坑的教训是：凡是 mutation 成功后会改变列表结果的，都要立刻失效对应的 query 缓存。

4. 鉴权实践：NextAuth 与 tRPC 中间件的组合方式

4.1 为什么我选了 JWT session 而非 database session

create-t3-app 默认集成 NextAuth.js，但它默认的 session 策略是 database session，需要建一张 Session 表。t3code 里我改成了 JWT session，理由很简单：少维护一张表，部署时不用处理额外的数据库回话机制。代价是 JWT 需要配置 secret，并且要在回调里手动把用户信息注入 token。

如果你用的是自建的邮箱密码体系，而不是纯 OAuth，JWT 策略会更合适。t3code 的 auth 配置核心是这样一段：

import NextAuth from "next-auth"; import Credentials from "next-auth/providers/credentials"; import bcrypt from "bcryptjs"; import { db } from "@/server/db"; export const { handlers, auth, signIn, signOut } = NextAuth({ session: { strategy: "jwt" }, providers: [ Credentials({ credentials: { email: { label: "邮箱", type: "email" }, password: { label: "密码", type: "password" }, }, async authorize(credentials) { const user = await db.user.findUnique({ where: { email: credentials.email as string }, }); if (!user || !user.passwordHash) return null; const ok = await bcrypt.compare( credentials.password as string, user.passwordHash ); return ok ? { id: user.id, name: user.name, email: user.email } : null; }, }), ], callbacks: { jwt({ token, user }) { if (user) token.id = user.id; return token; }, session({ session, token }) { if (token.id) session.user.id = token.id; return session; }, }, });

注意这里要安装bcryptjs，并且 User 表里要有passwordHash字段。用 OAuth 登录也能做，但如果你想要的是“邮箱注册 + 密码登录”这种自建账号体系，Credentials provider 是标准方案。

4.2 用 tRPC 中间件实现受保护的 procedure

create-t3-app 生成的src/server/api/trpc.ts里，其实已经内置了protectedProcedure和adminProcedure的雏形。核心逻辑很简单：执行 procedure 前先检查ctx.session是否存在，不存在就直接抛出未授权错误。

export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { session: { user: ctx.session.user }, }, }); });

t3code 里的文章创建、编辑、删除全部走protectedProcedure。这样做的好处是：即使前端忘了隐藏某个按钮，用户直接构造请求打到后端，服务端也会拦截。必须强调一件事——真正安全的鉴权一定发生在服务端，前端隐藏按钮只是体验优化，不是安全边界。这个认知我在代码注释里写了好几遍提醒自己。

4.3 类型扩展：Session 里的 user.id 不是默认就有的

这里的坑值得单独说。默认情况下，NextAuth 的session.user类型里并没有id字段，你直接在session.user.id上访问，TypeScript 会报错。t3code 里我用的是模块扩展来补全类型：

declare module "next-auth" { interface Session { user: { id: string; name?: string | null; email?: string | null; image?: string | null; }; } }

同时，记得在 jwt 和 session 回调里手动把 id 塞进去。我早期用 database session 时，就发现类型不对、运行时也不对，走 JWT 之后反而不容易出问题。原因是 JWT 的 token 生命周期很清晰，id 的注入点也比较固定，排查起来简单得多。

4.4 页面路由层怎么配合中间件

t3code 里不仅要保护 tRPC 的 mutation，后台管理页面也需要登录才能访问。Next.js 的中间件可以在请求层面做一次初筛：

export { auth as middleware } from "@/server/auth"; export const config = { matcher: ["/admin/:path*"], };

如果你创建项目时的 NextAuth 是 v4，写法会不太一样，可能是export { default } from "next-auth/middleware"。这个差别源于版本 API 的调整，我建议以你自己项目里的导出为准。在 t3code 里，我刻意把 matcher 限定到/admin前缀，避免把登录页和静态资源一起拦住，这样开发时的页面闪烁问题也会少很多。

4.5 权限分层：adminProcedure 怎么实现

内容站还有个典型需求：管理员能发布所有文章，普通用户只能看到自己的草稿。t3code 的做法是给 User 表加一个role字段，然后用一层adminProcedure包裹检查：

export const adminProcedure = protectedProcedure.use(({ ctx, next }) => { if (ctx.session.user.role !== "ADMIN") { throw new TRPCError({ code: "FORBIDDEN" }); } return next(); });

这种简单分层足够支撑内容站的权限需求，不需要引入复杂的 RBAC 框架。很多东西在业务到达一定复杂度之前，过度设计反而增加维护成本。

5. 部署与细节：环境变量、Prisma migrate 和 Vercel 上的一次出乎意料

5.1 本地到线上最容易忽略的差异：环境变量

t3code 第一次部署时，我天真地以为在本地能跑，线上就一定能跑。结果登录回调直接错乱，页面刷新就掉登录状态。查了一圈，问题出在环境变量：本地有.env，生产环境需要在平台的环境变量面板里重新配置一遍。

最关键的两个变量是数据库连接串和 NextAuth secret。数据库连接串必须指向生产数据库，NEXTAUTH_SECRET至少 32 位随机字符串，生成方式很简单：

openssl rand -base64 32

生成的 secret 要妥善保存，.env文件绝对不能提交进代码仓库。这一点怎么强调都不为过，一旦 secret 泄露，等于你的登录体系裸奔。建议直接把它写进.gitignore。

5.2 Prisma migrate 在生产环境的正确姿势

这是 t3code 部署过程中最出乎我意料的地方。我本以为在 Vercel 上跑完 build，Prisma 会像本地migrate dev一样自动把表建好，结果打开线上页面，接口直接报 500，查日志才知道数据库里连表都没有。

Vercel 的环境里不会自动执行 migrate，你必须在本地或 CI 里完成迁移后，再部署代码。正确做法是迁移文件跟着仓库走，然后在准备发布时执行：

npx prisma migrate deploy

注意这里用的是migrate deploy，不是migrate dev。migrate dev会做数据重置和交互式确认，适合开发环境；生产环境应该用migrate deploy静默执行已经生成的迁移文件，绝不带交互流程。

5.3 Serverless 函数与 Prisma 连接池：一个经典兼容问题

Vercel 的 Serverless 函数有个特点：冷启动后函数实例会创建数据库连接，但实例可能会频繁销毁重建。如果每次启动都新建一个 PrismaClient，很容易把数据库连接池打爆，日志里会出现too many connections。

create-t3-app 生成的src/server/db.ts已经用globalThis做了一层单例缓存，生产环境不会反复创建实例：

import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient; }; export const db = globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV === "development" ? ["query", "error"] : ["error"], }); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;

这个模式的核心理解就一句话：在长时间运行的服务里复用连接，在 Serverless 环境里用全局单例扛住并发实例。如果你不是用 create-t3-app 模板而是手动搭项目，很容易漏掉这一步，部署后高峰期就会出现数据库连接数疯狂上涨。

5.4 其他几个部署细节串烧

接下来是一些零散但同样能卡住上线的小事，我按踩坑顺序整理一下。

• 图片域名白名单：Next.js 的 Image 组件在本地读取 localhost 是正常的，到了线上，如果你引用了外链图片但没在images.remotePatterns里配置对应域名，图片会直接不显示，而且控制台还不会报明显错误。t3code 用的是用户头像外链，这个坑让我多花了一个小时。
• CORS 反而不用操心：t3code 是前后端同源请求，不涉及跨域，这点是 T3 全栈相比前后端分离项目的一大省心事。
• 错误日志的暴露控制：tRPC 默认会把错误信息抛给客户端，生产环境最好在onError回调里统一处理，避免把数据库报错的 SQL 细节怼到用户屏幕上。

6. 从能跑到好维护：我在 t3code 里总结的开发习惯

6.1 router 按业务域拆分，别把什么都塞进一个文件

t3code 早期，我把文章、用户、标签相关的 procedure 全部堆在一个postRouter里，大概写了二十多个 procedure 之后，文件已经乱到没法看。后来按业务域拆成了postRouter、userRouter、tagRouter，最后在root.ts里统一 merge。这个习惯和框架本身关系不大，但配合 tRPC 那种“一个文件一块业务”的结构非常顺手。

src/server/api/routers/ ├── post.ts ├── user.ts └── tag.ts

拆完之后，每次找代码的时间基本为零。这个回流成本随着项目体积增长会越来越明显。

6.2 React Query 的数据粒度：少而精

在 t3code 里我最大的体会之一，是不要为了省事，一个useQuery把整个页面所有数据都拉下来。列表页只管列表的 query，详情页只调详情接口，评论区单独一个 query，互相不干扰。

刚开始这样做会感觉代码行数变多，但后续加功能时心智负担明显更小。比如文章发布成功后，我只失效post.list的缓存，列表会刷新，详情页不受影响，页面之间的状态耦合非常低。

6.3 让编译器替你做 code review

t3code 做到后期，我养成了一个习惯：改完 Prisma schema 立刻跑prisma migrate dev，改完 tRPC procedure 立刻切到前端页面看有没有红波浪线。类型的作用与其说是“写的时候省时间”，不如说是“重构的时候扛风险”。

有次我把 Post 模型的content字段从 String 改成 JSON，整个前端调用链瞬间红了一片，十几分钟就全部改完。同样的事情放在传统前后端分离项目里，可能得翻半天接口文档再联调排错。

6.4 给同类型项目的一份维护清单

最后把 t3code 开发过程中沉淀下来的维护习惯整理成一个清单，供你参考：

• schema 变更后必须走 migrate，不要直接手改数据库结构；
• 每个 tRPC procedure 都要有 zod input 校验，哪怕是空对象；
• 涉及登录态的接口用 protectedProcedure，不要指望前端隐藏按钮保证安全；
• mutation 成功后及时invalidate对应 query，避免列表数据过期；
• 服务端日志里不要打印完整会话内容或密钥，打用户 id 就够了；
• 环境变量全部放.env，并且严格保证不提交仓库。

个人最后的一点体会是：t3code 这个项目做完后，我对 T3 组合的判断是“高匹配、高收益”。它真正解决的是“单一代码库 + TypeScript 全链路”这个具体场景里的重复劳动。如果你和我一样，平时维护一到三个 Web 应用，业务边界清晰，用它能把搭接口、对类型的碎活去掉一大半。但反过来，如果你面对的是十几个微服务、多语言多团队的环境，还是老老实实评估 REST、消息队列和网关那些更成熟的方案。工具本身没有高下之分，关键是项目上下文和它匹不匹配。接下来我打算把 t3code 的文章编辑器换成 MDX 渲染方案，再补一轮 E2E 测试，到时候再写一篇后续记录。