t3code实战：以TypeScript类型系统终结API文档，实现端到端类型安全的全栈应用

接触 TypeScript 差不多三年，我越来越觉得，前后端之间的那一层 API 文档，是整个开发链路里最脆弱的东西。前端同学按文档调接口，后端同学按文档出接口，两边各写各的，文档一过期，线上就出事。t3code 这个项目，就是我在这种背景下做的一个实验：把一整套业务从数据库到页面全部放进 TypeScript 类型系统里，让"沟通"直接变成"类型检查"。

简单说，t3code 是个基于 T3 Stack 的全栈应用代码库，核心成员是 Next.js + TypeScript + tRPC + Prisma + Tailwind CSS。这条技术路线在圈子里越来越常见，但真正把它跑通、跑稳、跑出工程化细节的人不算多。这篇文章不是官方文档的复述，而是我把一个真实项目从零搭到上线、再维护几个月的全过程拆解，里面会包括每一步为什么这样选型、实际踩过的坑，以及那些文档里不会写的小教训。不管你是想入门的全栈新手，还是已经写过不少 tRPC 想看看别人怎么组织的同学，应该都能从中找到点东西。

1. 被接口文档坑过之后：t3code 想解决的那件小事

1.1 一次联调事故是怎么改变我的写法的

去年有个内部工具项目，后端接口/api/articles/list返回结构里有一个字段叫tags，原本是string[]，后端某次重构把它改成了{ id: string; name: string }[]。文档没更新，前端还是按字符串数组渲染，结果页面上所有文章标签全部显示成[object Object]。这种问题不算致命，但排查起来很糟心——前端没错，后端也没错，错的是"文档"这个沟通介质本身。

t3code 的出发点就是干掉这层介质。如果前后端共享同一套类型定义，字段改了，TypeScript 编译直接报错，根本走不到联调环节。这就是为什么我最终选择 T3 Stack 而不是其他方案：它的核心思路不是"少写代码"，而是"让编译器替你把关"。

1.2 我理解的 T3 Stack 不是"全家桶"

很多人把 T3 Stack 理解成一个脚手架套餐，其实不太准确。它更像一组约定：Next.js 负责渲染和路由，TypeScript 负责把类型串起来，tRPC 负责端到端类型的 API 层，Prisma 负责数据库建模，Tailwind 负责样式。五个工具单独拿出来都不算稀奇，但它们组合起来有一个关键效果——类型从数据库表、到 API 参数、再到组件 props，全程"贯通"。

我给这个项目起名 t3code，一方面是因为核心是那三个 T（TypeScript、Tailwind、tRPC），另一方面是它确实代表了我写代码的方式变化：从"先想接口、再写两边"变成"先写 schema、再让类型自己长出来"。

1.3 项目范围和功能边界

t3code 不是一个玩具 demo，也不是一个大而全的中台系统，我刻意把它控制在一个"真实但不过大"的范围内：用户注册登录、文章/笔记的增删改查、标签归类、基于关键词的简单检索。功能看着朴素，但足够覆盖 tRPC 的 query、mutation、middleware、分页、错误处理这些核心用法，也足够暴露我后面要讲的坑。

如果一上来就奔着复杂业务去，学习成本会被业务复杂度稀释，最后变成"调框架"而不是"理解框架"。先在小项目里把链路吃透，再往大处铺，这是我给所有想尝试这套栈的人的第一条建议。

2. tRPC 链路拆解：一个函数调用如何在前后端之间流动

2.1 tRPC 不是黑魔法，它只是在 POST 一个 JSON

很多初看 tRPC 的人会困惑：前端的useQuery里明明是在"调用函数"，它怎么知道该请求哪个地址？答案其实很简单——tRPC 在运行时只做了一个动作：把 procedure 的路径序列化进请求体，发给唯一的 HTTP 端点。

// server 端定义 const appRouter = router({ article: { list: publicProcedure .input(z.object({ keyword: z.string().optional() })) .query(({ input }) => listArticles(input)), }, }); // 前端调用 const { data } = api.article.list.useQuery({ keyword: "t3" });

这个useQuery展开之后，发送的请求就是一行 POST，路径长这样：/api/trpc/article.list?batch=1。服务端收到之后，按路径找到对应的 procedure，执行函数，把结果序列化传回。所谓"端到端类型安全"，本质上就是用 TypeScript 的类型推断能力，让编译器根据服务端的 router 类型推导出客户端的调用签名。这里没有运行时魔法，也不涉及代码生成，纯粹是类型层面的映射。

