t3code 三段式代码生成体系：从设计到落地的工程实践

1. 从“t3code”这个名字说起：它到底是什么

第一次看到“t3code”这个词，很多人会愣一下——它不像某个具体框架的名字，也不像某个库的缩写，更像是一个内部代号或者项目昵称。我最初接触到它，是在一个做低代码配置平台的朋友那里，他提到团队内部有个叫 t3code 的小工具，用来把一堆零散的配置片段快速拼装成可运行的代码骨架。后来陆续在几个技术群里看到有人讨论，才发现这个词的覆盖面比我想的要宽：有人拿它指代一套轻量级的代码生成模板体系，有人用它命名自己的脚手架工具，还有人把它当成一种“三段式编码”方法论的简称。

不管具体指向哪一种，t3code 这个词本身透露出的信息很明确：它和代码的组织、生成、转换有关，而且带有一个“t3”的前缀，暗示着某种三段式、三层或者三阶的结构。这个前缀不是随便起的，在工程实践中，“三”往往对应着输入、处理、输出，或者定义、编排、执行这样的经典分层。所以我在拆解这个标题的时候，第一件事就是把它还原成一个可操作的问题：如果我要从零搭一套叫 t3code 的东西，它应该解决什么痛点，由哪些模块组成，每一步该怎么落地。

这篇文章面向的是那些手里有一堆重复代码、想用模板化手段提效的开发者，也适合正在设计内部脚手架、代码生成器的技术负责人。我会把 t3code 当作一个“代码生成与编排体系”来展开，从设计思路讲到核心实现，再到实际跑起来会遇到的坑。你不需要事先了解任何特定框架，只要写过代码、被重复劳动折磨过，就能看懂并且直接抄作业。

提示：本文里的 t3code 是一个通用化的项目代号，我会基于常见的代码生成实践来补全细节。如果你手头的 t3code 有特定含义，可以把对应的部分替换成你自己的场景，方法论是相通的。

2. 整体设计思路：为什么是“三段式”而不是一把梭

2.1 核心痛点：重复代码的三种形态

在动手设计 t3code 之前，我先梳理了一下日常开发中重复劳动到底出现在哪里。粗略分下来，无非三种情况。

第一种是结构重复。比如每新建一个 API 接口，都要写 controller、service、dao 三层，每层的文件名、类名、方法签名都有固定套路，只是实体名不同。这种重复最机械，也最适合用模板一次性生成。

第二种是逻辑重复。比如分页查询、条件过滤、异常包装、日志埋点，这些逻辑在每个接口里都长得差不多，但又不是完全一样，需要根据参数做微调。这种重复用纯模板不好处理，得靠“模板加钩子”的方式，在固定骨架上留出可编程的插槽。

第三种是配置重复。比如数据库连接、缓存策略、限流阈值，这些配置散落在各个文件里，改一处要同步好几处。这种重复需要的是“单一数据源加派生”，从一个中心配置派生出各处的配置片段。

t3code 的“三段式”设计，正好对应这三种重复：第一段负责结构生成，第二段负责逻辑编排，第三段负责配置派生。三段各司其职，又通过统一的元数据串联起来。这个划分不是拍脑袋定的，而是因为这三类重复的解决手段差异很大——结构生成靠模板引擎，逻辑编排靠 AST 操作或者代码拼接，配置派生靠数据转换。把它们混在一起做，最后会变成一个四不像的怪物。

2.2 方案选型：模板引擎、AST 与字符串拼接的取舍

确定了三段式之后，每一段用什么技术来实现，是第二个要拍板的问题。我试过三种主流方案，各有各的脾气。

纯字符串拼接是最容易上手的，拿一个字符串数组，按顺序 push 进去，最后 join 一下完事。它的优点是零依赖、调试直观，缺点是缩进和换行极难控制，生成出来的代码格式惨不忍睹，而且一旦模板里有条件分支，字符串就会变成一堆 if-else 嵌套的地狱。我早期做过一个用字符串拼接的生成器，维护了三个月就放弃了，因为改一个缩进规则要动十几个地方。

