t3code：一个基于模板与类型安全的TypeScript全栈代码生成工具

1. t3code是什么：一个为TypeScript全栈开发提效而生的命令行工具

先说结论：t3code是我最近折腾的一个开源命令行小工具，定位是“TypeScript全栈项目的代码生成与初始化脚手架”。名字里的t3，最早来自我团队内部对“TypeScript、类型安全、模板化”这三个关键词的缩写——Type、Type-safe、Template，后来干脆就叫t3code。它在做的事很简单：你告诉它“我要开一个新项目，用Next.js + tRPC + Prisma”，它就帮你把目录结构、依赖配置、基础CRUD的样板代码全部拉起来；你告诉它“我要为users表生成一组增删改查接口”，它就直接生成.ts文件，并且类型从头到尾是通的。

这个工具解决的痛点很实际。我见过太多团队在项目起步阶段浪费时间：手动复制上一个项目的文件夹、删掉无关代码、改包名、改路由、改环境变量，最难受的是改完发现类型引用还挂着旧路径。新人在这个环节尤其容易卡住，一问“这个service为什么报红”，十有八九是复制粘贴时漏了个import。t3code的出发点就是把这些重复劳动从“人肉操作”变成“一条命令”，同时保证生成物是类型安全的，而不是一堆能跑但不报错、一改就崩的散装代码。

如果你正在用TypeScript做主语言，日常要开新项目、写业务模块、维护一堆结构相似的接口，那这个工具的思路值得看一看。就算你不打算用它，文里关于模板设计、类型推导、代码生成器的取舍，也能给你自己做脚手架提供参考。我将从设计思路、核心实现、实操流程、踩坑经验几个方面展开，整体偏工程实践，适合已经写过一段时间业务的开发者阅读。

2. 整体设计与思路拆解：为什么选择“模板+生成”而不是“复制+修改”

2.1 代码生成器要解决的真实问题：一致性、类型安全、可演进

要理解t3code的设计，先要理解“脚手架”和“代码生成”的本质区别。传统的脚手架比如create-react-app，做的是“一次性初始化”：给你一套固定的基础项目结构，之后就不管你了。t3code做的是“持续生成”：不仅项目初始化用它，后续加模块、加接口、加数据模型，也用它。这意味着它必须解决三个核心问题：模板的一致性、生成结果与现有代码的类型兼容、以及后续演进时模板本身的可维护性。

一致性是首要目标。手工复制项目时，“上次多写了两个字段，这次忘了复制”是常有的事。模板化之后，每个新模块都来自同一套模板，字段、命名、目录结构天然一致。类型安全则更进一步：生成的代码不是“看起来像TypeScript的文本”，而是要能通过tsc --noEmit的检查。为了实现这一点，t3code内部把“数据模型定义”作为唯一可信源，所有生成逻辑都围绕这个模型展开，避免各部分各写各的类型。可演进性则是考虑到：团队规范会变，目录风格会变，生成器不能写死成“写一次用到死”。

2.2 为什么用CLI而不是GUI或Web界面

很多工具习惯做一个可视化界面，选择项目名、勾选功能模块、点击生成。t3code从一开始就决定做成纯CLI，原因很简单：代码生成是开发流程中的一环，不是终点。CLI可以自由嵌入到npm scripts、CI流水线、pre-commit钩子里，比如“每次改完schema自动重新生成类型和CRUD”。GUI在这个场景下反而成了累赘——你没法在一个网页里执行git diff并检查类型报错，更没法把“打开页面、点几个按钮”变成一键命令。

CLI的另一个优势是组合性。用户可以这样串起来用：

t3code init user-service --template server --orm prisma t3code add model user --fields "name:string,email:string,role:enum" t3code gen crud --model user --style rest

三条命令做完，一个带数据库模型、路由、服务层的模块就出来了。这个能力是GUI很难优雅实现的，因为命令行天然适合“多步骤串联”和“参数化输入”。

2.3 模板渲染与文件写入机制：为什么选EJS做基础层

t3code的模板渲染基于EJS做出二次封装。选EJS而不是Handlebars，也不是手写字符串拼接，有几个具体的考虑。EJS的语法和JavaScript几乎一致，学习成本低，团队成员都能快速上手改模板；它支持直接调用传入的数据对象，比如<%= model.fields.map(f => f.name).join(', ') %>，这让我能在模板里写点简单逻辑，但又不会像写完整JavaScript文件那样难以控制。更关键的是，EJS可以保留缩进和换行风格，生成的代码看起来就像人写的，而不是“机器吐出来的”。

