搞技术这么多年，我最怕的就是重复造轮子，尤其是那些“看起来很简单、做起来全是坑”的杂活。前阵子因为项目节奏太快，我开始重度使用一个叫t3code的代码生成与工程脚手架辅助工具，原本只是为了偷个懒，结果用下来发现这套思路值得好好聊一聊。今天这篇东西，是我自己从安装、配置到实际跑完一个完整模块的全程记录，包含我踩过的坑、对比过的方案，以及一些不写在官方文档里的经验。如果你也在搞自动化开发、想要提升编码效率，或者正处于从“手工写代码”向“半自动工程化”转型的阶段，这篇内容应该能帮你省掉不少摸索时间。

t3code 的本质，是一个融合了模板引擎、脚手架生成和通用代码逻辑的工程辅助框架。它解决的核心问题有两个：第一，把大量可复用的代码结构沉淀成模板，避免每次新开项目都从零开始；第二，把重复性极高的增删改查、接口对接、参数校验变成配置化生成，让coder把精力集中在业务判断和复杂逻辑上，而不是复制粘贴。这篇文章我会从整体设计思路、核心模块拆解、实际配置到最终跑通全流程，给你一份可以直接照做的参考。

1. 整体设计与思路拆解：为什么我需要一个“代码生成器”

先说个背景。我之前维护一个内部管理系统，前后端加起来几十个页面，每个页面几乎都是标准的列表、表单、详情三件套。技术栈不复杂：前端 Vue、后端 Java Spring Boot、数据库 MySQL。但问题是，每加一个业务模块，我都要把同样的流程走一遍：建表、写实体类、写 Mapper、写 Service、写 Controller、写前端列表页、写表单页、配路由、配菜单。这一套下来，熟手也得两个小时，而且最大的风险不是速度，是copy代码的时候容易漏改参数，经常出现字段名对不上、类型不匹配这类低级错误，排查起来很痛苦。

当时我评估过几个方案。第一个是直接用网上的代码生成器，比如 MyBatis Generator、MyBatis-Plus Generator。它们很强，但有个共性短板：只能生成单机项目的固定结构，而且生成出来的代码风格和团队规范经常不匹配，改模板的成本也不低。第二个方案是我自己维护一套公共代码库，新项目直接clone，但这种方式的问题是，公共库里改一个东西，老项目怎么同步？版本怎么管理？搞到最后往往仓库一堆分叉，乱成一团。

t3code 这条思路打动我的地方，是它把“生成”和“工程”分开了。它默认所有项目先通过模板初始化出一个完整的、可运行的工程骨架，再通过内置规则按模块生成业务代码。也就是说，它不只是生成单个文件，而是按“包结构、资源结构、配置结构”三层同时生成，生成完后的确是一个能跑起来的项目。这就比普通代码生成器更进一步，因为普通生成器往往只能生成Java源码，前端、路由、数据库脚本这些还是得自己手动搞。

我的使用场景属于典型的中等规模和强规范需求，团队五六个人，代码风格必须统一。t3code 这种模式很适合我们，因为模板是统一维护的，生成出来的风格天然一致；而且它支持自定义模板。后来我实际用了差不多两周，把内部系统里几个新模块全部跑了一遍，生产效率提升确实是肉眼可见的。

一个有意思的细节是，t3code 的理念跟传统“脚手架”不一样。脚手架像是在一张白纸上面先盖好毛坯房，t3code 更像是先给你一套完整的精装修房，然后你只需要按户型图修改局部墙面。这套思路对于成体系的项目帮助特别大，因为它把“工程创建”和“业务迭代”两个阶段的关注点彻底拆开了，管理起来更清晰。

1.1 模板先行：从“写代码”到“写生成规则”

用 t3code 之前，你得接受一个思维切换：你的核心产出不再是一行行代码，而是一套套生成规则。这套规则里有变量、有约束、有分支逻辑，代码本身反而是模型渲染出来的结果。一开始可能不适应，但一旦你想通这点，后面上手会非常快。

我当时做的第一件事，是把自己的历史项目整理出来，挑了一个结构最规整、规范最统一的模块作为基准，然后照着它的目录结构、代码写法把模板抽出来。模板里常见的有变量占位符，比如{{projectName}}、{{moduleName}}、{{entityName}}，也有循环指令，比如生成列表字段时，遍历字段数组去渲染表格列。这套模板语法跟市面上主流的模板引擎，比如 Velocity 或者 FreeMarker 很接近，写过服务端渲染的人几乎没有学习成本。

