做全栈开发这些年，我花在“对齐前后端类型”上的时间，远比写业务逻辑多。接口文档改了前端不知道，数据库字段换了后端忘了同步，等到运行时才发现类型对不上——这套问题几乎每个用 TypeScript 写全栈项目的人都遇到过。t3code 是我给自己整理的一套完整编码工作流，核心思路一句话：让编译器替你做前后端契约管理。它不是什么新框架，而是基于 T3 生态（TypeScript、Next.js、tRPC、Prisma、Tailwind CSS）的一整套从项目初始化、代码组织到日常迭代的实践方案。这篇文章我会把选型理由、落地步骤、代码约定，以及我在实际项目中踩过的坑全部拆开讲，适合正在用 TypeScript 做全栈开发、想彻底告别手工维护 API 层的团队和个人参考。
1. t3code 要解决的核心问题：全栈类型断层的三种典型场景
1.1 场景一：接口文档总是慢半拍
传统前后端分离开发里，后端写接口、维护文档，前端对着文档写请求层代码。问题是接口文档的更新永远滞后于代码：后端改了字段名但文档没改，或者文档改了但前端忘记同步，两边各说各话。我经历过最离谱的一次，一个GET /user/info接口在半年前把返回里的avatarUrl改成了avatar，前端页面一直展示空白头像，直到用户反馈才排查出来。这种问题在常规架构下几乎无法根治，只能靠 code review 和自觉。
1.2 场景二：同一份类型要维护两遍甚至三遍
很多项目会在前端types目录里手写和后端 DTO 对应的接口类型，后端改了字段前端就得同步改一遍。如果是多端项目，Web、小程序、管理后台各有一份 copy，改一次接口要动三四个文件。这不是技术问题，是管理问题，但技术方案可以消解它——如果把类型生成这件事交给编译器自动化，就永远不会出现“前端类型和后端实际返回不一致”的状态。
1.3 场景三：错误到运行时才暴露
手写类型最大的风险不是维护成本，而是它给了你虚假的安全感。你定义了{ name: string, age: number }，结果后端返回了{ name: string, age: string }，TypeScript 编译期完全不会报错，因为两边根本不知道对方的存在。等到页面渲染age.toFixed(2)直接崩。t3code 这类方案的核心价值，就是把这种运行时才暴露的错误提前到保存代码的那一刻。
这里我整理了一张传统方案和 t3code 方案的关键差异表：
| 对比维度 | 传统 REST + 手写类型 | t3code（tRPC 全链路类型推导） |
|---|---|---|
| 类型来源 | 前端手写，依赖文档同步 | 编译器从后端函数返回值自动推导 |
| 改接口字段 | 手动更新多处文件 | 后端类型一改，前端引用处立即报错 |
| 请求参数校验 | 常在后端 handler 内手写 | 输入校验与类型定义合一（zod） |
| 运行时类型错误 | 常见，线上才暴露 | 编译期拦截绝大多数 |
| 契约文档 | 需要额外维护 | 类型定义本身就是文档 |
三种场景归结起来是同一个病根：前端和后端之间缺少一个单一事实来源。t3code 的全部设计，都是围绕把“类型”确立为这份单一事实来源展开的。
2. 技术基座选型：为什么最终落在这五个库上
2.1 Next.js 承担应用外壳：路由与渲染的统一入口
第一个要定的是应用框架。我选择 Next.js 的核心原因是它把 API 路由、页面渲染、服务端能力放在同一个项目里，天然适合全栈 TypeScript。App Router 模式下，页面组件可以直接在 Server Component 里调用后端逻辑，不需要经过 HTTP 层，这会减少一层序列化损耗，也让类型在服务端组件里是天然共享的。
这里有个很多人忽略的点：t3code 的边界不是“一定要用 Next.js”，而是需要一个同时能写前端和服务端的宿主。理论上 Vite + Express 也能做，但 Next.js 的文件约定和生态成熟度让它成为最省心的选择，尤其是部署时一个应用就是一个整体，不用单独管理前后端两个进程。
2.2 tRPC：去掉 API 层之后，开发体验完全不同
tRPC 是整套方案里最“反直觉”的一环。常规思维里，前后端通信必须有一个显式的接口层，REST 或者 GraphQL 都行。但 tRPC 的思路是：前后端既然在同一个 monorepo 里，为什么不能让函数调用直接跨过网络边界？
做法是在服务端定义 procedure（可以理解为一个带校验的函数），前端通过类型安全的 client 直接“调用”它，参数和返回类型都由 TypeScript 自动推导。调用方拿着router.post.list()这样的方法，输入输出类型全部内联可见。REST 的fetch加await response.json()那一套在网络层是必要的，但在类型层是多余的。
2.3 Prisma：把数据库表结构也纳入类型体系
全栈类型链条里最难打通的是数据库这一环。ORM 那么多，我选 Prisma 是因为它的 schema 文件是数据库结构的单一事实来源，改 schema 后执行prisma generate，模型类型会直接注入客户端代码，查询结果天然带类型。
更关键的是 Prisma 的迁移机制。prisma migrate dev会为每次 schema 变更生成一段迁移 SQL，数据库结构演进和代码类型同步进行，这在多人协作时不至于出现“代码里用了新字段、数据库还没加列”的尴尬。
2.4 Tailwind CSS：样式层不参与类型，但要快
有人可能觉得 Tailwind 和“类型安全”话题无关，确实无关。我保留它纯粹是从效率出发：写全栈样板代码已经够多了，样式部分能少写点自定义 CSS 就少写点。Tailwind 的原子类让样式修改不跳出 JSX 上下文，在快速迭代业务页面时，心智负担明显低于传统的 CSS Modules。
2.5 TypeScript strict 模式：类型安全的最底层前提
以上所有工具都依赖 TypeScript，但如果你没开strict: true，整个链条还是会出现漏洞。strict模式下的null检查和索引访问限制，会让 Prisma 查询结果里的可空字段、tRPC 输入里的可选参数都得到正确收窄。我在所有 t3code 项目里都强制保持 strict 开启，这是不可妥协的底线。
3. 从零初始化 t3code 项目：完整实操步骤
3.1 初始化命令与目录结构
直接用社区维护的脚手架是最快的方式，它能避免我第一次手动组装时踩的那些坑：
npm create t3-app@latest交互式命令行会让你选择要包含的模块，我通常勾选 Next.js、tRPC、Prisma、Tailwind，鉴权选 NextAuth，包管理器用 pnpm。生成的目录结构大致如下：
├── prisma/ │ ├── schema.prisma │ └── migrations/ ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── server.ts │ │ └── client.ts │ └── app/ │ ├── page.tsx │ └── api/trpc/[trpc]/route.ts └── package.json这套结构最值得注意的一点：server/和trpc/严格分层。所有数据库访问和业务逻辑都放在server/api/routers下，客户端禁止直接 import 这些文件，只能通过trpc/react暴露出的 hooks。
3.2 定义首个数据模型并生成类型
假设我们要做一个简单的博客，先在prisma/schema.prisma里定义 Post 模型：
model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }然后执行npx prisma migrate dev --name init，Prisma 会创建数据库表并生成类型。这一步生成的Prisma.Post类型就是后续所有查询结果的类型来源。
3.3 打通第一条端到端类型安全的查询链路
在src/server/api/routers/post.ts里定义第一个 procedure：
import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "../trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string().min(1), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: input }); }), });注意create这条 procedure：zod 的 schema 既是运行时校验器，也是类型定义来源。前端传参如果有误，tRPC 会在请求进入 handler 前直接拦截，返回结构化错误。
前端调用时的体验是这样的：
import { api } from "~/trpc/react"; export function PostList() { const [posts] = api.post.list.useSuspenseQuery(); const createPost = api.post.create.useMutation({ onSuccess: () => { // 刷新列表 }, }); return ( <ul> {posts.map((post) => ( <li key={post.id}>{post.title}</li> ))} </ul> ); }我在编辑器里把鼠标悬停在posts上时，看到的类型就是 Prisma 从 schema 推导出的完整Post结构。这条链路上，数据库、服务端、客户端三个环节的字段名完全一致，不存在任何手写副本。
3.4 验证类型闭环：故意改错字段名
这一步我建议每个初学者都做一次，比看十遍文档都直观。把post.ts里返回的orderBy: { createdAt: "desc" }改成orderBy: { createAt: "desc" }，保存的瞬间编辑器就会报错：Post 模型上不存在createAt属性。再把前端posts.map((post) => post.tilte)打错一个字母，同样立即报错。
这个验证过程告诉你一件事：类型错误前置到了编译期，而不是等接口返回才暴露。t3code 的所有价值都可以浓缩在这次验证里。
4. 让代码库长期保持 t3code 风格的六个约定
脚手架能生成结构，但保持结构清爽需要约定。以下六条是我在真实项目里逐步沉淀下来的规则，按重要程度排列。
4.1 Router 按业务域拆分，而不是按操作类型
很多人下意识按“查询、提交、删除”来组织 router，我强烈不建议。正确做法是按业务域：userRouter、postRouter、commentRouter，各自内部才有 query 和 mutation。这样当一个业务域的逻辑变复杂时，相关代码都在一个文件里，上下文切换成本最低。root.ts里用createTRPCRouter合并所有子 router，前端调用路径就是api.post.list、api.user.profile这种语义清晰的层级。
4.2 所有输入必须经过 zod 校验
这条看似简单，实战中最容易被违反。临时加一个内部接口，想着“反正是我自己调”，就不写 input 校验直接接参数。结果前端传错类型、传 null，错误在 handler 深处才暴露，排查成本翻倍。我的习惯是：每个带 input 的 procedure，第一行永远是 zod schema，不允许存在裸参数。
4.3 服务端代码与客户端代码物理隔离
server/api/routers下的文件不得被客户端 import，trpc/react的 hooks 只能在components或app目录使用。如果你发现某个逻辑需要在两端复用，把它抽到src/shared目录，只放纯类型和纯函数，不碰数据库、不碰请求上下文。这个约定靠 code review 维持，也可以加 ESLint 规则限制 import 路径。
4.4 控制类型导出范围，别写“类型垃圾场”
tRPC 会自动推导类型，但这不代表你可以到处export type。我见过一个项目里有人把每个 procedure 的输入输出都单独export出去，前端到处 import，最后耦合成一团。正确做法是只在跨 router 共享时有选择地导出，比如从root.ts导出type AppRouter用于客户端类型注册，其余类型能藏在文件内部就藏住。
4.5 Schema 变更必须走迁移流程
任何时候改schema.prisma，不要手动去数据库里改表，不要跳过 migrate 直接prisma db push（除非是本地快速原型）。团队协作时，每次 schema 变更都应该伴随一次 migration 提交，这样回滚有据可查。我经历过一次生产事故：有人直接db push改了线上库结构，另一个同事不知情，prisma generate出的旧类型跑在新表上，查询直接报字段不存在。走迁移流程能彻底避免这类问题。
4.6 环境变量集中管理且运行时校验
数据库连接串、鉴权密钥这些，统一放在.env，并通过 zod 在应用启动时做一次校验。tRPC 的上下文模块经常用到 session、db 实例，如果某个环境变量缺失，越早暴露越好，而不是等到用户请求时才炸。
5. 实战中踩过的坑：完整排查过程与修复思路
5.1 依赖升级后“类型没同步”的假象
有次我把项目里@trpc/*从 10.x 升到 11.x，前端调用api.post.list.useQuery()突然全部飘红。第一反应是 tRPC 破坏性变更，查文档发现 11 里 hooks 从@trpc/react迁到了@trpc/react-query。但我修完导入后依然报错，最后定位到是trpc/react.tsx里的类型注册文件没有同步更新。这个文件的职责是把AppRouter类型注入 React hooks，版本升级后会改变内部类型结构，必须重新跑一遍createTRPCReact<AppRouter>()生成新代码。
排查思路总结：类型报错先分清是“代码逻辑错了”还是“类型管线断了”。后者优先检查三个文件——trpc/server.ts、trpc/react.tsx、server/api/root.ts，九成问题出在它们没跟上版本。
5.2 SSR 场景下 tRPC 上下文拿不到 Session
在 Next.js App Router 里做服务端渲染时，createContext里如果用了getServerSession获取用户信息，偶尔会返回 null。症状是：刷新页面时登录态丢失，客户端路由跳转后又正常。排查发现根因是 context 的创建时机在 session 初始化之前，tRPC 服务端调用在 SSR 阶段没有正确拿到 NextAuth 的 session。
解决方式是在trpc/server.ts里显式传参，而不是让 context 自己调getServerSession：
import { getServerSession } from "next-auth"; import { authOptions } from "~/server/auth"; export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerSession(authOptions); return { db, session, ...opts, }; };同时确保所有受保护的 procedure 用的是protectedProcedure，它在 handler 执行前检查ctx.session?.user，不存在就直接抛 UNAUTHORIZED 错误。
5.3 Prisma 查询的 N+1 问题在 tRPC 里更隐蔽
tRPC 的返回值完全由 Prisma 查询结果推导，这导致很多人忽略关联查询的加载策略。有次我写帖子列表接口，前端需要展示作者昵称，于是在post.findMany里没带include: { author: true }，而是前端拿到列表后循环调用api.user.getById。功能没问题，但列表 50 条就触发 50 次 HTTP 请求，页面性能直线下降。
tRPC 的类型安全会误导人：请求能通、类型正确，不代表实现是对的。关联数据必须在一次 Prisma 查询里用include或select取全，不要在前端循�环调用。
5.4 “构建期类型正确，运行时却报 undefined”的灵异事件
有一次next build顺利通过，但部署后接口偶尔返回Cannot read properties of undefined。排查后发现是 Prisma 的select语句里选了关联字段，但实际数据库数据不完整，某条记录的关联是 null，而 zod 输出校验默认不要求这个字段存在。
这给我一个教训：Prisma 查询结果的类型由 schema 推导，但运行时数据可能比 schema 更“陈旧”。对可空关联字段，前端渲染前要处理 null 分支，或者用 zod 在 procedure 出口做一次结构化校验。tRPC 的 output validator 就是干这个的，别嫌麻烦。
6. t3code 的收益边界与适用场景
6.1 效率提升的量化感受
跑通这套流程后，我最大的体感是“重构成本急剧下降”。以前改一个接口字段，要同时改后端 DTO、前端类型、文档三处，现在只需要改 Prisma schema 和对应的 procedure，前端所有引用点会像多米诺骨牌一样在编辑器里标红，逐个修完就收工。保守估计，我在这类项目里的联调时间减少了一半以上，尤其是字段调整频繁的业务，省下的时间非常可观。
6.2 什么时候不建议这套方案
t3code 不是银弹。如果你的项目有独立的移动端和 Web 端，且两端共用同一个后端 API，tRPC 的优势会被削弱，因为移动端没法直接用 tRPC client 连 Node 服务（除非运行在 React Native 且愿意维护适配层），这种场景 REST/GraphQL 公开 API 反而更合适。另外，如果团队里前端开发者对 TypeScript 掌握不熟，强制类型链路的收益会打折扣，因为错误可能出在类型体操本身而不是业务逻辑上。
6.3 可以继续扩展的方向
我在后续项目里给 t3code 补了三块东西：一是用tsx写了一段脚本，在 CI 里执行prisma migrate diff检查 schema 与迁移文件是否一致，防止有人跳过迁移；二是把上传文件、定时任务这类非典型请求从 tRPC 里拆出去，用 Next.js Route Handler 单独处理，避免让 procedure 承担非 JSON 负载；三是给所有 mutation 加了统一的错误码约定，前端根据 code 做全局 toast 提示，不用每个调用处写一遍错误处理。方案完善到这一步，它已经从一个脚手架变成了团队内部的工程规范。
最后分享一点实际体会：t3code 这类方案最打动我的，不是某个工具多好用，而是它改变了写代码的节奏——从前“写完接口自己测一遍”变成了“类型对了基本就对了，跑起来只是确认”。如果你也受够了前后端联调里那些重复而低效的对齐工作，不妨按上面的步骤搭一个最小项目跑通链路。先从小模块开始，让编译器多替你兜底，一两个迭代之后，你会感受到这种工作流给团队协作带来的真实变化。