文件写入层面，t3code不是简单把模板渲染结果直接落盘。它有一个预检阶段：检查目标路径是否存在、是否已有同名文件、是否属于“可安全覆盖”的白名单范围。默认配置下，如果文件已存在且不在白名单里，工具会跳过并提示用户手动检查，而不是擅自覆盖。这个设计避免了最惨烈的场景——一条命令把写了三天的业务代码冲掉。

3. 核心细节解析与实操要点：配置文件、模板结构、生成规则

3.1 t3code.config.ts：一条命令里所有参数的“唯一事实源”

t3code的配置文件和工具本身一样强调TypeScript。在项目根目录下放一个t3code.config.ts，所有生成规则都以类型安全的方式声明在里面。这不是为了花哨，而是为了让你打开配置的时候能获得智能提示：写错字段名会直接标红，不必对着文档翻来翻去。

配置里最重要的几项是：

这个配置文件本身也会被t3code读取并做运行时校验。比如restStyle如果填了一个不存在的选项，工具会在执行命令前就直接报错退出，而不是等生成完代码再让tsc去报错。这个“前置校验”的体验差距很大，等于把错误挡在生成动作之前。

3.2 模型定义语法：数据模型是第一公民

t3code生成代码时，所有内容和“模型定义”强绑定。模型定义可以放在单独的.t3model.ts文件里，也可以在t3code.config.ts里直接用defineModel函数声明。实际项目里我推荐单独建目录，因为你可能要维护几十个模型。

一个典型定义长这样：

defineModel("User", { fields: { id: { type: "string", primary: true }, name: { type: "string", rules: { required: true, max: 32 } }, email: { type: "string", rules: { required: true, format: "email" } }, role: { type: "enum", values: ["ADMIN", "MEMBER", "GUEST"], default: "MEMBER" }, createdAt: { type: "datetime", auto: true }, }, relations: [ { target: "Post", kind: "one-to-many", foreignKey: "authorId" }, ], });

有一点值得注意：这个模型定义不只是“建表结构”，它同时承担了“TypeScript类型定义”“校验规则定义”“关系定义”三重职责。这样设计是为了避免类型分裂——很多项目里数据库schema是一份类型，接口层是另一份类型，前端再写一份，三者不一致是迟早的事。t3code从源头让一份定义生成所有相关代码，从机制上消灭这个问题。

3.3 模板目录的组织方式：可复用颗粒度与可变颗粒度分开

用t3code做过几个项目后，我总结出模板组织的一个关键原则：把“固定不变的部分”和“随模型变化的部分”拆成不同的模板文件。比如service.base.ts里放的是所有service都要用到的通用封装；service.ts里放的是针对当前模型的业务逻辑骨架。前者相对稳定，后者频繁改动。t3code的默认模板目录是这样的：

templates/ ├── server/ │ ├── controller.ejs │ ├── service.base.ejs │ ├── service.ejs │ ├── router.ejs │ └── schema.prisma.ejs ├── client/ │ ├── api.ts.ejs │ ├── hooks.ts.ejs │ └── types.ts.ejs ├── shared/ │ ├── validation.ts.ejs │ └── index.ts.ejs └── partials/ ├── field-list.ejs └── relation-imports.ejs

partials目录是给模板复用的片段，类似编程语言里的“include”。EJS自带include能力，t3code又给它传入了当前模型上下文，所以partials里也能拿到完整的模型字段信息。这套划分方式，几个平行模块之间不会互相污染，改业务代码不影响通用层，通用层升级所有模块一起受益。

4. 实操过程与核心环节实现：环境准备、命令串联、生成逻辑拆解

4.1 环境准备与项目初始化

t3code要求Node.js 18或以上版本，这个要求主要因为工具内部使用了较新的原生fetch和crypto模块。全局安装还是项目级安装？我建议项目级安装，在devDependencies里加上t3code，然后通过npm scripts调用，这样每个项目锁定的版本是确定的，不会因为全局版本升级导致生成产物变化。

npm init -y npm i -D t3code npx t3code init

