t3code：基于Prisma Schema的TypeScript全栈代码生成器实战指南

t3code这个项目，最初其实只是我在折腾 T3 Stack 时顺手攒下的一堆模板代码。那时候每次开新项目都要重复一遍初始化、配 Prisma、写 tRPC router、再手搓前端表单，干到第三次实在觉得没意思了，就决定把这些流程固化成一个命令行工具。后来身边同事也经常卡在同样几个地方，于是干脆把它整理成了一个开源 CLI，也就是你现在看到的 t3code。

简单说，t3code 是一个面向 TypeScript 全栈开发者的脚手架和代码生成工具，核心解决的是“从数据库模型到接口再到前端页面”这条链路里大量重复样板代码的生成问题。你只需要写一份 Prisma schema，它就能帮你把对应的 tRPC 路由、Zod 校验、React 页面组件全部生成出来，而且保证类型安全贯穿始终。如果你是 Next.js + tRPC + Prisma 这套技术栈的玩家，或者团队里正在统一全栈项目结构，这篇文章应该能帮你省下不少时间。我会从设计思路、核心功能、完整实操和踩坑记录几个方面，把 t3code 从头到尾拆一遍。

1. 项目诞生背景：为什么 T3 Stack 需要一个生成器

1.1 T3 Stack 是什么，它解决了什么问题

T3 Stack 是社区里一套很流行的全栈 TypeScript 方案，核心由四个部分组成：Next.js 负责前端页面和 API 路由，tRPC 负责端到端类型安全的接口调用，Tailwind CSS 负责样式，Prisma 负责数据库访问。加上 TypeScript 本身，整个链路里类型可以从数据库一直贯穿到浏览器端。

这套组合最大的吸引力在于“类型安全感”。比如你在 Prisma 里定义了一个 User 模型，那么通过 tRPC 调用 getUser 的时候，前端拿到的返回类型是自动推导出来的，不需要手写 interface，也不需要维护一份单独的类型定义。只要后端改字段，前端编译期就能看到报错。这种感觉一旦习惯了，再回去写那些前端一套类型、后端一套类型、接口文档还得同步维护的项目，整个人都是崩溃的。

1.2 我在实际使用中反复踩到的三个痛点

T3 Stack 虽然香，但真正高频用起来之后，我发现样板代码的量比想象中大得多。

第一个痛点是初始化成本。虽然社区有 create-t3-app 这种官方脚手架，但每次初始完还是要手动配环境变量、改 Prisma 模型、建 tRPC router、写 Zod 校验。一个新项目从 init 到出现一个能跑的 CRUD 接口，顺利的话也要 20 到 30 分钟，大部分时间都花在复制粘贴上。

第二个痛点是 CRUD 代码的重复性。写一张业务表，就要写一遍 list 方法、getById 方法、create 方法、update 方法、delete 方法。五个方法长得几乎一样，区别只是字段不同。用 tRPC 写起来还算简洁，但依然要维护 router、schema 校验、权限判断这三层结构。做的表一多，工作量就是线性上升。

第三个痛点是类型定义分散。Prisma 生成的类型只在服务端可用，前端表单的输入类型、查询参数类型都要手动写一遍。就算用 zod 定义校验规则，前端输入类型和后端校验规则也容易慢慢失同步。时间一长，就会出现“接口能调通但 TypeScript 类型对不上”这种奇怪状态。

把这三个痛点叠在一起，我意识到真正缺的是一个能把 Prisma schema 当作唯一事实来源的生成器——你只改模型定义，其他代码尽量自动生成。这就是 t3code 最初的产品定位。

2. 整体设计与功能拆解：t3code 的核心能力

2.1 三个核心模块：脚手架、生成器、配置中心

t3code 本身不是一个单一脚本，而是拆成了三个模块：init、generate、config。

init 模块负责项目初始化。它做的事情类似 create-t3-app，但更偏工程化：会帮你搭好 monorepo 目录、配好 ESLint 和 Prettier、生成 Prisma schema 的模板、初始化 tRPC router 的目录结构。和官方脚手架最大的区别在于，init 生成的项目结构里预设了 t3code 的目录规范，方便后续交给 generate 继续使用。

