t3code实战：模板+数据+规则实现高效代码生成

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

第一次看到“t3code”这个词，很多人会以为是某个新出的编程语言，或者某个大厂内部代号流出的框架。我最初也是这么想的，直到自己动手把玩了一段时间，才慢慢摸清它的脾气。简单来说，t3code 是一套围绕“轻量级代码生成与结构化输出”构建的实践方案，它不是一个具体的库，也不是某个单一工具，而是一种把“模板 + 数据 + 规则”三者捏合在一起的工作方式。你可以把它理解成一个“代码流水线”：你给它一份结构化的输入（比如一份配置、一张表、一段 JSON），它按照你预设的规则和模板，吐出可以直接使用的代码、文档或者配置文件。

它解决的问题其实很朴素——重复性代码的批量生产。做过中后台系统的人都有体会，一张表对应一套 CRUD，十个模块就是十套几乎一模一样的增删改查，手写不仅慢，还容易漏字段、写错类型。t3code 这类思路的核心价值，就是把这部分“机械劳动”交给规则去完成，人只负责定义“长什么样”和“怎么变”。它适合谁呢？后端开发、全栈工程师、做低代码平台的同学，以及任何需要频繁产出结构化文本的人。哪怕你只是偶尔要生成一批 SQL 或者接口定义，这套思路也能帮你省下大量复制粘贴的时间。

我之所以愿意花时间研究它，是因为在实际项目里，“生成”比“手写”在可维护性上高出一个量级。手写的代码改一处要全局搜，生成的代码改模板就能全量刷新。这个差别在模块数量上去之后会非常明显。接下来我会把这套东西拆开，从设计思路到落地细节，再到踩过的坑，完整地讲一遍。

2. 整体设计思路：为什么是“模板 + 数据 + 规则”这三件套

2.1 核心思路拆解：把“变化”和“不变”分开

任何代码生成方案，本质上都在回答一个问题：哪些东西是固定的，哪些东西是变化的？t3code 的思路很清晰，它把整个生成过程拆成三层。最底层是数据层，也就是你的输入源，可能是一份 YAML 配置、一张数据库表结构、一个 JSON Schema，甚至是一段注释标记。中间层是规则层，负责把原始数据加工成模板能直接消费的形态，比如把下划线命名转成驼峰、把类型映射成目标语言的类型、把字段拆成必填和选填。最上层是模板层，也就是最终产出的“形状”，它决定了生成出来的代码长什么样。

这个分层的好处在于，每一层都可以独立替换。你今天用 MySQL 表结构做数据源，明天换成 Protobuf 定义，只要规则层做适配，模板层几乎不用动。反过来，你想把 Java 模板换成 TypeScript 模板，数据层和规则层也完全不受影响。我见过很多团队一开始把这三样东西揉在一个脚本里，结果需求一变就推倒重来，这就是没做分层的代价。

提示：分层不是目的，可替换才是。判断一个生成方案好不好，就看它换数据源或换目标语言时，需要改动的代码比例有多高。

2.2 方案选型背后的考量：为什么不直接用现成的 ORM 生成器

有人会问，MyBatis Generator、JPA 的逆向工程不也能生成代码吗，为什么还要自己搞一套 t3code？这个问题我认真对比过。现成的 ORM 生成器确实开箱即用，但它们的可定制性是有天花板的。你想在生成的实体类里加一个统一的审计字段，或者想让生成的 Mapper 带上特定的注解，往往要去改它的模板文件，而很多工具的模板是硬编码在 jar 包里的，改起来非常别扭。

t3code 这类自建方案的优势就在于完全掌控。模板是你自己的，规则是你自己的，想加什么逻辑就加什么逻辑。比如我们团队有个需求，生成的接口方法要根据字段是否为主键自动决定是getById还是getByCode，这种业务化的判断，现成工具基本做不到，但自己写规则就是几行代码的事。当然，代价是你得自己维护这套东西，所以它更适合生成需求稳定、重复度高、且有定制诉求的场景。如果只是偶尔生成一两个类，那确实没必要。