这步的灵魂，在于你要在设计模板时就把团队规范焊死。比如我们团队要求所有 Service 接口必须有注释、所有 Controller 返回统一叫R<T>、所有数据库时间字段统一叫created_at，这些规则如果靠人记肯定有人忘，但提前写进模板里，生成出来的东西天然合规，后面 Code Review 的压力会小很多。所以，项目初期多花点时间打磨模板，绝对划算。

1.2 模块热插拔：不必每次重新生成全量工程

t3code 另一个让我满意的地方是它的模块化增量生成能力。有些代码生成工具是“全量一次性”的，你执行一次生成，它会告诉你“项目已经存在”，然后掉头就走。但 t3code 不是，它允许你仅针对某个模块重新生成，比如我只想新增一个“订单管理”模块，不必把用户、角色、菜单这些已经存在的模块再覆盖一遍。

这个设计的价值，要等你的项目规模变大了才能体会。我当时的业务系统已经有六个核心模块，如果每次新增模块都要重新生成整个工程，光是文件覆盖检查就够头疼的。增量生成模式下，我只需要指定要加入的模块名，工具会自动读取全局配置和已有项目结构，只往指定位置插入新代码和路由配置，其他文件保持原样。这意味着我从“全工程重建”走向了“局部热插拔”，很舒服。

至于它是怎么定位插入点的？这就得说到 t3code 的“锚点机制”。它在生成模板时会自动搜索项目里的关键文件（比如pom.xml、router/index.js、menu.sql），然后基于可配置的锚点位置插入新内容，而不是简单粗暴地整文件覆盖。这也是我强烈建议后来人务必仔细研究的一个功能点，后面我会展开讲。

1.3 多项目支持：从单模块到多系统复用

我手里不止一个项目，团队也在同时维护两套系统。t3code 支持所谓的“多项目配置”，说人话就是：你可以配置多个项目模板源，不同业务团队维护各自的模板仓库，生成时指定用哪套规则即可。这个多项目配置能力，让我不再为“不同项目规范不同”而抓狂。

举个例子，A 项目用的是 Spring Cloud 微服务风格，B 项目是 Spring Boot 单体加多模块风格。正常情况下，这两套东西代码结构差异极大，不可能共用一套生成模板。以前我只能维护两套生成脚本。t3code 里只需要在配置文件里声明两个项目，用类似project: service-a的命令参数指定目标项目，工具会自己去找对应对的模板目录。

这套机制其实挺像工厂里给不同产品线配不同的模具，模具本身互不干扰，但都挂在同一个流水线上。对于公司内部存在多个技术栈或多种架构风格的场景，这个特性几乎就是刚需。

2. 核心细节解析与实操要点：从配置到第一行生成代码

光说不练假把式。这节我完整带你走一遍 t3code 的配置到生成流程，所有依赖和配置我都贴实际可用的版本。我用的环境是 macOS + IntelliJ IDEA + Java 17，但这套东西不挑操作系统，Windows 和 Linux 也一样能跑，只是命令行略有区别。

2.1 安装与初始化：三步跑通 Hello-level 工程

先看安装，t3code 本身是一个基于 Java 的命令行工具，也有嵌入式 API。最简单的用法是通过发行版的压缩包，解压之后配置环境变量。我在 Mac 上操作是这样的：

# 下载并解压到 /opt/t3code tar -zxvf t3code-1.2.0.tar.gz -C /opt/ # 建立软链接 ln -s /opt/t3code-1.2.0/bin/t3code /usr/local/bin/t3code # 验证版本 t3code --version

如果你用 Windows，解压后手动把 bin 目录加进 PATH 即可。这里有个小坑，就是一定确认系统里装了 JDK 8 以上的版本，别用 JRE 糊弄，因为 t3code 内部依赖 Java API，缺了编译组件会报莫名其妙的错误。我一开始就在这上面浪费了十分钟，日志一直提示NoClassDefFoundError，最后才发现是 JRE 环境的问题。

初始化项目用下面这条命令：

t3code init --template my-webapp --name demo-system

