做后端开发这些年我越来越发现一个规律真正浪费时间的往往不是复杂的业务逻辑而是那些结构高度雷同、字段来回搬的样板代码。DTO、VO、Entity、Mapper接口、XML映射文件翻来覆去就是增删改查加分页。后来我把几十个表的手写时间从两三天压缩到半小时靠的就是自己做了一个模板代码生成工具。这东西没有高深的技术含量但设计思路和踩坑经验很值得聊聊。无论你是想给团队搞一个统一的生成脚手架还是想把手头重复劳动自动化这篇文章都能提供一条可以直接落地的实践路径。1. 先想清楚什么样的代码适合交给模板什么样的不适合模板代码生成工具不是银弹。我见过不少人拿到这种工具之后试图用它生成所有代码结果业务一复杂生成的代码反而成了最大的维护负担。所以在动手做工具之前先要把边界划定清楚哪些代码适合生成哪些代码必须手写。1.1 适合生成的“三高”代码长什么样适合模板生成的代码通常有三个特征高重复、高结构、高字段驱动。高重复意味着同一个模式在项目中会出现几十次比如每个数据库表都要对应一套DTO、Service、Mapper高结构意味着代码的组织方式可以被一套固定规则描述比如所有Mapper接口都遵循“接口名 泛型实体 基础CRUD方法”的套路高字段驱动意味着核心差异点集中在字段名、字段类型、表名这些元数据上把这些元数据抽出来模板负责套壳即可。举一个最典型的例子从一张表生成Java三层代码。表结构里有表名、字段名、字段类型、注释、主键信息这些就是元数据。模板里写死类声明、注解、方法骨架元数据填入之后一个Entity类、一个Mapper接口、一个XML文件就出来了。这类代码根本没有手写的必要交给工具生成又快又不会漏字段。再比如前端页面列表页加表单页的骨架几乎一模一样无非是字段不同。用模板生成初始版本再在产物基础上调整样式和交互效率会高出很多。1.2 不适合生成的代码别指望模板帮你写业务有高重复就有高变化。一段代码如果包含复杂的业务校验、多分支状态流转、外部系统联动或者涉及领域模型的深层行为把它交给模板生成就是一个灾难。举个例子订单状态机这种代码每个状态之间的流转规则都不同有的状态需要校验库存有的需要回调外部支付系统有的需要触发消息通知。你没法用一套模板去描述这种逻辑强行适配只会让模板变得无比庞大、参数满天飞最后生成的代码还得大幅修改。我个人的判断标准很简单如果一段代码里超过三分之一的部分会因为业务规则而变化那它就该手写如果变化只发生在字段清单和命名上那模板生成就是首选。模板工具适合做“骨架”不适合做“血肉”。2. 从需求到架构一个模板生成工具的核心链路明确了边界之后就可以设计工具本身的架构了。一个完整的模板代码生成工具无论如何包装内部的链路都逃不开三件事准备元数据、编写模板、调用渲染引擎输出文件。理解这条链路是动手写代码前的必修课。2.1 元数据建模模板生成器的第一块地基元数据就是模板要消费的数据。在你写模板之前必须先想清楚模板里需要哪些变量这些变量从哪里来。最常用的元数据来源是数据库表结构。表名、表注释、每个字段的名称、类型、默认值、是否主键、是否可空、字段注释这些信息可以从数据库的系统表中查出来。我的工具最初版就是连上数据库读取这些信息封装成一个“表对象”。这个阶段最大的坑是命名风格的转换。数据库字段通常是snake_caseJava类属性通常是camelCase。比如数据库里的user_nameJava里要变成userName。而这些转换规则必须在元数据准备阶段就完成不能在模板里写一堆处理函数否则模板会变得一团乱麻。我通常会构建这样的元数据模型表名、表注释、类名首字母大写驼峰、字段列表每个字段包括数据库列名、Java属性名、Java类型、注释、是否主键。有了这个模型模板里就可以像写普通代码一样引用变量而不是到处拼字符串。2.2 模板语言选型6个常见引擎的取舍模板引擎是这个工具的渲染核心。市面上的模板引擎很多选型主要看你的生成目标和团队技术栈。我自己接触过的方案里有几个可以作为参考。Freemarker是Java后端生态里常用的选择语法成熟逻辑标签丰富适合生成Java、XML这类结构文件。Velocity和Freemarker类似但现在维护状态一般新项目不太推荐。Thymeleaf偏向Web渲染做代码生成反而有点大材小用。Go Template适合用Go写的工具链EJS和Handlebars适合前期它们语法简单对前端开发者友好。我自己最终选择了Freemarker。原因很实际它的空值处理、循环、条件判断语法都比较顺手而且对中文注释的兼容性做得不错。不过这不是唯一答案你完全可以根据自己最熟的生态选。选型时给你一个参考维度看模板里到底要写多少逻辑。如果只是简单的变量替换用哪个都行如果需要循环生成字段列表、需要条件判断跳过某些字段那模板引擎必须支持这些控制结构否则你只能在准备阶段把所有逻辑都算好得不偿失。2.3 渲染引擎之外目录规划、命名规则和输出结构模板负责生成文件的内容但文件要放在哪个目录、叫什么名字同样是生成工具的核心能力。很多人做生成工具只关注模板内容忽略了路径规划最后生成的代码要么全部堆在一个目录要么命名混乱需要手动移动。一个成熟的工具至少要做到根据元数据拼接目标文件路径比如接口生成到service/api目录实现类生成到service/impl目录根据模板类别决定文件后缀比如.java、.xml、.vue同一个表多次生成时自动覆盖旧文件同时保留人为修改过的区域。这些能力听起来琐碎却是工具能否真正用起来的关键。我见过很多生成项目死于“生成一时爽整理两小时”。3. 实战写一个“数据库表 - Java三层代码”的生成器理论说得再多不如看一份能落地的代码。下面我以“读取数据库表结构生成Java的Entity、Mapper接口、Mapper XML、Service接口”为例完整走一遍实现流程。这一节的代码是实际可运行的简化版本重点是让你看到元数据、模板、渲染如何串起来。3.1 第一步抽取表结构元数据先写一个元数据读取类用JDBC连接数据库读取表信息和列信息。这里我以MySQL为例逻辑非常直白。public class TableMetaReader { public TableInfo read(String tableName) { TableInfo tableInfo new TableInfo(); tableInfo.setTableName(tableName); tableInfo.setClassName(toCamelCase(tableName, true)); try (Connection conn DriverManager.getConnection(url, user, password)) { DatabaseMetaData metaData conn.getMetaData(); ResultSet columns metaData.getColumns(null, null, tableName, %); while (columns.next()) { FieldInfo field new FieldInfo(); field.setColumnName(columns.getString(COLUMN_NAME)); field.setComment(columns.getString(REMARKS)); field.setJdbcType(columns.getString(TYPE_NAME)); field.setJavaType(jdbcTypeToJavaType(field.getJdbcType())); field.setFieldName(toCamelCase(field.getColumnName(), false)); tableInfo.addField(field); } } catch (SQLException e) { throw new RuntimeException(读取表结构失败: tableName, e); } return tableInfo; } }这里面最核心的两个私有方法toCamelCase负责把user_name转成userName或UserNamejdbcTypeToJavaType负责把数据库类型映射成Java类型比如VARCHAR映射String、BIGINT映射Long、DATETIME映射LocalDateTime。类型映射表建议做成可配置的因为不同团队的字段规范不同。有人喜欢用BigDecimal存金额有人用Long存分这些映射规则如果不做成配置每换一个项目就要改源码。3.2 第二步设计模板变量与动态片段元数据准备好之后写模板就变成一件很舒服的事。下面是一段生成Entity类的Freemarker模板片段你可以直观感受一下变量是怎么被使用的。package ${packageName}.entity; import java.time.LocalDateTime; /** * ${tableComment} */ public class ${className} { #list fieldList as field /** * ${field.comment} */ private ${field.javaType} ${field.fieldName}; /#list #list fieldList as field public ${field.javaType} get${field.fieldName?cap_first}() { return this.${field.fieldName}; } public void set${field.fieldName?cap_first}(${field.javaType} ${field.fieldName}) { this.${field.fieldName} ${field.fieldName}; } /#list }这里用了两个Freemarker核心语法#list循环遍历字段列表?cap_first把属性名的首字母转大写用于拼接getter/setter方法名。包名、类名、字段类型、字段注释全部来自元数据对象模板里一个Java代码都没有写只有代码的“壳”。实际模板里还会有更多条件判断比如该字段是主键时加上Id注解字段类型是LocalDateTime时导入java.time包。为了控制篇幅这里只展示主脉络。3.3 第三步批量渲染并落盘元数据有了模板有了就差把两者揉在一起输出文件。这一步就是生成工具的运行时也是离“一键生成”最近的地方。public class CodeGenerator { public static void main(String[] args) throws Exception { Configuration cfg new Configuration(Configuration.VERSION_2_3_32); cfg.setDirectoryForTemplateLoading(new File(templates)); cfg.setDefaultEncoding(UTF-8); TableMetaReader reader new TableMetaReader(); ListString tables List.of(sys_user, sys_role, sys_menu); for (String tableName : tables) { TableInfo table reader.read(tableName); MapString, Object data new HashMap(); data.put(packageName, com.example.demo); data.put(tableComment, table.getTableComment()); data.put(className, table.getClassName()); data.put(fieldList, table.getFieldList()); Template entityTemplate cfg.getTemplate(entity.ftl); File outputDir new File(output/ table.getClassName()); outputDir.mkdirs(); try (Writer out new FileWriter(new File(outputDir, table.getClassName() .java))) { entityTemplate.process(data, out); } // 同样的方式渲染 Mapper、XML、Service ... } } }这段代码的意图很清楚指定模板目录、指定要生成的表清单、循环读取每张表的元数据、放入数据模型、逐个渲染模板并写到output目录。把表清单换成“读取某库全部表”就是一个批量生成所有表的完整工具。注意这里有个容易忽略的细节Writer必须指定编码。如果用系统默认编码Windows环境很容易生成出乱码文件。所有涉及文件读写的操作都建议显式传入UTF-8。3.4 生成的产物长什么样生成完之后打开文件应该和手写代码几乎一致。下面是sys_user表生成的Entity和Mapper接口节选你可以对比一下自己的手写习惯。package com.example.demo.entity; import java.time.LocalDateTime; /** * 系统用户表 */ public class SysUser { /** * 用户ID */ private Long userId; /** * 用户名称 */ private String userName; /** * 创建时间 */ private LocalDateTime createTime; public Long getUserId() { return this.userId; } public void setUserId(Long userId) { this.userId userId; } }package com.example.demo.mapper; public interface SysUserMapper { int insert(SysUser record); int deleteById(Long userId); int updateById(SysUser record); SysUser selectById(Long userId); ListSysUser selectList(SysUser query); }看到这里你应该能明白生成模式的核心价值就是把这些“一眼就能写”的代码变成“一点就出来”。“一眼就能写”不代表该手写当数量从1个表变成50个表时这个区分的必要性会非常清晰。4. 真实项目里的三次迭代从一次性脚本到团队通用工具一个工具从“自己能跑”到“团队能用”之间往往隔着很长的路。我自己的生成工具经历了三次比较大的迭代每一次迭代都对应一类真实痛点拿出来说说帮你少走弯路。4.1 第一版能跑就行启动最快的脚本第一版工具和上面示例差不多只有一个入口写死了一连串表名生成到output目录。用起来需要改代码但自己用得挺爽。这一版的教训很明确代码写死导致可复用性几乎为零。比如换个数据库要改连接串换个包名要改模板换个项目整个工具重写。第一版存在的意义只在于验证“模板 元数据 渲染引擎”这条路是否走得通。能走通就够了。这个阶段如果非要谈经验那就是“不要一上来就做配置系统”。先把核心链路跑通确认生成结果符合预期再考虑外部化配置。过早的抽象和配置化只会拖慢启动速度还会让你失去验证核心想法的窗口期。4.2 第二版类型映射和可配置字段解决“一半时间花在改生成结果”的问题第二版的主要矛盾是生成的代码能用但总有一部分需要手动改。最常见的是Java类型映射不对比如数据库DECIMAL映射成了BigDecimal团队实际用Long还有包名、作者信息、类上注释的格式都需要调整。我把这些内容全部搬到配置文件里做成了一个项目级的生成配置。配置文件里可以指定连接信息、需要生成的表清单或排除清单、包名、作者名、类型映射规则、是否生成XML、是否生成Service。这一版之后不同项目只要复制一份配置改几行即可。配置前置化的收益很清楚——把“个人的偏好”从代码里抽出来变成项目的一部分。团队里每个人跑出来的结果才能真正统一。4.3 第三版区分生成区与手写区解决“生成后不敢改”的窘境第三版解决的是我自己最头疼的问题生成的代码要不要手改实体类还好Mapper接口也勉强能忍但XML映射文件几乎一定会手写补充复杂查询。问题在于一旦手写了下一次重新生成就会把这些手写内容覆盖掉你唯一的出路是“生成之后绝不重跑”这样工具就变成了只能使用一次的消耗品。我的解法是在模板里显式区分两个区域生成区由工具完全控制手写区是预留的自定义区域。以XML文件为例模板会生成这样一个结构。!-- 自动生成区域重新生成将被覆盖 -- select idselectById resultType... select * from sys_user where user_id #{userId} /select !-- 手写区域重新生成时请保留 -- select idselectByCustomCondition resultType... !-- 手动补充的复杂查询写在这里 -- /select然后在渲染完成后工具扫描旧文件只替换自动生成区域保留手写区域。这个能力并不复杂本质是读取旧文件截取两个标记之间的内容重新拼接覆盖。有了这个机制之后重新生成才变成一件“安全”的事。你会愿意在表结构新增字段后重新跑一遍生成器而不必担心丢失任何手工劳动成果。5. 把生成能力变成“团队基础设施”要越过的坑当工具从个人脚本变成团队基础设施的时候遇到的问题就不再只是技术问题还包括代码审查、协作流程和规范化约束。这几个坑我都是亲眼见过、亲手踩过的。5.1 模板库和生成器本身也要走版本管理与评审团队里一旦多人使用生成工具模板代码就相当于“元代码”——它生成的是其他代码的母版。如果没有评审机制任何人对模板的一次“随手修改”都会影响后续所有人生成出来的代码质量。我见过最典型的事故有人在模板里给全局方法加了一个默认参数出发点是给某个特定模块用的结果其他模块重新生成后全部带上了这个参数编译错误一片。模板代码必须和被生成代码一样走严格的评审流程最好专门建一个代码仓库管理模板和主项目仓库分离单独设置修改权限。5.2 “可重复执行”比“一次性生成”更重要工具设计里有两条路一次性生成后不再回头和反复执行保持幂等。我强烈建议所有生成工具都朝着“可重复执行”的方向设计。怎么做到可重复执行核心是让生成操作保持确定性同样的输入元数据无论执行多少次产出必须一致生成前如果检测到旧文件必须明确覆盖策略生成结果和手写代码的边界必须清晰不能出现“这次跑完文件变了下次跑完又变回去”的不稳定状态。为了做到这一点我对所有模板做了快照测试预先准备一批固定的元数据样本执行生成对比输出的文件的哈希值每次都一致才算通过。这就是“生成器自己的回归测试”。5.3 数据源校验和非法输入生成工具也要有防御性生成工具的输入往往来自数据库的表结构或者外部传入的元数据这些数据默认不可信。比如表名里如果包含异常字符生成的Java类名轻则不符合代码规范重则连编译都过不了。又比如字段注释里可能包含半角引号直接拼进注释会破坏代码字符串。我后来在模板里对所有动态文本做了转义处理尤其是SQL脚本和一些XML文件防止特殊字符破坏文件结构。如果你生成的代码会被继续编译或部署那这就是一个安全问题而不仅是格式问题。生成出的文件必须保证“输入的是正常元数据吐出来的一定是合规代码”。在这方面花再多时间都不亏。6. 几个我反复验证过的落地建议文章最后一部分分享几个我自己反复验证过的小经验不算什么高深理论但直接影响使用体验。第一个建议是模板风格不要追求“完美”而是追求“贴近团队现有代码”。一开始我写模板时把生成的代码规划得非常理想化结果发现团队里老项目的风格完全是另一回事。后来我把模板改成对齐老项目风格甚至保留了原有的类注释格式生成的代码融进项目之后违和感为零代码评审也顺利了很多。第二个建议是生成工具一定要有“日志”和“预览”能力。日志要能告诉你这次生成了哪些文件、覆盖了哪些文件、哪些字段被跳过预览最好是能对比新旧文件之后再把修改落盘。有了这两样大家在跑工具之前会更有安全感尤其当它被集成到CI流程里时。第三个建议是先做一个小而垂直的场景不要一上来就想着“支持所有代码类型”。我最初只做Entity生成后来加Mapper再后来加XML和Service。每一次新增模板类型都先把生成的产物拿到真实项目里用上一周确认没有问题了再开放给团队。这种增量式的推进方式能帮你控制工具的复杂度。最后一个大实话模板代码生成工具最值钱的不是代码本身而是“对项目结构的抽象能力”。你会越来越清楚在一个项目里哪些东西是结构性的哪些是语义性的哪些可以交给模板哪些必须留给人手。这种判断能力比任何具体的模板语法都管用。我自己这几年最大的体会是生成工具应该让你讨厌的那部分工作变快而不是让你喜欢的业务编码变少。它节省下来的时间最终都花在了更有意思的复杂问题上了。如果你正在筹划类似的工具希望这篇分享能帮你明确边界、避开暗坑把一个真正可靠的代码生成基建搭起来。