1. 为什么我会盯上 t3codeTypeScript 项目里的重复劳动终于有解了先说说背景。我在一个以 Next.js 为主的前端团队里带基础设施相关的工作TypeScript 是我们的默认语言tRPC 做前后端接口联通Prisma 管数据库模型。这套组合网上一般叫 T3 Stack用熟了之后开发速度确实快但有一个问题一直没根治——样板代码太多了。每次接到一个新模块流程几乎固定先建页面路由再写 API 路由接着在 tRPC router 里挂 procedure然后去 Prisma schema 里加模型最后还要补 zod 校验、类型推导、错误处理。一个完整的 CRUD 模块走下来真正有业务逻辑的部分可能只占三成剩下七成全是格式化的重复代码。t3code 是最近在开发者社区里流传的一个针对这套开发模式的辅助工具准确说它更像一个代码脚手架 类型推导 规范模板的结合体。它做的事情不是帮你在编辑器里补全几个单词而是把你从零到一搭建一个类型安全的业务模块所需要的那套东西——路由、服务、校验、数据库模型——一次性按统一风格生成出来生成的结果直接放进现有项目结构里就能编译、能修改、能跑测试。我第一次看到它的思路时有点惊讶因为大部分脚手架工具都在做项目初始化也就是帮你把仓库拉下来、依赖装好、目录建好就结束了。而 t3code 的定位明显不在初始化这一步它解决的是项目跑起来之后每次新增业务模块时都要重复手敲的那部分。这两个场景的差别很大初始化只发生一次重复造模块却每天都在发生后者才真正决定团队的日常效率。这篇文章我会从实际使用的角度把 t3code 的工作流、配置方式、和现有工程的整合方法以及我踩过的几个坑完整复盘一遍。如果你也在用 Next.js、tRPC、Prisma 这一套技术栈或者你正处于想用脚手架但不想被脚手架绑架的阶段这篇内容应该对你有参考价值。2. 核心原理拆解t3code 是怎么做到生成即可用的在开始安装之前我建议你先理解 t3code 最基本的运行方式否则会在配置阶段走弯路。它本质上是一个代码生成器但生成逻辑不是简单的字符串拼接而是分了三层先读取你的现有工程结构再根据约定推导项目意图最后按模板渲染出代码。2.1 第一层读取工程结构确定生成位置很多脚手架工具默认你从空目录起步t3code 不是这样设计的。它会先扫描当前项目的目录结构识别关键文件——比如next.config.js、prisma/schema.prisma、src/server/api/root.ts——来判断你用的是哪个版本的 T3 结构然后根据识别结果决定新代码往哪里放。这意味着它对你的项目路径有明确的预期如果你的项目是标准的src/目录结构那基本不用额外配置。如果使用了 monorepo 或者自定义目录就需要在生成前指定路径映射。这一点我在后面的实操部分会展开讲。2.2 第二层从命令参数推导模块意图t3code 的生成命令通常长这样t3code generate resource --nameproduct --fieldsname:string,price:number,description:string?注意最后那个字段列表它不只是用来生成 Prisma 模型的还会同时影响 zod schema、tRPC procedure 的输入类型、API 层的参数校验甚至页面表单的初始结构。这是它和普通脚手架最不一样的地方——一份字段声明贯穿全链路。每个字段声明里可以带类型标记string、number、boolean、datetime、enum 等也可以带修饰符?表示可选[]表示数组还能显式指定关联关系比如categoryId:string:relation。t3code 会把这些信息编译成中间描述结构化数据再交给渲染层。2.3 第三层模板渲染和类型一致性检查中间描述结构确定后渲染层会按照内置的模板全家桶生成代码。模板覆盖这些文件Prisma schema 里的 model 定义zod 校验 schematRPC router 里的 CRUD proceduresServer 层的业务逻辑文件默认生成空壳业务代码留给你写API 路由的 error handler前端页面的列表、创建、编辑表单基础骨架可选的 React Hook Form 表单类型绑定生成完成后t3code 还会执行一轮轻量的类型一致性校验——它的做法是检查schema.prisma里的模型名和 tRPC router 中引用的名称是否匹配然后通过导出的类型检查脚本跑一次tsc --noEmit。这一轮校验可以保证生成结果不是看上去可用而是真的能过 TypeScript 编译。提示这一轮校验只做编译检查不做业务逻辑检查。生成代码里如果涉及关联查询、权限判断这类复杂逻辑还是需要你自己补全。3. 实操过程从安装到生成一个完整 CRUD 模块下面是我在一台干净的 Ubuntu 开发机上完整走了一遍的流程每一步都写出来包括中间遇到的环境问题方便你对照。3.1 环境准备与安装依赖环境要求不算高Node.js 18 或以上版本npm 9 以上项目本身是标准的 T3 结构。安装很简单npm install -g t3code t3code --version如果之前用过早期版本建议直接升级到最新版本早期版本对 pnpm 的支持有问题会出现依赖装完但命令找不到的情况。我在第一步就遇到了一个小问题公司内网环境没有配置 npm 镜像安装时一直卡在 postinstall 脚本的下载环节。最后用.npmrc指定了国内镜像源绕过下载环节才解决。这个失败原因和 t3code 本身无关纯属网络环境问题但如果你是初次使用建议第一时间确认镜像源配置不然会把时间浪费在定位安装失败上。3.2 初始化接入现有项目安装完以后进入你的现有项目先做一次接入检查t3code init这条命令不会立刻改你的文件它会做这几件事检测项目里的框架版本React、Next.js、Prisma、tRPC 各自版本检查目录结构是否匹配预期生成一份t3code.config.ts配置文件输出一份将要接管哪些目录的报告这一步对应到我前面说的读取工程结构。如果项目结构不符合预期init 阶段就会给出警告而不是等生成代码之后才报错。生成的t3code.config.ts长这样import { defineConfig } from t3code; export default defineConfig({ prismaSchemaPath: ./prisma/schema.prisma, trpcRouterDir: ./src/server/api/routers, outputDir: ./src/server/api/generated, enablePrismaSync: true, enableEsLintCheck: true, fieldNaming: camelCase, });注意outputDir这个字段它指的是生成的路由挂载位置默认建议独立成一个目录不要直接写到routers/里去和手写代码混在一起。原因我后面会详细讲。3.3 生成一个业务模块接入完成后我在测试项目里先生成了一个最简的category模块练手t3code generate resource --namecategory --fieldsname:string, slug:string:unique命令执行过程大概分四步日志里能看得很清楚✔ 读取 Prisma schema定位 model 挂载位置 ✔ 生成 model 定义、zod schema、tRPC router ✔ 将生成的 controller 模板写入 server 目录 ✔ 执行 tsc --noEmit 检查通过生成完成后prisma/schema.prisma末尾多了一段model Category { id String id default(cuid()) name String slug String unique createdAt DateTime default(now()) updatedAt DateTime updatedAt }同时 tRPC 目录里多了一个categoryRouter内置了create、list、getById、update、delete五个 procedure全部用 zod 做了输入校验返回类型直接从 Prisma 的 model 类型推导没有手写任何 interface。我特意打开生成的文件检查了一下发现几个细节处理得不错输入 schema 里的字符串字段默认加了.min(1, 不能为空)校验防止空字符串漏进数据库列表接口默认带分页参数page和pageSize并提供了基础的count统计删除接口不是物理删除而是做了软删除字段deletedAt的预留这些默认行为不一定都符合你的业务需求但它们体现了一个脚手架该有的态度先给一套安全默认值再允许你在配置里去改。3.4 查看生成成果修改业务逻辑生成完毕后核心业务逻辑文件是一个空的类export class CategoryService { async beforeCreate(input: CategoryCreateInput) { // TODO: 在这里写创建前的业务逻辑比如唯一性校验、字段加工 return input; } async afterCreate(result: Category) { // TODO: 创建完成后的额外处理比如写缓存、发事件 return result; } }这就是它故意的设计把能自动生成的部分全部自动生成把只能靠人的业务判断处理的部分留成一个明确的入口。我在实践中发现这个入口设计得很好用因为团队里不同人写的 CRUD 接口之所以风格不一致就是因为没有这样一个统一的插槽约束位置。现在大家都把代码写进beforeCreate/afterCreate评审代码时只需看这两个函数效率高很多。4. 接入现有团队工作流的正确姿势工具单独用很容易难的是嵌进一个已经运行了几个月的项目里并且不破坏现有规范。这个部分我从配置、目录隔离、CI 联动三个方面复盘我实际接入时的做法。4.1 目录隔离生成代码和手写代码必须分开这是我认为 t3code 使用里最重要的一条经验。刚开始接入时我直接把生成的路由写进了现有的routers/目录结果第一次跑完就出现了两个问题第一生成的代码风格和团队手写风格不一致被代码评审的同事提了一堆意见第二后续只要工具升级了模板重新生成就会覆盖掉手写代码导致要手动 merge。后来我统一改成生成的代码全部放在src/server/api/generated/目录下这个目录里的文件标记为由 t3code 生成不要手改。手写代码放在src/server/api/modules/通过 re-export 把生成的路由包一层再挂到 root router// src/server/api/generated/product.ts export const productRouter createTRPCRouter({ ... });// src/server/api/modules/product.ts import { productRouter } from ~/server/api/generated/product; // 在这里为 product 增加手写的 procedure export const extendedProductRouter mergeRouters(productRouter, createTRPCRouter({ customProcedure: ..., }));这样做的收益很明显工具升级后可以放心地重新生成不会覆盖手写逻辑Code review 时一眼就能看出哪些是工具产物哪些需要人工重点审查如果生成的代码有 bug可以直接在 generated 目录里全局搜索定位4.2 配置入库团队级统一约束t3code.config.ts里可以配置很多团队级的约束我的建议是把这几个字段固定下来配置项推荐值原因fieldNamingcamelCase避免生成字段命名风格在前后端间不一致enableEsLintChecktrue生成后自动过 lint不产出带 warning 的代码enablePrettierFormattrue统一格式减少 code review 噪音generateReactHookFormfalse按需开启不是所有团队都用 RHFsoftDeletetrue默认软删除安全第一有了统一的配置文件团队里任何人执行 t3code 生成的代码风格就是一致的。这个看起来简单实际上解决了一个很实际的问题新人对项目规范的了解程度不同但工具生成的代码天然符合规范等于把规范执行这件事从人来保证变成了工具保证。4.3 CI 阶段自动检查生成文件是否过期项目跑了两周之后我遇到了一个新问题有人在手写代码里改了 Prisma schema 的字段但生成的 zod schema 没有同步更新测试阶段才发现类型对不上。这时我才意识到t3code 的生成动作应该被纳入 CI 而不是只在本地手动执行。我的做法是加了两个 CI 检查第一个检查schema.prisma是否有未同步的变更t3code diff --schema prisma/schema.prisma --generated src/server/api/generated如果输出有差异CI 直接失败提示开发者执行t3code generate重新生成。第二个对 generated 目录强制执行tsc --noEmit确保推上来的代码是编译通过的。这套流程跑起来之后类型不一致的问题基本被消灭了。同事的反馈也很直接现在不用自己担心有没有漏改类型了工具会告诉我。5. 实测中的意外情况与避坑记录再好的工具实际使用时也会遇到一些设计之外的情况。这里写几个我印象比较深的坑以及对应的解决方案。5.1 枚举类型生成的边界问题在最初的测试里我给一个status字段设了enum类型t3code generate resource --nameorder --fieldsstatus:string:enum[PENDING|PAID|SHIPPED|DONE]生成出来的 Prisma enum 没有问题zod schema 也用z.enum()做了校验但前端表单部分生成的是一个原生 input 而不是 dropdown。原因是 t3code 在生成前端表单时对 enum 类型默认只在校验层做处理生成 UI 控件还需要额外的 map 配置。提示如果你需要前端下拉选项建议在t3code.config.ts里给该字段追加ui: { component: select, options: [...] }配置不要指望工具能自动推导出 UI 交互形态。这个坑的本质是枚举在数据层有明确含义但 UI 层没有唯一正确答案工具选择保守处理是合理的。理解这一点之后使用时的预期就不会错位。5.2 数据库迁移需要手动执行t3code 生成 Prisma model 后不会自动执行prisma migrate。我第一次生成完模型直接跑测试发现数据库表不存在卡了几分钟才反应过来。正确顺序是t3code generate resource --nameproduct ... npx prisma migrate dev --name add-product注意迁移顺序很重要一定要在生成代码之后、启动应用之前执行。否则 tRPC 查询会先失败造成代码没生效的错觉。5.3 和 prettier 的格式化冲突我在第一次运行时发现 CI 里的 prettier 检查挂了原因是 t3code 生成的文件带了它内置的格式化风格和团队的项目级prettier.config.js不完全一样主要是单引号和尾逗号的处理。解决办法是在t3code.config.ts里指定export default defineConfig({ prettier: { semi: false, singleQuote: true, trailingComma: es5, }, });然后执行一次t3code generate --all重新生成格式就和团队规范对齐了。这个配置必须在接入的第一天就设好否则后来再改git diff 会非常巨大。5.4 不要在 monorepo 根目录直接跑 generate我们团队有一个仓库是 turborepo 结构刚接入时我在根目录执行 t3code结果它把配置写到了根目录的t3code.config.ts生成代码时往 packages 外部写了文件直接破坏目录隔离。后来在 monorepo 里我把生成动作限制在具体的基础包目录内比如apps/web或packages/db里各自初始化一份配置反而更好用。因为每个包的生成目标更明确不会出现跨包引用路径错误的问题。6. 我对生成代码的最终处理原则七分自动三分人工复盘整个接入过程我最想分享的一个体会是用这类工具的边界感要清晰该交给工具的交给工具该保留人工判断的必须保留人工判断。我的团队现在对 t3code 生成的代码守这几条原则schema 定义、路由挂载、基础校验、错误处理这类格式化工件全部由工具生成业务逻辑、权限判断、第三方服务调用、缓存策略这些决策型代码全部手写生成代码一率不进手写引用的公共目录要引用就通过 re-export 包一层每次 t3code 升级版本后先跑一次--dry-run查看 diff再决定是否全量重新生成按这套原则跑了一个季度效果是CRUD 模块的开发时间从平均一小时压到了二十分钟左右类型相关 bug 明显减少code review 的注意力更容易集中在真正的业务逻辑上。最后分享一个配置小技巧如果你发现生成的列表接口每次都要自己在afterFind里补数据权限过滤可以在beforeFind钩子里统一注入where条件比如自动加上deletedAt: null或租户 ID一劳永逸。这个钩子和前面提到的beforeCreate一样都是生成后不会覆盖的人工入口把公共逻辑放进去生成代码天然继承。