t3code：从Prisma Schema自动生成T3全栈CRUD代码

把第三个业务模块的手写CRUD代码推倒重写的时候，我终于承认自己的问题不是写得慢，是写得烦。明明就是 list、get、create、update、delete 这几板斧，换张表名就要从头复制粘贴一遍，还得小心翼翼改掉所有驼峰命名、类型导入和 tRPC 路径。做 T3 Stack（Next.js + TypeScript + tRPC + Prisma + Tailwind CSS）全栈项目的人大概率都有这种体会：这套技术栈上手体验确实舒服，可当业务表多起来，那堆模板代码就会不间断地消耗你的耐心。

所以我花了几周时间写了这个叫 t3code 的开源小工具。它不是 ORM，也不是 CMS，而是一个面向 T3 项目的代码生成器：你给它一份 Prisma Schema，它帮你输出一整层可用的 tRPC Router、Zod 输入校验、React Query Hooks，甚至生成简单的管理页面骨架。这篇文章把它的设计思路、落地步骤和踩过的坑都写出来，如果你也在维护一个 T3 全栈工程，或者本身对“代码生成器”这种工具感兴趣，应该能从里面找到点能直接用上的东西。

1. 纯手写T3模块三个月后，我终于决定给自己做个代码生成器

1.1 一条User资源究竟要做多少步手工操作

先数一下在 T3 Stack 里新增一个资源的完整流程。假设业务上需要一个 User 模块，你至少要动这些文件：

• 在schema.prisma里定义 User model；
• 手动同步一份 Zod Schema 用来做 tRPC 输入校验，字段类型、必填可选、默认值都要和 Prisma 对齐；
• 新建一个 tRPC Router，把create、get、list、update、delete五个 procedure 都写出来，每个都还要包一层输入校验和错误处理；
• 在根 Router 里手动注册这个子路由；
• 去页面层写 React Query 的useQuery、useMutation，再配一个invalidate让缓存刷新；
• 写表单页、详情页、列表页，页面里再手写加载态、错误态、空态；
• 如果有权限控制，还要在每个 procedure 里重复贴 middleware 判断。

这已经算比较克制的项目了。如果模型里有 relation、多对多、枚举字段、软删除，步骤还要翻倍。第一次做觉得新鲜，第二次忍一忍，第三次开始暴躁。真正让我决定写 t3code 的瞬间，是有一次我在 Prisma Model 里把emailVerifiedAt从DateTime?改成了DateTime @updatedAt，结果忘了同步 tRPC 的 Zod Schema，线上报错查了半小时，最后发现只是校验层和数据库层不一致。

这种问题根本不是手速能解决的，是维护多份同步定义的必然代价。

1.2 自动化真正的收益不在敲字速度，而在“一致性”

很多人一听代码生成器，第一反应是“能省多少打字时间”。其实纯手打那点时间真不算什么，一个 CRUD 模块撑死写一两个小时。代码生成器真正的价值是让你永远不需要记住那套一致性约定，把“人肉保证同步”这件事变成“机器保证同步”。

比如我在 t3code 里约定了一套规则：

• Prisma model 字段名是什么，Zod 字段名就是什么；
• Prisma 必填字段对应z.string()/z.number()，可选字段对应.optional()；
• @default(now())的字段不出现在 create 输入里；
• @updatedAt的字段压根不生成到任何输入里；
• 外键字段只在 create/update 里暴露标量authorId，不暴露对象author。

这套规则一旦写进生成器，全项目所有模块都是同一副面孔。Review 代码的时候你不需要思考“这里为什么 nullable 没设nullish()”，生成结果永远符合预期。人写代码会疲劳、会状态差、会漏边界，生成器不会。

1.3 为什么不直接用现成的ORM或脚手架

市面上其实有不少能“从数据库结构生成代码”的东西。Prisma 官方有prisma-case-format、zod-prisma-types之类的生态工具，Next.js 生态里也有各种初始化脚手架。但我试用过一圈之后发现一个尴尬点：它们大多数只解决了“数据库 schema 到 TypeScript 类型”这一段，并没有解决“类型到 tRPC Router 和 React Query Hooks”这一段。

T3 项目真正重复劳动的重灾区是应用层，不是模型层。我需要的是能一次性生成post.router.ts、usePost.ts、PostForm.tsx这类文件的工具，而不是只生成一个PostCreateInputType。t3code 的定位就是填补这个空白：从 Prisma Schema 作为唯一输入，直接产出一整套能跑通前后端的胶水代码。

2. 用Prisma Schema当“唯一事实来源”，t3code的核心设计

