1. t3code是什么：一个全栈类型安全样板项目的起点
t3code 是我在本地维护的一个全栈项目代号，听起来像个随机字符串，其实就是 T3 Stack 的变形：TypeScript + Tailwind CSS + tRPC，再配合 Next.js 和 Prisma 打底。折腾这套东西的原因很简单，团队里新项目越来越多，每次前后端联调都要靠手动维护接口文档，改一个字段名要翻半天代码，实在受够了。
如果你正在纠结“全栈项目到底怎么搭才不容易烂尾”，t3code 可以作为一份参考答案：它从数据库到浏览器，类型链路一路贯通，服务端怎么定义输入输出，前端就怎么调用。接口改动不再靠会议室口头同步，编译器会先把不一致的地方揪出来。对于中小型项目、内部系统、以及一个人要扛全栈的场景，这套组合相当顶用。
1.1 技术栈选型：为什么偏偏是这三件套
很多人听到 T3 会以为是什么新框架，其实不是，它是一套工程组合拳。它的核心不是某个库有多强，而是把 TypeScript 的类型能力用到了通信层。
先看三个基础组件各自的定位：
- TypeScript 提供语言级别的类型。这一步不难理解，但关键在于它不只是给业务代码用，还承担了“服务端函数签名”的载体。
- Tailwind CSS 纯粹是为了把样式开发速度提上来，它不参与逻辑，但减少了写 CSS 文件的心智负担。
- tRPC 是真正的灵魂，它让前端直接调用后端函数，而且全程类型感知。
Prisma 负责数据库模型定义和访问，Zod 负责运行时输入校验。这两者也依赖 TypeScript 类型，但并不强制。实际使用中，我会把 Prisma + Zod 当成 T3 的标配，尤其是 Zod，它和 tRPC 的输入校验结合得非常顺。
为什么选这三件套而不是别的？核心原因就一句话：少一层中间描述，多一分类型安全。REST 接口你需要自己在两端维护类型定义，GraphQL 需要引入 codegen 生成类型，而 tRPC 直接把服务端路由的类型导出来给前端用，中间省掉了“描述接口”的环节。
1.2 和传统 REST / GraphQL 的真实差异
拿具体的开发场景对比最有说服力。传统 REST 模式下，后端返回一个用户列表，前端通常会自己定义一个User接口：
interface User { id: string; name: string; email: string; }问题来了：后端某天把email改成了primaryEmail，前端不会立刻报错，因为两边类型是手动维护的，没有绑定关系。真正发现问题是页面白屏或者某个字段显示为空，那时候就只能猜。
GraphQL 会好一些，服务端 schema 和客户端 query 有约束，但客户端拿到的数据类型仍然是 codegen 生成的。项目一旦复杂，codegen 产物和手写类型经常对不上，还得处理缓存、字段缺失等问题。
tRPC 的路径不一样。它不需要你定义接口描述文件，而是直接复用服务端函数的真实类型。你在服务端定义了：
listUsers: protectedProcedure.query(() => { return db.user.findMany(); });前端拿到的是从AppRouter推导出来的完整类型，data.name、data.email都是编辑器自动补全的。如果服务端改了字段，前端 TypeScript 会立刻标红，编译都过不去。
类型安全并不是防止逻辑错误，它解决的是“接口变化未被感知”这类协作层面的低级问题。而 t3code 想验证的正是这个：当类型从服务端一路贯通到客户端，日常联调成本能不能真正降下来。
2. 初始化与骨架：create-t3-app 背后藏着的设计决策
t3code 的基础架子是用官方脚手架拉起来的，这一步没什么花活，真正值得研究的是脚手架生成的目录结构为什么长这样。
2.1 初始化命令与依赖选型
初始化命令很简单：
pnpm create t3-app@latest交互式界面会让你选择需要的模块，我会勾上 Next.js、Prisma、tRPC、Tailwind CSS、Zod，其他像 NextAuth 这类按需选。包管理器我一直用 pnpm，这不仅是习惯，是因为 pnpm 的依赖管理是符号链接结构，能有效避免“幽灵依赖”和版本冲突，在多人协作项目里会少很多莫名其妙的 build 问题。
脚手架装完，目录结构大概是这样的：
src/ app/ # Next.js App Router 页面 server/ api/ root.ts # tRPC 根路由 routers/ # 各业务模块路由 trpc.ts # tRPC 初始化与上下文类型 db/ schema.prisma注意src/server这个目录的命名不是随手取的。Next.js 的 App Router 下，客户端组件里如果不小心 import 了服务端代码，框架并不会主动拦截所有情况。create-t3-app 默认把所有服务端逻辑放在src/server下，就是希望通过目录习惯来隔离服务端代码，避免 Prisma Client 被塞进浏览器 bundle。
2.2 服务端与客户端的边界是怎么划出来的
tRPC 的 API 入口在src/app/api/trpc/[trpc]/route.ts，这个文件负责把 HTTP 请求交给 tRPC 的 fetch adapter 处理：
import { fetchRequestHandler } from "@trpc/server/adapters/fetch"; import { appRouter } from "@/server/api/root"; import { createTRPCContext } from "@/server/api/trpc"; const handler = (req: Request) => fetchRequestHandler({ endpoint: "/api/trpc", req, router: appRouter, createContext: createTRPCContext, }); export { handler as GET, handler as POST };这段代码是整套架构的咽喉。它不是普通 API 路由，而是一个统一的 RPC 网关。所有 tRPC procedure 都会经过这里，公共的鉴权、数据库连接、日志注入都发生在createTRPCContext里。
这里有个设计点很关键：tRPC 的 API 表面上看是一整个 HTTP endpoint，实际上路由是拼出来的。前端调用链是client.project.list.query()，对应的 HTTP 请求是POST /api/trpc/project.list，服务端再把它解析成具体 procedure。这种设计的好处是路由天然按业务模块组织，而不是按资源路径硬拆。
3. tRPC 路由设计：从 server 到 client 的类型联动
tRPC 用起来容易，但想把它用好，得理解路由拆分和上下文注入这两件事。我在 t3code 里实践下来，以下几点是重中之重。
3.1 router 拆分：按业务模块组织，而不是按 HTTP 资源
REST 设计喜欢按资源划分 URL，比如/api/projects、/api/users。tRPC 虽然也可以这样，但更自然的组织方式是按业务模块拆 router，再挂到根路由上：
import { router } from "../trpc"; import { projectRouter } from "./routers/project"; import { userRouter } from "./routers/user"; export const appRouter = router({ project: projectRouter, user: userRouter, }); export type AppRouter = typeof appRouter;这里的AppRouter类型就是前后端共享的契约。前端createTRPCReact时用的就是这个类型：
import { createTRPCReact } from "@trpc/react-query"; import type { AppRouter } from "@/server/api/root"; export const api = createTRPCReact<AppRouter>();不需要额外生成任何类型文件，typeof appRouter这个类型引用就是一切。这也带来一个约束：root.ts里不能引用任何客户端专用代码，否则类型会污染整个前端的类型推导。
业务模块内部，我习惯把同一资源相关的 query 和 mutation 放一起：
export const projectRouter = router({ list: protectedProcedure.query(...), detail: protectedProcedure.input(z.object({ id: z.string() })).query(...), create: protectedProcedure.input(...).mutation(...), });这种组织方式的好处是看一个文件就能理解这个模块的所有能力，排查问题时不需要来回跳。
3.2 procedure 与 Zod 输入：运行时校验的第一道防线
类型安全保证的是编译期，但运行时收到的数据是不可信的。尤其是服务端接口，任何人都可以手动构造请求，跳过前端校验直接打过来。所以在 t3code 里，所有涉及输入的 procedure 我都会加上 Zod schema：
import { z } from "zod"; create: protectedProcedure .input( z.object({ name: z.string().min(1, "项目名不能为空"), description: z.string().max(500).optional(), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.project.create({ data: { name: input.name, description: input.description, ownerId: ctx.user.id, }, }); });这里的 Zod schema 做了两件事：运行时对参数做完整校验，同时通过类型推导把input的精确类型交给后端。一旦校验失败，tRPC 会自动返回带有结构化错误信息的响应，前端可以直接用error.data里的内容做提示。
可能有人觉得“前端已经校验过了，后端再校验一遍多余”，但我可以很负责任地说：后端校验永远不嫌多。一个没有后端校验的接口，等于把数据可信度完全交给了调用方，这在安全性和稳定性上都是不可接受的。
4. 实战：在 t3code 里实现一个带鉴权的项目清单模块
理论讲再多不如跑一个完整功能。我在 t3code 里做的第一个业务模块是“项目清单”，包含列表、创建、删除三个功能，核心是鉴权：用户只能看到自己创建的项目。这个模块完整走一遍，tRPC + Prisma 的开发流程就清晰了。
4.1 Prisma 模型定义与迁移
先定义两个模型，User和Project，关联关系是一对多：
model User { id String @id @default(cuid()) name String? email String @unique projects Project[] } model Project { id String @id @default(cuid()) name String description String? ownerId String owner User @relation(fields: [ownerId], references: [id]) createdAt DateTime @default(now()) }定义好以后执行：
pnpm prisma migrate dev --name init这里有一个容易忽略的点：查询当前用户的项目时，where条件里过滤的是ownerId，而不是先查出用户再查项目。直接在 Prisma 查询里下条件是最省事的：
list: protectedProcedure.query(async ({ ctx }) => { return ctx.db.project.findMany({ where: { ownerId: ctx.user.id }, orderBy: { createdAt: "desc" }, }); });4.2 受保护 procedure 与上下文注入
“受保护”说的是protectedProcedure。它的实现依赖中间件：
import { initTRPC, TRPCError } from "@trpc/server"; const t = initTRPC.context<{ db: PrismaClient; user?: { id: string } }>().create(); export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { user: ctx.user, }, }); });中间件里做了两件事：检查ctx.user是否存在，不存在直接抛UNAUTHORIZED；存在则把user注入到后续 procedure 的ctx中。这样业务代码里不需要关心“当前用户是谁”这个问题，直接使用ctx.user.id即可。
ctx.user是从哪来的？在createTRPCContext里根据请求的 session 或 token 解析出来的。t3code 里我用了很简化的方案：从 Authorization header 里拿 token，然后查用户信息：
export const createTRPCContext = async (opts: { headers: Headers }) => { const db = prisma; const token = opts.headers.get("authorization")?.replace("Bearer ", ""); let user: { id: string } | undefined; if (token) { // 这里做真实 token 解析，比如 jwt.verify const payload = await verifyToken(token); user = { id: payload.sub }; } return { db, user }; };实际项目里通常会直接接 NextAuth 的 session，逻辑是类似的：鉴权信息在 context 层解析好，后续 procedure 统一消费。
4.3 前端调用与缓存刷新：React Query 的正确打开方式
tRPC 前端不建议直接裸调用，通常配合 React Query 使用。t3code 用的是@trpc/react-query，它把 tRPC 客户端和 React Query 的 hooks 绑在了一起：
function ProjectList() { const { data, isLoading } = api.project.list.useQuery(); if (isLoading) return <div>加载中...</div>; return ( <ul> {data?.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> ); } function CreateProjectButton() { const utils = api.useUtils(); const createMutation = api.project.create.useMutation({ onSuccess: () => { utils.project.list.invalidate(); }, }); return ( <button onClick={() => createMutation.mutate({ name: "新项目", description: "来自客户的临时需求", }) } > 创建项目 </button> ); }有几个点值得注意：
useQuery和useMutation对应 tRPC 的 query 和 mutation，类型自动对齐。utils.project.list.invalidate()是标准的缓存失效手段，比手动setData改缓存更安全。onSuccess里做缓存刷新，用户可以立刻看到创建后的数据变化，不需要手动 reload 页面。
手动改缓存不是不能用，而是容易漏字段。invalidate让 React Query 重新请求一次服务端，拿到的是完整新鲜数据，省心。
4.4 前端错误处理：别把 error.message 一股脑丢给用户
tRPC 的错误对象不像普通 fetch 那样只有一个 message，它带有结构化信息。处理时可以按分类展示不同文案：
try { await createMutation.mutateAsync({ name }); } catch (error) { if (error instanceof TRPCClientError) { if (error.data?.code === "UNAUTHORIZED") { // 跳转登录页 } else if (error.data?.code === "BAD_REQUEST") { // 展示字段级错误 setFormError(error.message); } else { // 通用兜底 } } }这里的关键是：error.message在 Zod 校验失败时可能很长，直接展示给用户会看到一串内部细节。比较好的做法是服务端自定义错误消息，前端按code分类处理，而不是无脑展示原始字符串。
5. t3code 落地过程中的几个坑，踩完记得绕开
写这个项目两个月，踩过的坑却足够写一篇长文。这里挑几个对我影响最大的，不是网上复制来的，每一个都真实卡过我的开发进度。
5.1 类型爆炸：滥用 Prisma 返回类型导致前端类型服务变慢
一开始图省事，查询时直接把带关联关系的完整对象返回：
detail: protectedProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx }) => { return ctx.db.project.findUnique({ where: { id: input.id }, include: { owner: true, tasks: true, comments: true }, }); });服务端倒是爽了，前端data里什么都有。结果项目越写越大，TypeScript 语言服务开始变慢，编辑器提示卡顿，甚至有一次tsc检查耗时从几秒飙升到十几秒。原因就是 tRPC 会把这些深层嵌套类型全部通过类型推导传给客户端，Prisma 生成的类型本来就很复杂，层层嵌套后类型计算开销指数上涨。
解决办法是服务端做 DTO 裁剪，只返回页面真正需要的字段：
detail: protectedProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx }) => { const project = await ctx.db.project.findUnique({ where: { id: input.id }, include: { owner: true }, }); if (!project) return null; return { id: project.id, name: project.name, ownerName: project.owner.name, }; });瘦身后的返回类型简单直接，前端也不会被一堆不需要的字段干扰。
5.2 中间件顺序：在中间件里读不到后注入的 context
tRPC 的中间件和 Express 类似，顺序很重要。我第一次写权限控制时，想在鉴权中间件里顺便读取ctx.db，但发现ctx类型里根本没有db这个字段，报错报了一堆。
原因很简单：initTRPC.context<T>()里的泛型 T 是 context 的基础类型，中间件注入的新字段不会自动合并进 T。你得在初始化时就声明清楚 context 可能包含的字段，然后中间件返回的ctx才是扩展后的类型。如果基础类型里没有user字段，所有 procedure 的ctx.user都是类型错误。
正确的做法是：所有 context 可能存在的字段，都在初始化时就声明好：
const t = initTRPC .context<{ db: PrismaClient; user?: { id: string; name?: string } }>() .create();这样中间件和 procedure 里都能安全访问ctx.db和ctx.user，类型提示也完整。这个坑不致命，但第一次遇到时很迷惑，容易让人怀疑是不是 tRPC 的类型设计有问题。
5.3 server-only 代码被打进浏览器 bundle
Next.js 开发模式下很多错误不会直接暴露，直到你next build才发现客户端 bundle 里混进了服务端代码。我在一个页面组件里直接用import { prisma } from "@/server/db"，当时只是想快速测试一条数据查询，结果构建产物直接多出好几 MB 的 Prisma Client，页面首屏时间明显变长。
排查方式有两种：一是看next build输出的模块清单，二是按是否 import 了@/server/下的模块来人工检查。t3code 现在的准则是：客户端的页面组件、hooks、utils 只允许通过 tRPC 拿数据，任何直接访问prisma、schema的 import 都要标记为 bug。
更保险的做法是在服务端文件顶部加一行：
import "server-only";这个 npm 包会在客户端编译时报错，强制阻断服务端代码进入浏览器环境。属于零成本高回报的一行代码，强烈建议加上。
5.4 tRPC v10 升级到 v11 时的 Context 类型变化
t3code 从 v10 升到 v11 时，遇到过一次全项目范围的类型报错。最典型的是createContext的返回值类型和对不齐，initTRPC.context<T>()中的泛型要求比 v10 更严格。升级后大量提示Type 'Context' does not satisfy the constraint 'object'或者ctx.db类型为unknown。
查了半天文档，核心改动点是 v11 中 context 类型不再从CreateTRPCContext隐式推导，需要显式声明。我的解决方式是在trpc.ts里明确导出一个TRPCContext类型，并让createTRPCContext的返回类型与之严格匹配：
export type TRPCContext = { db: PrismaClient; user?: { id: string }; }; export const createTRPCContext = async (): Promise<TRPCContext> => { return { db: prisma }; };如果你正在把老项目的 tRPC 从 v10 升到 v11，最好先跑一遍tsc看看报错集中在哪个文件，通常都是 context 类型定义不到位造成的，不要一个个文件去硬改，从根上把类型对齐才是正解。
6. t3code 跑顺之后，我对这套架构的最终评价
项目跑到现在，我最直观的感受是：改动服务端返回值不再需要神经紧绷。以前改一个接口要通知前端、更新文档、确认字段，现在只要服务端代码改了，前端 TypeScript 会立刻在编辑器里报错，问题扼杀在开发阶段，而不是等到联调才发现。
这个收益不是某个库单独给的，而是 T3 整套工程化思路叠加出来的。TypeScript 管代码内部类型，tRPC 管跨进程类型，Prisma 管数据层类型，Zod 管运行时边界。每一层都在解决“类型断裂”的隐患，最终形成一个环环相扣的链路。
当然它也有不适合的场景。如果你的产品要对外提供大规模公共 API，让第三方开发者直接对接，tRPC 并不是最佳选择，因为外部用户不应该感知你的内部 RPC 结构。更合理的架构是内部用 tRPC 做 BFF 层，对外单独暴露 OpenAPI 或 REST 接口。这两者并不冲突，Next.js 的 route handler 完全可以同时承载两类入口。
如果你打算在小团队或内部系统中尝试这套组合，我会建议从 create-t3-app 开始，先跑通一个完整的 CRUD，再逐步加入鉴权、批量操作、服务端缓存这些复杂能力。t3code 目前就是这样一个样板，真实业务里的代码有套路可循以后，新功能从提需求到上线的时间会肉眼可见地缩短。
