1. 我为什么最终倒向 T3 技术栈类型安全才是团队的隐形契约先说个让我印象特别深的经历。之前在一个全栈项目里后端接口返回的字段叫userName前端某个页面里手滑写成了username。这种错误在开发环境根本不会报错因为前后端各有一套类型没人约束它们必须一致。等到联调那天页面白屏大家花了一个下午查接口、翻网络面板、对比字段名最后发现是大小写不一致。当时我就在想如果类型能从数据库一路传到浏览器这种低级问题是不是根本就不会发生后来我接触到 T3 技术栈——很多人叫它 t3code核心就是TypeScript 全栈开发的一套组合拳Next.js 做应用框架tRPC 做前后端接口调用Prisma 做数据库 ORMTailwind CSS 做样式校验交给 Zod。整套技术栈的设计哲学只有一个词类型安全。你不需要写 OpenAPI 文档不需要手工维护接口类型定义后端 router 里定义的输入输出类型前端直接infer出来。这不是省几行代码的问题而是把前后端契约从口头约定变成编译器强制执行的规则。我用它重写了一个内部小工具之后最大的感受是T3 栈不是某个单一技术有多强而是所有环节扣在一起之后类型系统变成了团队的隐形契约。后端改了字段前端编译立刻报错数据库 schema 调整Prisma 客户端类型同步更新tRPC 的类型跟着变整个链路没有一个环节能悄悄不兼容。这种连锁反应的价值在项目规模小的时候不明显等业务复杂到一百多个接口、几十张表的时候你会非常庆幸有这一层约束。这篇我就从一个实际项目的完整过程出发把 T3 栈从初始化、tRPC 路由设计、Prisma 建模到调试部署的每个环节掰开讲清楚。同时会把我踩过的坑、绕过的弯路、最终沉淀下来的习惯一起写出来。如果你正准备用 Next.js 做全栈或者在 REST API 和 tRPC 之间犹豫这篇应该能帮你少走不少弯路。2. 初始化一个 T3 项目create-t3-app 的可选项里藏着架构决策2.1 一条命令背后的目录结构逻辑初始化一个 T3 项目非常简单只要你已经装好了 Node.js我建议至少 18.x 版本最好 20执行npm create t3-applatest my-t3-app接着命令行会问你选哪些模块。你可能会想这些选项不就是几个复选框吗随便勾选就行其实不是。你选的每一个模块都会影响整个应用的数据流动方式。比如你勾了 NextAuth它会默认把认证中间件、session 类型、Prisma 适配器的初始化代码全部生成好你不勾 Prisma后面所有需要持久化的功能都得自己另找方案。所以这不是功能选择是架构方向的提前确定。我这边的建议组合是Next.jsApp Router TypeScript tRPC Prisma NextAuth Tailwind CSS。这套组合对应着一条非常清晰的数据链路Browser → Next.js Server Component / Client Component → tRPC Router → Prisma Client → Database。类型在这条链路的每一步都保持确定不会在某一个环节断掉。2.2 脚手架各选项的取舍细节T3 脚手架会问你几个问题我逐个说一下我的理解和选择逻辑选项我推荐的值核心考虑App Router 还是 Pages RouterApp RouterServer Components 是 Next.js 的未来方向tRPC 也有专门的 server 端 helper 配合tRPC 还是 RESTtRPC类型推断是本栈的核心收益选 REST 等于放弃了最大的优势数据库 ORMPrisma和 TypeScript 集成最紧密schema 即类型来源认证方案NextAuth生成全套集成代码session 类型可以直接传入 tRPC context样式方案TailwindT3 默认推荐配合 utility class 做 UI 足够高效这里我要特别提醒一点你不用担心以后能不能换成别的。脚手架生成的代码虽然耦合了这些模块但每个模块的边界是清晰的。tRPC router 不关心你用的是 Prisma 还是别的 ORM只要 context 里提供的db对象有同样的方法即可。真到换的那天工作量集中在 context 和少量数据访问层不会牵一发动全身。2.3 初始化后的目录结构如何理解项目生成后最重要的两个目录是src/app和src/server。src/app是 Next.js 的页面路由目录里面放页面、布局、客户端组件src/server是服务端逻辑的专属地盘包括 tRPC router、Prisma 实例、认证配置。这个客户端和服务端物理隔离的设计是有意为之。实际开发中你会慢慢感受到这种隔离的好处你在src/server里写的代码天然的不会被打包到浏览器端。Prisma 的数据库连接、NextAuth 的 secret、各种服务端专用逻辑都放在这个目录不用担心意外暴露给前端。我们团队有个同事以前习惯把所有逻辑都堆在 pages/api 下迁到 T3 之后他最大的感触是终于不用靠命名规范来提醒自己这段代码不能 import 到前端了。3. tRPC 路由设计的核心实践把 API 从接口文档变成类型推理3.1 先理解 tRPC 不是框架是 RPC 的 TypeScript 实现很多人第一次看到 tRPC 会把它和 GraphQL 做类比其实它们解决的问题是相似的让前端调用后端逻辑时不需要手动维护 URL、HTTP 方法、参数结构。但 tRPC 的思路更直接——既然前后端都用 TypeScript那就让类型系统自己推导出调用签名。这么说可能还抽象我放一个最简单的实例。假设你在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().int().positive().default(1) })) .query(async ({ ctx }) { const posts await ctx.db.post.findMany({ skip: (page - 1) * 10, take: 10, orderBy: { createdAt: desc }, }); return { posts, nextPage: page 1 }; }), });你在前端组件里这样调用const { data } api.post.list.useQuery({ page: 1 });注意看前端这里{ page: 1 }的对象如果你传一个字符串page: 1编辑器会立刻报错data对象的结构也是后端返回的类型你写data.posts.map()的时候posts的字段提示全部自动完成。这种体验远不只是少写类型定义那么肤浅它实际上消灭了一整类 bug接口参数传错、返回字段拼错、空值处理忘掉。3.2 Zod schema 是路由的输入闸门在 T3 栈里Zod 不是独立的表单校验库它是整个数据链路的第一道闸门。tRPC 每个 procedure 的input都是 Zod schema后端收到请求时先校验不合法就拒绝根本不会往下走到数据库层。我强烈建议你把 input schema 的编写当成接口文档来对待input: z.object({ id: z.string().min(1, ID不能为空), title: z.string().min(1).max(200), content: z.string().min(10), tags: z.array(z.string()).max(5).optional(), })这有几个隐藏的好处。第一前端拿到这个 schema 的类型定义所有参数提示、必填校验在设计阶段就完成了第二后端不会出现脏数据入库的尴尬——非法请求在边界处就被 ZOD 拦住了第三如果你使用zod的三方插件比如zod-form-data表单数据也能复用同一套 schema避免前后端各写一遍校验。3.3 Router 嵌套按业务域组织而不是按 REST 资源组织tRPC 的 router 是支持嵌套的这也是我项目里比较依赖的能力。我们可以把几个查询放在同一个postRouter里然后把postRouter挂到根 router 上。但如果只是机械地按资源分 router你会很快发现某些跨资源的逻辑没有归宿。我的习惯是按业务能力域来划分而不是纯表驱动。比如文章发布这个能力它天然包含了 posts 表的插入、tags 表的关联、用户信用分的更新这几个操作属于同一个业务事务。我会把它放在postRouter的publishprocedure 里而不是拆成三个独立的 API 让前端顺序调用。这样设计背后的理由是tRPC procedure 是天然的服务端函数一个函数应该做完整的工作单元而不是一个 HTTP 端点。前端只需要一次调用后端内部通过ctx.db.$transaction保证一致性。这比前端调三次 REST 接口去拼业务要可靠得多。4. Prisma 认证集成数据层是 T3 项目里最容易绊倒人的地方4.1 Prisma schema 设计时要想清楚的三件事Prisma 作为 ORM最大的特点是 schema 文件一改客户端类型自动重新生成。但这不代表 schema 随便写就行我总结了三件必须想清楚的事第一关系字段的命名要能表达业务意图。比如用户和文章是一对多关系你用posts还是articles决定了后面所有查询代码的可读性。我一个项目里用过writtenPosts作为关系名后续写 include 嵌套查询时一眼就能看懂是在查这个用户写过的文章。第二字段可选性的设计要结合页面需求。Prisma 里String?表示可空但它和数据库层面的NULL是绑定的。如果一个字段只是编辑时可选列表页永远有值最好的方式不是可空字段而是用一个默认空字符串default()兜底。否则你在页面渲染时每一处都要做空值判断。第三不要在 schema 里过度使用Json类型。虽然 Prisma 支持 JSON 字段非常灵活但它的代价是失去了类型推导。一旦你把某个业务结构存成 JSON后面想按这个字段做查询过滤就非常疼痛。我建议 JSON 只用于纯展示数据比如富文本的 Delta 格式或者第三方返回的原始数据。只要是参与业务判断的字段老老实实拆成列。这里放一个实践中很顺手的 schema 片段做参考generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) email String unique name String? passwordHash String? createdAt DateTime default(now()) updatedAt DateTime updatedAt posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt }4.2 NextAuth 与 tRPC context 之间的类型打通T3 项目里认证功能的集成脚手架已经帮你搭好了框架但你需要理解 session 和 context 的关系不然很容易掉进前端登录了后端还认为你没登录的坑。在src/server/api/trpc.ts里tRPC 的createTRPCContext会把 NextAuth 的 session 挂到 context 上。也就是说每个 procedure 都可以通过ctx.session拿到当前用户信息。脚手架还默认生成了protectedProcedure它会在执行前检查 session 是否存在不存在就走未授权逻辑。但这里有个很容易忽略的细节session 里的 user 类型默认只有 id、name、email 这几个字段。如果你的业务需要拿到用户的角色、积分、头像等数据不能在组件里直接ctx.session.user.role这个字段根本不在 NextAuth 的默认类型里。我当时就是在这里吃了亏以为自己配置错了后来才发现需要扩展类型声明。正确做法是在自己的types/next-auth.d.ts文件里扩展 Session 和 User 类型import { DefaultSession } from next-auth; declare module next-auth { interface Session { user: { id: string; role: string; points: number; } DefaultSession[user]; } interface User { role: string; points: number; } }这样之后ctx.session.user.role就能正常推导了。这类类型声明增强是 T3 栈开发中非常常见的操作因为整个系统的边界都靠类型撑着第三方库的类型一旦不够用就需要你自己补齐。4.3 我做 Prisma 查询时踩过的 N1 和事务问题刚开始用 Prisma 时最容易犯的错误是信任 Prisma 会自动优化查询延迟加载。其实不是。当你在一个 tRPC procedure 里先查了一个 Post 列表然后在列表的 map 循环里去访问每个 Post 的author信息Prisma 会为每一篇文章单独发一条 SQL这就是经典的 N1 问题。解决方式很简单一次性include或select需要的关联数据。const posts await ctx.db.post.findMany({ where: { published: true }, include: { author: { select: { id: true, name: true, email: true }, }, }, });回到前端后每个 post 对象里直接带上了 author 信息不需要二次请求。这个改动看起来小实际对接口耗时的改善可能是几十倍的差距。我还习惯给查询加上cache标注后面讲生产优化时细说只对真正高频且低实时性要求的数据做缓存免得优化带来了过期的数据。另一个需要注意的地方是事务。Prisma 原生支持$transaction当你需要同时更新多张表时必须放进事务否则中间任何一步出错数据就处于不一致状态。tRPC procedure 虽然是一个函数但后端执行时并不会自动包事务。我代码里凡是涉及业务规则要求原子操作的逻辑都会显式包一层ctx.db.$transaction比如发文章时同时建立标签关联、扣减用户的每日发布额度。5. 从开发到生产T3 项目的调试、优化与部署避坑指南5.1 Server Components 和 tRPC 的边界什么时候该用哪个用 App Router 的时候你有 Server Component 和 Client Component 两种选择再加上 tRPC 也能在服务端调用我在项目里经常会被问Server Component 里能不能直接用 Prisma 查数据那还用什么 tRPC这个问题问得好。答案是你可以直接用 Prisma但大多数场景不要这样用。原因有三点第一如果在 Server Component 里直接prisma.post.findMany()这个查询逻辑散落在组件文件里没法被 Client Component 复用也脱离了 tRPC router 的统一路由管理。第二tRPC procedure 可以作为统一的数据访问 API允许你在其中放鉴权、校验、缓存、日志这些逻辑如果挨个写在组件里将来维护会崩溃。第三当某个页面既需要服务端查询又需要前端交互数据时你希望它的数据获取方式是一致的。我目前的习惯是页面首屏的基础数据用 server 端 helper 调用 tRPC procedure交互性强的数据用 client 端 useQuery。同一套 procedure 可以被两种方式复用类型都是从 router 自动推导的。这保证了架构的一致性也没有牺牲性能。有个小技巧脚手架里有server/api/trpc/server.ts这个文件里面导入了createCaller的辅助函数你可以直接在 Server Component 里这样调用const { data } await api.post.list({ page: 1 });这里得到的 data 类型和前端useQuery是一模一样的。数据到了 Client Component 也不需要二次转换直接作为 props 传下去即可。5.2 生产部署细节环境变量、构建和运行时的身份切换T3 项目部署到生产环境前我有几条几乎每次都会踩到的经验列出来供你参考数据库连接字符串用连接池方式。PostgreSQL 的DATABASE_URL在本地可以用postgresql://user:passlocalhost:5432/db但生产环境建议带?connection_limit5之类的参数防止连接数打满。NextAuth 的 secret 必须设置。开发环境脚手架会自动给一个随机 key但生产环境如果没有设置每次重启 session 都会失效用户会莫名其妙地被登出。我习惯把NEXTAUTH_SECRET写到环境变量里用openssl rand -base64 32生成。构建时prisma generate要能拿到 schema。在 CI/CD 里如果你构建阶段没有数据库权限可以设置DATABASE_URL为 dummy 值只要 schema 存在就能生成客户端。真正关键的迁移操作prisma migrate deploy放到启动前单独执行。.env文件一定不能进版本库。T3 脚手架的默认.gitignore已经帮你排除了.env但如果你自己反应快、手动复制了.env注意别改名复制成.env.backup之类照样会泄露。如果你用 Docker 部署一条比较稳的顺序是先跑prisma migrate deploy再启动next start。常见的问题是有人把迁移操作放在了应用启动命令里导致每个实例启动都会尝试跑一次迁移两个实例同时跑就冲突了。5.3 性能优化React Query 的缓存策略和 tRPC 的响应式更新tRPC 前端调用本质上走的是 React Query很多人以为它就是一个把数据拿到并渲染的封装其实它内置的缓存和失效策略是性能优化的核心。默认情况下useQuery的数据会在 0 秒后认为过期在窗口重新聚焦时会重新拉取。这个机制保证了数据不太旧但对一些高频读写的页面会造成不必要的网络压力。我的做法是按业务特点调整staleTimeconst { data } api.post.list.useQuery( { page: 1 }, { staleTime: 30_000 } // 30秒内不重复请求 );对于带参数经常变化的查询用一个比参数更细粒度的 key 语义确保缓存不会互相污染。React Query 的 key 是 tRPC 自动生成的你一般不需要手动管理。真正让我觉得 T3 栈上瘾的功能是写操作之后的数据失效。你调用api.post.create.useMutation()提交成功后只需执行utils.post.list.invalidate()前端所有跟文章列表相关的查询会自动重新拉取一次并更新 UI。你不用手动去清缓存、不用在多个组件之间同步状态React Query 会精准地处理依赖关系。这个体验用熟之后再回去写裸的fetch 手动 setState 会非常不习惯。5.4 日志与可观测性生产环境下排查问题的三板斧最后聊聊生产环境的排错。T3 应用的请求链路比较长浏览器 → Next.js → tRPC → Prisma一旦出问题你得知道在哪个环节定位。第一板斧是tRPC 中间件的日志。脚手架已经给了logger的示例你可以在createTRPCContext外层加一个中间件打印 procedure 的路径、耗时和状态码。这个日志在验证接口到底有没有被调到时特别有用。export const loggerMiddleware t.middleware(async ({ path, type, next }) { const start Date.now(); const result await next(); const durationMs Date.now() - start; console.log([tRPC] ${type} ${path} took ${durationMs}ms); return result; });第二板斧是Prisma 的 SQL 日志。在创建 Prisma client 时把log: [query]打开你会看到每个查询实际发到数据库的 SQL 语句很多性能问题一眼就能看出来多查了一条不必要的关联表查询条件走错了索引第三板斧是Next.js 的构建输出和运行时日志。本地开发看不出区别上了生产之后SSR 报错、Server Component 渲染失败、API route 超时都会在next start的进程日志里显示。我习惯把 Next.js 进程托管到 PM2 或者 Docker 的 log driver保持日志持久化否则容器一重启日志就没了排查问题非常被动。6. 从一个小项目到规模化我对 T3 code 的实践经验总结做个整体总结的话我想把 T3 栈给我的启发收敛成一句话类型不只是约束更是效率。当一个项目的所有边界都由类型连接起来时很多以前只能靠自觉的事情现在变成了编译器不让你错。我见过不少后端开发者和前端开发者第一次接触 tRPC 后的反应基本都是原来前后端联调可以不需要等待、不需要文档。不过我也要说清楚什么场景不适合 T3。如果你的接口需要被第三方客户端比如移动端 App、外部服务调取你还是需要一个公开的 REST 或 GraphQL APItRPC 类型推导的好处没法传递给 TypeScript 之外的消费者。这种情况下我会把这套 T3 逻辑作为内部管理后台的技术栈对外则单独起一个 API 服务层。混用的方式稍微增加了一点维护成本但业务收益是值得的。在我现在的项目里从底层 schema 设计到前端页面渲染整个链路已经形成了改一处、类型提示跟着改的正反馈循环。数据库加一个字段Prisma client 重新生成tRPC procedure 返回类型自动变宽前端用到一个新字段时代码提示直接出现。这种体验是我以前在 REST 时代完全不敢想象的。如果你打算在下一个全栈项目里尝试一种更高效的协作方式我建议直接拿一个内部工具或者一个非核心业务模块做起跑通一遍初始化、建模、路由、认证、部署全流程你会发现这套技术栈值得给团队推广。
1. 我为什么最终倒向 T3 技术栈类型安全才是团队的隐形契约先说个让我印象特别深的经历。之前在一个全栈项目里后端接口返回的字段叫userName前端某个页面里手滑写成了username。这种错误在开发环境根本不会报错因为前后端各有一套类型没人约束它们必须一致。等到联调那天页面白屏大家花了一个下午查接口、翻网络面板、对比字段名最后发现是大小写不一致。当时我就在想如果类型能从数据库一路传到浏览器这种低级问题是不是根本就不会发生后来我接触到 T3 技术栈——很多人叫它 t3code核心就是TypeScript 全栈开发的一套组合拳Next.js 做应用框架tRPC 做前后端接口调用Prisma 做数据库 ORMTailwind CSS 做样式校验交给 Zod。整套技术栈的设计哲学只有一个词类型安全。你不需要写 OpenAPI 文档不需要手工维护接口类型定义后端 router 里定义的输入输出类型前端直接infer出来。这不是省几行代码的问题而是把前后端契约从口头约定变成编译器强制执行的规则。我用它重写了一个内部小工具之后最大的感受是T3 栈不是某个单一技术有多强而是所有环节扣在一起之后类型系统变成了团队的隐形契约。后端改了字段前端编译立刻报错数据库 schema 调整Prisma 客户端类型同步更新tRPC 的类型跟着变整个链路没有一个环节能悄悄不兼容。这种连锁反应的价值在项目规模小的时候不明显等业务复杂到一百多个接口、几十张表的时候你会非常庆幸有这一层约束。这篇我就从一个实际项目的完整过程出发把 T3 栈从初始化、tRPC 路由设计、Prisma 建模到调试部署的每个环节掰开讲清楚。同时会把我踩过的坑、绕过的弯路、最终沉淀下来的习惯一起写出来。如果你正准备用 Next.js 做全栈或者在 REST API 和 tRPC 之间犹豫这篇应该能帮你少走不少弯路。2. 初始化一个 T3 项目create-t3-app 的可选项里藏着架构决策2.1 一条命令背后的目录结构逻辑初始化一个 T3 项目非常简单只要你已经装好了 Node.js我建议至少 18.x 版本最好 20执行npm create t3-applatest my-t3-app接着命令行会问你选哪些模块。你可能会想这些选项不就是几个复选框吗随便勾选就行其实不是。你选的每一个模块都会影响整个应用的数据流动方式。比如你勾了 NextAuth它会默认把认证中间件、session 类型、Prisma 适配器的初始化代码全部生成好你不勾 Prisma后面所有需要持久化的功能都得自己另找方案。所以这不是功能选择是架构方向的提前确定。我这边的建议组合是Next.jsApp Router TypeScript tRPC Prisma NextAuth Tailwind CSS。这套组合对应着一条非常清晰的数据链路Browser → Next.js Server Component / Client Component → tRPC Router → Prisma Client → Database。类型在这条链路的每一步都保持确定不会在某一个环节断掉。2.2 脚手架各选项的取舍细节T3 脚手架会问你几个问题我逐个说一下我的理解和选择逻辑选项我推荐的值核心考虑App Router 还是 Pages RouterApp RouterServer Components 是 Next.js 的未来方向tRPC 也有专门的 server 端 helper 配合tRPC 还是 RESTtRPC类型推断是本栈的核心收益选 REST 等于放弃了最大的优势数据库 ORMPrisma和 TypeScript 集成最紧密schema 即类型来源认证方案NextAuth生成全套集成代码session 类型可以直接传入 tRPC context样式方案TailwindT3 默认推荐配合 utility class 做 UI 足够高效这里我要特别提醒一点你不用担心以后能不能换成别的。脚手架生成的代码虽然耦合了这些模块但每个模块的边界是清晰的。tRPC router 不关心你用的是 Prisma 还是别的 ORM只要 context 里提供的db对象有同样的方法即可。真到换的那天工作量集中在 context 和少量数据访问层不会牵一发动全身。2.3 初始化后的目录结构如何理解项目生成后最重要的两个目录是src/app和src/server。src/app是 Next.js 的页面路由目录里面放页面、布局、客户端组件src/server是服务端逻辑的专属地盘包括 tRPC router、Prisma 实例、认证配置。这个客户端和服务端物理隔离的设计是有意为之。实际开发中你会慢慢感受到这种隔离的好处你在src/server里写的代码天然的不会被打包到浏览器端。Prisma 的数据库连接、NextAuth 的 secret、各种服务端专用逻辑都放在这个目录不用担心意外暴露给前端。我们团队有个同事以前习惯把所有逻辑都堆在 pages/api 下迁到 T3 之后他最大的感触是终于不用靠命名规范来提醒自己这段代码不能 import 到前端了。3. tRPC 路由设计的核心实践把 API 从接口文档变成类型推理3.1 先理解 tRPC 不是框架是 RPC 的 TypeScript 实现很多人第一次看到 tRPC 会把它和 GraphQL 做类比其实它们解决的问题是相似的让前端调用后端逻辑时不需要手动维护 URL、HTTP 方法、参数结构。但 tRPC 的思路更直接——既然前后端都用 TypeScript那就让类型系统自己推导出调用签名。这么说可能还抽象我放一个最简单的实例。假设你在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().int().positive().default(1) })) .query(async ({ ctx }) { const posts await ctx.db.post.findMany({ skip: (page - 1) * 10, take: 10, orderBy: { createdAt: desc }, }); return { posts, nextPage: page 1 }; }), });你在前端组件里这样调用const { data } api.post.list.useQuery({ page: 1 });注意看前端这里{ page: 1 }的对象如果你传一个字符串page: 1编辑器会立刻报错data对象的结构也是后端返回的类型你写data.posts.map()的时候posts的字段提示全部自动完成。这种体验远不只是少写类型定义那么肤浅它实际上消灭了一整类 bug接口参数传错、返回字段拼错、空值处理忘掉。3.2 Zod schema 是路由的输入闸门在 T3 栈里Zod 不是独立的表单校验库它是整个数据链路的第一道闸门。tRPC 每个 procedure 的input都是 Zod schema后端收到请求时先校验不合法就拒绝根本不会往下走到数据库层。我强烈建议你把 input schema 的编写当成接口文档来对待input: z.object({ id: z.string().min(1, ID不能为空), title: z.string().min(1).max(200), content: z.string().min(10), tags: z.array(z.string()).max(5).optional(), })这有几个隐藏的好处。第一前端拿到这个 schema 的类型定义所有参数提示、必填校验在设计阶段就完成了第二后端不会出现脏数据入库的尴尬——非法请求在边界处就被 ZOD 拦住了第三如果你使用zod的三方插件比如zod-form-data表单数据也能复用同一套 schema避免前后端各写一遍校验。3.3 Router 嵌套按业务域组织而不是按 REST 资源组织tRPC 的 router 是支持嵌套的这也是我项目里比较依赖的能力。我们可以把几个查询放在同一个postRouter里然后把postRouter挂到根 router 上。但如果只是机械地按资源分 router你会很快发现某些跨资源的逻辑没有归宿。我的习惯是按业务能力域来划分而不是纯表驱动。比如文章发布这个能力它天然包含了 posts 表的插入、tags 表的关联、用户信用分的更新这几个操作属于同一个业务事务。我会把它放在postRouter的publishprocedure 里而不是拆成三个独立的 API 让前端顺序调用。这样设计背后的理由是tRPC procedure 是天然的服务端函数一个函数应该做完整的工作单元而不是一个 HTTP 端点。前端只需要一次调用后端内部通过ctx.db.$transaction保证一致性。这比前端调三次 REST 接口去拼业务要可靠得多。4. Prisma 认证集成数据层是 T3 项目里最容易绊倒人的地方4.1 Prisma schema 设计时要想清楚的三件事Prisma 作为 ORM最大的特点是 schema 文件一改客户端类型自动重新生成。但这不代表 schema 随便写就行我总结了三件必须想清楚的事第一关系字段的命名要能表达业务意图。比如用户和文章是一对多关系你用posts还是articles决定了后面所有查询代码的可读性。我一个项目里用过writtenPosts作为关系名后续写 include 嵌套查询时一眼就能看懂是在查这个用户写过的文章。第二字段可选性的设计要结合页面需求。Prisma 里String?表示可空但它和数据库层面的NULL是绑定的。如果一个字段只是编辑时可选列表页永远有值最好的方式不是可空字段而是用一个默认空字符串default()兜底。否则你在页面渲染时每一处都要做空值判断。第三不要在 schema 里过度使用Json类型。虽然 Prisma 支持 JSON 字段非常灵活但它的代价是失去了类型推导。一旦你把某个业务结构存成 JSON后面想按这个字段做查询过滤就非常疼痛。我建议 JSON 只用于纯展示数据比如富文本的 Delta 格式或者第三方返回的原始数据。只要是参与业务判断的字段老老实实拆成列。这里放一个实践中很顺手的 schema 片段做参考generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) email String unique name String? passwordHash String? createdAt DateTime default(now()) updatedAt DateTime updatedAt posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt }4.2 NextAuth 与 tRPC context 之间的类型打通T3 项目里认证功能的集成脚手架已经帮你搭好了框架但你需要理解 session 和 context 的关系不然很容易掉进前端登录了后端还认为你没登录的坑。在src/server/api/trpc.ts里tRPC 的createTRPCContext会把 NextAuth 的 session 挂到 context 上。也就是说每个 procedure 都可以通过ctx.session拿到当前用户信息。脚手架还默认生成了protectedProcedure它会在执行前检查 session 是否存在不存在就走未授权逻辑。但这里有个很容易忽略的细节session 里的 user 类型默认只有 id、name、email 这几个字段。如果你的业务需要拿到用户的角色、积分、头像等数据不能在组件里直接ctx.session.user.role这个字段根本不在 NextAuth 的默认类型里。我当时就是在这里吃了亏以为自己配置错了后来才发现需要扩展类型声明。正确做法是在自己的types/next-auth.d.ts文件里扩展 Session 和 User 类型import { DefaultSession } from next-auth; declare module next-auth { interface Session { user: { id: string; role: string; points: number; } DefaultSession[user]; } interface User { role: string; points: number; } }这样之后ctx.session.user.role就能正常推导了。这类类型声明增强是 T3 栈开发中非常常见的操作因为整个系统的边界都靠类型撑着第三方库的类型一旦不够用就需要你自己补齐。4.3 我做 Prisma 查询时踩过的 N1 和事务问题刚开始用 Prisma 时最容易犯的错误是信任 Prisma 会自动优化查询延迟加载。其实不是。当你在一个 tRPC procedure 里先查了一个 Post 列表然后在列表的 map 循环里去访问每个 Post 的author信息Prisma 会为每一篇文章单独发一条 SQL这就是经典的 N1 问题。解决方式很简单一次性include或select需要的关联数据。const posts await ctx.db.post.findMany({ where: { published: true }, include: { author: { select: { id: true, name: true, email: true }, }, }, });回到前端后每个 post 对象里直接带上了 author 信息不需要二次请求。这个改动看起来小实际对接口耗时的改善可能是几十倍的差距。我还习惯给查询加上cache标注后面讲生产优化时细说只对真正高频且低实时性要求的数据做缓存免得优化带来了过期的数据。另一个需要注意的地方是事务。Prisma 原生支持$transaction当你需要同时更新多张表时必须放进事务否则中间任何一步出错数据就处于不一致状态。tRPC procedure 虽然是一个函数但后端执行时并不会自动包事务。我代码里凡是涉及业务规则要求原子操作的逻辑都会显式包一层ctx.db.$transaction比如发文章时同时建立标签关联、扣减用户的每日发布额度。5. 从开发到生产T3 项目的调试、优化与部署避坑指南5.1 Server Components 和 tRPC 的边界什么时候该用哪个用 App Router 的时候你有 Server Component 和 Client Component 两种选择再加上 tRPC 也能在服务端调用我在项目里经常会被问Server Component 里能不能直接用 Prisma 查数据那还用什么 tRPC这个问题问得好。答案是你可以直接用 Prisma但大多数场景不要这样用。原因有三点第一如果在 Server Component 里直接prisma.post.findMany()这个查询逻辑散落在组件文件里没法被 Client Component 复用也脱离了 tRPC router 的统一路由管理。第二tRPC procedure 可以作为统一的数据访问 API允许你在其中放鉴权、校验、缓存、日志这些逻辑如果挨个写在组件里将来维护会崩溃。第三当某个页面既需要服务端查询又需要前端交互数据时你希望它的数据获取方式是一致的。我目前的习惯是页面首屏的基础数据用 server 端 helper 调用 tRPC procedure交互性强的数据用 client 端 useQuery。同一套 procedure 可以被两种方式复用类型都是从 router 自动推导的。这保证了架构的一致性也没有牺牲性能。有个小技巧脚手架里有server/api/trpc/server.ts这个文件里面导入了createCaller的辅助函数你可以直接在 Server Component 里这样调用const { data } await api.post.list({ page: 1 });这里得到的 data 类型和前端useQuery是一模一样的。数据到了 Client Component 也不需要二次转换直接作为 props 传下去即可。5.2 生产部署细节环境变量、构建和运行时的身份切换T3 项目部署到生产环境前我有几条几乎每次都会踩到的经验列出来供你参考数据库连接字符串用连接池方式。PostgreSQL 的DATABASE_URL在本地可以用postgresql://user:passlocalhost:5432/db但生产环境建议带?connection_limit5之类的参数防止连接数打满。NextAuth 的 secret 必须设置。开发环境脚手架会自动给一个随机 key但生产环境如果没有设置每次重启 session 都会失效用户会莫名其妙地被登出。我习惯把NEXTAUTH_SECRET写到环境变量里用openssl rand -base64 32生成。构建时prisma generate要能拿到 schema。在 CI/CD 里如果你构建阶段没有数据库权限可以设置DATABASE_URL为 dummy 值只要 schema 存在就能生成客户端。真正关键的迁移操作prisma migrate deploy放到启动前单独执行。.env文件一定不能进版本库。T3 脚手架的默认.gitignore已经帮你排除了.env但如果你自己反应快、手动复制了.env注意别改名复制成.env.backup之类照样会泄露。如果你用 Docker 部署一条比较稳的顺序是先跑prisma migrate deploy再启动next start。常见的问题是有人把迁移操作放在了应用启动命令里导致每个实例启动都会尝试跑一次迁移两个实例同时跑就冲突了。5.3 性能优化React Query 的缓存策略和 tRPC 的响应式更新tRPC 前端调用本质上走的是 React Query很多人以为它就是一个把数据拿到并渲染的封装其实它内置的缓存和失效策略是性能优化的核心。默认情况下useQuery的数据会在 0 秒后认为过期在窗口重新聚焦时会重新拉取。这个机制保证了数据不太旧但对一些高频读写的页面会造成不必要的网络压力。我的做法是按业务特点调整staleTimeconst { data } api.post.list.useQuery( { page: 1 }, { staleTime: 30_000 } // 30秒内不重复请求 );对于带参数经常变化的查询用一个比参数更细粒度的 key 语义确保缓存不会互相污染。React Query 的 key 是 tRPC 自动生成的你一般不需要手动管理。真正让我觉得 T3 栈上瘾的功能是写操作之后的数据失效。你调用api.post.create.useMutation()提交成功后只需执行utils.post.list.invalidate()前端所有跟文章列表相关的查询会自动重新拉取一次并更新 UI。你不用手动去清缓存、不用在多个组件之间同步状态React Query 会精准地处理依赖关系。这个体验用熟之后再回去写裸的fetch 手动 setState 会非常不习惯。5.4 日志与可观测性生产环境下排查问题的三板斧最后聊聊生产环境的排错。T3 应用的请求链路比较长浏览器 → Next.js → tRPC → Prisma一旦出问题你得知道在哪个环节定位。第一板斧是tRPC 中间件的日志。脚手架已经给了logger的示例你可以在createTRPCContext外层加一个中间件打印 procedure 的路径、耗时和状态码。这个日志在验证接口到底有没有被调到时特别有用。export const loggerMiddleware t.middleware(async ({ path, type, next }) { const start Date.now(); const result await next(); const durationMs Date.now() - start; console.log([tRPC] ${type} ${path} took ${durationMs}ms); return result; });第二板斧是Prisma 的 SQL 日志。在创建 Prisma client 时把log: [query]打开你会看到每个查询实际发到数据库的 SQL 语句很多性能问题一眼就能看出来多查了一条不必要的关联表查询条件走错了索引第三板斧是Next.js 的构建输出和运行时日志。本地开发看不出区别上了生产之后SSR 报错、Server Component 渲染失败、API route 超时都会在next start的进程日志里显示。我习惯把 Next.js 进程托管到 PM2 或者 Docker 的 log driver保持日志持久化否则容器一重启日志就没了排查问题非常被动。6. 从一个小项目到规模化我对 T3 code 的实践经验总结做个整体总结的话我想把 T3 栈给我的启发收敛成一句话类型不只是约束更是效率。当一个项目的所有边界都由类型连接起来时很多以前只能靠自觉的事情现在变成了编译器不让你错。我见过不少后端开发者和前端开发者第一次接触 tRPC 后的反应基本都是原来前后端联调可以不需要等待、不需要文档。不过我也要说清楚什么场景不适合 T3。如果你的接口需要被第三方客户端比如移动端 App、外部服务调取你还是需要一个公开的 REST 或 GraphQL APItRPC 类型推导的好处没法传递给 TypeScript 之外的消费者。这种情况下我会把这套 T3 逻辑作为内部管理后台的技术栈对外则单独起一个 API 服务层。混用的方式稍微增加了一点维护成本但业务收益是值得的。在我现在的项目里从底层 schema 设计到前端页面渲染整个链路已经形成了改一处、类型提示跟着改的正反馈循环。数据库加一个字段Prisma client 重新生成tRPC procedure 返回类型自动变宽前端用到一个新字段时代码提示直接出现。这种体验是我以前在 REST 时代完全不敢想象的。如果你打算在下一个全栈项目里尝试一种更高效的协作方式我建议直接拿一个内部工具或者一个非核心业务模块做起跑通一遍初始化、建模、路由、认证、部署全流程你会发现这套技术栈值得给团队推广。