generate 模块是整个工具的核心。它读取 Prisma schema，解析出每个模型和字段，然后按模板生成 tRPC router、Zod 输入校验、前端页面组件。默认支持 list、getById、create、update、delete 五个标准接口，也支持按需开关。比如某个表只需要只读接口，那就在模型上加一个 @@t3code.withoutDelete 这样的属性，生成器就会自动跳过相关代码。

config 模块负责项目级配置。在项目根目录下生成一个 t3code.config.ts，里面可以配置输出目录、是否生成前端页面、默认分页大小、是否开启软删除等。配置项统一在 init 阶段生成，之后不需要再去改散落的常量。

2.2 为什么代码生成比复制粘贴更靠谱

有人可能会问，用模板代码生成器，跟我直接从旧项目里复制一段过来改改有多大区别？区别其实很大，主要体现在三个方面。

第一是稳定性。复制粘贴的问题在于代码会漂移，每个项目里的版本会因为当时改过多少次而变得不一样，出问题时很难排查。生成器的模板是同一套，每次生成出来的代码结构完全一致，团队接手时心智负担小很多。

第二是可持续更新。模板脚本是活的，你改了模板，重新跑一遍生成器，所有项目都能跟着更新。但复制粘贴的代码散落在各个仓库里，想统一改一个逻辑基本做不到。

第三是模型和代码的同源。代码生成器直接基于 Prisma schema 而不是基于你手写的代码，所以加字段、删字段、改类型这些操作，只要 schema 一变，生成的代码自动跟着变，不会出现数据库和接口不一致的问题。

2.3 工具链选型背后的理由

t3code 本身用 Node.js + TypeScript 编写，命令行交互用的是 Commander.js，模板渲染用 Handlebars，Prisma 解析用的是官方 DMMF（Document Metadata Model Format）。这几个选型都不是随便定的，说下理由。

Commander.js 是 Node CLI 生态里最成熟的选择，参数解析、子命令、帮助信息都是现成的，没必要为了 CLI 去引入更大的框架。Handlebars 做代码模板很合适，因为它自带逻辑控制能力又不会太复杂，模板看起来接近普通代码，维护成本低。Prisma DMMF 是 Prisma 官方提供的模型格式，可以直接拿到所有模型的字段、类型、关系信息，比正则表达式去解析 schema 文件靠谱一万倍。

注意：生成器的核心不是“生成代码”这个动作，而是“如何保证生成的代码符合项目规范”这件事。模板、命名规则、目录结构这三样一旦定好，整个工程的一致性才有保障。

3. 实操演示：用 t3code 从零跑通一个全栈 CRUD 模块

3.1 环境准备与项目初始化

首先确认本机环境：Node.js 16 以上，包管理器用的 npm 或 pnpm 都行。然后全局安装 t3code：

npm install -g t3code

安装完成后，创建一个新项目：

t3code init litemall cd litemall npm install

init 命令会问你几个问题，包括包管理器选择、是否初始化 git 仓库、是否启用前端页面生成。我建议这里全部选 yes，因为后面演示的前端部分依赖这些配置。初始化完成后目录结构大致如下：

litemall/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ ├── server/ │ │ ├── api/ │ │ ├── db.ts │ │ └── auth.ts │ └── styles/ ├── t3code.config.ts └── package.json

跑完 npm install，先验证一下项目能正常启动，再进入下一步。

3.2 声明数据模型，生成服务端接口

假设我们要做一个简单的商品模块。在 prisma/schema.prisma 里加上模型定义：