模板引擎（比如 Mustache、Handlebars、Jinja 这类思路）解决了格式和分支的问题，模板文件本身可读性很好，非开发人员也能看懂。但它的短板在于“逻辑表达力有限”，遇到需要根据已有代码结构做判断的场景，模板里写不了复杂逻辑，只能把大量计算前置到数据准备阶段，导致数据准备层越来越臃肿。

AST 操作是最强大的，直接操作语法树，生成出来的代码保证语法正确，还能做语义级别的变换。但它的门槛也最高，不同语言的 AST 结构差异很大，写一个通用的 AST 生成器几乎等于重新发明一门语言。而且 AST 操作调试起来很痛苦，一个节点类型搞错，报错信息往往指向莫名其妙的位置。

t3code 最终采用的是混合策略：结构生成用模板引擎，因为这部分格式要求高、逻辑简单；逻辑编排用“模板加占位符加后处理”的方式，先用模板生成骨架，再用轻量的文本替换和插入完成逻辑填充；配置派生用纯数据转换，不涉及代码生成。这个组合的好处是，每一段都用它最擅长的工具，避免了一把梭带来的复杂度爆炸。

2.3 元数据设计：三段之间的“通用语言”

三段式要跑通，中间必须有一层统一的元数据来描述“要生成什么”。这层元数据的设计质量，直接决定了 t3code 好不好用。我的经验是，元数据要满足三个条件：人类可读、机器可解析、可增量修改。

人类可读意味着它最好是 YAML 或者 TOML 这种格式，而不是二进制或者过度嵌套的 JSON。机器可解析意味着字段名要稳定，不能今天叫entityName明天叫modelName。可增量修改意味着当我要给已有模块加一个字段时，不需要重写整个元数据文件，只需要在对应位置追加一行。

我最终定的元数据结构大致是这样的：顶层分structure、logic、config三个块，分别对应三段。structure里描述实体名、字段列表、层级关系；logic里描述需要注入的逻辑片段标识和参数；config里描述这个模块需要哪些配置项、默认值是什么、从哪个中心配置派生。这个结构看起来简单，但实际用起来发现，百分之八十的生成需求都能覆盖，剩下的百分之二十通过扩展字段解决。

注意：元数据里千万不要放“生成后的代码长什么样”这种信息，那是模板的职责。元数据只描述“要什么”，不描述“怎么呈现”。这个边界一旦模糊，元数据就会变成另一种形式的代码，失去抽象价值。

3. 核心细节解析：三段各自的关键实现

3.1 第一段：结构生成里的模板组织技巧

结构生成这部分，表面上看就是“拿模板渲染一下”，但实际做下来，模板怎么组织有很多讲究。我踩过的最大一个坑，是把所有模板放在一个大文件里，用条件判断来区分不同场景。结果模板文件膨胀到两千多行，改一个地方要上下翻半天，而且条件嵌套太深，渲染出来的结果经常多一个空行或者少一个逗号。

后来我改成按“层”拆模板，按“片段”组合。比如一个典型的后端模块，分成 controller 层、service 层、dao 层、model 层四个模板文件，每个文件只负责自己这一层的骨架。然后在元数据里声明这个模块需要哪几层，生成器按需加载对应的模板。这样做的好处是，每层模板可以独立修改和测试，新增一层只需要加一个模板文件，不用动已有的。

模板内部的写法也有技巧。我习惯把可变部分全部用命名占位符标出来，比如{{entityName}}、{{fieldList}}，而不是用位置参数。命名占位符的好处是，即使模板结构调整了，只要占位符名字不变，元数据就不用改。另外，对于列表类型的字段（比如一个实体有多个属性），我会在模板里用循环语法展开，而不是在数据准备阶段拼成一个长字符串。这样模板的可读性更好，调试时也能一眼看出循环边界在哪里。

还有一个细节是空行和缩进的控制。模板引擎通常会把占位符替换后的换行也带进去，导致生成出来的代码里出现连续空行。我的做法是在模板里用特殊的注释标记来控制换行，比如{{!trim}}表示这一行渲染后如果为空则删除。不同模板引擎的语法不一样，但思路是通用的：把格式控制的逻辑放在模板层，不要留给后处理。后处理做格式清理，规则一多就会互相打架。