2.3 优势与边界：它擅长什么，不擅长什么

t3code 最擅长的场景有三个。第一是中后台的 CRUD 批量生成，一张表对应 Controller、Service、Mapper、DTO 一整套，模板固定，数据规整，生成效率极高。第二是多端一致性保障，同一份数据源同时生成后端接口定义和前端请求方法，字段名、类型、必填项天然对齐，省去了前后端对字段的扯皮。第三是配置文件的批量产出，比如给几十个服务生成统一的部署配置，改一个参数全量刷新。

它不擅长的也很明确。复杂的业务逻辑生成不了，模板只能处理结构化的重复，遇到需要多步推理、条件分支嵌套很深的逻辑，硬塞进模板只会让模板变得不可读。一次性的、没有规律的代码也不值得生成，写模板的时间可能比手写还长。我的经验是，当一个东西你手写超过三遍，且第四遍和前三遍结构一致时，就该考虑生成了。这个判断标准很土，但特别管用。

3. 核心细节解析：数据、规则、模板各自的门道

3.1 数据层：输入源的清洗比想象中重要

数据层看起来最简单，无非是读一份配置。但实际操作中，输入数据的质量直接决定生成结果的质量。我踩过最大的坑就是直接拿数据库的information_schema当数据源，结果字段注释缺失、类型不统一、默认值乱七八糟，生成出来的代码一堆问题。后来我们定了个规矩：任何进入生成流程的数据，必须先经过一次清洗和标准化。

具体怎么做？以数据库表为例，我会先跑一个提取脚本，把表名、字段名、字段类型、是否可空、注释、默认值这些信息拉出来，然后做三件事。第一，统一命名规范，把user_name、userName、UserName全部归一成一种风格，通常我选下划线，因为它在各种语言里都好转换。第二，补全缺失的元信息，注释为空的字段要么补上，要么标记出来人工确认，类型映射不了的（比如某些数据库特有的类型）单独列一张表处理。第三，过滤系统字段，create_time、update_time、deleted这类审计字段单独抽出来，生成时统一注入，不跟业务字段混在一起。

# 清洗后的数据源示例 table: user_account comment: 用户账户表 columns: - name: id type: bigint nullable: false primary: true comment: 主键 - name: user_name type: varchar length: 64 nullable: false comment: 用户名 - name: status type: tinyint nullable: false default: 1 comment: 状态 1正常 0禁用

这份 YAML 就是规则层和模板层的“合同”，只要它稳定，后面两层就稳定。我强烈建议把清洗逻辑单独写成一个模块，不要和生成逻辑混在一起，因为数据源会变，清洗规则也会变，分开之后各自演进互不干扰。

3.2 规则层：类型映射和命名转换是重头戏

规则层是 t3code 里最“有技术含量”的部分，因为它要处理各种映射和转换。类型映射是第一道坎。数据库的varchar到 Java 是String，到 TypeScript 也是string，但decimal到 Java 是BigDecimal，到 TypeScript 却是number或者string（取决于精度要求）。这些映射关系必须显式定义，不能靠猜。

我通常会用一张映射表来管理，长这样：

命名转换是第二道坎。数据库喜欢下划线，Java 喜欢驼峰，前端喜欢小驼峰，URL 路径又喜欢中划线。这些转换看似简单，但边界情况很多。比如user_id转驼峰是userId，但user_ID呢？URL_path呢？我的做法是统一先转成小写再处理，并且对连续大写做特殊处理，避免出现uRLPath这种尴尬结果。这块逻辑我单独写了一个工具类，配了二十多个测试用例，跑通了才敢用在生成流程里。

注意：命名转换一定要有测试覆盖。我见过因为一个字段名转换错误，导致生成的接口路径和前端请求路径对不上，排查了半天才发现是a_b_c被转成了aBC而不是aBC的预期形态。

3.3 模板层：可读性比炫技重要