init命令会在当前目录生成一套最简模板骨架：t3code.config.ts、最小模板目录、以及一个README说明文件。接下来创建第一个模型：

npx t3code add model Post \ --fields "title:string,content:string,published:boolean" \ --relations "author:User@many-to-one"

这条命令做了三件事：在models目录生成post.model.ts，更新index.ts把新模型导出，最后在generated目录下生成对应的类型校验文件。你可以打开post.model.ts看一眼，里面就是用户用命令行参数声明的内容渲染成模型定义语法。这种从参数到文件的转换，也是模板渲染的一个典型场景。

4.2 生成CRUD后端代码：从模型定义到完整接口

只声明模型还不够，实际开发需要对应的CRUD接口。执行：

npx t3code gen crud --model Post

工具会读取post.model.ts，解析出字段、类型、关系，然后遍历templates/server目录的每个模板，用模型数据渲染并写入src/server目录。最终生成的文件大致如下：

src/server/ ├── controllers/ │ └── post.controller.ts ├── services/ │ ├── post.service.ts │ └── post.service.base.ts └── routes/ └── post.routes.ts

生成的post.service.base.ts禁用了eslint规则@typescript-eslint/no-explicit-any，因为要动态处理数据库返回的类型。post.service.ts则是留给你写业务逻辑的地方。为什么会生成两个service文件？这是我的个人习惯：基础模板文件是“工具生成的、可以重新生成的”；业务逻辑文件是“人写的、应该被git跟踪且不被覆盖的”。t3code通过文件名后缀base来区分这两类，overwrite白名单里默认也把*.base.*包含进去了。这个“生成物和人工物分离”的规则非常关键，建议任何类型的代码生成器都遵循。

4.3 生成前端API调用代码：类型无缝对接

服务端生成完之后，前端需要的API调用代码同样可以生成：

npx t3code gen client --model Post

这条命令会在src/client/api.ts里追加关于Post的get、list、create、update、delete五个方法，同时在src/client/types.ts中追加Post类型和CreatePostInput、UpdatePostInput类型。最关键的在于，t3code会先读取服务端controller的返回类型声明，用来推导前端方法返回值的类型——它强制生成器去读服务端文件，而不是凭空生成前端类型。这意味着你改了模型的字段后，重新执行gen client，前端调用的返回值类型会自动跟着变。

实际开发中，我最常用的是改完模型定义后，连续跑两条命令：

npx t3code gen crud --model Post npx t3code gen client --model Post

然后全局跑一次tsc --noEmit，确认没有断链。整个过程基本在十秒以内完成。

4.4 生成逻辑的核心实现：解析、校验、合并三步法

t3code的生成核心并不复杂，但每一步都有讲究。它执行一轮生成时，内部按“解析->校验->合并”三个步骤进行。

解析阶段，读取所有模型定义文件，把defineModel里的字段和关系转换成一个中间数据结构。这个结构统一为ModelDefinition接口，内部包含fields数组、relations数组、indexes数组等。所有模板共享同一份数据，避免每类文件各自解析一遍导致不一致。

校验阶段，检查模型定义本身是否合法：主键是否存在、字段名是否重复、枚举的值是否为空、relation引用的目标模型是否已定义。这一步还会检查模板文件是否存在，模板语法是否有错。EJS语法错误往往很难排查，所以t3code会对模板做一次预渲染，把错误定位到具体行号。

合并阶段，对每个模板执行渲染，并把结果写入文件系统。这里有个值得注意的实现细节：t3code不会直接写最终产物，而是先写到一个临时目录，全部生成成功了再原子性替换到目标目录。如果中间任何一步失败，临时目录直接删除，目标目录保持原样。这个机制在大模块生成时尤其有价值，避免生成一半留下半成品。

5. 常见问题与排查技巧实录：实测中踩过的坑和对应解法

5.1 Node版本过低或过高导致的依赖安装失败

t3code使用了fs.cpSync和structuredClone这些较新的Node API。我在一台Node 16的老环境机器上安装时，npm install能过，但一执行t3code init就报“fs.cpSync is not a function”。这个问题极好排查，但新手容易懵，以为是包坏了。

解法优先级是：最优先换Node版本，建议直接上18.17或20+；临时方案是在执行命令前用npx -p node@20 node来强制指定Node版本。我在实际项目中已经统一把.nvmrc设为20，并写进了npm script里：