我用一个生活化的类比理解它：tRPC 不是什么通信协议，它只是把"电话总机"换成了"直接拨分机号"。每个 procedure 就是一台分机，路由路径就是分机号，前端拨号时输入法（TypeScript）已经提前把每个分机能说什么话、该带什么参数都告诉你了。

2.2 Router 与 Procedure 的划分策略

实践下来，router 的划分不要照着 "一个表一个 router" 的思维来，而要按"业务能力域"来分。t3code 里我分了三个核心 router：

每个 router 内部保持"只做一件事"。比如 article 的list.query只负责"查询"，不负责"统计"，统计标签频率的事情放给 tagRouter。这样做的直接好处是：后续调用useUtils().article.list.invalidate()时，缓存失效的粒度可控，不会因为一个 router 塞了太多不相干的逻辑而误伤整片客户端缓存。

2.3 认证上下文：把用户信息接进类型系统

用户登录之后，每个 procedure 内部怎么知道"当前是谁"？tRPC 的做法是通过createContext在每次请求时组装上下文对象。

// server/trpc.ts export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerAuthSession(); return { session, db }; }; const t = initTRPC.context<typeof createTRPCContext>().create(); export const publicProcedure = t.procedure; export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { ...ctx, user: ctx.session.user } }); });

这一步是整个链路里最有价值的设计之一。一旦protectedProcedure里的ctx.user被类型标注为"必定存在的用户对象"，所有受保护路由内部就不用再各处判断if (!ctx.user) return，因为类型系统已经帮你保证了：能走到这个函数体里，用户必然已登录。我实测下来，这能删掉差不多三分之一的安全检查代码，而且比手写的判断更可靠。

需要提醒的是，createTRPCContext会在每个请求时执行，所以里面不要放重量级初始化操作，比如每次 new 一个 PrismaClient——那会让连接池管理彻底失效，内存和数据库连接数都会出问题。

3. Prisma 与 Zod 的分工：数据模型这一层最容易乱

3.1 Schema 设计时的三个习惯

Prisma 的schema.prisma是 t3code 里所有类型的源头，我把它当成"团队共同语言"来对待，而不是普通的配置文件。三个习惯用了几个月，效果很明显：

第一，模型名用名词单数，字段名一律小驼峰，外键关系字段加_id后缀。比如article模型里写authorId，关系字段author单独声明。这能避免 Prisma 自动生成类型时出现语义混淆。

第二，所有业务表都带createdAt和updatedAt，不要省略。这不仅为了审计，更重要的是很多查询排序和缓存失效策略都要依赖时间字段，后面想补，迁移成本比一开始加上去高得多。

第三，必须显式声明关系。t3code 里文章和标签是多对多关系，我用了隐式多对多表，Prisma 会自动维护_ArticleToTag关联表。但如果业务后续要往关联表上挂字段（比如"标注时间"、"标注人"），隐式表就改不动了。所以只要有一丁点扩展可能，我建议直接建显式中间模型，比如ArticleTagRelation：

model Article { id String @id @default(cuid()) title String content String tags ArticleTagRelation[] createdAt DateTime @default(now()) } model Tag { id String @id @default(cuid()) name String @unique articles ArticleTagRelation[] } model ArticleTagRelation { article Article @relation(fields: [articleId], references: [id]) tag Tag @relation(fields: [tagId], references: [id]) articleId String tagId String createdAt DateTime @default(now()) @@id([articleId, tagId]) }

3.2 Zod 校验和 Prisma 输入的边界

tRPC 的input解析用 Zod，Prisma 的create/update接收的类型又是另一套。很多人一开始会犯同一个错：让 Zod schema 的字段和 Prisma 的 model 字段一一对应，然后直接拿 input 塞给 Prisma。这在简单场景没问题，但业务一复杂就有隐患。

我现在的做法是：Zod schema 描述的是"客户端传上来的内容"，Prisma input 描述的是"要落库的数据结构"，中间夹一层薄薄的转换函数。比如创建文章时，客户端传tags: ["TypeScript", "tRPC"]，转换函数负责把字符串数组映射成connectOrCreate需要的结构，同时收口一些客户端不该传的字段，比如authorId——它应该从ctx.user取，而不是信任请求体。

const createArticleSchema = z.object({ title: z.string().min(1).max(120), content: z.string().min(1), tags: z.array(z.string()).max(5).optional(), }); export const createArticle = protectedProcedure .input(createArticleSchema) .mutation(async ({ ctx, input }) => { const tags = input.tags?.map((name) => ({ where: { name }, create: { name }, })); return ctx.db.article.create({ data: { title: input.title, content: input.content, authorId: ctx.user.id, tags: tags?.length ? { create: tags } : undefined, }, }); });

