不烧token的模板代码生成：原理、选型与工程落地

1. 为什么“不烧token”的代码生成仍然值得花时间：模板生成工具的真实定位

1.1 从一次次“照着改”说起：重复代码的真正成本

去年我在团队里接手一个比较头疼的活儿：后端接口定义调整过后，前端调用层、Mock数据、类型定义、接口文档样例这些代码要跟着同步改。刚开始大家手动改，文件少，十来分钟能搞定；等到超过二十个接口，每次改完总有几处漏改，要么字段名拼错，要么新增字段没补到Mock里，最要命的是编译不报错，等到联调时才炸出来。

那一阵子我反复做的事情，基本就是“照着老文件复制一份，然后替换字段名”。做第三遍的时候我开始意识到：这类工作本质上是把一份稳定的模板套用在不同数据上。后来每次有新需求，我就把模板代码生成工具这个概念拿出来，先别急着写业务代码，问一句：这段代码的模式是不是固定的？如果是，那它就应该由规则生成，而不是由人肉复制。

那段时间我也留意到，网上讨论代码生成的时候，经常把“模板代码”、“模板字符串”、“模拟量模型转C代码”这类词混在一起。其实它们共享同一个底层思路：先描述产物长什么样，再把变化点抽象成参数或者循环，最后用工具批量生成。区别只在于模板的复杂度和运行环境。

1.2 模板生成与AI生成不是替代关系，是分工关系

现在只要聊到代码生成，大家第一反应都是大模型。热门搜索词里也经常出现“AI提词器”、“提示词模板”、“AI生成代码工具”。这导致一个误区：很多人觉得有了AI以后，模板代码生成工具就该淘汰了。我实际用下来发现恰恰相反，它们解决的是两个层面的问题。

AI生成擅长的是“一次性、探索性”的工作。你问它“帮我写一个用户分页查询接口”，它会给你一段看起来合理的代码，但下一个需求换了一个小条件，它给出的代码很可能就是另一副长相。模板生成做的恰恰是反过来：一旦一段代码在每个业务模块里都长得差不多，就把规律固定成模板，字段、类型、命名规则的差异通过配置注入。它不智能、不灵活，但胜在确定性和可控性。

拿我们自己团队的经历来说，接口类型定义这类产物，我用模板生成工具跑一遍，十秒出几十个文件，零成本，而且每次生成结果完全一致。如果让AI来写，单次速度也不慢，但你要检查它有没有漏字段，有没有把枚举值写错，是不是每次生成完结构都一样。这种“检查成本”累积起来比写模板本身还高。搜索热词里那句“简单、高效、不烧token”说得非常准确，静态模板生成最大的优势就是不依赖大模型，不需要走接口调用，本地一条命令就能批量产出。

1.3 判断自己要不要上模板生成器的几个信号

很多人听到“代码生成工具”，第一反应是“我们项目没那么复杂，不需要”。但实际上模板生成工具恰恰适合中等复杂度、重复度高的工程，而不是超大型系统。判断标准很直接：

• 你会不会频繁做“照着某个已有文件改出一份新文件”的操作？
• 同一批代码是否同时存在多种变体，比如不同字段类型、不同命名风格？
• 改一个公共结构时，是不是要同步修改很多个下游文件？
• 你希望新成员接手时不用猜“这个文件是怎么写出来的”？

如果这四条中了三条，那不管你是做后端接口、前端页面、配置文件还是嵌入式代码，都值得花半天时间搭一个最小的模板生成骨架。好处是后面每一次结构变更，都只需要改模板或配置，而不是追着几十个文件做手工同步。

2. 模板代码生成的内核：模板字符串、模板文件与规则设计

2.1 模板字符串：代码生成器的最小单元

聊模板代码生成，绕不开“模板字符串”这个词。它是所有生成逻辑的基础单元：一段文字里嵌入若干占位符，运行时用真实数据替换占位符。例如你生成一个TypeScript类型的时候，本质上做的是下面这件事：

原始文本：

code复制export interface {{ name }} {
  {{ fieldList }}
}

如果传进来的实体名是Order，字段列表是id: string、amount: number，替换之后得到的就是：

code复制export interface Order {
  id: string;
  amount: number;
}

看着很简单，但90%的“模板代码生成工具”其实就是把这种逻辑放大到整个文件级别。你平时用的字符串拼接不也是这个道理？区别在于，模板字符串把“结构”和“数据”分开了：结构永远不变，数据每次不同。这个分离，就是代码生成工具的骨架。

字符串级别的模板，适合应付非常小的片段。一旦要生成的内容超过几十行，你需要的不再是字符串，而是模板文件。

2.2 把模板字符串扩展成模板文件：变量、循环、条件

真正的代码生成器，一般每个产物对应一个模板文件。模板文件里除了变量替换，至少还要支持三种能力：循环、条件、注释控制。