模板层决定了最终产出的样子。t3code 常用的模板引擎有几种选择，我试过字符串拼接、Mustache 风格的引擎，最后稳定用的是支持条件判断和循环的模板引擎。原因很简单，生成逻辑里不可避免会有“如果字段是主键就加注解”“如果字段可空就加校验”这类分支，纯字符串拼接写起来太痛苦。

写模板有几个原则我一直在遵守。第一，模板里不做复杂计算，所有需要判断的逻辑尽量在规则层算好，模板只负责“填空”。比如字段是否必填，规则层直接给一个required: true的标记，模板里就写if required，而不是在模板里判断nullable == false && default == null。第二，模板要能独立阅读，一个好的模板，哪怕不懂生成逻辑的人看了，也能大致猜出生成出来的代码长什么样。第三，缩进和空行要处理好，生成的代码如果缩进混乱，review 的时候会被骂，所以模板里的缩进要跟目标语言的规范一致。

// 模板片段示例（伪代码） public class {{className}} { {% for field in fields %} /** {{field.comment}} */ private {{field.javaType}} {{field.camelName}}; {% endfor %} }

这个模板一眼就能看懂，生成出来的类结构也清晰。我见过有人把整个生成逻辑塞进模板，几百行的模板里全是条件判断，那种模板维护起来就是灾难，改一个地方要通读全文。

4. 实操过程：从零搭一套可用的生成流程

4.1 环境准备与目录结构设计

动手之前先把目录结构定好，这步偷懒后面会加倍还回来。我的习惯是分成四个目录：datasource放数据提取和清洗的脚本，rules放类型映射和命名转换的配置，templates放各种目标语言的模板，output放生成结果。再加一个config.yaml作为总入口，指定这次生成用哪个数据源、哪套规则、哪些模板。

t3code/ ├── config.yaml ├── datasource/ │ ├── extract.py │ └── clean.py ├── rules/ │ ├── type_mapping.yaml │ └── naming.py ├── templates/ │ ├── java/ │ │ ├── entity.tpl │ │ ├── mapper.tpl │ │ └── service.tpl │ └── typescript/ │ └── api.tpl └── output/

这个结构的好处是职责清晰。数据源换了只动datasource，目标语言加了只加templates下的子目录，规则调整只改rules。团队协作时，不同人负责不同目录，冲突也少。我建议一开始就把这个骨架搭好，哪怕先放空文件，也比后面重构强。

4.2 数据提取与清洗的完整实现

数据提取我一般用 Python 写，因为处理文本和结构转换特别顺手。以 MySQL 为例，核心就是查information_schema.columns，把需要的字段拉出来。这里有个细节，字段顺序要按ordinal_position排，不然生成出来的类字段顺序是乱的，看着难受。

import pymysql import yaml def extract_table(conn, table_name): sql = """ SELECT column_name, data_type, character_maximum_length, is_nullable, column_default, column_comment, column_key FROM information_schema.columns WHERE table_name = %s ORDER BY ordinal_position """ with conn.cursor(pymysql.cursors.DictCursor) as cur: cur.execute(sql, (table_name,)) rows = cur.fetchall() return normalize(rows) def normalize(rows): columns = [] for r in rows: columns.append({ 'name': r['column_name'].lower(), 'type': r['data_type'], 'length': r['character_maximum_length'], 'nullable': r['is_nullable'] == 'YES', 'default': r['column_default'], 'comment': r['column_comment'] or '', 'primary': r['column_key'] == 'PRI' }) return {'table': table_name, 'columns': columns}

清洗阶段做三件事：过滤审计字段、补全空注释、标记主键。审计字段我用一个白名单来过滤，create_time、update_time、create_by、update_by、deleted这几个是常客。空注释我会填一个默认值比如“待补充”，这样生成出来的代码里注释不会空着，review 时一眼能看到哪些没写。主键标记直接透传，规则层会用它来决定生成getById还是getByCode。

4.3 规则配置与模板编写实战

规则配置我全部用 YAML，因为可读性好，非开发人员也能看懂。类型映射就是一张大表，前面已经展示过。命名转换我写了一个函数，核心逻辑是按下划线分割，首段小写，后续段首字母大写。