这样分层之后，Zod 负责"门卫"，Prisma 负责"账房"，职责清楚，后续加权限逻辑、加审计字段都不用在两边反复改。

3.3 查询性能：select 白名单比 include 更可控

Prisma 的include用起来很爽，但我在 t3code 的列表页吃过亏。一次article.list查询，为了省事include了作者和全部标签，结果前端列表只需要标题和摘要，等于每次请求都白取了文章全文和一堆用户字段。数据量小看不出来，等文章积累到几百篇，响应时间翻了一倍还多。

后来我定了两条规矩。列表接口一律用select白名单，只取要渲染的字段；详情页要关联数据时才用include，而且嵌套的select也要显式指定。另外，凡是查列表，我固定用skip/take做分页，同时返回总数，t3code 里就直接让list.query返回{ items, total, hasMore }这种结构。类型安全在这里还能顺手防手滑——前端少取字段，编译不会报错，但响应体里就会缺数据，页面渲染出来不对。用select之后，这种缺失在写代码的时候就能发现。

4. 从空目录到页面出数据：搭建过程中的实测步骤与报错

4.1 环境准备与项目初始化

t3code 的初始化用的是create-t3-app官方脚手架。这一步本身不复杂，但有几个前置条件容易忽略，我列一下实测版本要求：

• Node.js 18+（我用的 20 LTS，pnpm 8+）
• 数据库，本地开发直接用 Docker 起一个 PostgreSQL 15 最省事
• .env里必须配好DATABASE_URL和NEXTAUTH_SECRET，缺一个启动就会报错

初始化的时候，脚手架会问你要不要启用 NextAuth、Prisma、Tailwind、tRPC。我的建议是：第一次跑通时全选上，别怕代码多，因为后面要讲的很多坑恰好发生在这些模块的交互处，先让整体架构跑起来，再逐个精简。如果只选其中几个，后面手动接入反而容易出兼容问题。

4.2 打通第一个数据库查询到页面展示

初始化完成后，我走了一条"最小闭环"路线来验证整套体系：定义 Article 模型 -> 迁移生成表 -> 写一个article.detail.query-> 在页面里调用并渲染。步骤按顺序来：

# 1. 修改 prisma/schema.prisma，定义好模型 # 2. 跑迁移，生成数据表和客户端类型 npx prisma migrate dev --name init_article npx prisma generate

// 3. 定义 tRPC procedure export const articleRouter = router({ detail: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) => { return ctx.db.article.findUnique({ where: { id: input.id }, include: { tags: true }, }); }), });

// 4. 页面里调用，这里用的是 Next.js App Router 的 Server Side 方式 import { api } from "~/trpc/server"; export default async function ArticlePage({ params }: { params: { id: string } }) { const article = await api.article.detail({ id: params.id }); return <ArticleView article={article} />; }

跑通这一条之后，整个项目的"骨架"就建立了。之后每加一个功能，都是在这个闭环上加分支，不会再有"不知道怎么接"的时刻。

4.3 我在这个环节踩过的三个坑

这个环节看着顺畅，实际上我至少踩了三个值得记录的坑。

第一个坑：改了schema.prisma之后忘了跑prisma generate，结果类型报错说db.article不存在。这个错误信息极具迷惑性，因为它指向的是 Prisma Client 的用法，而不是 schema。排查了十分钟才想起来客户端类型没重新生成。后来我养成了习惯：每次迁移完顺手跑prisma generate，没有例外。

第二个坑：tRPC v11 里createServerSideHelpers和 App Router 的配合。如果你像我一样初始化时选了 App Router，服务端调用 tRPC 不要用createServerSideHelpers那套旧的 SSR 思路，直接用新版的apiserver 端实例，或者用server/trpc.ts里暴露的api对象。混用两套方式会导致超时或者类型对不上的诡异问题。

第三个坑：React 18 Strict Mode 下，开发环境里useQuery会请求两次。这不是 bug，是 StrictMode 故意触发的双调用，用来暴露不纯函数。如果你在 mutation 里有副作用逻辑，千万别依赖"只跑一次"，幂等性要提前设计好。

5. 部署上线前必须补的三张安全网：类型系统的边界

5.1 第一张网：输入校验不能只靠前端

端到端类型安全解决的只是"类型对得上"，不等于"数据是合法"。我见过不少人以为有了 tRPC + Zod 就万事大吉，实际上 ZOD 校验是服务端 procedure 执行前唯一一道防线，而它默认只校验类型和简单约束。比如文章标题最长 120 字符、tags 最多 5 个，这些业务规则必须写成 Zod schema，不能寄希望于客户端表单校验。