循环解决的是“同样的结构重复出现N次”的问题。比如每个字段都要生成三行代码，就要用类似下面的写法（以Jinja2语法为例）：

jinja复制{% for field in entity.fields %}
  {{ field.name }}?: {{ field.tsType }};
{% endfor %}

条件解决的是“某些字段可能有默认值、某些字段可能是主键”这种分支场景：

jinja复制{% if field.isPrimary %}
  @PrimaryKey()
{% endif %}
export {{ field.name }}: {{ field.tsType }};

模板代码生成工具和普通文本模板的最大区别在于：它要生成的是可读、可维护的代码，不是单纯的字符串。所以模板文件开头的“生成标记”也非常重要：

code复制// AUTO-GENERATED by template-generator, DO NOT EDIT manually.

这段注释看着不起眼，实际上是后期排查“怎么有人改了生成文件”的关键线索。它让下游维护者知道，这个文件不能直接手改，改完下一次生成又会覆盖。

2.3 自定义规则是它相对于现成生成器的最大价值

市面上现有的代码生成工具非常多，比如一些脚手架工具、模型转换工具、甚至工业界常用的仿真模型生成C代码工具。它们解决的问题很专一，开箱即用。但到了自己团队场景，往往会有一些“不太一样”的规则：你的DTO字段可能是下划线命名，但前端要求小驼峰；你的实体可能带审计字段，每个接口都需要补充创建人、创建时间这种公共字段；你的Mock数据可能要根据字段类型自动生成不同长度的随机串。

这些规则在现成工具里只能靠配置项硬凑，很多时候干脆不支持。所以现在比较流行的做法，是基于模板引擎搭建一套“可自定义规则”的轻量生成工具：解析外部输入，套用自己的模板，内部用自定义函数处理字段命名、类型映射这些转换逻辑。

这类工具做出来之后非常稳，不依赖模型接口，不需要云端计算，也不会因为一次版本升级导致生成结果变化。这也是为什么一些搜索热词里会强调“简单、高效、不烧token”，因为它本质上是一个确定性的本地程序。

3. 模板引擎选型：我的一次对比和落选理由

3.1 主流模板引擎的横向对比

做模板代码生成工具时，技术选型是第一道坎。很多人会直接选用自己最熟悉的语言生态里的模板引擎，但我觉得还是先看一遍候选再决定更好。下面是我个人用过或对比过的几类模板引擎：

从表格能看出，大部分引擎的基础能力差不多。真正影响选型的不是“能不能循环”，而是自定义扩展能力、模板调试成本、以及你们团队后续维护工具时更熟悉哪门语言。

3.2 我是怎么基于Jinja2搭出轻量生成骨架的

我最终选的是Jinja2。原因有三：第一，主项目里Python脚本比较多，用Python维护生成器没有额外的运行环境成本；第二，Jinja2的过滤器机制非常适合做“类型映射”这类代码生成中绕不开的转换逻辑；第三，它自带的模板继承和宏（macro）可以很好地解决“多个端共用一套类型”的问题，不用把同样的结构复制三份模板。

我搭出来的骨架非常轻，核心概念只有三个目录：contracts/放输入配置，templates/放所有代码模板，out/放生成结果。配置用JSON格式描述实体，长这样：

json复制{
  "name": "Order",
  "fields": [
    { "name": "id", "type": "string", "isPrimary": true },
    { "name": "amount", "type": "number", "default": 0 },
    { "name": "status", "type": "enum", "enumValues": ["CREATED", "PAID", "CLOSED"] }
  ]
}

这套JSON只描述业务侧和团队约定相关的东西，模板文件里再负责把它翻译成具体语言的代码。比如生成TypeScript字段时，只要在Jinja2环境里注册一个自定义过滤器：

python复制def to_ts_type(field_type: str) -> str:
    mapping = {
        "string": "string",
        "number": "number",
        "enum": "string"
    }
    return mapping.get(field_type, "unknown")

env.filters["to_ts_type"] = to_ts_type

用了过滤器之后，模板里的逻辑会清爽很多。生成一个字段类型时，模板里只需要写：

jinja复制export {{ field.name }}: {{ field.type | to_ts_type }};

如果以后项目改成生成Go结构体，我只需要换一套模板文件和一个to_go_type过滤器，输入JSON完全不用动。这就是把“数据描述”和“产物描述”分开后的好处。

3.3 哪些情况不建议自己搭，直接用现成脚手架更划算

自己搭模板生成器会上瘾，这很危险。有一类情况我不会自己搭：公司内部已经有非常成熟的脚手架工具，并且它可以根据特定配置生成完整项目。这类工具往往已经帮你封装好了目录结构、初始化依赖、版本号管理，是面向“新项目”而不是“重复文件生成”的。如果你要的是一整套项目骨架，不要重复造轮子，直接用现成的脚手架再配合少量模板覆盖，效率更高。