执行完成后，当前目录下会生成一个demo-system目录，里面自带 Maven/Gradle 工程结构、前端工程骨架、基础配置文件。之前我手动搭这套骨架大概得半天，现在秒级生成，光这段就让我对内卷工期有了新的底气。

2.2 配置文件的解构：不看文档也能看懂八成

t3code 的核心配置是一个 YAML 文件，名字类似t3code.yaml。我把它贴在下面，重点部分加了注释，你看完之后基本就能自己上手改配置了。

project: name: demo-system type: springboot # 工程类型：springboot / frontend / fullstack packageName: com.demo.system port: 8080 template: source: templates/springboot # 模板目录，相对于项目根目录 output: ./generated # 输出目录 database: driver: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/demo username: root password: pass tables: - sys_user - sys_order specs: author: t3code-group dateFormat: yyyy-MM-dd HH:mm:ss

这个文件初看挺唬人，其实分层很清晰。project段描述目标工程本身，template段决定生成器去哪找模板、往哪输出，database段告诉生成器提供的数据表结构信息从哪来，specs段定义一些全局变量。tables字段尤其关键，t3code 会去读取这些表的元数据，比如字段名、类型、注释，然后自动映射成实体类的属性。

需要注意的是，type不像你想的只有一种模式。它的设计是让你声明目标工程的类型，这样生成器会决定要渲染哪些文件模板。springboot类型会生成 Controller、Service、Mapper 等，frontend类型会生成 Vue 页面和路由文件，fullstack则两边都会生成，适合我这种前后端一起交付的场景。

2.3 表结构读取：为什么 GUI 链接数据库之前要若干个前置条件

数据库表结构是谁告诉 t3code 的？答案是它自己读。但这里有个起手式你需要懂：它连接数据库之后，会读取系统表（information_schema），把表和字段的血肉全都送进模板。所以，如果你要生成的表还没建好，t3code 生成的内容就是无源之水。

我第一次用的时候犯了个错误，没在数据库里建表就强行执行生成命令，工具倒是没报错，但生成出来的实体类属性全是默认值，字段匹配乱七八糟，相当于生成了个寂寞。后来我记得在它的官方文档里看到一句话，大意是“t3code 只负责把已有结构转成代码，不负责替你设计数据库”，这句话请务必画线加粗。

所以正确姿势是这样的：先用标准的数据库迁移工具，比如 Flyway 或 Liquibase，把表结构定义好，确认字段名、类型、注释都符合规范，然后让 t3code 去读。你可能会好奇，为什么字段注释这么重要？因为 t3code 会把数据库字段注释直接映射成 Java 代码里的 Swagger 注解和注释文本，你要是表里字段注释写的是“某编号”“某名称”这种废话，那生成的接口文档和代码注释也会非常敷衍，后面同事看着都糟心。

2.4 模板变量与指令：能插入、能循环、能判断

模板语法这一块，我直接把常用指令列给你。t3code 的默认语法符号是双花括号，跟 Vue 模板有点像，但它还支持控制结构。下面是我在实体类模板里经常用的一段示例：

