我最早认真研究模板代码生成不是跟风也不是为了写文档而是被项目里的重复劳动逼的。那会儿团队里接一个微服务模块就要手动搭 Controller、Service、Mapper 三层结构增删改查、分页、批量操作代码长得都差不多改个字段名还得全文扫一遍。加班到凌晨两点之后我彻底想清楚了一件事模板代码生成的本质其实就五个字——模板 数据 渲染。把代码里变的部分抽象成变量把不变的部分固化成模板运行时塞进真实数据一个文件就出来了。这篇文章我想把这条原理掰开揉碎讲透从模板引擎的底层工作流程到我自己写的迷你生成器再到工程落地时的选型、配置和坑适合那些要搭脚手架、做低代码平台、或者单纯想告别无脑复制粘贴的朋友。1. 模板代码生成是什么为什么绕不开它1.1 我真实遇到的一次重复劳动场景我记忆最深刻的一次是做订单中台的某个子模块。订单表、订单明细表、支付记录表、退款单表一共四张表我要为每张表写一套 Controller、Service、Mapper 和对应的 XML。单是样板代码就写了接近上千行每张表的增删改查逻辑一模一样区别只有表名、主键类型和几个字段。写完一张表复制一份把 User 改成 Order把 Order 改成 OrderItem再改掉方法名和返回类型循环四遍。这种活做多了人会进入一种机械状态。最危险的是全局替换有一回我用编辑器全局替换 UserId 为 OrderId结果把订单表的主键字段也一起替换了编译才发现。那种低级错误不是不细心而是这种工作根本不该让人来做。当时我就想如果有工具能告诉我“结构已经固化了你只要提供字段清单、包名、实体名”我就能把时间省下来去写真正有难度的东西。这个想法其实就是模板代码生成最初的动机。后来我去翻开源脚手架和代码生成器的源码发现那些看起来很高端的工具核心也就一层窗纸先写一个模板文件把代码里那些会变的东西挖空再用运行时数据把这些空填回去。明白这一点之后我再看任何生成器都不觉得神秘了。1.2 模板代码生成的本质模板 数据 渲染模板代码生成这个名字容易给人造成误解乍一听好像是很复杂的人工智能生成代码其实不是。它的核心模型非常简单模板固化的结构 数据变化的参数 输出文件成品代码打个比方模板就是老师发下来的填空题试卷试卷上印好的部分是结构挖空的部分是不能确定的内容。数据模型就是老师手里的标准答案渲染过程就是监考老师把答案填进空里。整张试卷填完就是你最终要的成品。代码生成器本质上就是一个自动“填答题卡”的机器。为什么这套思路能解决重复劳动因为它把“重复”和“变化”强制分开了。重复的部分永远留在模板里只写一次比如包声明、类声明、注解引入、方法签名变化的部分全部作为变量暴露给调用方比如实体名、字段名、字段类型、主键命名。你不再需要为了一个新表复制 100 行代码然后肉眼找差异只需要准备一张表的元数据字典生成器把数据填进模板字段怎么变都由模板规则控制。这也是为什么同一个模板引擎能同时生成 Java、Python、SQL、前端表单因为引擎本身不关心业务它只负责处理文本结构。你给它什么样的模板和数据它就给你什么样的文件仅此而已。1.3 它能解决什么不能解决什么模板代码生成能解决的东西必须满足一个前提输出结果有明确规律。最典型的就是 CRUD 代码其次是 Mapper XML 的 resultMap、insert 语句里的字段列表还有配置中心的 yaml 片段、数据字典的枚举类、接口文档字段说明、DTO 的 getter/setter。这些内容高度结构化几乎没有创造性差异人写和机器写结果完全一样。它不能解决的是强业务逻辑部分。比如审批流的节点跳转、状态机的状态迁移、复杂的规则引擎条件分支这些需要根据业务上下文做判断的地方模板生成的充其量是个骨架真正的血肉必须由人手工补上。所以工程化的生成器都会留一个扩展口有的叫 afterGenerate 钩子意思是模板生成文件之后允许你继续用脚本往文件里追加自定义逻辑。做生成器设计的时候一开始就承认“模板不是万能的”反而会让这个工具活得更久。不要指望着一个模板消灭所有手写这不现实。2. 核心原理模板引擎是怎么把文本变成代码的2.1 三个核心阶段解析、编译、渲染模板代码生成的“发酵车间”就是模板引擎只要理解了引擎就理解了所有生成器。市面上的模板引擎五花八门底层工作过程大致一致分三步解析阶段读入模板原始文本按语法规则把一串字符切分成 token。比如{{ name }}这是一个变量 token{% for item in list %}这是一个循环指令 token普通文本是文本 token。编译阶段把 token 组织成节点树也叫 AST。这一步是把“模板文本”变成“可执行结构”的关键。有的引擎还会再进一步把 AST 编译成字节码或类文件。Jinja2 会把模板编译成 Python 字节码FreeMarker 会在首次加载时把模板编译成 Java 类Vue 的模板编译器也是这个思路。渲染阶段拿到数据模型后深度遍历节点树把变量节点替换成实际值把循环节点照着列表重复展开把条件节点根据真假决定是否输出子节点最终把所有节点的输出拼接成一个字符串或一个文件。把上面这个过程套到一张试卷上解析就是读题标出哪些地方要填、哪些是固定段落编译就是把这张试卷改造成答题卡渲染就是在答题卡上往里填字然后交卷。理解这三个阶段最大的价值是你能分清“慢在哪里”。如果每次渲染都要重新解析和编译模板那性能肯定上不去。所以高效引擎都会做模板缓存第一次解析编译之后把 AST 或字节码缓存起来第二次请求直接进入渲染阶段。这个缓存策略在生成器工程里是必须考虑的参数我在第 4 章会专门讲。2.2 指令系统插值、判断、循环的底层逻辑模板引擎的语法看起来五花八门但指令类型翻来覆去就三种插值、判断、循环。只要吃透这三种指令在编译阶段被翻译成什么样子你就掌握了模板代码生成的核心。先看一段常见的模板语法{{ user.name }} {% if user.enabled %} 用户已启用 {% endif %} {% for role in user.roles %} {{ role.name }} {% endfor %}第一行是插值表达式编译期会生成一个变量节点节点的表达式是user.name。渲染这个节点时引擎会拿着 key 去当前上下文中取值先取user再取name。如果取到值就转成字符串输出取不到则走空值策略。第二段是判断指令编译期生成一个条件节点表达式是user.enabled条件节点的子节点是那个“用户已启用”文本。渲染逻辑很简单表达式结果是真就渲染子节点是假直接跳过。第三段是循环指令编译期生成一个循环节点。这个节点的设计非常巧妙它把自己包裹的那段 body 变成子节点列表渲染时拿到user.roles这个可迭代对象每遍历出一个元素就重新建立一层子上下文把当前元素绑定到循环变量名role上然后让子节点在这个新上下文里渲染一遍。所以你看抽象一点说模板引擎就是一个“节点树遍历器”指令节点是带逻辑的节点文本和插值节点是普通叶子节点。你写模板的时候是在写树的语法引擎做的事情是把树翻译成输出。2.3 数据绑定与上下文user.name 是怎么取到的模板里写user.name看着简单背后其实是数据绑定机制。渲染上下文是一个类似 Map 的命名空间也可以理解成作用域链。当引擎渲染变量节点时它会把表达式user.name按点拆成两段先在上下文中找user拿到结果之后再拿name去取属性。如果user本身是 Java Bean 或 Python 对象就反射调用 getUser() 或直接访问 name 属性如果user是 Map就用 get(name)。这就是为什么 FreeMarker 的数据模型既可以塞 Map 也可以塞普通 Java 对象。作用域链是这个机制里很容易被忽视的点。循环节点内引擎创建了一个新的子上下文而子上下文外层仍然是主上下文。这意味着模板里在 for 循环内可以访问外层变量也能用循环变量覆盖外层同名变量。大多数引擎在这个覆盖行为上是一致的循环结束后覆盖消失外层的值恢复。另外数据绑定不止是取值还支持注入函数和过滤器。比如在 Java 模板里写name?cap_first这个cap_first实际上就是一个被注入上下文的字符串处理函数。工程化的代码生成器非常依赖这一点因为生成代码经常要对字段做命名转换驼峰、下划线、首字母大写都靠注入的辅助函数实现。理解了数据绑定你就明白了为什么模板不能直接访问运行环境里的任意对象所有能用的变量和函数都必须由渲染方显式塞进上下文。3. 从模板引擎到代码生成器一个能跑的迷你实现3.1 为什么我建议你亲手写一遍市面上现成的模板引擎已经非常成熟按理说不需要自己重复造轮子但我还是建议你亲手写一个最简版的。原因很简单原理解得再清楚不亲眼看着自己的代码把字符串变成文件总觉得那层东西还是别人的。我自己第一次写迷你模板引擎的时候写了一下午代码不到两百行但写完之后再看 FreeMarker 的模板缓存、空值处理、宏定义都突然通了。因为你知道它大概在什么位置做了什么事情阅读官方文档就像在复习自己设计过的东西。接下来我给出的实现是我实际写过的版本稍作简化的结果它不支持复杂继承不支持宏只支持插值、条件、循环但足够演示完整原理。3.2 最小实现tokenize 与 parse第一步是解析。我用一个正则把模板切成三类 token纯文本、{{ ... }}插值、{% ... %}指令。正则用带捕获组的方式 split这样匹配到的 token 会保留在结果列表里。import re TOKEN_RE re.compile(r(\{\{.*?\}\}|\{%.*?%\}), re.DOTALL) def tokenize(template): parts TOKEN_RE.split(template) return [p for p in parts if p ! ]有了 token 列表之后parse 函数负责把它们组装成节点树。这里我用一个栈来处理嵌套的 for 和 if遇到{% for %}就创建一个 ForNode把后续的节点都挂到它下面直到遇到{% endfor %}才结束嵌套。下面是我实现的节点类骨架class TextNode: def __init__(self, text): self.text text def render(self, context): return self.text class VarNode: def __init__(self, expr): self.expr expr.strip() def render(self, context): value resolve(self.expr, context) return if value is None else str(value) class ForNode: def __init__(self, var_name, items_expr, children): self.var_name var_name self.items_expr items_expr self.children children def render(self, context): items resolve(self.items_expr, context) or [] buf [] for item in items: ctx dict(context) ctx[self.var_name] item for child in self.children: buf.append(child.render(ctx)) return .join(buf) class IfNode: def __init__(self, cond_expr, children): self.cond_expr cond_expr self.children children def render(self, context): if resolve(self.cond_expr, context): return .join(c.render(context) for c in self.children) return 你仔细看 ForNode 的 render它做的事就是我在第 2 章讲的循环节点逻辑取出可迭代对象遍历给每一项建立子上下文重新渲染子节点。一共就这几行代码但这就是整个循环指令的真相。3.3 最小实现render 与节点类接下来是 resolve 函数和 parse 主逻辑。resolve 处理带点的表达式比如user.name就按点拆开一层层在当前上下文里取def resolve(expr, context): current context for key in expr.split(.): key key.strip() if isinstance(current, dict): current current.get(key) else: current getattr(current, key, None) if current is None: return None return current def parse(tokens): root [] stack [(None, root)] for token in tokens: stripped token.strip() if stripped.startswith({%): inner stripped[2:-2].strip() if inner.startswith(for ): parts inner.split() children [] stack[-1][1].append(ForNode(parts[1], parts[3], children)) stack.append((ForNode, children)) elif inner.startswith(if ): children [] stack[-1][1].append(IfNode(inner[3:].strip(), children)) stack.append((IfNode, children)) elif inner in (endfor, endif): stack.pop() elif stripped.startswith({{): stack[-1][1].append(VarNode(stripped[2:-2])) elif token: stack[-1][1].append(TextNode(token)) return stack[0][1] def render(template, context): return .join(node.render(context) for node in parse(tokenize(template)))整个实现就结束了。它没有模板缓存没有宏没有空白控制但它的完整工作链路和主流引擎是一样的切 token、建节点树、遍历渲染。你可以拿这个实现去跑一下最简单的模板看看输出结果再看 FreeMarker 的文档会更有实感。3.4 用它生成一个 Controller 和 DTO光有引擎还不够模板代码生成必须有实际业务模板。我拿这个迷你引擎生成了一个 Spring Controllertemplate package {{package}}; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/{{entity_lower}}) public class {{entity}}Controller { private final {{entity}}Service service; public {{entity}}Controller({{entity}}Service service) { this.service service; } GetMapping public {{entity}} get(RequestParam Long id) { return service.get(id); } PostMapping public {{entity}} create(RequestBody {{entity}} entity) { return service.create(entity); } } context { package: com.example.demo.controller, entity: User, entity_lower: user, } print(render(template, context))输出就是一个完整可编译的 Java 类包名、类名、方法签名全部填好。你再换一组数据比如传entityProduct、entity_lowerproduct生成的代码就会自动变成 ProductController。这就是模板代码生成最日常的用法。控制器只能展示插值我们再写一个 DTO 字段生成的模板让循环也参与进来dto_template public class {{entity}}DTO { {% for field in fields %} private {{field.type}} {{field.name}}; {% endfor %} } dto_context { entity: User, fields: [ {type: Long, name: id}, {type: String, name: userName}, {type: Integer, name: age}, ], } print(render(dto_template, dto_context))输出结果正好是三个 Java 成员变量字段顺序和 fields 列表一致。这个顺序其实是很有讲究的如果这个模板被用来生成 Mapper XML 的 resultMap字段顺序一变整个映射就乱了我在第 5 章会具体说这个坑。3.5 从玩具走向工程还需要补哪些环节上面的实现能跑通原理但如果拿去做真正的脚手架生成器还差得很远。我归纳了四个必须补的工程环节。文件系统操作是第一个。真实的生成器不是把结果 print 到控制台而是要按照目标工程结构创建目录、写文件。模板文件和输出路径之间通常有一套映射规则比如 template/controller/EntityController.java.ftl 对应输出到 src/main/java/com/example/controller/EntityController.java。批量渲染是第二个。一个模块往往需要同时生成 Controller、Service、Mapper、XML 多个文件生成器要遍历模板目录对每个模板执行渲染然后按映射规则落盘。这里要做好失败处理不要让生成到一半的脏文件留在工程里。变量约定是第三个。实体表 user_info 生成 Java 类时应该是 UserInfo生成路径变量时是 userInfo生成数据库字段时是 user_info生成文件前缀时是 userInfo。这些转换规则必须统一封装不能在每个模板里各自写一遍。幂等保护是第四个也是我觉得最重要的一点。同一个模板、同一份数据重复跑生成器最终产物应该完全一致。如果模板没变第二次生成就应该跳过或者直接覆盖成相同内容不能出现“第一次生成和第二次生成结果不同”的情况。很多团队成员不愿意用代码生成器就是因为生成器跑一次改一批文件Git 差异满天飞吓人。4. 工程落地模板引擎选型与关键配置4.1 主流模板引擎横向对比模板引擎的选型本质上是选语言生态和语法能力。我把几个主流的整理成了表格方便对照引擎语言生态特点典型场景注意点FreeMarkerJava类型严格、功能全、可嵌 Java 代码大型代码生成器、低代码平台空值默认报错需要显式配置VelocityJava老牌、语法简单老项目维护性能一般、社区已冷ThymeleafJava标签语法直白、与 HTML 亲和Web 页面渲染默认自动转义生成代码时要关Jinja2Python灵活、空白控制好、支持模板继承Cookiecutter 脚手架、配置生成对缩进敏感的模板要留意空白符Go templateGo标准库自带、无第三方依赖CLI 工具、云原生脚手架内置函数少复杂逻辑困难从我自己用过的感受说Java 生态里 FreeMarker 是生成器首选因为它的数据类型更严谨模板里能拿到真正的 Java 对象字段类型判断、泛型处理都比 Velocity 方便太多。Velocity 胜在简单但简单也意味着限制稍微复杂点的逻辑就得往数据模型里塞大量计算好的东西模板本身失去了表现力。Python 生态的 Jinja2 在脚手架生成场景里几乎是事实标准Cookiecutter 底层就是它。它的空白控制符{%- -%}非常实用生成对缩进敏感的 Python 代码时好用。Go 生态的 template 如果你只是做一个命令行工具能少装一个第三方依赖就少装一个但它的函数集很基础稍微复杂点的字符串变换就要自己注册方法。4.2 生成代码时必须盯紧的四个配置无论选哪个引擎有四件事必须在动手写模板前定好。第一件是空值处理策略。FreeMarker 默认对空值抛异常Jinja2 默认渲染空字符串或者字符串 None这两个行为天差地别。写 Java 生成器时就容易遇到实体字段为空直接渲染失败的情况条件分支里的空对象访问尤其要小心。我的习惯是模板里做统一兜底使用name!或name|default()不要让模板引擎自己发挥。第二件是自动转义。很多模板引擎有个贴心设计默认把输出内容做 HTML 转义防止 XSS。但模板代码生成不是渲染网页我们需要的是原样输出。如果忘了关掉自动转义生成的 Java 代码里的泛型尖括号会被转成lt;gt;直接编译失败。代码生成场景必须显式设置 Text 模式或者在表达式上加 no_escape 过滤。第三件是空白控制。模板文件里指令标签所在的那一行渲染后往往会残留多余的空行和缩进。前面提到 Jinja2 用{%-和-%}控制空白FreeMarker 可以用#compress包裹代码段或者干脆在写模板时把指令和文本放在同一行来规避。这个东西很小但影响观感生出的代码如果缩进乱七八糟同事不会来怪引擎只会怪你。第四件是模板缓存。服务端渲染场景里模板缓存是性能利器但代码生成器场景里反而容易造成困惑。如果你在开发调试生成器改完模板后渲染结果没变十有八九是缓存没关。工程上的建议是开发环境关缓存生产环境开缓存并配合模板文件 mtime 校验保证模板更新能及时生效。4.3 编码、命名与文件结构规范模板代码生成还有一个特别容易被忽略的领域编码。我踩过一次很深的坑生成的 Java 文件中文注释全部乱码排查半天发现模板文件是 UTF-8输出文件也写了 UTF-8但代码里读取模板时用了系统默认字符集Windows 下是 GBK直接就乱了。推荐做法是全链路统一 UTF-8模板、代码读取、FileWriter所有环节都显式指定编码不要依赖系统默认值。命名转换是代码生成器的“翻译官”。你手里最原始的数据通常是数据库表字段比如user_name生成 Java 属性要变成userName生成类名要变成UserInfo生成 XML 字段要保持user_name生成前端表单 label 又要变成“用户名”。这些规则一定要收敛到几个纯函数里比如snakeToCamel、snakeToPascal、toPlural模板里只调用函数名不直接写转换逻辑。文件结构规范上每个生成模块的输入输出目录要保持一致。模板放哪个目录生成结果放哪个目录子目录结构怎么映射这些规则在项目文档里写清楚。最怕的是生成器项目跑起来之后模板目录混乱谁也不知道 Entity.java.ftl 在哪里那这个工具很快就会被团队弃用。5. 常见问题与排查技巧实录5.1 渲染后全是空行和多余缩进这是新手玩模板代码生成遇到的第一个“鬼打墙”。模板明明写着很整齐渲染出来的文件却到处都是空行。原因其实很简单模板里指令标签自身占了行渲染后指令被移除但那一行的换行符留了下来。比如这样一段public class {{entity}} { {% for field in fields %} private {{field.type}} {{field.name}}; {% endfor %} }for 那行删除后留下一个空行endfor 那行又留下一个空行中间字段越多空行越密集。解决办法按引擎分。Jinja2 用{%- for ... -%}把指令周围空白吞掉FreeMarker 可以打开 whitespace stripping让纯指令行自动剥离或者把循环指令和文本内容放在同一行写。我这里给一条判断标准生成出来的代码每一行都必须是由模板里的文本 token 主动产生的输出指令标签本身不应该产生任何空白凡是管不住这个的模板写法都要改。5.2 变量找不到输出 “None/null” 或直接报错变量取不到值是第二高频的问题。现象分两种Jinja2 那边经常渲染出一个字符串 “None”FreeMarker 那边干脆抛异常说 “The following has evaluated to null or missing”。这个问题的根源绝大多数不是模板写错而是数据模型和模板的约定不一致。模板里写user.name你数据里塞了一个空 user或者字段名拼写不一致引擎取不到自然会走空值策略。调试思路很简单在渲染入口把 context 打出来肉眼核对一遍 key 的层级结构基本一眼就能看出问题。还有一种隐蔽情况是对象属性是 null但引擎不会继续往里取。比如user.address.city如果 user 有值、address 为 nullJinja2 返回空你继续写city就会在 address 这个位置断掉。工程上我建议把嵌套取值拆开每层都用默认值兜底宁可模板啰嗦一点也不要让它运行时崩。5.3 循环 Map 时顺序乱套、字段错位用模板代码生成 DTO、Mapper XML 的时候字段顺序非常关键。很多人给引擎传一个 Java HashMap 当 fieldMap模板里用循环遍历生成出来的字段顺序和自己定义时完全不一样一会儿 id 跑后面去了一会儿 createTime 跑前面来了没有任何记忆逻辑。原因不用怀疑HashMap 本身不保证顺序。你定义字段的顺序并不会被它记住。Java 端要用 LinkedHashMapPython 端用普通 dict 就好Python 3.7 之后默认保持插入顺序。C# 的字典也不要依赖枚举顺序用有序字典或者转成 List 再循环。这条经验在生成 resultMap 时尤其重要字段一乱数据库列映射错位运行期查出来的数据会张冠李戴。我自己的规定是所有需要保持字段顺序的上下文一律使用有序结构并且在模板循环结束后做一个顺序断言防止以后换了数据来源导致静默错乱。5.4 自动转义把代码符号改成了实体字符我第一次用 Thymeleaf 做生成器时生成的 Java 代码里String全变成了lt;Stringgt;编译直接失败。当时第一反应是模板写错了后来才发现是自动转义的锅。Thymeleaf 默认会转义输出文本这是为网页安全设计的但我们在生成源代码转义反而是破坏行为。用 FreeMarker 时也遇到过同样的事某个配置把 outputFormat 设成了 HTML结果生成的 yaml 文件里特殊符号全部实体化。解决方式很简单但很容易忘进入代码生成模式前检查引擎的输出格式配置统一设为 RAW/TEXT或者在后处理阶段做反转义。我的建议是前者反转义不可靠且容易误伤本来就含实体字符的内容。意外收获是我后来专门在生成器的 smoke test 里加了一条断言渲染结果里不允许出现lt;或gt;。只要出现生成流水线立刻红灯避免这类问题溜进正式产物。5.5 批量生成时文件覆盖与幂等保护批量生成最怕误伤。模板修改了一下跑一次生成器结果把同事手改过的代码覆盖了这会直接引发团队血案。我这里总结了一套文件落地策略你可以直接抄作业先渲染到内存字符串再检查目标文件是否存在。不存在就直接写存在且内容完全相同跳过不产生任何 Git 变化存在且内容不同再细分如果模板未变更说明是手写改动建议备份后覆盖或直接报警让调用方确认。模板本身有新变化那覆盖是预期行为但最好还是保留一个 diff 报告供人工 review。还有一个很实用的技巧生成器不要直接写目标目录先写到一个临时目录全部成功后再原子性移动到目标位置。这样万一中途某个模板渲染失败目标工程仍然保持完整不会出现缺胳膊少腿的情况。这个习惯帮我挽回过很多次项目事故。最后再多说一点我的心得。模板代码生成这个方向真正的难度不在语法而在你对“模板引擎默认行为”的理解程度。空白、空值、转义、缓存、顺序这五件事每一个都能把你卡到深夜。真把原理吃透之后那些重复的 CRUD 在你眼里就不再是代码而是一堆可预测的字符串。而你要做的就是把规则写清楚然后让机器去干活。