另外，如果你对模板引擎完全陌生，项目只有一两个文件需要生成，手动复制也就几分钟的事，没必要花半天造工具。模板生成器的维护成本不在“写”那一下，而在后续的业务规则变化、字段类型扩展上。开始投入之前，至少要确认同样的变更在未来三个月内会出现五次以上。

4. 一个“配置进、代码出”的生成器是怎么攒出来的

4.1 第一步：把“契约”定义成一份稳定输入

模板生成工具最容易犯的错误是入口太窄：只支持手写一份JSON。我推荐把输入定义层的格式和业务约定强绑在一起，这样之后它不只是给程序员用，也可以由负责接口定义的人直接维护。

我采用的输入格式非常接近接口契约：实体名、字段列表、枚举定义、接口路径、Mock规则都在同一个JSON文件里。第一版只有实体和字段，后面陆续加上了枚举、接口、Mock规则。每加一类配置，只需要在模板里引入一个新循环，生成的文件相应多出一段。

拿字段校验来举例：同一个字段，在后端需要做非空校验，在前端需要做表单校验，生成器的输入层只需要统一标记required: true即可，具体怎么表达交给模板。

json复制{
  "name": "User",
  "fields": [
    { "name": "userId", "type": "string", "required": true },
    { "name": "userName", "type": "string", "required": true },
    { "name": "email", "type": "string", "required": false }
  ]
}

做这一步的时候有个教训：不要把所有字段都抽象成代码层面的真实类型。输入层应该尽量贴近“业务领域模型”，类型映射这样的技术细节留在模板层完成。如果你在契约文件里早早就写好了tsType: number，那以后要生成Java版本就很难复用了。

4.2 第二步：模板按“产物维度”组织，而不是按语言维度

模板文件怎么放，决定了这个生成器能走多远。有些人按“Java模板目录”、“TS模板目录”、“Python模板目录”划分，结果同一个业务实体要在三套目录下分别维护，改一个字段名要同步三次。

更推荐的做法是按“产物维度”组织，也就是按一次业务变更会产生哪些文件来组织。例如一次接口契约变更往往同时要出类型定义、服务调用封装、Mock数据三个文件，那就把这三个模板放一起：

code复制templates/
  api_hub/
    types.ts.j2
    api_service.ts.j2
    mock_data.ts.j2
    README.md.j2

生成的时候直接遍历api_hub下的模板文件，对同一份contracts/order.json分别渲染，输出到同一个业务目录。这样有一个很直观的好处：看到一种实体，就知道它会生成哪些文件，不会出现“某个实体漏了Mock文件”的情况。

模板的命名上也建议加上.j2这类后缀，和真正的生成产物区分开。编辑器也能通过后缀识别Jinja2语法，代码高亮会舒服很多。

4.3 第三步：生成脚本只要做好“读取-渲染-写文件”三件事

生成脚本本身不需要花哨，最核心的逻辑其实很短。下面是简化后的核心脚本：

python复制from jinja2 import Environment, FileSystemLoader
import json
import sys
import os

def main():
    contract_path = sys.argv[1]
    with open(contract_path, encoding="utf-8") as f:
        contract = json.load(f)

    env = Environment(loader=FileSystemLoader("templates/api_hub"))
    env.filters["to_ts_type"] = to_ts_type
    env.filters["camel_case"] = camel_case

    output_dir = f"out/{contract['name'].lower()}"
    os.makedirs(output_dir, exist_ok=True)

    for template_name in env.list_templates():
        output_name = template_name.replace(".j2", "")
        content = env.get_template(template_name).render(entity=contract)
        with open(os.path.join(output_dir, output_name), "w", encoding="utf-8") as f:
            f.write(content)

if __name__ == "__main__":
    main()

这段代码之所以短，是因为把大量“智能”放在模板和过滤器里，脚本本身只负责搬运。从工程角度看这是好事：生成器的行为可以被模板Review，而不需要每次改逻辑都要看一堆命令式代码。

实际使用是这样一条命令：

bash复制python generator.py contracts/order.json
python generator.py contracts/user.json

如果需要对目录下所有合同一次性生成，也很简单：

