前一阵在团队内部搭微服务的时候被一堆重复的 DTO、Mapper、校验规则搞得烦不胜烦。后来我抽空整理了一套内部小工具代号就叫 t3code。用了一段时间之后团队里好几个同事都过来问能不能开源、能不能给他们也装一份。所以今天这篇文章想从一个真实的开发者视角把这个工具的设计思路、核心细节、实操过程以及我踩过的坑完整地拆开讲一讲。t3code 不是一个大而全的低代码平台也不是什么商业级脚手架生成器。它本质上是一个面向“有明确规范、可重复生成”的开发场景的代码生成框架名字里的 t3 有我自己定义的含义Template模板、Transform变换、Target目标产物。它把“代码生成”这件事拆成三层让团队可以把自己的编码规范固化成模板把数据库表结构、接口定义甚至需求描述作为输入一键生成可维护、可二次修改的工程代码。如果你也在维护一套内部后台系统、微服务框架或者经常被重复的样板代码拖慢节奏这篇文章值得读完。1. 内容整体设计与思路拆解1.1 为什么我会做 t3code而不是直接用市面上的生成器先说背景。我们团队当时的痛点非常具体微服务拆分之后每个服务都有几乎一样的 CRUD 逻辑、分页查询、统一返回体、参数校验。按传统写法每开一个新服务光把这些样板代码敲完就要一两天。后来我们也找过现成的代码生成器但用下来总有几个问题第一很多生成器是“重框架绑定”的。它默认你的项目结构、持久层方案、异常处理方式都是它预设的那一套遇到自定义场景反而束手束脚。第二生成出来的代码往往是一次性“死代码”生成完就断开了联系——数据库加了个字段生成器不会增量更新只能整文件重新生成结果把人工改动全覆盖了。第三它们大多只解决“从数据库表到 Java 代码”这一条链路但实际开发中还有大量场景是“从接口定义到 TypeScript 类型”“从需求文档到字段字典”这些非典型生成需求。所以我想要的是一个“框架级的生成工具”而不是“特定语言的脚手架”。t3code 的核心思路很简单把输入解析、模板渲染、代码输出这三件事彻底解耦。输入可以是数据库 Schema、JSON 配置、OpenAPI 文档甚至是一段 Markdown 格式的字段描述输出可以是 Java、TypeScript、SQL、HTML、Markdown 文档。中间只通过一层结构化的“中间模型”来传递数据。这个设计带来的直接好处是团队想支持一门新语言不需要改生成核心只需要写一套新模板想支持一种新输入源只需要写一个新的解析器。代价是开发门槛比写一次性脚本高但换来的是长期可维护性。1.2 核心架构Template、Transform、Target 三层模型t3code 的运行时架构可以拆成三个核心概念Template模板层所有输出文件的“形状”都由模板决定。模板不是简单的字符串拼接而是带类型感知的。比如在模板里引用一个field.type如果这个类型对应的语言映射不存在模板引擎会直接报错而不是生成一个错误代码。模板还支持“块继承”和“片段覆盖”类似后端模板的 layout 机制能让多个服务的代码结构保持一致但局部逻辑可以各自覆写。Transform变换层变换层负责把“任意输入”扭转为“统一中间模型”。中间模型定义了常见的代码结构概念包名、类名、字段、方法、注释、泛型约束、注解/装饰器。数据库解析器把表结构变成中间模型OpenAPI 解析器把接口定义也变成中间模型这样下游模板根本不需要知道输入源是什么。Target目标层目标层管理“输出”。你可以在配置里声明哪些模板对应哪些中间模型、生成到哪个目录、使用什么文件命名策略、生成之后要不要执行格式化命令比如gofmt或prettier。目标层还有一个很重要的职责是“增量痕迹管理”——它会在生成文件的头部写入一个指纹标记下次生成时通过指纹对比决定是跳过、覆盖还是提示冲突。这一点后文会详细展开因为它直接影响工具在团队中是否真的能被用起来。三层的划分听起来像教科书但实际写代码时它非常管用。我之前也尝试过把逻辑揉在一个大函数里快速实现最后都因为需求迭代而崩掉。分层之后每一层都可以单独测试和替换。这也是 t3code 能在团队里活下去的根本原因。1.3 对比t3code 与常见脚手架工具的差异维度传统脚手架如 Yeoman、Spring Initializr单表代码生成器t3code输入源交互式问答数据库表结构多源数据库、JSON、OpenAPI、Markdown输出语言固定预设单语言模板决定任意语言覆盖策略一次性生成全量覆盖指纹增量更新与项目生命周期初始化阶段使用每次改表手动跑可嵌入 CI随构建运行自定义门槛需要写生成器插件受限于配置项写模板即可论“开箱即用”传统的脚手架确实更省心因为它们在初始化阶段非常成熟。但 t3code 定位的不是初始化而是“长期演进中持续的代码规范化生成”。这是完全不同的使用场景。2. 核心细节解析与实操要点2.1 中间模型设计一切生成的基石中间模型我内部叫 T3Schema是整个工具最核心的数据结构。它的设计原则可以概括为“像 JSON 一样通用像类定义一样严格”。举个例子同样是“用户”这个实体数据库里是user表接口文档里是User对象在 T3Schema 里都会归一成同一套描述entity: User table: user fields: - name: id type: bigint primaryKey: true autoIncrement: true comment: 主键 - name: username type: varchar length: 64 nullable: false comment: 登录名 - name: password_hash type: varchar length: 128 nullable: false sensitive: true comment: 密码哈希禁止日志输出 - name: created_at type: datetime default: CURRENT_TIMESTAMP comment: 创建时间这份描述同时携带了数据库层面的属性表名、字段长度、默认值和业务语义敏感字段标记。模板层拿到这份描述后怎么用完全取决于目标语言。比如 Java 的模板会把password_hash映射成JsonIgnore字段而 TypeScript 的模板可能只生成类型定义而不生成运行时校验。在设计 T3Schema 时我踩过最大的坑是“过度设计”。初版我加了继承、泛型、多态、接口实现等大量抽象概念以为这样可以应对所有场景。结果团队里其他同事看到模型文档直接放弃使用。后来我砍掉一半概念只保留实体、字段、枚举、关系、方法这五个核心类型99% 的生成场景反而都覆盖了。生成工具的中间模型应该服务于“你团队真实存在的代码模式”而不是理论上的所有代码模式。2.2 模板语法与渲染引擎的取舍模板引擎我最终没有自己造轮子而是选用了 Go 的text/template为基础做了一层封装扩展。为什么选它理由有三个第一text/template的语法足够克制。它没有复杂到像 Ruby 的 ERB 那样可以写各种逻辑但又不至于像 Mustache 那样连个“不等于”判断都要绕弯子。团队里写模板的人用一两天就能上手这比功能强大但学习曲线陡峭的引擎要友好得多。第二它在渲染时对“缺字段”的行为是可控的。默认情况下text/template访问一个不存在的字段会报错这反而成了优点——生成时如果中间模型缺字段宁可失败也不要生成一个带着nil的残缺代码。这个特性对保证输出质量很重要。第三模板的热重载实现简单。开发模板时不需要重启进程保存后立即生效这对反复调整模板格式的体验非常关键。一个典型的模板片段长这样以生成 TypeScript 类型为例{{- /* 类型模板生成 TypeScript interface */ -}} export interface {{ .Entity.Name }} { {{- range .Entity.Fields }} {{ .Name }}: {{ typeMapper .Type }}; {{- end }} }其中typeMapper是模板引擎的扩展函数负责把数据库类型映射到 TypeScript 类型。这里有个小技巧映射函数是可以在模板里被覆写的。项目根目录如果放了一个overrides/typeMapper.tpl文件会自动覆盖内置的默认映射。这样不同团队、不同语言习惯都能各自适配而不需要 fork 工具本身。2.3 指纹增量更新机制避免“生成一次改一次废一次”这是 t3code 和大部分一次性生成器最大的区别。我用一个简单但实用的机制来解决“二次生成覆盖手工代码”的冲突问题。每次运行时t3code 会在文件的头部或尾部可配置写入一段隐藏标记// [t3code:generated 2025-01-12T00:00:00Z hash:8f6d2b1]下次再生成时工具会先读取目标文件的标记做三种判断如果标记不存在说明这是人工创建的文件绝不覆盖只在控制台提示“检测到非生成文件已跳过”。如果标记存在并且 hash 值没有变化说明上次生成后没人改过直接覆盖为最新内容。如果标记存在但 hash 值变化了说明生成后有人手工改过不直接覆盖而是生成一个.new后缀的文件并输出 diff 摘要让开发者决定是保留手工修改还是接受新生成结果。这个方法不复杂但非常实用。很多人写生成脚本时根本没意识到“增量保护”才是工具能被长期使用的关键。一开始没有这个机制的时候我自己的体验都是生成完代码手工调整格式下一次全量生成所有调整灰飞烟灭。两次之后就不想再用这个工具了。所以如果你打算做一个类似的工具请一定把“写入标记——判断标记——增量更新”这个机制作为基础功能来做而不是后续再补。2.4 典型使用场景拆解t3code 适合用的场景我按优先级排了个序高优先级数据库表结构变更后生成实体类、Mapper 接口、DTOOpenAPI 接口定义生成前端 TypeScript 类型和 API 封装新增微服务时生成统一的项目骨架。中优先级配置文件的批量生成比如不同环境的application.yml片段数据库初始化脚本和回滚脚本的成对生成枚举字典在前后端之间的同步生成。低优先级文档类输出比如根据实体生成 Markdown 数据字典。这个场景不是不能用只是 Markdown 人工维护的价值也不低生成出来的文档如果没有和其他系统联动很容易变成“一次性文档”。我个人不建议把 t3code 用于“需要高度定制算法逻辑”的代码生成。模板擅长的是“结构性重复”不是“创造性逻辑”。如果一个类的行为完全取决于业务条件那个方法体内最好留空或者只生成 TODO 注释让开发者去实现而不是试图通过模板穷举逻辑分支。3. 实操过程与核心环节实现3.1 安装与初始化t3code 是一个命令行工具安装方式很简单。我们用 Go 写的主体所以分发是一个二进制文件。官方提供了三种获取方式直接下载编译好的可执行文件、通过go install源码安装、通过 Homebrew 安装仅 macOS。我个人推荐第一种因为团队分发时不需要每台机器都有 Go 环境。安装完成后在项目根目录执行初始化命令t3code init --project my-service这一步会在当前目录生成一个t3code.yaml配置文件和一个templates/目录。初始的配置文件长这样project: my-service name: demo input: type: db dsn: root:passwordtcp(127.0.0.1:3306)/my_app schema: my_app outputDir: ./generated targets: - name: java-entity templates: templates/entity/*.tpl outPath: ./src/main/java/com/example/entity matcher: {{ .Entity.Name | pascalCase }}.java - name: ts-types templates: templates/ts-type/*.tpl outPath: ./web/src/types matcher: {{ .Entity.Name | camelCase }}.ts这一份配置同时声明了“从同一个数据库 schema 生成 Java 实体和 TypeScript 类型”。实际执行时两个 target 是并发执行的。这个特性在生成大项目时能明显节省时间。3.2 从零到一一个数据库表生成完整代码案例下面我用一个非常具体的例子展示从数据库表到最终代码的完整链路。假设我们的user表结构如下CREATE TABLE user ( id bigint(20) NOT NULL AUTO_INCREMENT, username varchar(64) NOT NULL, email varchar(128) DEFAULT NULL, password_hash varchar(128) NOT NULL, status tinyint(4) NOT NULL DEFAULT 1, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;配置文件中的input部分已经声明了数据源。运行t3code generate --only-tables user工具的解析器会读取表结构转成 T3Schema然后分发到两个 target。Java 实体生成的模板简化版package {{ $.Config.PackageName }}; import java.time.LocalDateTime; import javax.persistence.*; import com.fasterxml.jackson.annotation.JsonIgnore; Entity Table(name {{ .Entity.Table }}) public class {{ .Entity.Name | pascalCase }} { {{- range .Entity.Fields }} Column(name {{ .Name }}) {{- if .PrimaryKey }} Id GeneratedValue(strategy GenerationType.IDENTITY) {{- end }} {{- if .Sensitive }} JsonIgnore {{- end }} private {{ dbToJava .Type }} {{ .Name | camelCase }}; {{- end }} // getters and setters omitted for brevity }最终生成的 Java 代码的关键部分如下Entity Table(name user) public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) Column(name id) private Long id; Column(name username) private String username; Column(name email) private String email; JsonIgnore Column(name password_hash) private String passwordHash; Column(name status) private Integer status; Column(name created_at) private LocalDateTime createdAt; Column(name updated_at) private LocalDateTime updatedAt; }前端 TypeScript 的生成结果export interface User { id: number; username: string; email?: string; passwordHash: string; status: number; createdAt: string; updatedAt: string; }注意password_hash自动映射为passwordHash驼峰命名同时 Java 端被标记了JsonIgnore。这就是“中间模型 模板”的协作成果敏感字段标记只存在于 T3Schema 中Java 模板和 TS 模板各自按照自己的语言习惯来处理它。3.3 配置文件的进阶用法多输入源与条件生成实际项目中我们往往不只有数据库一种输入。比如前端类型可能来自 OpenAPI而后端实体来自数据库。t3code 支持在配置文件中声明多个输入源并在 target 上指定使用哪个输入源input: db: type: db dsn: root:passwordtcp(127.0.0.1:3306)/my_app openapi: type: openapi spec: ./docs/openapi.yaml targets: - name: java-entity templates: templates/entity/*.tpl input: db outPath: ./src/main/java/com/example/entity - name: ts-api-client templates: templates/ts-api/*.tpl input: openapi outPath: ./web/src/api配置项与配置项之间还有一层“条件标签”机制。比如某个字段带上了deprecated: true标记模板里可以用{{ if not .Field.Deprecated }}把它过滤掉确保不生成废弃字段的代码。这个机制配合Deprecated注解或者前端deprecatedJSDoc 一起用效果非常好。3.4 把 t3code 接入 CI让代码生成成为构建的一部分工具只有在“每次变更都自动执行”的状态下才能真正发挥价值。我建议把生成步骤嵌入 CI 流水线。一个典型的 GitHub Actions 片段- name: Generate code from DB schema run: | t3code generate --config ./t3code.yaml - name: Check for uncommitted changes run: | if [ -n $(git status --porcelain) ]; then echo Generated code is out of date. Please run t3code generate locally. exit 1 fi这里的关键是第二步生成之后检查 git 工作区是否干净。如果生成的代码和仓库里已提交的代码不一致CI 直接失败。这个策略逼着团队成员在本地跑一次生成或提交生成的代码。长期坚持下来生成的代码会永远保持最新并且不会有“手改生成文件导致下次生成冲突”的问题。3.5 编写自定义模板的最佳实践如果你打算为团队定制模板我有几条经验可以分享模板文件要有规范的外部契约。每套模板目录里放一个README或template.yaml声明这个模板期望哪些参数、依赖哪些扩展函数、输出文件命名规则是什么。团队协作时别人改模板前先看这个说明能减少大量沟通成本。善用“片段模板”。不要把一个大文件写成一个模板。比如 Java 实体类我会拆成header.tpl包声明和 import、class.tpl类主体、fields.tpl字段声明、methods.tplgetter/setter。通过组合的方式复用。这样如果某天团队决定加一个父类只需要改class.tpl一个文件。模板必须跑测试。t3code 提供了t3code test template子命令可以输入一份样例 T3Schema自动渲染所有模板并做快照对比。模板改了之后跑一遍测试能看到所有受影响的输出文件差异。我团队里的同事刚开始嫌麻烦不愿意写测试直到有一次改了一个字段命名规则导致几十个生成文件格式崩了才意识到模板测试不是可选项而是必选项。不要迷信“配置即代码”。有些工具鼓励把所有逻辑塞进配置文件但模板里偶尔也需要一点点逻辑分支。t3code 的做法是基础逻辑字段类型映射、命名转换写成内建函数复杂业务分支由模板控制。后者用起来相对自由但也最容易失控。所以我的经验是模板里的逻辑分支越少越好如果一段模板超过 30 行就应该考虑拆分子模板或把逻辑下沉到扩展函数里。4. 常见问题与排查技巧实录4.1 模板渲染后出现空字节或乱码这是我遇到的第一个坑。原因是text/template默认不会把{{- -}}的空白处理得完全符合预期尤其是 Windows 环境下的 CRLF 换行符。生成的代码在 Unix 和 Windows 下二进制内容不一致有时打开文件会看到\r字符。排查思路先在配置里开启debug.keepWhitespace: true然后对比生成文件原始字节。定位到发生乱码的模板位置后在模板相应位置显式去掉多余空白。解决办法也很干脆在生成流程的“目标层”统一加了一个“规范化”步骤所有生成文件都经过\n统一换行并且对特定语言Java、TS 等强制执行格式化命令。这样任何人、任何操作系统上运行 t3code产出的代码都是一样的。4.2 字段命名冲突user_name与username的映射争议团队里经常出现命名规范分歧。A 同事认为数据库里的user_name翻译成 Java 应该是userNameB 同事认为应该是username。t3code 内置了五种最常见的命名策略原样、驼峰、帕斯卡、蛇形、短横线但配置哪种往往会吵起来。我的处理方式是在中间模型里定义“显式覆盖”字段。只要 T3Schema 里有nameOverride字段模板就不再使用自动命名规则。这样做的好处是生成工具可以保持“默认自动映射”但遇到特殊字段时可以直接在输入源上手工指定最终名字避免为了一个特例改全局命名策略。4.3 增量更新时 hash 误判手改格式导致大量冲突有段时间我发现在本地跑t3code generate后总有十几条“检测到人工修改输出 .new 文件”的提示。原因是团队成员在 IDE 里开了自动格式化生成了代码后 IDE 把引号换成了统一风格导致 hash 变化。这不属于“人工逻辑修改”却触发了冲突保护。解决方法是把“指纹标记”放在文件尾部并且在对比时忽略纯格式差异——工具会在 hash 计算前先对文件做一次“格式归一化”剥离空白字符差异后才计算 hash。这样即使 IDE 把缩进从 2 空格换成 4 空格只要逻辑没变就不会被判定为冲突。4.4 配置了 DSN 但连不上数据库开发场景中团队成员本地数据库账号密码各不相同。最开始我在t3code.yaml里直接写死 DSN结果每个人都要改配置。后来改用环境变量注入input: type: db dsn: ${DB_DSN}并支持.env文件读取。这个改动表面上只是把硬编码换成了占位符但实际节省了大量配置管理成本。顺便说一句如果数据库表结构变动频繁建议把input里的schema字段指向一个只读账号避免生成代码时误触写权限。4.5 性能问题全量生成数千表时太慢我们的系统早期有接近三千张表。全量解析渲染初版花了将近一分钟。这个速度在做本地生成时还能接受但放在 CI 里就太慢了。性能优化做了三件事解析器部分加了“延迟加载”。不需要字段详情的场景比如只生成表清单不读取列信息。多 target 并发改为“按输入源分组串行组内并发”。同时访问同一个数据库连接的并发度太高反而会拖慢连接池。模板缓存。渲染前先比较模板文件的 mtime 和上一次编译的哈希没有变化就直接复用已编译模板跳过重新解析。优化之后同样的三千表全量生成压到了十秒以内。但说句实话日常开发根本用不到全量生成绝大多数时候只针对一两个表增量生成毫秒级完成。4.6 模板调试技巧一步步看清楚渲染在干什么很多人第一次写模板会直接对着报错信息一脸茫然。我给一个最简单的调试方法在模板里临时加上调试函数调用{{ dump .Entity }}这会以格式化 JSON 的形式打印当前的 T3Schema 数据。t3code 内建了dump扩展专门用于查看渲染上下文。另一招是使用--dry-run参数只输出文件路径而不真正写盘方便确认命名规则是否正确。模板书写complex 时建议总是先--dry-run验证一批文件再实际生成。5. 扩展玩法与更多适用场景工具沉淀到一定程度后你会发现它不仅能生成“代码”还能解决很多和结构化输出相关的问题。5.1 用 t3code 生成数据字典与同步文档团队里“数据字典文档过期”几乎是通病。我们用 t3code 写了一个docs/data-dictionary.md.tpl模板每次生成代码时自动更新数据字典# 数据字典 ## 用户表 user | 字段 | 类型 | 说明 | 是否主键 | 是否可空 | | --- | --- | --- | --- | --- | | id | bigint | 主键 | Y | N | | username | varchar(64) | 登录名 | N | N |虽然听起来有点“杀鸡用牛刀”但效果出奇地好。团队对文档的信任度大幅提升因为文档不再依赖某个人记不记得更新而是跟着代码一起自动保持最新。5.2 作为前后端类型契约的“同步枢纽”前后端联调时最容易出现“后端改了字段名但前端不知道”。我们利用 t3code 的 OpenAPI 输入源写了一套 TypeScript 类型和 API 函数的生成模板。每次后端修改 API跑一次生成前端仓库自动收到新的类型定义。后续配合 CI 检查前端类型永远与后端接口同步。这个用法不需要额外的跨团队管理成本却直接消除了一个非常大的协作痛点。5.3 私有化交付时生成差异化代码另一个很有意思的场景是私有化部署。不同客户的项目需求不一样有些要 MySQL有些要 PostgreSQL有些用本地文件存储有些用对象存储。以前我们做私有化交付靠 copy 代码、手工改配置后来发现用 t3code 的“条件标签”机制可以轻松做到一套模板、多套产出。配置里定好客户代号模板里按标签判断是否包含特殊逻辑生成时只需要替换一个配置文件即可。6. 写在最后可能有人会觉得做一个内部代码生成工具是不是在重复造轮子。我不这么认为。市面上的工具解决的是“通用问题的生成”而 t3code 解决的是“你家团队特定规范的生成”。它的核心价值不在于生成代码本身而在于把团队对“代码应该长什么样”的共识固化成了机器可执行的模板。写模板的过程本质上是在做团队规范的梳理和落地。我给的建议是如果你发现自己团队在重复编写同一类代码并且经常因为“格式不一致”“字段漏配”“文档过期”而苦恼不妨也尝试构建一个类似 t3code 的轻量框架。不必一上来就做成大型系统先从一个数据库表的实体类生成开始跑通了再逐步扩展输入源和模板。等到团队里所有人都在用并且依赖它时你会意识到这个工具真正的价值不是省下的那几天开发时间而是让整个团队的代码质量和协作效率悄悄上了一个大台阶。 
长河君 · 2026/10/29 7:03:32 · 阅读 1.2k t3code：一个支持增量更新的多语言代码生成框架实践
前一阵在团队内部搭微服务的时候被一堆重复的 DTO、Mapper、校验规则搞得烦不胜烦。后来我抽空整理了一套内部小工具代号就叫 t3code。用了一段时间之后团队里好几个同事都过来问能不能开源、能不能给他们也装一份。所以今天这篇文章想从一个真实的开发者视角把这个工具的设计思路、核心细节、实操过程以及我踩过的坑完整地拆开讲一讲。t3code 不是一个大而全的低代码平台也不是什么商业级脚手架生成器。它本质上是一个面向“有明确规范、可重复生成”的开发场景的代码生成框架名字里的 t3 有我自己定义的含义Template模板、Transform变换、Target目标产物。它把“代码生成”这件事拆成三层让团队可以把自己的编码规范固化成模板把数据库表结构、接口定义甚至需求描述作为输入一键生成可维护、可二次修改的工程代码。如果你也在维护一套内部后台系统、微服务框架或者经常被重复的样板代码拖慢节奏这篇文章值得读完。1. 内容整体设计与思路拆解1.1 为什么我会做 t3code而不是直接用市面上的生成器先说背景。我们团队当时的痛点非常具体微服务拆分之后每个服务都有几乎一样的 CRUD 逻辑、分页查询、统一返回体、参数校验。按传统写法每开一个新服务光把这些样板代码敲完就要一两天。后来我们也找过现成的代码生成器但用下来总有几个问题第一很多生成器是“重框架绑定”的。它默认你的项目结构、持久层方案、异常处理方式都是它预设的那一套遇到自定义场景反而束手束脚。第二生成出来的代码往往是一次性“死代码”生成完就断开了联系——数据库加了个字段生成器不会增量更新只能整文件重新生成结果把人工改动全覆盖了。第三它们大多只解决“从数据库表到 Java 代码”这一条链路但实际开发中还有大量场景是“从接口定义到 TypeScript 类型”“从需求文档到字段字典”这些非典型生成需求。所以我想要的是一个“框架级的生成工具”而不是“特定语言的脚手架”。t3code 的核心思路很简单把输入解析、模板渲染、代码输出这三件事彻底解耦。输入可以是数据库 Schema、JSON 配置、OpenAPI 文档甚至是一段 Markdown 格式的字段描述输出可以是 Java、TypeScript、SQL、HTML、Markdown 文档。中间只通过一层结构化的“中间模型”来传递数据。这个设计带来的直接好处是团队想支持一门新语言不需要改生成核心只需要写一套新模板想支持一种新输入源只需要写一个新的解析器。代价是开发门槛比写一次性脚本高但换来的是长期可维护性。1.2 核心架构Template、Transform、Target 三层模型t3code 的运行时架构可以拆成三个核心概念Template模板层所有输出文件的“形状”都由模板决定。模板不是简单的字符串拼接而是带类型感知的。比如在模板里引用一个field.type如果这个类型对应的语言映射不存在模板引擎会直接报错而不是生成一个错误代码。模板还支持“块继承”和“片段覆盖”类似后端模板的 layout 机制能让多个服务的代码结构保持一致但局部逻辑可以各自覆写。Transform变换层变换层负责把“任意输入”扭转为“统一中间模型”。中间模型定义了常见的代码结构概念包名、类名、字段、方法、注释、泛型约束、注解/装饰器。数据库解析器把表结构变成中间模型OpenAPI 解析器把接口定义也变成中间模型这样下游模板根本不需要知道输入源是什么。Target目标层目标层管理“输出”。你可以在配置里声明哪些模板对应哪些中间模型、生成到哪个目录、使用什么文件命名策略、生成之后要不要执行格式化命令比如gofmt或prettier。目标层还有一个很重要的职责是“增量痕迹管理”——它会在生成文件的头部写入一个指纹标记下次生成时通过指纹对比决定是跳过、覆盖还是提示冲突。这一点后文会详细展开因为它直接影响工具在团队中是否真的能被用起来。三层的划分听起来像教科书但实际写代码时它非常管用。我之前也尝试过把逻辑揉在一个大函数里快速实现最后都因为需求迭代而崩掉。分层之后每一层都可以单独测试和替换。这也是 t3code 能在团队里活下去的根本原因。1.3 对比t3code 与常见脚手架工具的差异维度传统脚手架如 Yeoman、Spring Initializr单表代码生成器t3code输入源交互式问答数据库表结构多源数据库、JSON、OpenAPI、Markdown输出语言固定预设单语言模板决定任意语言覆盖策略一次性生成全量覆盖指纹增量更新与项目生命周期初始化阶段使用每次改表手动跑可嵌入 CI随构建运行自定义门槛需要写生成器插件受限于配置项写模板即可论“开箱即用”传统的脚手架确实更省心因为它们在初始化阶段非常成熟。但 t3code 定位的不是初始化而是“长期演进中持续的代码规范化生成”。这是完全不同的使用场景。2. 核心细节解析与实操要点2.1 中间模型设计一切生成的基石中间模型我内部叫 T3Schema是整个工具最核心的数据结构。它的设计原则可以概括为“像 JSON 一样通用像类定义一样严格”。举个例子同样是“用户”这个实体数据库里是user表接口文档里是User对象在 T3Schema 里都会归一成同一套描述entity: User table: user fields: - name: id type: bigint primaryKey: true autoIncrement: true comment: 主键 - name: username type: varchar length: 64 nullable: false comment: 登录名 - name: password_hash type: varchar length: 128 nullable: false sensitive: true comment: 密码哈希禁止日志输出 - name: created_at type: datetime default: CURRENT_TIMESTAMP comment: 创建时间这份描述同时携带了数据库层面的属性表名、字段长度、默认值和业务语义敏感字段标记。模板层拿到这份描述后怎么用完全取决于目标语言。比如 Java 的模板会把password_hash映射成JsonIgnore字段而 TypeScript 的模板可能只生成类型定义而不生成运行时校验。在设计 T3Schema 时我踩过最大的坑是“过度设计”。初版我加了继承、泛型、多态、接口实现等大量抽象概念以为这样可以应对所有场景。结果团队里其他同事看到模型文档直接放弃使用。后来我砍掉一半概念只保留实体、字段、枚举、关系、方法这五个核心类型99% 的生成场景反而都覆盖了。生成工具的中间模型应该服务于“你团队真实存在的代码模式”而不是理论上的所有代码模式。2.2 模板语法与渲染引擎的取舍模板引擎我最终没有自己造轮子而是选用了 Go 的text/template为基础做了一层封装扩展。为什么选它理由有三个第一text/template的语法足够克制。它没有复杂到像 Ruby 的 ERB 那样可以写各种逻辑但又不至于像 Mustache 那样连个“不等于”判断都要绕弯子。团队里写模板的人用一两天就能上手这比功能强大但学习曲线陡峭的引擎要友好得多。第二它在渲染时对“缺字段”的行为是可控的。默认情况下text/template访问一个不存在的字段会报错这反而成了优点——生成时如果中间模型缺字段宁可失败也不要生成一个带着nil的残缺代码。这个特性对保证输出质量很重要。第三模板的热重载实现简单。开发模板时不需要重启进程保存后立即生效这对反复调整模板格式的体验非常关键。一个典型的模板片段长这样以生成 TypeScript 类型为例{{- /* 类型模板生成 TypeScript interface */ -}} export interface {{ .Entity.Name }} { {{- range .Entity.Fields }} {{ .Name }}: {{ typeMapper .Type }}; {{- end }} }其中typeMapper是模板引擎的扩展函数负责把数据库类型映射到 TypeScript 类型。这里有个小技巧映射函数是可以在模板里被覆写的。项目根目录如果放了一个overrides/typeMapper.tpl文件会自动覆盖内置的默认映射。这样不同团队、不同语言习惯都能各自适配而不需要 fork 工具本身。2.3 指纹增量更新机制避免“生成一次改一次废一次”这是 t3code 和大部分一次性生成器最大的区别。我用一个简单但实用的机制来解决“二次生成覆盖手工代码”的冲突问题。每次运行时t3code 会在文件的头部或尾部可配置写入一段隐藏标记// [t3code:generated 2025-01-12T00:00:00Z hash:8f6d2b1]下次再生成时工具会先读取目标文件的标记做三种判断如果标记不存在说明这是人工创建的文件绝不覆盖只在控制台提示“检测到非生成文件已跳过”。如果标记存在并且 hash 值没有变化说明上次生成后没人改过直接覆盖为最新内容。如果标记存在但 hash 值变化了说明生成后有人手工改过不直接覆盖而是生成一个.new后缀的文件并输出 diff 摘要让开发者决定是保留手工修改还是接受新生成结果。这个方法不复杂但非常实用。很多人写生成脚本时根本没意识到“增量保护”才是工具能被长期使用的关键。一开始没有这个机制的时候我自己的体验都是生成完代码手工调整格式下一次全量生成所有调整灰飞烟灭。两次之后就不想再用这个工具了。所以如果你打算做一个类似的工具请一定把“写入标记——判断标记——增量更新”这个机制作为基础功能来做而不是后续再补。2.4 典型使用场景拆解t3code 适合用的场景我按优先级排了个序高优先级数据库表结构变更后生成实体类、Mapper 接口、DTOOpenAPI 接口定义生成前端 TypeScript 类型和 API 封装新增微服务时生成统一的项目骨架。中优先级配置文件的批量生成比如不同环境的application.yml片段数据库初始化脚本和回滚脚本的成对生成枚举字典在前后端之间的同步生成。低优先级文档类输出比如根据实体生成 Markdown 数据字典。这个场景不是不能用只是 Markdown 人工维护的价值也不低生成出来的文档如果没有和其他系统联动很容易变成“一次性文档”。我个人不建议把 t3code 用于“需要高度定制算法逻辑”的代码生成。模板擅长的是“结构性重复”不是“创造性逻辑”。如果一个类的行为完全取决于业务条件那个方法体内最好留空或者只生成 TODO 注释让开发者去实现而不是试图通过模板穷举逻辑分支。3. 实操过程与核心环节实现3.1 安装与初始化t3code 是一个命令行工具安装方式很简单。我们用 Go 写的主体所以分发是一个二进制文件。官方提供了三种获取方式直接下载编译好的可执行文件、通过go install源码安装、通过 Homebrew 安装仅 macOS。我个人推荐第一种因为团队分发时不需要每台机器都有 Go 环境。安装完成后在项目根目录执行初始化命令t3code init --project my-service这一步会在当前目录生成一个t3code.yaml配置文件和一个templates/目录。初始的配置文件长这样project: my-service name: demo input: type: db dsn: root:passwordtcp(127.0.0.1:3306)/my_app schema: my_app outputDir: ./generated targets: - name: java-entity templates: templates/entity/*.tpl outPath: ./src/main/java/com/example/entity matcher: {{ .Entity.Name | pascalCase }}.java - name: ts-types templates: templates/ts-type/*.tpl outPath: ./web/src/types matcher: {{ .Entity.Name | camelCase }}.ts这一份配置同时声明了“从同一个数据库 schema 生成 Java 实体和 TypeScript 类型”。实际执行时两个 target 是并发执行的。这个特性在生成大项目时能明显节省时间。3.2 从零到一一个数据库表生成完整代码案例下面我用一个非常具体的例子展示从数据库表到最终代码的完整链路。假设我们的user表结构如下CREATE TABLE user ( id bigint(20) NOT NULL AUTO_INCREMENT, username varchar(64) NOT NULL, email varchar(128) DEFAULT NULL, password_hash varchar(128) NOT NULL, status tinyint(4) NOT NULL DEFAULT 1, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;配置文件中的input部分已经声明了数据源。运行t3code generate --only-tables user工具的解析器会读取表结构转成 T3Schema然后分发到两个 target。Java 实体生成的模板简化版package {{ $.Config.PackageName }}; import java.time.LocalDateTime; import javax.persistence.*; import com.fasterxml.jackson.annotation.JsonIgnore; Entity Table(name {{ .Entity.Table }}) public class {{ .Entity.Name | pascalCase }} { {{- range .Entity.Fields }} Column(name {{ .Name }}) {{- if .PrimaryKey }} Id GeneratedValue(strategy GenerationType.IDENTITY) {{- end }} {{- if .Sensitive }} JsonIgnore {{- end }} private {{ dbToJava .Type }} {{ .Name | camelCase }}; {{- end }} // getters and setters omitted for brevity }最终生成的 Java 代码的关键部分如下Entity Table(name user) public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) Column(name id) private Long id; Column(name username) private String username; Column(name email) private String email; JsonIgnore Column(name password_hash) private String passwordHash; Column(name status) private Integer status; Column(name created_at) private LocalDateTime createdAt; Column(name updated_at) private LocalDateTime updatedAt; }前端 TypeScript 的生成结果export interface User { id: number; username: string; email?: string; passwordHash: string; status: number; createdAt: string; updatedAt: string; }注意password_hash自动映射为passwordHash驼峰命名同时 Java 端被标记了JsonIgnore。这就是“中间模型 模板”的协作成果敏感字段标记只存在于 T3Schema 中Java 模板和 TS 模板各自按照自己的语言习惯来处理它。3.3 配置文件的进阶用法多输入源与条件生成实际项目中我们往往不只有数据库一种输入。比如前端类型可能来自 OpenAPI而后端实体来自数据库。t3code 支持在配置文件中声明多个输入源并在 target 上指定使用哪个输入源input: db: type: db dsn: root:passwordtcp(127.0.0.1:3306)/my_app openapi: type: openapi spec: ./docs/openapi.yaml targets: - name: java-entity templates: templates/entity/*.tpl input: db outPath: ./src/main/java/com/example/entity - name: ts-api-client templates: templates/ts-api/*.tpl input: openapi outPath: ./web/src/api配置项与配置项之间还有一层“条件标签”机制。比如某个字段带上了deprecated: true标记模板里可以用{{ if not .Field.Deprecated }}把它过滤掉确保不生成废弃字段的代码。这个机制配合Deprecated注解或者前端deprecatedJSDoc 一起用效果非常好。3.4 把 t3code 接入 CI让代码生成成为构建的一部分工具只有在“每次变更都自动执行”的状态下才能真正发挥价值。我建议把生成步骤嵌入 CI 流水线。一个典型的 GitHub Actions 片段- name: Generate code from DB schema run: | t3code generate --config ./t3code.yaml - name: Check for uncommitted changes run: | if [ -n $(git status --porcelain) ]; then echo Generated code is out of date. Please run t3code generate locally. exit 1 fi这里的关键是第二步生成之后检查 git 工作区是否干净。如果生成的代码和仓库里已提交的代码不一致CI 直接失败。这个策略逼着团队成员在本地跑一次生成或提交生成的代码。长期坚持下来生成的代码会永远保持最新并且不会有“手改生成文件导致下次生成冲突”的问题。3.5 编写自定义模板的最佳实践如果你打算为团队定制模板我有几条经验可以分享模板文件要有规范的外部契约。每套模板目录里放一个README或template.yaml声明这个模板期望哪些参数、依赖哪些扩展函数、输出文件命名规则是什么。团队协作时别人改模板前先看这个说明能减少大量沟通成本。善用“片段模板”。不要把一个大文件写成一个模板。比如 Java 实体类我会拆成header.tpl包声明和 import、class.tpl类主体、fields.tpl字段声明、methods.tplgetter/setter。通过组合的方式复用。这样如果某天团队决定加一个父类只需要改class.tpl一个文件。模板必须跑测试。t3code 提供了t3code test template子命令可以输入一份样例 T3Schema自动渲染所有模板并做快照对比。模板改了之后跑一遍测试能看到所有受影响的输出文件差异。我团队里的同事刚开始嫌麻烦不愿意写测试直到有一次改了一个字段命名规则导致几十个生成文件格式崩了才意识到模板测试不是可选项而是必选项。不要迷信“配置即代码”。有些工具鼓励把所有逻辑塞进配置文件但模板里偶尔也需要一点点逻辑分支。t3code 的做法是基础逻辑字段类型映射、命名转换写成内建函数复杂业务分支由模板控制。后者用起来相对自由但也最容易失控。所以我的经验是模板里的逻辑分支越少越好如果一段模板超过 30 行就应该考虑拆分子模板或把逻辑下沉到扩展函数里。4. 常见问题与排查技巧实录4.1 模板渲染后出现空字节或乱码这是我遇到的第一个坑。原因是text/template默认不会把{{- -}}的空白处理得完全符合预期尤其是 Windows 环境下的 CRLF 换行符。生成的代码在 Unix 和 Windows 下二进制内容不一致有时打开文件会看到\r字符。排查思路先在配置里开启debug.keepWhitespace: true然后对比生成文件原始字节。定位到发生乱码的模板位置后在模板相应位置显式去掉多余空白。解决办法也很干脆在生成流程的“目标层”统一加了一个“规范化”步骤所有生成文件都经过\n统一换行并且对特定语言Java、TS 等强制执行格式化命令。这样任何人、任何操作系统上运行 t3code产出的代码都是一样的。4.2 字段命名冲突user_name与username的映射争议团队里经常出现命名规范分歧。A 同事认为数据库里的user_name翻译成 Java 应该是userNameB 同事认为应该是username。t3code 内置了五种最常见的命名策略原样、驼峰、帕斯卡、蛇形、短横线但配置哪种往往会吵起来。我的处理方式是在中间模型里定义“显式覆盖”字段。只要 T3Schema 里有nameOverride字段模板就不再使用自动命名规则。这样做的好处是生成工具可以保持“默认自动映射”但遇到特殊字段时可以直接在输入源上手工指定最终名字避免为了一个特例改全局命名策略。4.3 增量更新时 hash 误判手改格式导致大量冲突有段时间我发现在本地跑t3code generate后总有十几条“检测到人工修改输出 .new 文件”的提示。原因是团队成员在 IDE 里开了自动格式化生成了代码后 IDE 把引号换成了统一风格导致 hash 变化。这不属于“人工逻辑修改”却触发了冲突保护。解决方法是把“指纹标记”放在文件尾部并且在对比时忽略纯格式差异——工具会在 hash 计算前先对文件做一次“格式归一化”剥离空白字符差异后才计算 hash。这样即使 IDE 把缩进从 2 空格换成 4 空格只要逻辑没变就不会被判定为冲突。4.4 配置了 DSN 但连不上数据库开发场景中团队成员本地数据库账号密码各不相同。最开始我在t3code.yaml里直接写死 DSN结果每个人都要改配置。后来改用环境变量注入input: type: db dsn: ${DB_DSN}并支持.env文件读取。这个改动表面上只是把硬编码换成了占位符但实际节省了大量配置管理成本。顺便说一句如果数据库表结构变动频繁建议把input里的schema字段指向一个只读账号避免生成代码时误触写权限。4.5 性能问题全量生成数千表时太慢我们的系统早期有接近三千张表。全量解析渲染初版花了将近一分钟。这个速度在做本地生成时还能接受但放在 CI 里就太慢了。性能优化做了三件事解析器部分加了“延迟加载”。不需要字段详情的场景比如只生成表清单不读取列信息。多 target 并发改为“按输入源分组串行组内并发”。同时访问同一个数据库连接的并发度太高反而会拖慢连接池。模板缓存。渲染前先比较模板文件的 mtime 和上一次编译的哈希没有变化就直接复用已编译模板跳过重新解析。优化之后同样的三千表全量生成压到了十秒以内。但说句实话日常开发根本用不到全量生成绝大多数时候只针对一两个表增量生成毫秒级完成。4.6 模板调试技巧一步步看清楚渲染在干什么很多人第一次写模板会直接对着报错信息一脸茫然。我给一个最简单的调试方法在模板里临时加上调试函数调用{{ dump .Entity }}这会以格式化 JSON 的形式打印当前的 T3Schema 数据。t3code 内建了dump扩展专门用于查看渲染上下文。另一招是使用--dry-run参数只输出文件路径而不真正写盘方便确认命名规则是否正确。模板书写complex 时建议总是先--dry-run验证一批文件再实际生成。5. 扩展玩法与更多适用场景工具沉淀到一定程度后你会发现它不仅能生成“代码”还能解决很多和结构化输出相关的问题。5.1 用 t3code 生成数据字典与同步文档团队里“数据字典文档过期”几乎是通病。我们用 t3code 写了一个docs/data-dictionary.md.tpl模板每次生成代码时自动更新数据字典# 数据字典 ## 用户表 user | 字段 | 类型 | 说明 | 是否主键 | 是否可空 | | --- | --- | --- | --- | --- | | id | bigint | 主键 | Y | N | | username | varchar(64) | 登录名 | N | N |虽然听起来有点“杀鸡用牛刀”但效果出奇地好。团队对文档的信任度大幅提升因为文档不再依赖某个人记不记得更新而是跟着代码一起自动保持最新。5.2 作为前后端类型契约的“同步枢纽”前后端联调时最容易出现“后端改了字段名但前端不知道”。我们利用 t3code 的 OpenAPI 输入源写了一套 TypeScript 类型和 API 函数的生成模板。每次后端修改 API跑一次生成前端仓库自动收到新的类型定义。后续配合 CI 检查前端类型永远与后端接口同步。这个用法不需要额外的跨团队管理成本却直接消除了一个非常大的协作痛点。5.3 私有化交付时生成差异化代码另一个很有意思的场景是私有化部署。不同客户的项目需求不一样有些要 MySQL有些要 PostgreSQL有些用本地文件存储有些用对象存储。以前我们做私有化交付靠 copy 代码、手工改配置后来发现用 t3code 的“条件标签”机制可以轻松做到一套模板、多套产出。配置里定好客户代号模板里按标签判断是否包含特殊逻辑生成时只需要替换一个配置文件即可。6. 写在最后可能有人会觉得做一个内部代码生成工具是不是在重复造轮子。我不这么认为。市面上的工具解决的是“通用问题的生成”而 t3code 解决的是“你家团队特定规范的生成”。它的核心价值不在于生成代码本身而在于把团队对“代码应该长什么样”的共识固化成了机器可执行的模板。写模板的过程本质上是在做团队规范的梳理和落地。我给的建议是如果你发现自己团队在重复编写同一类代码并且经常因为“格式不一致”“字段漏配”“文档过期”而苦恼不妨也尝试构建一个类似 t3code 的轻量框架。不必一上来就做成大型系统先从一个数据库表的实体类生成开始跑通了再逐步扩展输入源和模板。等到团队里所有人都在用并且依赖它时你会意识到这个工具真正的价值不是省下的那几天开发时间而是让整个团队的代码质量和协作效率悄悄上了一个大台阶。