def to_camel(name): parts = name.lower().split('_') return parts[0] + ''.join(p.capitalize() for p in parts[1:]) def to_pascal(name): return ''.join(p.capitalize() for p in name.lower().split('_'))

模板编写我用的是 Jinja2 风格的语法，因为它支持宏和继承，多个模板之间可以复用公共片段。比如 Java 的实体类模板和 DTO 模板，字段声明部分几乎一样，我就抽一个field_declaration宏出来，两边都引用它。这样改字段声明格式时只改一处，非常省心。

{% macro field_declaration(field) %} /** {{ field.comment }} */ private {{ field.javaType }} {{ field.camelName }}; {% endmacro %}

生成的时候，把清洗后的数据、规则配置、模板路径一起传给引擎，遍历模板目录，每个模板生成一个文件，按目标语言的目录结构输出。整个过程我封装成一个命令，python generate.py --config config.yaml，一条命令全量刷新。

4.4 生成结果的校验与回归

生成完不是就完事了，必须做校验。我一般做三层校验。第一层是语法校验，Java 的用javac编译一下，TypeScript 的用tsc --noEmit检查，能过编译说明至少语法没问题。第二层是结构校验，检查生成的类数量、方法数量是否和预期一致，比如一张表应该生成一个实体类、一个 Mapper 接口、一个 Service 类，数量对不上说明模板有问题。第三层是差异校验，把这次生成的结果和上次的做 diff，如果差异超出预期（比如只改了一个字段却生成了几十处变化），就要排查是不是规则或模板被误改了。

# 语法校验示例 javac -d /tmp/check output/java/**/*.java tsc --noEmit output/typescript/**/*.ts

这套校验流程我建议固化成 CI 的一部分，每次生成后自动跑，有问题直接拦住。我吃过亏，有一次模板里少了个分号，生成了一堆编译不过的代码，手动改了半天才发现是模板问题，从那以后校验就成了标配。

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

5.1 生成结果不符合预期的排查思路

生成结果不对，原因通常出在三个地方：数据、规则、模板。排查顺序我建议从数据开始，逐层往上。先看清洗后的数据对不对，字段名、类型、注释是不是符合预期。数据没问题再看规则，类型映射有没有漏配，命名转换有没有边界情况没覆盖。最后看模板，条件判断是不是写反了，循环是不是漏了字段。

我整理了一张速查表，覆盖了最常见的几类问题：

这张表我贴在团队 wiki 上，新人遇到问题先查表，大部分情况能自己解决，省了我不少答疑时间。

5.2 踩过的坑：那些文档不会告诉你的细节

第一个坑是编码问题。数据库里的中文注释，提取出来在某些环境下会变成乱码，生成到代码里就是一堆问号。解决办法是在连接和读写时统一指定 UTF-8，Python 里就是charset='utf8mb4'，文件读写也显式指定编码。这个坑不踩一次很难想到，但踩过一次就永远忘不了。

第二个坑是默认值处理。数据库字段有默认值，比如status默认1，生成代码时如果直接把默认值写进字段初始化，遇到null语义的字段就会出问题。我的做法是默认值只在 DTO 或配置里体现，实体类字段不写初始化，避免和业务逻辑冲突。

第三个坑是模板的空白控制。Jinja2 的{% for %}循环如果不在合适的位置加-控制空白，生成出来的代码会多出一堆空行。我一开始没注意，生成的类里字段之间隔了三四行，看着特别乱。后来在循环标签上加{%- for ... -%}就好了。

提示：模板引擎的空白控制是个细节活，建议每写一个新模板，先渲染一个最小数据集，肉眼检查输出格式，确认没问题再上真实数据。

5.3 性能与规模：表多了之后怎么办

单表生成很快，但当一个库有上百张表时，问题就来了。我实测过，一百张表串行生成大概要几十秒，主要耗时在数据库查询和文件写入上。优化手段有两个。第一是批量查询，一次性把整个库的表结构拉出来，而不是一张一张查，这一下就能省掉大量往返时间。第二是并行生成，表与表之间是独立的，用多进程或线程池并行处理，速度能提升好几倍。