bash复制for f in contracts/*.json; do python generator.py "$f"; done

4.4 第四步：生成结果的Code Review与后续修改策略

我见过很多团队用代码生成工具之后产生一个矛盾：生成的结果到底算不算人工代码？要不要走Code Review？我的答案是，一定要走，但Review的方式和手写代码不同。

生成的代码只要模板稳定、输入JSON正确，那么人工Review时只需要关注三件事：

1. 输入JSON里的字段和真实业务需求是否一致；
2. 模板里有没有因为上个版本残留导致的兼容问题；
3. 生成结果对比上一次生成，有没有非预期的diff。

操作上，我会先把生成结果放到一个临时目录，然后和上次提交的结果做一次diff。如果diff里的变化全部能对应到这次输入JSON的变化，那就可以放心提交。如果出现了某段改动无法从前端配置解释，那往往意味着模板或者过滤器里埋了坑。

5. 模板生成器踩过的坑：复杂模板维护与黄金文件策略

5.1 模板里越写越多的业务逻辑，怎么拦住

模板代码生成工具用久了，最容易出现的问题是模板逐渐臃肿。一开始，模板文件还很干净，变量加循环，读起来一目了然。后来业务方提需求：这个字段在状态下要有一个默认值，那个字段在某些情况下不加注释。当时图省事，直接在模板里写了很长的判断逻辑。三个月后再看，模板文件已经像一块打了太多补丁的旧布。

后来我定了两条规矩：

• 模板里只做“渲染”，不承载“计算”。涉及字段转换、默认值推导、命名风格转换的，一律写进过滤器或预处理器。
• 如果模板文件里的if嵌套超过了三层，就要回头问：是不是输入JSON缺少一个抽象字段？

举个例子，“根据字段类型决定是否生成默认值”这种逻辑，最合适的做法是在JSON解析阶段就提前算好一个hasDefault标志，模板里只判断这个布尔值。判断都放模板里不是不行，但会显著拉高阅读难度。

5.2 用黄金文件做模板回归：把“能跑”变成“始终不坏”

模板生成器面临的最大风险不是第一次生成不了文件，而是改模板的时候悄悄破坏了一些原本正确的输出。哪怕只是改了一个过滤器的命名规则，都可能导致所有已有文件的结构变化。

我应对这个问题的方式是引入“黄金文件”（Golden Files）策略。第一次人工确认生成结果无误后，把输出文件拷贝到一个expected/目录下，作为基准结果。之后每次修改模板或输入配置，都运行一次自动对比：重新生成结果，和黄金文件做diff，看着不顺眼的改动一目了然。

bash复制python generator.py contracts/order.json --output tmp_out
diff -ru expected/order tmp_out/order

再进一步，可以在持续集成流程里挂一个定时检查，每当模板有改动，自动执行一次全部合约的生成并对比。这个实践非常像前端团队做UI回归测试的思路：没人规定生成器必须配测试，但它确实是维护阶段最省钱的做法。

5.3 处理“生成范围边界”：哪些代码坚决不让工具生成

模板代码生成工具很容易越用越“贪”。一开始只是想生成类型定义，后来想把Service层也生成，再后来想把业务校验规则也放进去。这个趋势不完全是坏事，但必须时刻守住一条边界：代码里真正需要人做业务思考和取舍的部分，不适合放进模板。

模板生成适合的是高确定性的声明式转换：这个字段叫什么、什么类型、是否可空、需不需要序列化、接口路径是什么。这些信息一旦明确，机器生成是完全可靠的。但“这个业务逻辑是放在服务端还是放前端提前校验”、“两个后台服务之间的调用是不是要加一层缓存”这类问题带设计判断，强行抽象进模板只会让模板变成面条代码。

我把这个边界写成了一种约定：每个模板生成文件开头都带生成标记。凡是带标记的文件，不允许手改；凡是需要手写业务逻辑的文件，坚决不放进生成目录。两个目录在工程结构上分开，从根上避开“生成了又手工改”的冲突。

5.4 代码生成器在其它领域还大有可为

模板代码生成的思路不仅适用于日常开发中的接口文件，其实很多看起来“硬核”的领域也在用同一套逻辑。工业界常见的仿真模型自动生成C代码，抛开底层的编译细节，本质上也是“一套模型描述 + 一张代码模板 = 目标产物”。数控加工里的G代码生成也是基于设备模板和加工路径配置来合成最终指令。这些跨界例子给我们做普通工程工具的人一个提醒：把稳定性内容沉淀成模板，是跨领域通用的工程效率手段，而不只是写网页接口的前后端开发小哥才需要的东西。

最后分享一点维护经验。定制的模板代码生成工具，运行起来很快，但它更像一个“代码资产管家”，不是一锤子买卖。每当你发现一条公共约定需要调整，最先改的不该是那些下游文件，而是模板本身。反过来，如果你需要频繁改模板才能让某一个具体业务跑通，那就该停下来审视一下：是不是这个业务本身太特殊了，压根不适合走批量生成这条路。

我现在接到“把这一组接口按新规范再生成一遍”这类需求，已经从过去的恐惧变成了期待：打开合约JSON，补几个字段，改一下模板里对应的类型映射，跑一条命令，十分钟后对着diff做一次Review，收工。这种确定性带来的安全感，是大模型随口给一段代码永远替代不了的。