"scripts": { "gen:init": "npx t3code init", "gen:crud": "npx t3code gen crud --model ${npm_config_model}" }

5.2 模板修改后重新生成，报“Template render error: xxx is not defined”

这个问题经常出现在修改模板但忘了传入对应变量时。比如你在controller.ejs里加了一行<%= authGuard %>，但t3code默认传给controller模板的上下文里没有authGuard这个变量，EJS会毫不犹豫地报错。

排查思路：打开模板文件，确认引用的变量一定存在于渲染上下文里。我在实践中学到，最好的方式是在模板里加默认值兜底：<%= authGuard ?? 'true' %>，这样即使某个模型没传相关配置，生成也不会直接崩。另一个常见问题是EJS的include路径写错了，它默认相对当前模板文件解析。如果你把partials放在templates/partials，在主模板里引用时建议写绝对路径，比如include('/partials/field-list')，而不是include('../partials/field-list')，后者在当前模板在不同子目录时会突然失效。

5.3 快速筛选：重新生成代码时，发现自己写的业务代码被覆盖

这是我从使用经验里提炼出最重要的警告：默认情况下，只有*.base.*和*.gen.*不会被覆盖保护。如果你把一个手写的业务逻辑文件直接放在generated目录下，下次重新生成大概率被覆盖。

我的做法是这样的：建立一个明确共识，文件夹名写上后缀_handwritten的部分，绝对不允许模板写入；模板里的service.ejs只生成“骨架代码”，比如空的list()方法和一个带着TODO的customLogic()方法，业务细节全部放在service.handwritten.ts里由t3code的“合并机制”自动引入。这个合并机制是我后续加的：检测到存在service.handwritten.ts时，不会覆盖它，只会在service.ts里自动加上一行export * from './service.handwritten'。有了这个约定，我基本不再担心覆盖问题。

5.4 生成后tsc报错，发现关系字段类型对不上

关系字段是最容易出现类型不一致的部分。比如模型定义里写了authorId: string，但在relation里指定的foreignKey却是authorUuid，生成的类型里就同时存在authorId和authorUuid两个字段。这种错误在运行时很难发现，直到某个深夜别人接口报错你才开始排查字段名。

t3code本身会在生成时做一些基础校验——如果foreignKey在fields里不存在，会直接抛错。但如果你字段名叫authorId、关系外键也叫authorId，而实际数据库里存的是authorUuid，这种语义不一致工具是发现不了的。我的建议是在模型定义阶段就统一一个命名规范，统一采用“目标模型名小写 + Id”。团队里有这个约定之后，类型对不上的问题几乎消失了。

5.5 生成代码风格与团队eslint配置冲突

生成的代码不一定符合团队自定的eslint规则。比如t3code生成的代码默认使用单引号和分号，但有些团队配置了无分号风格，于是一生成的代码就满屏红波浪线。这个问题不致命，但很影响观感，也会导致CI里的eslint检查挂掉。

解决方案有两个：一是在生成后接一个eslint --fix命令，把生成器的输出归一化成团队风格；二是在模板文件里直接服从团队规范，改一次模板，以后生成结果都合规。我个人建议第二种——模板本身就是活文档，把团队的代码规范沉淀在模板里，比每天跑fix命令更干净。如果你选择了第一种，也别忘了在npm script里串联起来，比如：

"gen:all": "t3code gen crud --model ${npm_config_model} && eslint --fix generated/"

5.6 增量生成时的缓存问题：为什么改了模型定义但生成结果没变

t3code默认带了一个简单的增量缓存——它会对比模型文件的hash值和上次生成时的hash值，如果没变化就跳过生成。这个设计是为了大项目加速，但有一个坑：你改了模板文件，模型没动，t3code默认不会重新生成，导致你感觉“改了模板怎么不生效”。

解决方法是执行npx t3code gen --no-cache强制跳过缓存。我在写模板调试时基本每次都带--no-cache，确认模板效果之后再正常生成。这个细节如果你不知道，会白白浪费很多时间怀疑人生。

6. 模板开发实战：从零编写一个Controller模板需要注意什么

6.1 模板上下文到底有什么：别凭感觉猜字段