model Product { id String @id @default(cuid()) name String @db.VarChar(128) description String? @db.VarChar(512) price Decimal @db.Decimal(10, 2) stock Int @default(0) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

保存后执行生成命令：

t3code generate

生成器会读取 Product 模型，然后在 src/server/api/routers/ 下生成 product.ts。内容大致包含五个 tRPC 方法：list、getById、create、update、remove。list 方法默认支持分页和按创建时间倒序，create 和 update 会自动生成对应的 Zod schema 做输入校验。

// src/server/api/routers/product.ts（生成片段） import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "../trpc"; import { prisma } from "../db"; const productInput = z.object({ name: z.string().min(1).max(128), description: z.string().max(512).optional(), price: z.number().min(0), stock: z.number().int().min(0).default(0), }); export const productRouter = createTRPCRouter({ list: publicProcedure .input(z.object({ page: z.number().int().default(1), pageSize: z.number().int().default(20) })) .query(async ({ input }) => { const where = {}; const total = await prisma.product.count({ where }); const items = await prisma.product.findMany({ where, skip: (input.page - 1) * input.pageSize, take: input.pageSize, orderBy: { createdAt: "desc" }, }); return { items, total }; }), // getById / create / update / remove 此处从略 });

3.3 生成前端页面与路由

服务端接口生成好之后，前端页面可以用下面的命令补上：

t3code gen page Product

这条命令会生成两个文件：一个是商品列表页，包含表格、分页、删除按钮；一个是商品编辑页，包含表单、校验提示、提交逻辑。生成的页面会直接调用 tRPC 的 productRouter 上的方法，类型是自动推导的，不需要手动引入类型定义。

这里有一个值得注意的设计细节：t3code 生成的前端页面默认不依赖任何 UI 组件库，而是用原生 HTML 标签加 Tailwind 类名。这样做的好处是避免了团队换 UI 库时生成代码直接作废。如果你用的组件库是 shadcn/ui，可以在 t3code.config.ts 里开启 antd、mui 之类的模板预设，生成器会输出对应的组件版本。

3.4 接入鉴权与角色权限

默认生成的 router 用的是 publicProcedure，也就是任何人都能调用。实际业务里显然不能这么裸奔。t3code 支持在模型上标记权限属性，然后重新生成。

在 Product 模型上加上：

model Product { // ...原有字段 @@t3code.requireAuth(create: "ADMIN", update: "ADMIN", remove: "ADMIN") }

保存后重新运行 generate，生成的 product.ts 里 create、update、remove 都会从 publicProcedure 变成 protectedProcedure，并且会在方法内部校验当前用户的角色是否为 ADMIN。校验逻辑统一封装在 src/server/auth.ts 中，不需要每个 router 里自己写。

提示：权限属性写在模型上，而不是写在生成器配置里，是因为权限是业务模型的一部分，应该跟着模型定义走。如果哪天商品模块不再需要管理员才能编辑，直接在模型上改掉再重新生成就行，不用去代码里翻权限判断。

4. 实际踩坑记录：6 个高频问题整理

4.1 生成之后 TS 编译直接报错

最常见的问题是模型里用了 Prisma 特有的字段类型，比如 Decimal，但手写的调用代码里把它当成 number。t3code 在生成 Zod schema 时会把 Prisma.Decimal 映射成 z.number()，运行时没问题，但 TypeScript 会因为 Decimal 类型和 number 类型不一致而报错。

解决办法是生成的代码里不要直接用 Prisma 返回的对象，而是包一层序列化方法。我自己的习惯是在 src/server/serializers.ts 里加一个 productSerializer 函数，把 Decimal 转成字符串，把日期转成 ISO 格式。这样既避开 TS 报错，也方便前端处理长精度数字。

4.2 重复生成导致代码文件内累积垃圾代码

早期版本我只做整文件覆盖，后来发现一个问题：如果一个文件在生成后被手工加过代码，下一次 generate 会把手工代码整个冲掉。后来我改成了分段生成策略，把文件分成“生成区”和“自留区”。生成区由 t3code 管理，自留区完全不动。

如果你在用其他代码生成器，也建议确认一下它的文件处理策略。如果是全量覆盖，那就要么别手改生成文件，要么把自定义逻辑放到单独文件里再 import 进来。

4.3 Zod schema 和前端类型不一致

有时候改了 Prisma 模型重新生成后，前端页面的表单还是旧字段。这个多半是 tRPC 的类型缓存没刷新。Next.js 开发模式有时不会主动重新编译 tRPC 的类型定义，刷新页面依然显示旧的字段。

绕过的办法是重启 dev server，大部分时候能解决。如果重启还不行，检查一下 tsconfig 是不是开了 incremental 增量编译，把 .tsbuildinfo 缓存清掉再试。

4.4 Prisma 模型变动后生成代码没跟着变

如果你在 schema 里改了字段名，但没有重新跑 t3code generate，那么数据库迁移和代码生成是脱节的。我自己定的流程是先改 schema，然后跑 prisma migrate dev，再跑 t3code generate。顺序不能反，因为生成器需要读取 Prisma Client 的类型定义，而 migrate 之后这些定义才会更新。

4.5 自定义扩展代码被下一次生成覆盖

这是一个设计取舍问题。t3code 默认把生成的 router 文件当成受管文件，任何手工修改都会在下次生成时被覆盖。如果要加自定义查询方法，正确做法是把自定义逻辑放到 src/server/api/routers/product.custom.ts，然后在主 router 里通过 merge 方式合并进去：

import { productCustomRouter } from "./product.custom"; export const productRouter = createTRPCRouter({ ...productBaseRouter, custom: productCustomRouter, });

这样既保留了生成代码的纯净性，又不妨碍扩展。如果你需要完全自由的 router 控制权，可以在配置里把 project 模式从 generated 改成 hybrid，生成器会只输出基础函数而不再直接注册路由。

4.6 Node 版本和包管理器兼容问题

t3code 依赖一些比较新的 Node API，早期我在 Node 14 上跑会直接报错。后来把最低版本提到了 Node 16，并且建议用 Node 18 LTS 或 20 LTS。团队里如果用的是 nvm，记得在 .nvmrc 里固定版本，不然每个成员的本地环境会不一致。

5. 进阶玩法：把 t3code 接入团队工作流

5.1 用配置文件统一团队规范

t3code.config.ts 是 t3code 的中央配置入口，适合沉淀团队规范。比如统一输出目录、统一前端组件库模型、统一时间格式化方式，都可以在这里配好。你还可以把配置文件放到 git 里维护，保证所有成员生成出来的代码结构一致，避免出现“我页面放 components/ 你页面放 views/”这种细节分裂。

5.2 自定义模板与插件化扩展

如果内置的模板样式不符合团队风格，t3code 支持自定义模板目录。在配置里指定 templateDir 后，生成器会优先读你目录下的模板文件，而不是内置模板。模板语法采用 Handlebars，只要懂一点点模板语法，就能把团队已经沉淀好的代码风格固化进去。

我自己实际的做法是把公司内部的日志规范、错误处理函数直接写进模板，这样生成出来的代码天然带上了团队标准，新成员写代码时也不需要去记这些约束。

5.3 在 CI 里做代码一致性检查

t3code 可以提供一条 diff 命令，对比当前代码与重新生成后的代码是否一致。这个命令可以放进 CI 流程里，比如每次 PR 触发时跑一下，如果发现有人手工改动过生成文件，就标记构建失败。这一步听起来严格，但实际能避免大量无意义的代码 review 争论。既然这些文件本来就是机器生成的，就没有理由手改。

5.4 面向非后端同学的协作模式

还有一个意外的用法。我发现 t3code 特别适合让前端同学独立完成小型项目的后端部分。因为后端接口代码完全由 schema 生成，前端同学只需要会写 Prisma 模型，不需要深入 tRPC 和 Zod 的细节。团队里如果有“前端为主、附带全栈”的角色，t3code 可以有效降低他们的后端上手门槛。

6. 我对 t3code 后续演进的几个想法

我自己现在最常用的方式，是先和业务同学对齐模型字段，然后直接改 schema 跑 generate，数据库表和接口几乎是同时出来的。整个过程里我只需要关注业务规则和权限设计，样板代码不需要关心。对于小团队和独立开发者来说，这种“声明优先、生成兜底”的开发风格非常省事。

如果你想尝试类似思路，建议先从一个小模块跑一遍完整流程，不要一上来就生成整个项目的所有表。等跑顺一个模块之后，再评估是否要把生成器推广到更多场景。t3code 的定位不是替代业务开发，而是把那些机械重复、改了容易出错的胶水代码接管掉，把人解放出来去处理真正有挑战的部分。