3.2 第二段：逻辑编排的“插槽加钩子”模式

逻辑编排是 t3code 里最考验设计功力的部分。结构生成出来的代码只是空壳，真正让代码跑起来的是里面的业务逻辑。但业务逻辑千变万化，不可能全部预置在模板里。我的解法是在模板里预留“插槽”，在元数据里声明“钩子”。

插槽是模板里的一段特殊标记，比如// @slot:validation，表示这个位置将来会被替换成一段校验逻辑。钩子是元数据里的一段描述，比如hook: validation, params: {required: true, maxLength: 50}，表示在这个插槽处注入一个校验钩子，参数是必填和最大长度五十。生成器在渲染完模板后，会扫描所有插槽，根据元数据里的钩子声明，从钩子库里找到对应的代码片段，替换进去。

钩子库是一组预写好的代码片段，每个片段对应一种常见逻辑。比如validation钩子对应一段参数校验代码，pagination钩子对应一段分页查询代码，logging钩子对应一段日志埋点代码。钩子库可以随着项目积累不断扩充，新项目直接复用。这个模式的好处是，常见逻辑开箱即用，特殊逻辑可以自定义钩子，既保证了效率，又保留了灵活性。

我实测下来，一个中等复杂度的 CRUD 接口，用插槽加钩子的方式，从元数据到可运行代码只需要不到一分钟，而且生成的代码风格统一，review 起来很轻松。相比之下，手写同样的接口至少要十五分钟，还容易漏掉校验或者日志。

提示：钩子库的代码片段一定要带单元测试。因为钩子是被注入到不同上下文里的，一个钩子在小范围测试通过，不代表在所有插槽位置都能正常工作。我吃过这个亏，一个分页钩子在某个特定模板里生成的变量名和模板已有变量冲突，导致编译报错，排查了半天。

3.3 第三段：配置派生的“单一数据源”原则

配置派生这段，核心原则只有一条：所有配置只有一个权威来源，其他地方的配置都是派生出来的。比如数据库连接信息，只在中心配置里写一次，各个模块的配置文件通过生成器从中心配置派生。这样改数据库地址时，只需要改一处，重新生成一遍，所有模块的配置同步更新。

实现上，我用的是一个简单的“配置模板加数据绑定”机制。中心配置是一个 YAML 文件，里面按环境（开发、测试、生产）分块。每个模块的配置模板里用占位符引用中心配置的字段，比如{{db.host}}、{{db.port}}。生成器读取中心配置和模块配置模板，渲染出该模块最终的配置文件。

这里有个容易忽略的点是敏感信息的处理。中心配置里如果直接写密码，生成出来的配置文件里也会带密码，万一提交到代码仓库就麻烦了。我的做法是，中心配置里敏感字段只写占位符，比如{{secret:db_password}}，生成器在渲染时从环境变量或者密钥管理服务里取值。这样配置文件里永远不会出现明文密码，安全性有保障。

另外，配置派生要支持覆盖机制。有些模块可能需要特殊的配置值，不能完全从中心配置派生。我的做法是在模块元数据里加一个configOverride块，里面的字段优先级高于中心配置。这样既保持了单一数据源的原则，又给了模块级别的灵活性。

4. 实操过程：从零跑通一个 t3code 生成流程

4.1 环境准备与目录结构

要跑通 t3code，先得把目录结构定下来。我用的结构是这样的：

t3code/ ├── metadata/ # 元数据目录 │ ├── modules/ # 各模块的元数据文件 │ └── center.yaml # 中心配置 ├── templates/ # 模板目录 │ ├── structure/ # 结构模板 │ ├── hooks/ # 钩子库 │ └── config/ # 配置模板 ├── generator/ # 生成器代码 │ ├── index.js # 入口 │ ├── structure.js # 第一段：结构生成 │ ├── logic.js # 第二段：逻辑编排 │ └── config.js # 第三段：配置派生 └── output/ # 生成结果输出目录

这个结构的关键是元数据、模板、生成器代码三者分离。元数据描述要什么，模板描述长什么样，生成器代码描述怎么拼。三者独立修改，互不影响。我见过有人把模板直接写在生成器代码里，结果改一个模板要重新编译生成器，效率极低。