开发自己的模板时，最大的困惑往往是“我能用哪些变量”。t3code提供的模板上下文有以下几个核心对象：

如果模板里引用了不存在的变量，EJS在渲染时才报错，这时候排查比较被动。建议在写模板前先执行npx t3code debug --model User，它会打印出传给模板的完整JSON结构，省得靠猜。这个命令是我自己加上去的调试口子，实际使用价值极高。

6.2 一个Controller模板的写法示例

拿最简单的REST风格controller模板举例（templates/server/controller.ejs）：

import { Request, Response } from 'express'; import * as service from '../services/<%= model.name.toLowerCase() %>.service'; export async function list<%= model.name %>(req: Request, res: Response) { const result = await service.list<%= model.name %>(); res.json(result); } export async function get<%= model.name %>(req: Request, res: Response) { const { id } = req.params; const result = await service.get<%= model.name %>(id); res.json(result); } // ... create、update、delete 同理

这段模板里出现了很多<%= model.name %>插值。实现上就是把模型名拼进去，生成出来的文件在IDE里看起来和手写代码没有区别。真正上手体验后会发现，模板本身不应该包含复杂逻辑，一个字段转换、一个循环判断可以，但如果模板里出现三层嵌套条件，那说明模型定义应该多提供一些辅助信息，而不是在模板里做数据处理。

6.3 编写模板时的两个重要建议

第一个建议：模板里不要在文件头部写死注释“此文件由工具生成，请勿修改”。这话写出来虽然诚实，但团队成员不一定真的会在IDE打开这个文件时注意到。更好的做法是在文件顶部加一行@generated标记，配合eslint的--report-unused-disable-directives，某些工具会自动识别并跳过对这些文件的告警。t3code生成的默认文件都带这个标记。

第二个建议：模板文件不要追求“一次写完”。先写一个最小可用的模板，生成一次看效果，再迭代修改。EJS模板的调试反馈周期其实相对长，因为你要改模板、执行生成、跑tsc检查。所以我会把一个模板的迭代拆成几个小步骤，先保证文件能出来、结构正确，再逐步润色代码风格和注释。直接一口气写上百行模板，大概率第一次生成的产物是一堆报错，而且难以定位。

7. 关于“用生成器维护代码规范”这件事的一些体会

7.1 生成器不是银弹，但能消掉一大类低级错误

用了t3code几个月后，我最大的感受是：它不能替你设计业务架构，但能消掉一大类“低级但致命”的错误。比如字段改了个名字，手写代码时你改了service忘了改controller，或者前端类型和后端不一致——这些问题在生成器模式下从机制上被消灭了。模板写好了，整个团队生成出来的代码风格完全一致，代码review的讨论重点终于可以聚焦在业务逻辑而不是命名风格、字段对齐、import顺序上。

7.2 模板本身是要维护的产品

很多人以为做了模板就一劳永逸，其实模板和普通业务代码一样需要持续迭代。你会在实际开发中发现某些命名规则不够好、某些校验逻辑不够稳、某些生成的代码在极端边界下不够友好——这些体验最终都会沉淀为模板的更新。我现在把t3code的模板目录当成一个独立的子项目来维护，有版本记录，有变更日志，也鼓励团队同事提交模板改进建议。

7.3 这类工具后续可以往哪扩展

就我目前的使用体验来说，t3code还可以做几个方向上的扩展：一是支持更多数据库ORM的模板适配（目前默认Prisma，但TypeORM用户也不少）；二是加强“从模型定义到前端表单”的生成链路，直接把表格、筛选、分页这类重复组件也生成出来；三是把模板上传到云端，形成团队共享的模板仓库，新成员加入时直接拉取一套团队标准的模板组合。这些都是顺着“定义一次，处处生成”的思路延伸出来的方向。

回到实践本身，我给自己的团队定了一条规矩：凡是结构相似、类型相关、容易因为复制粘贴出错的代码，一律走t3code生成；凡是业务特殊、逻辑复杂的代码，一律保留人工书写并通过标记文件隔离。这条规矩执行下来，新项目的启动时间从原来的一天压缩到了一个小时以内，日常模块开发的时间也省了至少三分之一。如果你正在为项目里大量的样板代码和类型不同步烦恼，可以试着把“模板化生成”这套思路做成自己的小工具，哪怕只是一个本地脚本，带来的收益也会超出预期。