2.1 字段类型映射规则：Prisma类型到Zod类型的对应

t3code 最关键的设计决策，是让prisma/schema.prisma成为整个生成流程的唯一事实来源。原因很简单：Prisma Schema 已经是你的数据库结构定义，它具有不可辩驳的权威性。与其再造一套 DSL，不如直接解析 Prisma Schema，把它的字段类型映射成 Zod 类型。

最基础的映射关系我用一张表列在下面，这是生成器的核心映射表，也是使用者最先应该理解的部分：

Prisma 字段类型	t3code 生成的 Zod 类型	说明
String	z.string()	默认不设最小长度，避免业务误伤
Int	z.number().int()	你几乎不会想要一个浮点数的 Int
Float	z.number()
Boolean	z.boolean()
DateTime	z.coerce.date()	关键在coerce，后面踩坑小节细说
Json	z.unknown()	JSON 字段结构不可预测，交给业务层再校验
Enum	z.enum([...])	直接从 Prisma enum 定义里提取所有值
String?	z.string().optional()	可选字段统一.optional()
String @default(...)	z.string().default(...)	默认值尽量和数据库保持一致

我特意强调DateTime用z.coerce.date()而不是z.date()。因为 tRPC 客户端传参时，前端很可能直接发 ISO 字符串过来，z.date()会直接拒绝，但coerce会帮你把字符串转成 Date 对象。实测下来，这能让接口层少很多无谓的报错。

对于@db.VarChar(255)这种修饰符，我不会把它转成.max(255)，因为数据库层面已经限制了长度，应用层再重复限制容易导致明明写了 200 个字也存不进去的困惑。想限制长度的话，可以在配置里给特定字段追加校验规则，而不是让生成器自动读@db属性。

2.2 从model标记推导CRUD能力：@id、@updatedAt与关系外键

知道了字段类型还不够，生成器还得知道哪些字段该出现在 create 输入，哪些该在 update 时处理，哪些要作为查询条件。我用 Prisma 自身的标记来判断：

• @id字段：create 时不可传入（除了少数用@default(cuid())的场景），get 和 update 时作为主键查询参数；
• @default(now())或@default(dbgenerated(...))字段：create 输入里直接省略，由数据库生成；
• @updatedAt字段：任何输入都不暴露，Prisma 会在更新时自动维护；
• @unique字段：额外生成一个getByEmail/getBySlug之类的查询 procedure，但默认不公开，需要配置开启；
• @relation字段：不会生成对象本身作为输入，而是从fields: [authorId]里提取对应的标量外键字段，放进 create/update 输入。

这里最容易被忽视的是 relation 的处理。新手很容易在生成器里把author这个关系字段也当成普通字段生成一个z.object({...})，结果真正提交时 Prisma 根本不知道你要传什么。正确做法就是只暴露标量外键，让调用方传authorId: "cm5..."。后面我会专门讲这个问题为什么是坑。

2.3 t3code.config.ts 如何控制生成行为

任何一个生成器，如果只能“一把梭生成所有模型”，那它在真实项目里没法用。不同团队的命名风格、模块边界、权限策略差异太大了。所以 t3code 提供了一个类型安全的配置文件t3code.config.ts，核心配置项长这样：

import { defineConfig } from "t3code"; export default defineConfig({ schemaPath: "./prisma/schema.prisma", outputDir: "./src/server/generated", generateHooks: true, generatePages: false, models: ["Post", "User", "Comment"], includeRelations: true, fieldNaming: "camelCase", tsxImportPath: "~/utils/api", useServerOnly: true, zodGenerator: { additionalRules: { title: (field) => field.name.includes("title") && field.type === "String" ? [z.string().min(1).max(120)] : [] } } });

每个配置项都有它的用途。models用来限定只生成指定模型，避免一次性生成几百个文件把 git diff 搞得没法看。fieldNaming控制多词字段的转换风格，团队里有人喜欢user_id，有人喜欢userId，统一在这里设置。tsxImportPath解决的是 monorepo 或者不同项目别名不一致的问题，否则生成出来的 import 路径全是错的。

这里要强调一下我的一个设计偏好：配置项是“行为约束”，不是“万能开关”。一上来堆一百个配置项只会让工具更难以维护。t3code 的方向是让 80% 的项目不需要任何额外配置，只把少数团队级差异暴露出来。

3. 从零开始：把t3code应用到一个新鲜出炉的T3工程

3.1 安装与初始化：npx t3code init

用 t3code 的第一步很简单，在任意 T3 工程根目录运行：

npx t3code init