package {{packageName}}.entity; import lombok.Data; import java.time.LocalDateTime; @Data public class {{entityName}} { {{#each fields}} /** {{comment}} */ private {{javaType}} {{fieldName}}; {{/each}} }

这个模板渲染之后，会针对sys_user表生成类似如下内容：

package com.demo.system.entity; import lombok.Data; import java.time.LocalDateTime; @Data public class SysUser { /** 用户ID */ private Long id; /** 用户名 */ private String username; /** 创建时间 */ private LocalDateTime createdAt; }

看到没，我并没有手动指定每一个字段，生成器拿到表的元数据之后自动填进去了。这里最值得钻研的是{{#each fields}}这种循环块，它遍历的是数据库表里查出来的字段数组，每个元素都包含comment、javaType、fieldName这几个属性。你只要记住这些内置属性的命名，写模板就不会卡壳。

有的模板里还有条件判断，比如只需要对时间类型字段额外加@JsonFormat注解，就可以写{{#if isDateType}}指令。所以不要觉得模板就是把代码字符串拼一拼，它本质上已经是带逻辑的代码了，会写模板的人，生成的代码质量能甩开不会写模板的人两条街。

3. 实操过程与核心环节实现：一个订单模块的完整落地

这节我用一个“订单模块”作为案例，从配置文件编写、模板调整、执行生成到代码修补，给你完整走一遍。这个模块包含一张主表sys_order和一张子表sys_order_item，主表存订单头信息，子表存商品明细，典型的一对多关系。用 t3code 来做，这个过程可以压缩到十分钟以内。

3.1 准备数据库表：字段设计和注释决定生成质量

数据库这步其实是最关键的，因为 t3code 的设计哲学是“数据库定义优于代码定义”。我先用 SQL 建两张表，这里贴核心结构：

CREATE TABLE `sys_order` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '订单ID', `order_no` varchar(32) NOT NULL COMMENT '订单编号', `customer_name` varchar(64) NOT NULL COMMENT '客户名称', `total_amount` decimal(10,2) NOT NULL COMMENT '订单总金额', `status` tinyint NOT NULL DEFAULT 0 COMMENT '状态：0-待支付 1-已支付 2-已取消', `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_order_no` (`order_no`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表'; CREATE TABLE `sys_order_item` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '子项ID', `order_id` bigint NOT NULL COMMENT '所属订单ID', `product_name` varchar(128) NOT NULL COMMENT '商品名称', `price` decimal(10,2) NOT NULL COMMENT '商品单价', `quantity` int NOT NULL COMMENT '购买数量', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单明细表';

这两张表并不是特别复杂，但类型上有代表性：有字符串、有整数、有小数、有日期、有枚举语义的整数。t3code 会自动把bigint映射成Long，把decimal映射成BigDecimal，把datetime映射成LocalDateTime。这能满足大多数业务场景，如果出现特殊类型比如 JSON 字段，你可以在后处理阶段手动调整。

注意一下注释里的中文，比如“客户名称”“订单总金额”，t3code 会把这些注释直接塞进生成的 Swagger 注解里，所以注释写得好，接口文档就漂亮；注释写“字段1”“字段2”这种，后续补文档的功夫够你喝三壶。这是我在实际项目里印象最深的细节之一。

3.2 编写主配置与模块清单：增量生成的关键所在

表建好之后，修改t3code.yaml里的配置，让生成器知道这轮要处理哪些表。因为这次是想走增量生成，我只把新表加进tables列表，不动其他模块的配置：

database: url: jdbc:mysql://localhost:3306/demo username: root password: pass tables: - sys_order - sys_order_item

这里重点说一下增量生成的执行机制。t3code 分析表时，会发现sys_order_item里有个外键字段order_id。它本身并不关心数据库层有没有建物理外键，它只根据字段名和字段注释去推测关系。如果你想让子表实体里带一个List<SysOrderItem> items属性来体现一对多关系，就需要在配置里补充一点关系声明。不然 t3code 默认只会把子表当成一个独立实体去生成。

关系声明的方式是在配置里加relations段。比如我这样写：

relations: - type: oneToMany mainTable: sys_order childTable: sys_order_item joinColumn: order_id targetField: items

这样配置之后，生成的Order实体类里会自动多出一个List<OrderItem> items字段，Controller 的详情接口也会默认去查询子表记录并塞进返回结构里。这段配置看起来不长，但带来的开发量节省却非常可观。

3.3 执行生成与代码走读：看看工具吐出来什么东西

配置写完执行：

t3code generate --config t3code.yaml --project demo-system

生成的代码在./generated目录下。我习惯生成完之后立即用 IDE 打开做一次走读，确认没有明显问题再往主工程里合并。那次的生成结果大致是这样的结构：

generated ├── entity │ ├── SysOrder.java │ └── SysOrderItem.java ├── mapper │ ├── SysOrderMapper.java │ └── SysOrderItemMapper.java ├── service │ ├── SysOrderService.java │ ├── SysOrderServiceImpl.java │ ├── SysOrderItemService.java │ └── SysOrderItemServiceImpl.java └── controller ├── SysOrderController.java └── SysOrderItemController.java

我随手打开SysOrderController.java瞅了一眼，内容基本符合预期，典型的 CRUD 接口：分页查询、详情、新增、修改、删除都有，而且@Api注解、@RestController注解、统一返回类型R模板都用上了。心里那块“担心生成代码不能直接跑”的石头落了一半。

后端代码没问题，前端页面也要生成。因为我配置的type是fullstack，它顺带把 Vue 的列表页和表单页也一并吐出来了。页面里列表的列顺序、搜索条件、表单字段全部跟着表结构走，字段注释自动变成了输入框的 label 和 table 的列名。看到这里我确实觉得，如果业务是标准 CRUD，t3code 确实能让我从繁琐里彻底解放出来。

3.4 代码合并与手工修补：工具不是万能的，好工程师才是

生成只是完成了大概 80%，剩下 20% 需要你自己动手。比如那次生成的OrderController，它默认的查询条件只有精确匹配，而实际业务里客户名称肯定要模糊搜索，订单金额范围查询也得支持。所以我手动改了一下查询参数类，加了两个条件，然后把 Service 实现里的查询逻辑稍微调整了一下。

还有一点要注意，t3code 生成的删除接口逻辑默认是物理删除，而我们业务要求订单不能真的删，要做逻辑删除。我就在实体类加了个deleted字段，把删除方法改成先更新状态位。这种业务规则类的东西，没有工具能替你决定，必须人来判断。

我对这类半自动生成的代码有个明确原则：可以接受结构高度相似，但绝不接受逻辑完全照搬。生成器负责让你少敲 80% 的键盘，剩下 20% 的决策才是你作为工程师真正的价值所在。别指望一个工具生成完就万事大吉，那种偷懒心态才是项目后期最大的隐患。

3.5 路由与菜单合并：锚点机制是增量的灵魂

刚才提到 t3code 的锚点机制，这一步就见真章了。执行生成之后，我那些新增的前端页面文件只是放在了generated目录里，还没捎进原来的demo-system工程。其实 t3code 支持自动合并，它会去找主工程里的关键文件，比如router/index.js和menu.sql，然后把新路由和菜单配置插到指定锚点之后。

我在实际配置里，路由文件的锚点是一行注释：

// t3code:router-insert

t3code 扫描到这行注释后，会把新模块的路由配置追加在这行注释的下方。这样就不用每次都担心把整个文件搞乱。菜单 SQL 同理，它会解析出已有的菜单目录结构，找到新模块对应的父级菜单，然后生成子菜单插入 SQL。锚点配置不复杂，但这套设计让我感觉它真的理解“工程化”的痛点，而不是单纯生成一堆散文件让你自己折腾。

在做这些合并的时候，最需要小心的是别让锚点重复。如果你在多个分支之间切来切去，锚点注释可能被合并出多份，t3code 扫描到多个同锚点会怎么处理？我建议在生成前先全局搜一下，确认锚点唯一。这种小检查花不了十秒钟，但能避免后续整个工程配置文件出现隐患。

4. 常见问题与排查技巧实录：那些没人提前告诉你的坑

工具再好用，不代表不会踩坑。我这段时间用 t3code 写过两个完整模块，中间遇到不少问题，有的是配置层面，有的是环境层面的，有的直接把人搞崩溃。这节我把它们整理成速查表，你照着排查基本能省掉大半时间。

4.1 字段类型映射不准确：BigDecimal 变成了 Double 怎么办

第一次用的时候，我有一个字段是decimal(10,2)，心想着应该生成BigDecimal，结果打开实体类一看，t3code 把它映射成了Double。虽然在 Java 里这个类型能编译能跑，但金额字段用 Double 是绝对要遭天谴的，精度问题早晚会变成财务事故。

后来翻配置，发现database段里有个typeMapping选项，可以自定义类型映射规则。我加了一行：把decimal显式映射成java.math.BigDecimal，重新生成后问题解决。这类问题最容易出现在新数据库版本或者新表类型上，你以为生成器认识，其实它默认走的别名映射跟你想的不一样。碰到金额、百分比这类高精度字段，不要偷懒，一定要在配置里钉死类型。

这里额外多说一句，我见过一些同学工具生成完之后，人工把所有Double改成BigDecimal，一改改几十处。真要遇到这种，别硬刚，先回去看配置，从源头修正永远比事后修补效率高。

4.2 表名或字段名被人为加上了反引号

第二次踩坑是 MySQL 表名，我用的表名sys_order，结果生成出来的 Mapper XML 里表名和字段名全被套上了反引号`，像这样：

SELECT `id`, `order_no` FROM `sys_order`

反引号在 MySQL 里是完全合法的，我用的是 Navicat，直接执行没问题。但后来同事把这段 SQL 丢到数据库还原本地执行，因为有些环境配置没有启用 ANSI_QUOTES，就显得有点多余了。更重要的是，如果你后续接入了其他数据库，比如 PostgreSQL，反引号会直接报错。

解决办法是在生成配置里把quoteIdentifiers关掉。我一开始不知道这个开关存在，还是翻配置文件时瞥见的。这里给后来人一个忠告：工具生成的代码不是圣旨，只要它不符合你的实际运行环境，该关的开关尽早关，别让代码迁就工具。

4.3 生成的项目依赖版本太老，引入冲突

t3code 默认模板里用的 Spring Boot 版本可能不是最新的，如果你所在团队的项目已经升级到 Spring Boot 3 或 Java 21，直接合并生成的代码大概率会爆编译错误。我当时就遇到了一个典型的兼容问题：模板生成的javax.annotation.Resource在新版 Spring 里已经被替换成jakarta.annotation.Resource，导致代码根本无法通过编译。

这个问题不在工具本身，而在模板滞后性。t3code 只是个框架，模板内容到底谁维护？真正的答案是你的团队。只要你们自己维护一套跟技术栈同步的模板，就不会出现这种版本断层。所以强烈建议，让团队里对构建体系最熟的那位同事，在上线 t3code 之前先把模板升级到位，并打上版本标签。别用开箱即用的模板直接上生产，相信我，会出事。

4.4 文件合并时覆盖掉了手工修改

这是我印象最深的一个坑。当时我生成完模块后，又手工调整了OrderServiceImpl.java，加了一些自定义业务逻辑。后来表结构加了新字段，我重新跑了一次 generate，结果OrderServiceImpl.java直接被覆盖，手工逻辑全没了。那一刻真的很绝望。

后来我才知道，t3code 对某些文件类型（比如 Service 实现类）默认行为就可能是覆盖。你有没有办法让它不覆盖？有，但需要你主动在配置里设置“文件保护规则”。具体做法是在模板目录下建立一个类似ignore.txt的文件，把不想被覆盖的文件路径写进去；或者在模板文件名中加上.retain后缀。比如SysOrderServiceImpl.java.retain，生成器看到这个标记后，如果发现目标文件已存在，就直接跳过不覆盖。

这个经验给我上了很重要的一课：任何自动生成工具，合并策略都要提前定义清楚。你要明确区分哪些文件是“完全生成型”的，哪些是“一次性生成”后永远手工改的。宁可多花五分钟做配置，也不要等到代码被覆盖后再去逼着团队着急恢复历史版本。

4.5 多模块项目里“实体类重名”冲突

还有一次，我向一个已有多模块项目里生成新模块时，发现工具检测到两个模块里都叫Order的实体类，直接报错停了。其实这在单体多模块架构里很常见。不同业务域都有“订单”概念，但含义完全不同，比如交易订单和售后订单。如果包名没有区分，生成器生成的类名撞车，编译器也会直接炸。

解决办法有两个，你可以选择其一：第一，在生成配置里为不同模块指定不同的包名，像com.demo.trade.domain和com.demo.afterSale.domain，这样类名就算相同也不会冲突；第二，如果你够看重一致性，可以在表前缀上做文章，比如trade_order、after_sale_order，映射出来的实体类自然是TradeOrder和AfterSaleOrder，彻底杜绝歧义。

工具本身没有智能到能读懂业务边界，所以这类命名规划最好在项目前期就建立规则。业务领域的分寸感，还得靠人类自己把握。

4.6 老生常谈但必须说：生成前备份，生成后查看差异

最后一条不是 t3code 特有的问题，而是所有生成类工具的通病，但我还是想强调一遍。但凡我要对已有工程执行生成命令，一定会在版本管理工具里先把当前分支的干净状态做好提交，或者至少备份一份临时分支。如果生成结果不满意，直接回退重来，比Debug那堆生成代码快太多了。

对于使用 Git 的团队，我建议每次生成时，立即git diff --stat看看改了哪些文件，重点关注是否触碰了不该碰的内容。不一样的地方扫一眼觉得合理再提交，不要闭着眼睛git add . && git commit。工具能提速，但审核的底线永远在自己手里。

5. 高级玩法与团队落地建议：把它从“个人工具”变成“团队基建”

前面聊的更多是个体开发者怎么用 t3code 提效，但如果你把它放到五个人以上的团队里，它的价值还能再上一层楼。前提是，你得把它从“某个人的脚本”升级成“团队的工程基建”。这节分享一些我这边正在实践的进阶用法，以及踩过坑后总结出的管理经验。

5.1 把模板沉淀为团队资产，并纳入版本管理

t3code 的模板既然决定了代码风格，那它就绝不应该只存在某个人的笔记本里。我们团队的做法是，在 GitLab 上单独建一个t3code-templates仓库，所有模板都存放在这个仓库里，走 MR 评审机制。任何人要改模板，先提 Merge Request，其他团队成员 review 通过后才合入。这样大家改模板是有记录有共识的，不会出现“谁手贱改了模板导致全组代码风格漂移”的事故。

这其实跟代码评审的本质一样，只不过我们评审的对象从业务代码变成了模板代码。刚开始大家不太习惯，觉得模板也要评审有点小题大做。但后来一次偶然的模板 bug，差点让全组生成的代码都带上一个低级错误，从那时起，就再也没人嫌模板评审麻烦了。

5.2 定制业务骨架：不只是 CRUD，还要有业务规范

纯 CRUD 只是 t3code 的入门用法。它真正的潜力，在于你能把凡是“重复出现的模式”全部沉淀成模板。比如你们团队的数据权限逻辑，后端的@DataScope注解切面、前端的数据范围下拉框逻辑，这些代码模式几乎每个模块都需要。与其让人肉手写，不如直接做进模板。

我这边后来把“创建人、创建时间、更新人、更新时间”四个审计字段预置进了模板，每个实体都会自动带上审计注解，免去了大量重复劳动。同时，把统一异常处理，全局日志切面也预置到模板里。这些偏底层的基建在普通代码生成器里很难做，因为它们对业务侵入性太强，需要深度定制生成规则，但 t3code 这种强模板方案就能很自然地处理。

5.3 与 CI/CD 流水线整合：从提交到生成的自动化

落地到团队后，我们做了个更大胆的尝试：把 t3code 集成进 CI/CD。流程大概是这样的：开发人员在需求名下把数据库表结构提交到迁移脚本仓库，触发构建后，流水线自动执行 t3code，生成完整工程，然后推送到一个带有generated标签的代码评审分支。开发人员只需要在这条分支上补充业务逻辑，然后发起合并请求即可。

这套流程目前在我们团队还是半自动状态，因为不是所有需求都是纯 CRUD，很多模块涉及复杂的审批流，生成完之后还得手动大改。但即便只解决那些“标准模块”的生成，也把团队事务性工作的耗时至少砍掉了 60%。对于多项目并行、节奏又快的团队，这种自动化能力是很值钱的。

不过我也要泼点冷水。t3code 自动化整合并不适合一上来就全量推广。我见过一个团队，为了追求“全自动生成”，硬是把业务复杂的模块塞进了标准化模板里，结果生成的代码既难用又难维护，最后不得不推倒重来。我建议你从“新模块、新需求”开始推广，让原生适合标准化的业务先跑起来，等团队形成共识、规则稳定后再扩大范围。

5.4 项目演进中的长期视角：生成只是“起点”不是“终点”

最后分享一个我自己的体会。别指望用 t3code 生成了一个模块，这个模块就永远不改了。业务系统是活的，需求总是会变，代码总是会演进。当手工修改与自动生成发生冲突时，你要知道何时停止使用生成器，转回纯手工维护。

我的判断标准是看改动幅度。如果一个模块经历了三轮以上的需求变更，实体字段、查询逻辑、返回结构已经跟原始数据库表结构产生了明显偏差，那我就不再对它执行 t3code 生成命令了。因为此时再生成，带来的不是效率，而是冲突。工具是用在“开荒”阶段的，后续的“种田”还是需要人慢慢耕耘。

意识到这个边界，算是用这类工具比较成熟的心态。我不是要把 t3code 捧上神坛，我只是觉得在合适的时机、合适的范围内，它能给你省下的时间确实非常可观。关键是你要明白：工具帮你完成的是“量”的工作，而“质”的把关永远在你自己手里。