生成器本身用什么语言写都行，我用的是 Node.js，因为模板引擎生态成熟，而且和前端项目容易集成。如果你团队主要用 Java，用 Java 写生成器也完全没问题，思路是一样的。

4.2 编写第一个元数据文件

假设我要生成一个用户管理模块，元数据文件metadata/modules/user.yaml大概长这样：

name: user structure: entity: User fields: - name: id type: Long comment: 用户ID - name: username type: String comment: 用户名 - name: email type: String comment: 邮箱 layers: - controller - service - dao - model logic: hooks: - slot: validation hook: requiredFields params: fields: [username, email] - slot: pagination hook: standardPagination config: override: cache.ttl: 300

这个文件描述了一个用户模块：实体叫 User，有三个字段，需要生成四层代码，校验插槽注入必填校验，分页插槽注入标准分页，缓存过期时间覆盖为三百秒。写起来很直观，非开发人员也能看懂大概意思。

4.3 结构模板的编写与调试

以 controller 层模板为例，templates/structure/controller.tpl大概是这样：

package {{package}}.controller; import {{package}}.service.{{entity}}Service; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/{{entityLower}}") public class {{entity}}Controller { private final {{entity}}Service {{entityLower}}Service; public {{entity}}Controller({{entity}}Service {{entityLower}}Service) { this.{{entityLower}}Service = {{entityLower}}Service; } @GetMapping("/{id}") public Object getById(@PathVariable Long id) { // @slot:validation return {{entityLower}}Service.getById(id); } @GetMapping("/page") public Object page(@RequestParam int page, @RequestParam int size) { // @slot:pagination return {{entityLower}}Service.page(page, size); } }

模板里的{{package}}、{{entity}}、{{entityLower}}都是占位符，渲染时会被元数据里的值替换。// @slot:validation和// @slot:pagination是插槽标记，第二段逻辑编排会在这里注入钩子代码。

调试模板时，我习惯先用一个最小的元数据文件跑一遍，看渲染结果是否符合预期。如果格式有问题，先改模板；如果内容不对，先查元数据。不要同时改模板和元数据，否则出了问题不知道是哪边的锅。

4.4 钩子注入的完整流程

钩子注入分三步。第一步，生成器扫描模板，找出所有插槽标记，记录插槽名称和位置。第二步，读取元数据里的钩子声明，按插槽名称匹配。第三步，从钩子库加载对应的代码片段，用参数渲染后替换插槽标记。

以requiredFields钩子为例，钩子库里的片段templates/hooks/requiredFields.tpl是这样：