这个命令会生成一个带默认值的t3code.config.ts，并且自动检测你项目里的schema.prisma路径。如果检测到你是 pnpm 工程，它会在 devDependencies 里写入t3code；如果没有检测到，它只生成配置，不会强行改你的 package.json。

我建议 init 之后先改两个配置：models先填一个简单的模型测试，比如["User"]；outputDir先设为./src/server/generated。不要一上来就全量生成，尤其项目里模型已经很多的情况，先在单个模型上验证结果，再逐步放开。

3.2 一个带关联关系的Prisma示例

为了展示 t3code 的实际效果，我用一个非常经典的两层模型结构做演示，一个 User 多个 Post：

model User { id String @id @default(cuid()) email String @unique name 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) authorId String author User @relation(fields: [authorId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

这个例子虽然小，但已经把主键、唯一索引、可选字段、默认值、时间戳、外键关系、反向关系全包括了。拿它来验证生成器比拿空表好用得多。

3.3 执行生成的完整链路：Schema -> Router -> Hooks -> 页面

配置写好后，运行：

npx t3code generate

t3code 会读取 schema，解析 model，然后按目录结构输出文件。生成结果大致是这个样子：

src/server/generated/ ├── post.router.ts ├── post.schema.ts ├── user.router.ts ├── user.schema.ts └── hooks/ ├── usePost.ts └── useUser.ts

拿 Post 模块举例，post.schema.ts大概长这样：

import { z } from "zod"; export const postCreateSchema = z.object({ title: z.string().min(1), content: z.string().optional(), published: z.boolean().default(false), authorId: z.string().cuid(), }); export const postUpdateSchema = z.object({ title: z.string().min(1).optional(), content: z.string().nullish(), published: z.boolean().optional(), authorId: z.string().cuid().optional(), }); export const postListSchema = z.object({ take: z.number().int().min(1).max(100).default(20), skip: z.number().int().default(0), cursor: z.string().cuid().optional(), });

对应的post.router.ts：

import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import type { PrismaClient } from "@prisma/client"; import { postCreateSchema, postUpdateSchema, postListSchema } from "./post.schema"; export const postRouter = createTRPCRouter({ list: publicProcedure .input(postListSchema) .query(async ({ ctx }) => { const results = await ctx.db.post.findMany({ take: input.take, skip: input.skip, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: "desc" }, }); return results; }), get: publicProcedure .input(z.object({ id: z.string().cuid() })) .query(async ({ ctx }) => ctx.db.post.findUnique({ where: { id: input.id } })), create: publicProcedure .input(postCreateSchema) .mutation(async ({ ctx }) => ctx.db.post.create({ data: input })), update: publicProcedure .input(z.object({ id: z.string().cuid(), data: postUpdateSchema })) .mutation(async ({ ctx }) => ctx.db.post.update({ where: { id: input.id }, data: input.data })), delete: publicProcedure .input(z.object({ id: z.string().cuid() })) .mutation(async ({ ctx }) => ctx.db.post.delete({ where: { id: input.id } })), });

页面层的 hook 也一并生成好了，hooks/usePost.ts：

import { api } from "~/utils/api"; export function usePostList() { const list = api.post.list.useQuery({}); const utils = api.useUtils(); const create = api.post.create.useMutation({ onSuccess: () => utils.post.list.invalidate(), }); const update = api.post.update.useMutation({ onSuccess: () => utils.post.list.invalidate(), }); const remove = api.post.delete.useMutation({ onSuccess: () => utils.post.list.invalidate(), }); return { list, create, update, remove }; }

这些生成出来的代码完全是“T3 项目的语言”，没有抽象封装，没有奇怪的工厂函数，任何人拿到都能直接看明白。我觉得这是代码生成器最重要的品质：生成结果要像团队里最细心那个同事手写出来的。

3.4 把生成结果挂进根Router

文件生成后还需要手动做一步：把子路由挂到根 Router 上。从src/server/api/root.ts里修改：

export const appRouter = createTRPCRouter({ post: postRouter, user: userRouter, });

如果你把generatePages设成 true，t3code 还会生成src/pages/posts/index.tsx、src/pages/posts/new.tsx、src/pages/posts/[id].tsx三个基础页面。考虑到每种技术栈的页面写法差异极大，这个开关默认关闭，我更建议团队里由一个人先跑通一版页面样板，剩下的人照着改。

4. 真正跑起来才发现的五个“坑”，以及t3code给出的解法

4.1 可选外键和嵌套创建的输入校验如何合并

这是我在第一次用自己生成的 Router 调 Post 创建接口时立刻炸掉的坑。postCreateSchema里写了authorId: z.string().cuid()，看起来没问题。但有个业务场景是“从草稿状态创建帖子，先不指定作者”，于是我需要把authorId变成可选的。

改法很直接，postCreateSchema变成：

authorId: z.string().cuid().optional(),

问题出在 Prisma 的create调用上。如果 input 里authorId是undefined，Prisma 不会报错；但如果当用户传了null，Prisma 会直接抛Argument authorId must not be null。因为 tRPC 的输入缺省是undefined，只要生成器严格处理可选为空的情况，其实不太会踩到。真正隐蔽的是另一种写法：

data: { ...input, authorId: input.authorId ?? undefined }

如果你生成器不够小心，在create的 data 里直接展开 input，当用户没有传 authorId 时一切正常；一旦某个前端把空字符串传进来，Zod 校验拦截住了空串，但用户预期是什么？这里需要在 schema 上用.optional()还是.nullish()做明确区分。

最后的解法是：t3code 生成 create 的 data 之前会做一次“抹空”处理，把所有值为null的可选字段过滤成undefined，再把对象交给 Prisma。这样既保持了 tRPC 输入层的宽容度，又不让 Prisma 有机会把null写进非空字段。

4.2 Date对象在tRPC输出和React Query缓存里的序列化

第一次跑通生成代码后，我在列表页把createdAt直接渲染出来，页面上显示的不是时间，而是一段奇怪的字符串。查了半天才发现 T3 Template 默认给 tRPC 加了superjson作为 transformer，它能把 Date 对象序列化成 ISO 字符串再传回客户端，React Query 拿到之后又会把它反序列化为 Date。

听起来没问题，但如果你在自定义 procedure 里显式返回一个对象，而对象里的字段本身不是 Prisma 返回的 Date，而是你从别的地方塞进去的字符串，类型系统就会悄悄骗了你：TypeScript 认为它是 Date，运行时它是 string。等到页面调date.toISOString()就炸。

t3code 的应对策略是在生成的 Zod Schema 里统一用z.coerce.date()，并且在生成的 Router 代码里不直接 return 掉 Prisma 对象，而是通过一个可配置的serialize钩子交给团队自己决定。默认情况下我使用 superjson 的标准行为：不做特殊处理，但强烈建议所有页面层渲染时间时用Intl.DateTimeFormat，不要直接依赖Date对象方法。

4.3 多词模型名和字段名的命名转换

我的项目里有一个模型叫PostCategory，数据库表名被 Prisma@@map映射成了post_categories。生成器如果不做统一命名转换，会生成postcategory.router.ts这种东西，导入的时候既不好看也容易冲突。

t3code 内部维护了一套完整的命名映射：

• 模型名PostCategory-> 变量名postCategory，文件名为post-category.router.ts；
• 字段名createdAt-> 配置里如果设置fieldNaming: "snake_case"，则生成created_at；
• tRPC 根路由 key 统一使用 camelCase，和 React Query 的api.postCategory.list保持一致。

这里最容易出错的是外键字段。比如模型里写authorId，Prisma 在数据库里的实际列名可能是author_id。生成器必须追踪@relation(fields: [authorId])，而不是靠猜。我在第一版实现里正则切分下划线，结果遇到一个字段叫userIdNo，差点没把命名搞炸。后来干脆用了一个成熟的 camelCase 转换库，所有转换规则收敛在一个文件里，再也没出过玄学命名。

4.4 生成器自己的版本管理：Prisma枚举和Client导入路径

Prisma 每个大版本都会调整生成的 client 导入方式。从 Prisma 5 到 Prisma 6，@prisma/client依然能用，但很多人开始用新的prisma-clientgenerator，默认输出到自定义目录。这直接影响 t3code 生成代码里的导入路径：

// 旧版预期 import { PrismaClient } from "@prisma/client"; // 新版预期，假设输出目录是 ./src/generated/prisma import { PrismaClient } from "~/generated/prisma/client";

我在 t3code 配置里加了prismaClientPath这一项，让使用者显式声明 client 的导入地址。枚举类型的处理也类似：如果 Schema 里定义了 enum，生成代码时会生成独立的enums.ts，所有的z.enum([...])会引用这个文件，避免每个 router 文件里重复粘贴一组枚举字符串数组。这样当你新增一个枚举值，只要重新生成一次，所有校验逻辑自动更新。

4.5 不是所有东西都该“生成”，用注释标记跳过区域

代码生成器的边界要非常清醒：有些东西确实适合生成，有些东西生成了反而碍事。比如一个列表接口可能需要非常复杂的过滤排序逻辑，生成器硬要生成一个固定的findMany就是画蛇添足。

t3code 支持在 Prisma Schema 里通过注释标记跳过：

model SecretNote { /// @t3code.ignore id String @id @default(cuid()) encrypted String }

被标记的模型不会生成任何文件。另外，对于单个字段，你也能用/// @t3code.input: omit或/// @t3code.input: readonly来控制是否出现在创建或更新输入里。这个能力我越用越觉得重要，它把你从“生成器能这么做吗”的焦虑里解放出来：生成满足 80% 场景，剩下 20% 用注释显式声明例外，而不是改配置或者手工改代码。

5. 如果你也想写一个代码生成器，我从t3code里总结的经验

5.1 为什么用AST而不是字符串替换去改代码

t3code 第一版也用正则做文件改写，当时觉得“生成代码而已，何必上编译分析”。结果遇到格式变化就出 Bug：不同人的代码缩进、引号风格、最后一行有没有分号，都会让正则匹配失效。

后来我把生成器的核心从“替换文本”改成“操作 AST”，用 TypeScript 官方的 compiler API 和 ts-morph 来读取、变换、输出代码。好处是：

• 不再关心原文件里到底有没有分号、用的是单引号还是双引号；
• 可以精准定位 class 的位置、import 语句的位置，然后插入新代码；
• 生成代码前能自动格式化，输出结果和 Prettier 一致。

代价是学习曲线变陡，ts-morph 文档不太全，很多 API 要靠试。但这是值得的，因为代码生成器最容易翻车的地方就在文本处理。我花在 AST 上的调试时间，比写生成逻辑本身还多。

5.2 生成代码的可读性大于一切，别搞抽象封装

我在做 t3code 最初几版的时候犯过错：为了让生成的代码“干净”，把很多逻辑抽成了共享的 base 类和工厂函数。结果生成出来的文件确实很短，但读代码的人根本不知道这些 base 类做了什么，调试的时候要跨好几个文件跳来跳去。

后来我意识到，对代码生成器而言，生成结果应该“幼稚”：把该写的字段、该导入的类型、该写的调用全部平铺展开，宁可多写几行，也不要为了 DRY 引入一层抽象。因为生成器的产出并不是给人反复维护的，它需要的是“一眼看过去就懂”。举个例子，与其生成usePaginatedQuery({ model: "post" })，不如直接生成一份完整的usePostList函数。代码是重复了一点，但每个文件的独立性和可读性都得到了保证。

5.3 预留逃生舱门：生成头部注释标明手动修改会被覆盖

无论生成器有多么好用，总会有需要手改生成结果的时候。t3code 会在每个生成文件的头部自动写入一行注释：

// @generated by t3code - manual edits will be overwritten

这行注释有双重作用。第一，git diff 的时候一眼就能看出哪些文件是机器生成的，review 时不用逐行检查；第二，万一有人忘了改配置而直接手改生成文件，下次运行 generate 时他会发现自己改的东西丢了，从而知道应该去改配置或 Prisma Schema。

我建议任何写代码生成器的人都保留这个习惯，最好再加一个// @t3code-managed标记，让 CI 脚本能扫描出那些“被手动修改过的生成文件”并给出警告。逃生舱门是给特殊情况用的，但不能让紧急改法变成常态。

5.4 生成器本身的快照测试和下一步规划

代码生成器有一个特别让人头疼的问题：你修了一个 Bug，改了一行转换逻辑，结果可能会悄悄影响几十个模型的生成结果。我现在的做法是维护一组“金样本”模型放进 fixture 目录，每次改动 t3code 后跑一遍快照测试，把生成结果全部输出，然后和上一次的快照做 diff。只要 diff 里出现非预期的变化，就能立刻定位。

下一步我准备给 t3code 加一个diff命令，让它能和 git 结合：执行npx t3code generate --dry-run时，不实际写入文件，而是输出“哪些文件会新增、哪些会更新、哪些会删除”。这样在 CI 里也可以跑一次，把生成结果是否与仓库一致作为检查项，从源头上杜绝“生成器和手改代码脱节”的问题。

如果你也想做类似方向的工具，我的建议是：先把“一小块最痛的流程”做通，再慢慢扩展。t3code 最初只生成 tRPC Router，连 Zod 都没有。后来发现 Router 里的 input 还要手动写，才加上了 schema 生成；再后来发现页面层重复，又加了 hooks。功能迭代是被真实需求推着走的，而不是一开始就设计一个全能怪物。

最后分享一个小技巧：升级 t3code 的时候，不要只看 release note，直接在你的项目里跑一次 dry-run，然后把 diff 认认真真看一遍。机器生成的代码，往往比你的记忆更诚实。