from concurrent.futures import ThreadPoolExecutor def generate_all(tables, config): with ThreadPoolExecutor(max_workers=8) as executor: executor.map(lambda t: generate_one(t, config), tables)

但并行要注意输出目录的隔离，不同表生成的文件不能互相覆盖。我的做法是按表名建子目录，或者文件名带上表名前缀，这样并行写也不会冲突。规模上去之后，这些工程化的细节比生成逻辑本身更重要。

6. 扩展玩法：t3code 思路还能用在哪

6.1 从代码生成到文档生成

t3code 这套“数据 + 规则 + 模板”的思路，换个模板就能生成文档。我们团队现在用同一份数据源，既生成代码，也生成接口文档。文档模板里把字段名、类型、注释、是否必填都列出来，生成 Markdown 或者 HTML，直接挂到内部文档站上。好处是文档和代码永远同步，因为它们是同一次生成的产物，不存在“代码改了文档没改”的问题。

这个扩展特别适合接口频繁变动的项目。以前前后端对接口，靠的是口头沟通或者手写文档，经常对不齐。现在数据源一改，代码和文档一起刷新，前端直接看生成的文档，字段类型、必填项一目了然，扯皮少了很多。

6.2 多语言产出的协同策略

同一个数据源生成多种语言的代码，关键在于规则层要按语言分开配置。Java 的类型映射和 TypeScript 的不一样，命名习惯也不一样（Java 用驼峰，Python 用下划线）。我的做法是在rules目录下按语言建子目录，每个语言一套映射和转换规则，模板也按语言分目录。生成时指定目标语言，引擎自动加载对应的规则和模板。

这样做的代价是规则配置变多了，但收益是各语言可以独立演进。比如前端团队想把 TypeScript 的decimal从number改成string，只改 TypeScript 的映射就行，不影响 Java。这种隔离在多团队协作时特别重要，避免了“改一处影响一片”的连锁反应。

6.3 与现有工程体系的集成方式

生成的东西最终要进到工程里，怎么集成是个问题。我试过三种方式。第一种是生成后手动拷贝，适合生成频率低的场景，简单但容易忘。第二种是生成到源码目录，直接覆盖，适合生成频率高、且生成文件不手动修改的场景，但风险是手改会被覆盖。第三种是生成到独立目录，通过构建脚本合并，适合生成文件和手写文件混合的场景，最灵活但配置稍复杂。

我现在用的是第三种。生成的代码放在generated目录，手写的业务逻辑放在src目录，构建时把generated加入源码路径。这样生成的文件永远不被手改，手写的文件也不受生成影响，边界非常清晰。代价是要配一下构建工具，但一次配置长期受益，我觉得很值。

7. 我个人的一些实操体会

这套东西我用了大半年，最大的感受是它改变了我对“写代码”这件事的认知。以前觉得代码就得一行行敲，现在会先想“这部分能不能生成”。这个思维转变带来的效率提升，比任何快捷键都大。当然，生成不是银弹，它适合结构化的重复劳动，不适合需要创造力的逻辑设计。判断标准还是那条：手写超过三遍且结构一致，就该考虑生成。

另外一点体会是，模板和规则要当成代码来维护。很多人觉得模板就是配置文件，随便写写就行，结果后面改起来痛苦不堪。我的做法是模板也进版本控制，也写测试，也做 code review。规则配置同理，类型映射表加一条要说明为什么加，命名转换改逻辑要有测试覆盖。把它当正经代码对待，它才能稳定地为你干活。

最后分享一个小技巧：生成之前先备份。虽然生成是可重复的，但万一模板改错了，生成出一堆废代码，有备份就能快速回滚。我现在的流程是生成前自动把output目录打个时间戳的包，出问题直接解压回去，几秒钟的事，但能省下大量排查时间。这个习惯看起来笨，但真的管用。