代码生成器优化实战：从模板解析到结构化生成

1. 我为什么会对代码生成器做一次大规模优化我接手这个内部代码生成器项目的时候它已经跑了一年多周边两个核心业务的 CRUD、接口骨架、数据模型、事件消息都靠它来出。功能上确实什么都能生成但速度越来越慢早期两三秒出一套模板到了后面生成一套包含六张表、带前后端代码的业务模块经常要等三分钟往上。我一开始以为是服务器负载问题后来发现瓶颈根本不在执行环境而在模板和解析逻辑本身。具体表现是每个新模块加进来我们都在往模板仓库里塞一套新的模板文件。有按表结构生成的、有按业务场景生成的、有带多语言注释的、还有单测模板模板之间大量重复很多子片段被复制了几十份。我曾经做过一次统计当时模板仓库里已经有超过两百个模板文件公共片段超过四十个大部分模板之间互相 include整个模板依赖图连起来像一团毛线。而渲染入口每次都是全量解析、全量渲染——不管你这次只改了某一张表的一个字段程序也会把整个模板树从磁盘里重新读一遍、解析一遍、执行一遍。这在业务复杂度不高的时候无所谓但当模板数量超过几百个、单个模板又嵌套多层 include 的时候每次全量跑就是灾难。我当时最直观的感受是这不是功能问题是设计问题。优化之前必须先把生成慢的根因找到否则加再多的缓存也只是饮鸩止渴。于是我给这次优化定了个目标先把渲染链路上每一环的耗时测量出来再做有针对性的改造而不是上来就四处加缓存。后来证明这个思路是对的因为很多所谓的性能瓶颈实测下来发现根本不是瓶颈真正的问题往往藏在那些看起来理所当然的设计里。这套优化策略不只适用于某种特定模板引擎凡是基于模板的代码生成工具包括 API 骨架生成、CRUD 生成、SDK 脚手架生成等场景基本都能套用。1.1 业务代码的模板堆积让生成速度拖到不可接受从一个具体案例说起。当时有一个新业务模块需要生成数据表一共八张模板仓库里对应了三种不同风格的模板。开发同学把描述文件写完点了生成结果等了将近四分钟才出全部代码。更尴尬的是他中途以为程序卡死了正准备重启服务结果刚好生成完毕。这种体验谁碰上都会崩溃。我后来用性能分析工具把整个生成链路拉了一遍发现耗时分布是这样的模板文件读取占 12%模板语法解析占 48%渲染执行占 31%其余是 IO 和日志。看到这个比例就知道最大的问题在解析上——同一个模板文件每次生成都要重新 parse 一遍纯属重复劳动。这也解释了为什么模板越多越慢。早期模板少解析开销小感觉不明显。等到模板仓库膨胀到几百个文件每个文件又带有自身文法结构全量解析的成本就变得不可忽视了。正常的业务需求是改一个字段生成对应代码程序却把整个模板仓库反复揉了一遍这种设计天然就扛不住规模增长。1.2 生成结果的一次性和返工率高才是真正的隐形损耗跟生成速度相比更麻烦的是生成结果的可用性。这个生成器的典型使用方式是开发同学根据需求把表结构、字段备注、枚举字典填进一份 YAML 描述文件然后点一次生成得到一堆代码文件。但这些代码往往只能算草稿离能提交 review还有一段距离import 语句混乱有些引用根本不存在需要手工删字段命名风格不统一有的生成驼峰、有的生成下划线生成的 CRUD 方法没有考虑软删除、审计字段、多租户这些业务普遍存在的逻辑每次重新生成都会覆盖手动修改过的代码团队只能约定生成之后不要再动它我记得最夸张的一次某个模块的表结构比较复杂生成出来的代码里有三十多个 import 是没用的每个都要手工删。这样搞了几次之后团队里开始有人宁可先不生成直接手写代码因为手写反而更快。生成器从提效神器变成了可有可无的辅助工具这个定位很尴尬。这些问题的后果是生成器只完成了四成的工作剩下的六成还得人肉返工。越复杂的业务返工越重。有人开玩笑说这个生成器最大的价值是帮你把六十分的草稿打出来剩下的都是手工课。我听了只能苦笑因为背后确实是优化策略缺位——大家只关心生成器能不能生成没人在意生成完的东西能不能直接用。所以这次的优化不只是让它变快更是一整套围绕速度、质量、可维护性的策略组合。下面一个一个展开。2. 模板引擎与解析层先解决生成慢的根因2.1 预编译模板把每次都要做的解析工作前移当时我们用的模板引擎是典型的运行时解析模式。每次渲染都是先读文件再 parse 成语法树最后执行渲染函数。问题是 parse 这一步非常贵同样的模板在一百次请求里被解析了一百次。优化思路很朴素把模板解析成可复用的渲染函数或中间表示在生成器启动时做一次预编译运行阶段直接执行。具体做法是在模板文件旁边维护一个编译缓存目录模板内容没有变化就直接加载编译产物。这一步做完单次渲染的成本直接降了一个数量级。在选择预编译方案时有一个关键点不是所有模板引擎都适合。我们试验过三种方案方案优点缺点运行时引擎文件缓存改动小、不用换引擎每次启动仍要做语法解析只是跳过部分 IO预编译成渲染函数执行速度最快、可做静态优化升级引擎后需要全量重新编译预编译成中间字节码兼顾速度与跨语言实现复杂团队维护成本高最终我们选了预编译成渲染函数的方案。原因是团队对这门语言的工具链最熟悉而且模板语法相对稳定晋级概率很低。这里有个容易被忽略的坑预编译缓存必须和模板文件做内容哈希绑定不能只按文件名判断。否则模板改了但编译缓存没失效线上生成的就是旧逻辑。后来我们统一改成按文件内容 hash 作为缓存 key这个问题才算根治。注意预编译缓存必须和模板文件做内容哈希绑定不能只按文件名判断。模板改了但缓存没失效线上生成的就是旧逻辑。2.2 缓存粒度设计同样是缓存粒度错了等于没缓存很多人一听说优化生成器第一反应是加缓存但是缓存粒度选错的话效果很有限。我见过两种极端第一种是缓存整棵渲染结果。这对静态页面生成可能很好用但代码生成器的输入往往多变整棵缓存命中率极低大部分情况下缓存只是白白占内存。第二种是只缓存模板文件内容。这样做只是省掉了磁盘 IOparse 和执行的开销一点没省。真正合适的粒度是分层缓存。我们最终实现了三层第一层模板文件内容层按文件 hash 缓存避免重复读盘。第二层模板片段层把 include 的公共子片段按输入参数 hash 缓存命中后跳过整个子模板的渲染。第三层渲染产物层仅对输出完全可枚举的配置做整块缓存比如某业务某数据库表结构枚举组合下的整包生成结果。这里最值得说的其实是第二层。因为代码生成器的模板复用场景非常多比如一个通用的分页查询片段可能在几十个模板里都被 include。只要输入参数相同片段就能直接复用渲染结果这一层命中率通常能到六成以上比整天想着优化模板表达式强得多。不过要小心片段缓存的 key 必须包含该片段所依赖的全量上下文不能只放几个显式参数。有一次我们漏掉了上下文里的全局命名风格变量导致同一个片段在不同命名风格配置下返回了同样的旧结果排查了很久。后来把所有片段依赖都声明清楚key 里带上完整上下文 hash再没出过这个问题。2.3 增量生成只重算上游变更影响到的部分全量渲染还有一个大问题输入文件里哪怕只有一个字段变化整个依赖树都会重算。这种全量重算在小项目里无所谓到了几百张表、几十个包级别的项目里就是灾难。增量生成的思路是追踪每个输出文件与输入配置的依赖关系构建一张输入-输出依赖图。运行时先比较输入文件的内容 hash找出真正变化的节点再只对受影响的输出文件重新生成。实现时我用了一个很简单的方案在描述文件里显式声明每个输出模块依赖了哪些输入项例如UserController 依赖 user 表的 schema 和 base_api 公共模板。生成器在启动时构建依赖图之后每次增量只需要遍历受影响节点。我当时在描述文件里设计了一个依赖区块看起来类似这样outputs: - module: user-service templates: - resource/controller.gtpl - resource/service.gtpl dependencies: - schema: user - enum: user_status - config: naming_style第一次实现增量时我犯过一个错误只对比了表结构 schema 的 hash没把枚举字典、全局配置这些隐式依赖放进去。结果某个枚举值变了相关的校验代码却没有重新生成。这个问题比慢更可怕因为它是静默的代码看起来没问题但业务逻辑已经旧了。吃一堑长一智后来我在设计依赖图时明确把所有输入源头统一抽象成配置项每一个输出文件都要声明它依赖哪些配置项。为了避免漏声明我在校验阶段加了一条规则如果一个输出文件引用了某个配置项就必须在依赖声明里显式出现否则生成器直接报错。这个设计表面上是给使用者添麻烦实际上避免的维护问题更大。如果一个输出文件引用了某个配置项就必须在依赖声明里显式出现否则生成器直接报错。这个规则能杜绝隐式依赖导致的静默失效。2.4 并发渲染的注意事项做完预编译和缓存之后单次生成速度已经很快了但团队经常会批量生成大量模块。这个时候并发渲染就提上了日程。实现并发最直接的方式是用线程池并行处理多个模块的渲染任务。但代码生成器并发有几个独特的坑第一模板渲染上下文不能共享。不同的模块可能配置不同的命名风格、不同的包路径如果把全局 context 做成单例并发下就会相互串值。解决方式是把上下文对象改成线程隔离或者干脆做到不可变渲染时传递给单个任务。第二输出文件写入的原子性。并发写文件时如果两个任务恰好都要更新同一个共享配置文件就会产生锁竞争甚至写坏文件。我们后来规定每个生成任务只写自己模块目录下的文件公共配置文件放到最后单独串行合并。第三模板引擎本身是否线程安全。有的模板引擎内部持有非线程安全的状态表面上有缓存实际并发渲染时直接抛异常。这个在选型阶段就要验证不要等到生成了十几个模块才发现。并发带来的性能提升很可观。实测在优化完成后并发生成 8 个独立模块总耗时从串行的大约 50 秒压到了 9 秒左右。但说实话对于那种一条龙生成整个项目骨架的场景并发收益有限因为骨架模块之间的依赖性太强强行并行反而把依赖图搞复杂。增量生成反而是更合适的方案。3. 生成质量优化让机器产出的代码真的能直接使用速度优化只是第一步。我真正花时间最多的地方是怎么提高生成结果的可用性。因为只有生成结果能直接进代码库生成器才有价值。3.1 结构化代码生成优于字符串拼接很多代码生成器第一版都是字符串拼模板。模板里塞满占位符输出直接就是字符串。这种方案写起来最快但一旦业务复杂化字符串拼接的弊病就暴露了无法理解代码结构很难做条件片段控制缩进和空行完全靠模板维护而且无法保证括号闭合。生成的代码稍微有点复杂度语法错误率就很高。更稳健的路径是结构化生成。简单说法是先构建一个描述代码结构的中间对象比如类、方法、字段、注解的树形结构再由一个专门的渲染器把结构对象序列化成目标语言的文本。这样生成的每个片段都是结构合规的括号、分号、缩进的规则由渲染器统一处理。我举一个很常见的例子生成一个根据用户 ID 查询用户的方法。字符串拼接的做法是先把方法体的每一行拼好最后套上一个方法壳子。而结构化做法是先定义 method 对象设定返回值、参数、异常声明然后往里面加 statement。生成器负责把 statement 序列化成正确的缩进文本。最终效果是同样的逻辑不管嵌套多深渲染器都能保证生成的代码语法正确。简化一点的伪代码是这样的method Method(namefindUserById, return_typeUser) method.add_parameter(id, Long) method.add_statement(Assignment(variableuser, valueuserMapper.selectById(id))) method.add_statement(Return(expressionuser))当然结构化生成对模板语法的表达能力有一定限制尤其是一些自由发挥的写法不太好实现。我的建议是九成常规代码走结构化生成剩下一成特殊场景比如动态拼接查询条件、生成 XML 配置可以用受控的文本片段兜底。3.2 依赖关系与导入管理生成器最容易出问题的另一个地方是 import 管理。字符串拼接时代import 要么写死在模板里要么靠使用者在配置文件里手填。前者导致生成的代码常常 import 了一堆没用的包后者则经常漏导入。我们在优化时加了一个符号引用收集机制生成器在构建结构化代码时每个被引用的类、枚举、工具方法都会被标记为一个符号引用等整个模块结构构建完毕后统一做依赖解析。解析规则包括同包下的类无需导入不同包的类要生成对应的 import 语句同名类出现时标记冲突要求配置里显式指定全限定名外部依赖比如框架类库要判断是否出现在项目的依赖清单中不在的话生成警告这样做之后生成的 import 语句基本不需要人工调整了。最关键的是同名类冲突检测这个问题如果不处理生成的代码会在编译期直接报ambiguous reference而且排查起来非常痛苦。有了冲突检测之后生成器会在生成时就报出哪个模块的哪个类名和哪个包冲突了用户按提示改配置就行。3.3 命名冲突检测与作用域分析命名冲突不只是 import 层面的问题在同一个文件内部也很常见。比如用户定义了一个字段叫 createTime而模板里恰好又用 createTime 作为内部临时变量名。字符串拼接模板根本感知不到这种冲突生成的代码编译能过但逻辑会被意外改写。结构化生成方案更容易和作用域分析结合。我们在生成每个方法前先收集方法作用域内已经存在的所有变量名模板内部使用的临时变量名如果和它们冲突就自动加前缀重命名。同样在生成类字段时如果字段名和继承父类的方法名冲突也会自动处理或直接报告。这里有个教训不要只检查字段名是否重复还要检查字段名在方法体里会不会被当作变量引用。有一次我们生成的 setter 方法里参数名和类字段名相同按规则应该用 this 区分但字符串模板里漏写了 this导致生成出来的代码看起来对逻辑却把字段覆盖成参数值。后来我们在生成器里规定所有字段引用都必须显式带 this 前缀同时做变量名作用域校验确认模板临时变量与字段名无冲突。这个规则执行后类似问题就绝迹了。3.4 基于契约的验证层生成后自动做静态检查提高可用性还有一种思路不是靠生成时小心而是生成之后自动验证。我们当时在生成器里加了一个验证层每次生成完代码后自动执行几道检查第一道是语法级检查直接调用编译器或 linter 的 API对生成的源文件做 parse。语法错误会定位到具体文件和行号。第二道是符号级检查主要解决引用了不存在的类或方法这类问题。通过解析生成的 AST 和项目依赖信息做交叉比对。第三道是规则级检查比如所有新增的数据库字段必须出现在建表脚本中、所有对外接口方法必须有完整注解。这些规则来自历史代码评审中大家反复提的意见。验证层刚上线的时候被开发者抱怨过因为生成器会拒绝输出一些看起来能跑的代码。但坚持用了两周之后大家慢慢发现凡是经过验证层放行的代码直接提交 review 的通过率变高了。规则的优先级可以配置调整但验证能力本身绝对不能省。一个值得注意的点验证层不是越严格越好。太严格的规则会让生成器变成审批机器大家又开始手动绕过。配合团队实际排查节奏来配置规则优先级比较重要关键还是先解决最高频的语法错误和缺失依赖。4. 可维护性与扩展性生成器的寿命取决于结构前面讲的都是生成器怎么调快、怎么调准。但生成器本身也是一个项目它有自己的生命周期。如果它的结构不健康每次新增模板都要动主流程代码那离维护崩溃就不远了。4.1 用配置和规范代替写死在模板里的逻辑代码生成器的模板非常容易变成藏逻辑的地方。比如一个业务场景的模板里可能直接用 if 判断配置文件里有没有某个字段进而决定生成不同的代码。这样写很方便但模板很快就变得不可读而且同样一段业务逻辑会在好几个模板里各写一份。更健康的方式是把业务逻辑抽到配置规范和预处理器里。模板文件尽量只描述在什么条件下输出什么结构条件本身从配置解析结果中获取。例如是否支持软删除不应该在每个模板里各自判断一遍而是由预处理器读取配置后把删除策略解析成soft或hard等明确状态模板只需要根据这个状态分支输出即可。这个设计的直接收益是业务规则的修改点从几十个模板收敛到一个预处理器或者一份规范文档。团队新增成员时理解成本也大幅下降——看模板只需要关注输出结构看预处理器只需要关注业务规则两边互不干扰。4.2 模板版本化与生成器自身的兼容策略代码生成器最尴尬的场景是模板更新了但存量代码还是旧格式生成的。团队如果继续使用旧模板生成新代码代码风格会新旧混杂如果强制所有人升级又可能把已经手改过的模块重新生成搞乱。我们采用的方案是模板版本化 生成元数据。每个模板都有一个版本号生成结果文件头部会写清楚此文件由某模板 v3.2 生成。生成器保留历史版本模板的迁移规则当模板升级时可以自动识别已经生成的文件并基于迁移规则做差异化更新而不是整个文件重来。这个策略落地后大大降低了升级阻力。过去每升级一次模板团队都要花两三天做全量重新生成和差异比对。现在只需要跑一个迁移命令生成器自己会计算改动。需要提醒的是迁移规则必须覆盖用户手动修改过的代码处理方式是预留手动修改区用标记注释把自动生成区和手动修改区隔离开。模板升级时自动生成区重新生成手动修改区原样保留。这是非常实用又容易遗漏的一点。4.3 让生成器支持多种代码风格上下文注入代码生成器很容易被吐槽的另一个点是生成的代码风格和团队手写风格不一致。加入的同事有的习惯类型后面带空格有的不带有的用两个空格缩进有的用四个。如果生成器写死一种风格必然有人不满意。解决方案是风格上下文注入所有涉及代码风格的地方都从上下文对象取值而不是在模板里写死。包括缩进宽度、是否使用分号、命名大小写规则、注释风格、import 排序规则等。生成器拿到一套风格配置就能让机器产出的代码和团队手写代码看起来像一个模子刻出来的。为了不把这个做成万能配置中心我建议只暴露高频差异项不要试图覆盖所有代码风格细节。实践中发现配置项超过十五个之后使用者就开始懒得配置了。我们最终控制在八个核心风格参数覆盖缩进、引号、空行、命名、注释五类。再复杂的风格需求靠预处理器扩展点解决而不是堆配置项。4.4 插件化的输出适配器还有一个提升扩展性的方式是让输出层插件化。很多代码生成器是一语言绑定的写死了输出某一种语言代码。但业务团队今天可能用一种语言过两年某个模块切到新语言生成器就得重写。与其这样不如在生成器核心和语言输出之间加一层适配器接口。适配器接口大概定义三件事如何从结构化中间对象生成模块骨架如何把公共模板片段还原成目标语言的语法元素以及如何执行目标语言的语法检查。核心引擎只负责构建结构、解析依赖、做符号分析语言相关的细节全部交给适配器。这样新增一种语言时只需要实现一个适配器而不是动模板仓库的核心逻辑。这个改造看起来工作量很大实际上核心引擎和输出层解耦之后新增适配器的成本主要在模板编写。我在实践中的体会是不要试图一开始就支持多种语言而是先把适配器接口留出来等第二个语言需求出现时再接插件化改造这样既不会过度设计也不会让后续扩展推倒重来。5. 优化前后的实测数据与常见误区聊完策略再说点实在的。我把自己做优化前后的实测数据拉了出来给准备做类似改造的同学一个参考。数据来自一组固定的模拟项目八张业务表、三个业务模块、包含 CRUD 和查询接口。5.1 优化前后对比一组模拟项目的实测数据指标优化前优化后提升幅度单模块全量生成耗时43 秒6.8 秒约 6.3 倍单字段修改后的增量生成耗时43 秒1.2 秒约 36 倍生成的代码语法错误率每 5 次生成约 2 次连续 50 次无语法错误显著收敛人工返工耗时估算每次约 30 分钟每次约 5 分钟约 6 倍模板新增一个业务模块的耗时半天1 小时含测试约 4 倍一组数据很容易被质疑所以我解释一下提升的来源分布速度提升主要来自预编译模板和片段缓存增量生成对单字段修改场景贡献最大。质量提升主要来自结构化生成和验证层。可维护性提升来自配置化改造和适配器接口。这些改进没有哪个是银弹组合起来才有效。关于语法错误率这个指标我得说明一下结构化生成和验证层上线前字符串模板偶尔会因漏括号或漏分号产生语法错误通常要到 CI 阶段编译失败才被发现。优化后生成阶段就有检查所以错误率才显著收敛。5.2 常见误区把生成快当作唯一优化目标我在刚做优化的时候也犯过这个错误。一开始只盯着生成耗时觉得只要生成速度上来了工具就好用了。结果速度优化完团队反馈依然很一般。原因是生成结果还需要大量手改速度再快源头计划还是六十分。后来我才意识到对代码生成器来说产出可直接被 review 的代码才是第一原则。速度是体验的一部分但质量才是价值的核心。如果你的生成器只能输出一封草稿再快也只是一封格式好看的草稿。一个可参考的目标是新生成代码的 review 通过率尽量接近手写代码。这个目标很难一蹴而就但可以把框架搭好验证层、依赖检查、命名检测、代码风格统一逐步逼近。速度优化可以作为锦上添花但不能本末倒置。5.3 常见误区用黑魔法模板表达式解决所有问题另一个误区是过度依赖模板语言的高级特性。模板语言通常提供了循环、条件、宏、管道表达式等能力很多同学喜欢用这些黑魔法写逻辑一口气在模板里完成数据转换、条件判断和输出编排。这样在单个模板里看起来很聪明但维护成本极高。我见过一个 20 行的模板片段里嵌了 5 层条件嵌套、3 个变量引用和 1 个正则替换功能倒是实现了可是换个人来改就需要半小时。更麻烦的是这种黑魔法模板没法做单元测试一旦跑挂只有运行时才暴露。优化方向是把复杂逻辑尽量往预处理器或配置层迁移模板保持简单输出结构的原则。判断逻辑放预处理器数据转换放解析层模板只负责根据已经处理好的状态输出。这样模板可读性大幅提升问题定位也容易得多。5.4 我踩过的一个典型坑缓存失效不彻底最后分享一个让我印象深刻的坑。当时我们给模板文件加了内容 hash 缓存但忘了把全局配置和依赖描述文件纳入缓存失效判断。结果有一次业务同学改了全局配置里的命名风格从驼峰改成下划线模板文件本身一个字节都没变缓存直接命中生成的代码依然是驼峰。这个 bug 的影响很隐蔽没有报错代码能编译但风格完全不符合新规范。最后是团队在做代码审查时发现风格不对才回溯到缓存失效逻辑。排查过程并不难难的是意识到缓存 key 必须覆盖所有影响输出但又不在模板内容里的因素。从那以后我定了一个铁律所有缓存 key 必须由模板内容 hash、相关配置项 hash 和依赖描述 hash 三者共同构成。宁可让缓存命中率低一点也不能因为缓存造成输出不一致。这个问题做生成器的人早晚会遇到提前想清楚能省很多麻烦。所有缓存 key 必须由模板内容 hash、相关配置项 hash 和依赖描述 hash 三者共同构成。宁可命中率低也不能因为缓存造成输出不一致。6. 写在最后的一个小建议优化代码生成器这件事我最大的体会是不要把生成器当成一个一次性脚本而要当成一个持续演进的产品。它和业务代码一样需要测试、版本管理、代码评审和文档。把模板当作代码来管理把配置规范当作接口契约来维护生成器才不会在半年后变成团队的负担。最后分享一个实际操作中的小技巧每次做完代码审查把审查意见里反复出现的修改点沉淀成模板规则或验证规则。比如如果十次审查里有八次都提到分页查询必须带上总数统计那就把这条写进验证层。久而久之生成器会越来越贴近团队的真实需求优化也就有了方向。