更隐蔽的是"实体是否属于当前用户"这种归属校验，它和类型无关，是纯业务逻辑。t3code 里我写了一个小约定：所有 mutation 的第一个动作必须是"查出目标实体并检查归属者"，否则直接抛FORBIDDEN。这个动作不要偷懒，因为类型安全不会帮你挡住越权访问。

5.2 第二张网：错误信息别直接透出到页面

tRPC 默认会把 procedure 里抛出的错误原样返回。开发时很方便，生产环境却是隐患——查错的堆栈、数据库表名、内部逻辑，都不该让用户看到。我在 t3code 里自定义了errorFormatter，把错误收敛成{ code, message }两层，内部错误在生产环境统一替换成"服务器开小差了"。

// server/trpc.ts function errorFormatter({ error, shape }) { const isDev = process.env.NODE_ENV !== "production"; return { ...shape, message: isDev ? error.message : shape.code === "INTERNAL_SERVER_ERROR" ? "服务器开小差了" : shape.message, }; }

另一个容易忽略的点：生产环境的日志端要记录完整错误，页面端只给用户看精简信息。两头各留一份，排查问题时不至于抓瞎。

5.3 第三张网：单点查库与缓存失效节奏

tRPC 的客户端缓存是 React Query 管理的，默认缓存生命周期挺长。t3code 早期遇到过一个问题：文章更新之后列表页数据不刷新，用户反复确认"点了保存为什么不生效"。根因是 mutation 成功后没有正确失效相关 query。

解法也很标准，在每个 mutation 的onSuccess里调用对应列表的 invalidate：

const utils = api.useUtils(); const createArticle = api.article.create.useMutation({ onSuccess: async () => { await utils.article.list.invalidate(); await utils.tag.popular.invalidate(); }, });

这里有个细节容易被忽略：一次创建操作可能影响多个 query（文章列表、详情、标签热榜），每个都要显式失效，漏一个，就会被缓存"骗"一次。上线前把 mutation 和它影响的 query 清单列一遍，能省掉很多线上"已修复但用户看不到"的沟通成本。

6. 跑了三个月之后的体会：t3code 还能怎么长

6.1 从单机教程走向多人协作的形态变化

t3code 跑到现在，最明显的变化是"类型就是文档"这件事在我这个几人小团队里形成了正循环。新同学接手某个列表页，不用再去翻接口文档，直接看articleRouter的定义，输入输出一目了然。那种"前后端各有一套字段名，凭默契猜"的沟通消耗，基本消失了。

当然它也有边界。类型安全覆盖不到性能问题、覆盖不到业务规则变化，也不可能替代设计评审。真要说实用性最强的部分，反而是 tRPC 把上下文和校验收口到一处之后，代码审查的工作量肉眼可见地下降了——一个 mutation 几十行，逻辑摊开摆在面前，比分散在 controller、service、validation 三层里好审得多。

6.2 后续准备做的两个方向

我接下来的打算，一是给 t3code 增加基于 tRPC subscription 的实时能力，比如文章评论数实时刷新，用 v11 的订阅机制走 SSE 通道，绕开成本偏高的 WebSocket 基础设施。二是把数据层挪到 Drizzle 上做一轮对比——这不代表 Prisma 不好，而是我想搞清楚在 select 频繁的场景下，SQL 生成器的体感差异有多大。技术选型不能靠信仰，得靠实测数据。

6.3 如果你想在自己的项目里复制这条路

最后分享几条我这几个月攒下的实操心得，都是文档里不会明确写的事：

一，刚开始别追求"所有数据都走 tRPC"。页面里有一些跟后端无关的静态配置，直接从共享常量文件里拿就好，不必强行套 procedure，否则 router 文件会膨胀得很难读。

二，middleware 是 tRPC 最容易上头的功能，但要克制。日志、鉴权、数据权限这种横切逻辑进 middleware 合理，但具体的业务校验尽量留在 procedure 内部，因为业务规则会频繁变，放 middleware 里反而降低可读性。

三，schema 文件里写中文注释。类型能表达结构，但表达不了业务意图。比如"这个字段决定文章是否在首页展示"，一句注释顶得上后面排查时的两小时。

t3code 本身还在迭代，它不是什么了不起的作品，更像是我给自己搭建的一间"类型安全实验室"。如果你也厌倦了在文档和代码之间来回翻译，找个周末拿这个小而完整的项目练一遍手，会比看十篇架构文章收获更大。整个过程中遇到类型报错，记得先怀疑是不是忘了 generate，这大概是我最想提前递给你的一把伞。