if ({{#each fields}}{{this}} == null{{#unless @last}} || {{/unless}}{{/each}}) { throw new IllegalArgumentException("必填字段不能为空"); }

渲染时，fields参数是[username, email]，生成出来的代码是：

if (username == null || email == null) { throw new IllegalArgumentException("必填字段不能为空"); }

这段代码会被插入到 controller 模板的// @slot:validation位置。整个过程是自动的，元数据里声明了要什么钩子，生成器就去找对应的片段注入。

注意：钩子片段的参数命名要和元数据里的参数命名严格一致。我遇到过元数据里写fieldList，钩子片段里写fields，结果渲染出来是空的，排查了半天才发现是名字对不上。建议在生成器里加一个参数校验，发现钩子声明的参数和片段需要的参数不匹配时直接报错，不要静默失败。

4.5 配置派生的参数计算

配置派生这部分，参数计算主要体现在“派生规则”上。比如中心配置里数据库连接池大小是maxPoolSize: 20，某个模块的配置模板里写的是{{db.maxPoolSize}}，那生成出来就是 20。但如果模块元数据里覆盖了db.maxPoolSize: 10，那生成出来就是 10。

这里有个计算细节：覆盖值的类型要和原值一致。如果中心配置里是数字 20，覆盖值写成了字符串 "10"，生成出来的配置文件里就会出现类型不一致的问题。我的做法是在生成器里做一次类型检查，发现类型不匹配时给出警告，并尝试自动转换。自动转换失败的，直接报错终止生成。

另外，配置派生要支持条件派生。比如某个配置项只在生产环境生效，开发环境用默认值。我的做法是在配置模板里用条件语法：

{{#if isProd}} timeout: 3000 {{else}} timeout: 30000 {{/if}}

isProd这个变量从中心配置的环境标识派生。这样一套模板可以适配多个环境，不用为每个环境单独维护一份配置。

5. 常见问题与排查技巧实录

5.1 生成代码格式错乱的排查思路

格式错乱是最高频的问题，表现五花八门：多空行、少空行、缩进不一致、括号不匹配。排查时我按这个顺序走：

先看模板本身。把模板文件单独渲染一遍，不注入任何钩子，看输出是否正常。如果模板本身就有格式问题，那和钩子无关，改模板就行。

再看钩子注入。如果模板正常，注入钩子后格式乱了，那问题出在钩子片段上。检查钩子片段的缩进是否和插槽位置的缩进一致。比如插槽在方法体内部，缩进是八个空格，钩子片段如果从行首开始写，注入后就会顶格，破坏格式。我的做法是钩子片段不写行首缩进，由生成器根据插槽位置自动补齐。

最后看后处理。如果模板和钩子都正常，但最终输出还是有问题，那可能是后处理规则互相冲突。比如一个规则删空行，另一个规则加空行，两个规则同时生效就会打架。这时候要检查后处理规则的执行顺序，确保删除类规则在添加类规则之后执行。

5.2 元数据与模板不匹配的典型表现

元数据和模板不匹配，通常不会直接报错，而是生成出“看起来对但实际不对”的代码。典型表现有三种。

第一种是占位符未替换。生成出来的代码里还留着{{entityName}}这样的字样。这通常是因为元数据里字段名写错了，或者模板里占位符拼写错了。排查方法是把元数据和模板里的占位符列出来对比，找出不一致的那个。

第二种是循环渲染结果为空。比如字段列表明明有值，但生成出来的代码里字段部分什么都没有。这通常是因为元数据里字段列表的路径写错了，生成器取不到值，循环体执行了零次。排查时在生成器里加日志，打印出循环前的数据，看是不是空数组。

第三种是条件分支走错。比如本该走生产环境分支，结果走了开发环境分支。这通常是环境标识的取值逻辑有问题，或者元数据里覆盖了环境标识。排查时打印出条件判断的实际值，和预期对比。

5.3 钩子冲突与优先级处理

当多个钩子注入到同一个插槽，或者钩子代码和模板已有代码冲突时，需要一套优先级机制。我的做法是给每个钩子声明一个priority字段，数字越小优先级越高。生成器按优先级排序后依次注入，高优先级的钩子先执行。

如果两个钩子优先级相同，按元数据里声明的顺序注入。如果钩子代码和模板已有代码冲突（比如变量名重复），生成器会检测到并报错，提示手动解决冲突。我一般不推荐自动重命名变量，因为自动重命名可能引入难以察觉的语义错误，手动解决虽然麻烦一点，但更可靠。

提示：钩子冲突最好在开发阶段就暴露出来，不要等到生成时才报错。我的做法是写一个“钩子兼容性检查”脚本，在 CI 里跑，提前发现潜在冲突。这个脚本会模拟所有钩子的注入，检查是否有变量名重复、方法签名冲突等问题。

5.4 生成结果与手写代码的合并策略

实际项目中，生成出来的代码往往需要和手写代码合并。比如生成器生成了一个 service 类，但开发者手动在里面加了一个自定义方法。下次重新生成时，如果直接覆盖，手写的方法就丢了。

我的策略是生成区与手写区分离。在模板里用注释标记出生成区的开始和结束，比如// @generated-start和// @generated-end。重新生成时，只替换生成区的内容，手写区原样保留。这个策略要求开发者在手写代码时严格遵守区域约定，不要往生成区里塞手写逻辑。

另一个策略是生成到独立文件，通过继承或者组合与手写代码关联。比如生成一个UserServiceBase类，手写一个UserService类继承它。重新生成时只覆盖UserServiceBase，UserService不受影响。这个策略更干净，但要求代码结构支持继承或者组合，不是所有场景都适用。

6. 工具选型与扩展思路

6.1 模板引擎的对比与选择

虽然 t3code 的思路是语言无关的，但模板引擎的选择会影响开发体验。我对比过几种常见的模板引擎思路，列个表供参考。

我的建议是，结构生成用 Mustache 或 Handlebars 风格，逻辑编排用 Jinja 风格或者自定义的插槽机制，配置派生用纯数据转换。不要试图用一个引擎解决所有问题，那样只会让模板变得难以维护。

6.2 从单模块到多模块的扩展

单模块跑通之后，扩展到多模块是自然的下一步。扩展时要注意两点。

第一点是模块间的依赖关系。比如订单模块依赖用户模块，生成订单模块时可能需要引用用户模块的实体类。我的做法是在元数据里声明dependencies字段，生成器根据依赖关系决定生成顺序，并在模板里自动导入依赖模块的包路径。

第二点是公共模板的抽取。多个模块的 controller 模板可能百分之九十是一样的，只有实体名不同。这时候可以把公共部分抽成一个基础模板，各模块模板继承基础模板，只覆盖差异部分。这样改一处公共逻辑，所有模块同步生效。

6.3 与 CI/CD 流程的集成

t3code 生成器最好集成到 CI/CD 流程里，每次元数据变更时自动重新生成代码，并跑一遍编译和测试。这样能保证生成结果始终和元数据一致，避免手动生成遗漏。

集成方式很简单，在 CI 配置里加一个步骤，调用生成器命令，然后执行编译。如果编译失败，说明生成结果有问题，CI 直接失败，阻止合并。这个机制能拦住百分之九十的生成错误，非常值得做。

注意：CI 里生成代码时，要确保生成器的版本和本地一致。我遇到过本地生成正常、CI 生成失败的情况，最后发现是 CI 用的生成器版本旧了，不支持新的元数据字段。解决办法是在项目里锁定生成器版本，CI 和本地用同一个版本。

7. 我踩过的坑与实操心得

第一个坑是过度设计元数据。刚开始做 t3code 时，我想把元数据设计得无比灵活，支持各种嵌套和条件。结果元数据文件变得比生成的代码还复杂，写元数据的时间比手写代码还长。后来我砍掉了百分之七十的字段，只保留最核心的实体名、字段列表、层级、钩子声明，效率立刻上来了。元数据的设计目标是“够用就好”，不是“无所不能”。

第二个坑是钩子库缺乏版本管理。钩子库里的代码片段会随着项目演进不断修改，但已经生成的项目可能依赖旧版本的钩子。如果直接改钩子库，重新生成旧项目时行为会变。我的解决办法是给钩子库打版本标签，元数据里声明依赖的钩子版本，生成器按版本加载对应的钩子片段。这样旧项目重新生成时，用的还是旧版本钩子，行为一致。

第三个坑是忽略生成代码的可读性。一开始我只关注生成结果能不能编译，忽略了代码格式和注释。结果生成出来的代码虽然能跑，但 review 时没人愿意看，因为格式混乱、没有注释。后来我在模板里加了统一的格式规则和注释占位符，生成出来的代码和手写的几乎没区别，review 效率大幅提升。生成代码也是给人看的，可读性和可编译性同样重要。

第四个坑是没有做生成结果的 diff 检查。重新生成代码后，如果不做 diff，很容易覆盖掉手写的改动。我的做法是在生成器里加一个--dry-run模式，只输出 diff 不实际写入，人工确认后再正式生成。这个模式救过我好几次，避免了一次误覆盖。

最后分享一个小技巧：给生成器加一个“生成报告”功能。每次生成后，输出一份报告，列出生成了哪些文件、注入了哪些钩子、覆盖了哪些配置。这份报告在排查问题时非常有用，能快速定位是哪个环节出的问题。报告格式用 Markdown 就行，简单直观。

这个内容后续还可以这样扩展：把生成器做成一个 Web 服务，元数据通过界面填写，模板在线编辑，生成结果直接下载。这样非开发人员也能参与代码生成，进一步降低门槛。不过这是另一个话题了，等有机会再展开聊。