企业官网建设流程全解析

那大概是引入代码生成器三个月之后，项目开始出现“熟悉的痛感”。

一开始所有人都觉得这工具很爽：建表、生成、CRUD一套带走，半天工作量变成十分钟。但越往后越不对劲——有人偷偷改了生成代码，有人复制了一份模板改成“我的版本”，最要命的是，当数据库字段变化需要重新生成时，没有一个人敢点那个覆盖按钮。因为大家心里都清楚：一旦覆盖，自己手工加的代码就全没了。

那段时间我一直在想，“代码生成器优化”这件事到底在优化什么？总不能是让生成速度更快一点就算优化吧。后来我把自己踩过的坑、试过的路，以及最后沉淀下来的一套策略整理成了这篇文章，适合正在用生成器、或者准备在团队里引入生成器的同学参考。内容不会只讲某个具体工具怎么用，而是从输入、模板、引擎、产物、质量、团队六个层面讲清楚优化策略。你会发现，大多数“生成器难用”的问题，根本不是生成器本身的锅。

1. 先想清楚：你是在优化生成器本身，还是在优化生成出来的代码？

1.1 两个方向，两种完全不同的做法

我在很多团队里见过同一个误区：大家一边抱怨生成出来的代码质量差，一边去找引擎性能优化的方案。这是典型的“诊断错误”。

优化生成器本身，指的是引擎的运行效率，比如渲染速度、并发能力、缓存策略、增量输出。优化生成出来的代码，指的是让最终产物更符合团队规范、更容易维护、性能更稳。这是两个完全不同的方向，解决的问题也不一样。

举个例子：如果你一直觉得生成的实体类没有注释、字段类型映射不对，那你真正要优化的是“输入”和“模板”这两层。这时候去研究线程池、并发渲染，一点作用都没有。反过来，如果生成一百张表要跑上几分钟，大家每次都要等在终端前，那才需要看引擎层。

我建议团队里所有跟生成器相关的问题，先统一口径，不要用“生成器不好用”这种模糊描述。任何抱怨都必须指向具体的表现。这个习惯一旦养成，后面所有优化工作都会顺很多。

1.2 把生成过程拆成四层，定位问题更精准

代码生成器从原理上可以拆成四层，这是我后来做任何优化前都会画在脑子里的框架：

• 输入层：数据库表结构、接口定义、领域模型、配置文件、元数据。
• 模板层：定义产物形状的模板文件、代码片段、宏定义。
• 引擎层：模板渲染机制、遍历逻辑、文件输出策略、并发调度。
• 产物层：最终生成的实体类、接口、SQL脚本、前端页面代码。

每一层对应完全不同的优化手段。输入层的问题要靠规范化、校验器来解决；模板层的问题要靠模板工程化、分层设计来解决；引擎层的问题才需要用到并发、缓存、渲染选型这些手段；产物层的问题则要靠编译门禁、静态检查、测试策略来兜底。

一旦你手里有了这个四层模型，很多模糊的“优化需求”就能立刻变成具体任务。比如“生成的代码风格不统一”，属于模板层；“生成的代码没有注释”，可能同时涉及输入层和模板层；“生成太慢”，才是引擎层。“生成之后别人不敢改”，属于产物层的覆盖策略问题。

1.3 我从“疯狂改模板”到“回头改输入”的转变

我自己在这上面是交过学费的。

早期我们业务模块差异很大，有的表需要逻辑删除，有的表需要乐观锁，有的表要带审计字段，还有的表又要求不生成Service。当时我的第一反应是“那就让模板聪明一点”，于是模板里塞满了if判断，去检测表有没有软删除字段、有没有version字段、有没有create_time字段。半年之后，模板已经变成一团乱麻，每次改需求都像走雷区。

后来我换了个思路：不在模板里做判断，而是在生成器代码里先解析表结构，把特征提炼出来，生成一个清晰的渲染上下文。模板只做简单输出。这个转变带来的效果非常直观：模板行数降了百分之六七十，生成出来的代码反而更符合预期了。因为判断逻辑写在了可以单测的Java代码里，而不是藏在模板引擎的if嵌套中。

这件事给我的启发很大：优化代码生成器，第一优先级不是让模板变得更聪明，而是让输入变得更规整、让逻辑所在的位置更合理。模板应该是一个“哑巴”，负责按图索骥，而不是负责思考。

2. 输入治理：别把脏数据喂给生成器

2.1 同样的生成器，为什么换个项目就翻车？

我以前一直奇怪，同一套生成器，在公司A项目跑得好好的，拿到B项目就各种别扭。后来才明白，问题不在生成器，在输入。

A项目的表结构非常规整，表名统一小写下划线，主键统一叫id，字段注释齐全，公共字段命名一致。B项目呢？一个用驼峰命名，一个用下划线命名，有的表注释空白，枚举字段直接建成int，字段含义全靠猜。这种输入喂进去，生成器再强也生成不出好东西。

代码生成器的本质是什么？是把输入中蕴含的约定批量转化为代码。输入侧的约定越多、越清晰，输出就越可控。输入侧没有约定，生成器就只能靠猜，猜出来的东西当然不能指望有多好。所以优化策略的第一步，永远不是改模板，而是治理输入。

2.2 表结构输入：一份可落地的规范化清单

如果你用的是基于数据库表结构生成代码的工具，可以先对照下面这份清单检查现有库表：

• 表名、字段名统一小写下划线风格，禁止驼峰。主键统一叫id，业务主键统一以code或id结尾，便于模板生成按主键查询的方法。
• 公共字段统一命名。created_at、updated_at、deleted、version这些字段必须全团队统一，这样模板才能针对这些字段做统一处理，比如自动填充审计逻辑、逻辑删除、乐观锁。
• 表和字段必须有注释。这不是可有可无的规范，而是硬性要求。注释缺失会导致生成出来的Javadoc、Swagger注解全是空的，前端拿到接口文档也是一脸懵。
• 枚举字段必须用注释标明取值范围。不要只写一个status int，要写成“状态：0-禁用、1-启用、2-锁定”，否则生成出来的枚举注释毫无意义。
• 字段类型必须落在映射表内。比如datetime -> Instant、decimal(18,2) -> BigDecimal、tinyint -> Boolean。不在映射表里的类型应该在生成前就被发现，而不是生成后编译报错。

你是可以自动检查的。以MySQL为例，生成前跑一遍下面的查询，就能拿到全部表字段的命名和注释情况：

SELECT table_name, column_name, column_comment, data_type FROM information_schema.columns WHERE table_schema = 'your_db_name' ORDER BY table_name, ordinal_position;

拿到结果后，在生成器里做一次遍历校验，不满足规范的表直接列入清单并提示。哪怕只做警告，也会逼着大家下次建表时把注释补上。

2.3 接口定义与领域模型：约定先于生成

如果你生成的是REST API的客户端代码或服务端接口骨架，那么OpenAPI定义就是输入侧的“宪法”。operationId、tag、summary、schema的命名质量，直接决定生成代码里的方法名、类名和注释。我见过不少项目的OpenAPI文件里summary全空，生成的接口全是一堆/api/v1/getSomething这种无意义描述，问题根源不在生成器，而在文档本身没人管。

领域模型也一样。状态枚举、字段分组、必填约束，这些语义应该在输入层定义清楚，而不是靠模板去猜。比如“订单状态”这个字段，如果你在输入里只给它一个Integer，那模板就算再聪明也无法帮你生成业务守卫逻辑。如果你把枚举值定义成OrderStatus并在输入里标出来，生成器就能做出状态流转校验方法。

这其实是一种投资思维：花时间把输入定义得越精确，后面省下的时间就越多。把输入当成脏数据之前，别急着怪生成器。

2.4 生成器的第一道关卡：前置校验器

很多生成器的问题不是生成能力弱，而是“什么脏活都敢接”。我强烈建议给生成器加一个preflight阶段，在真正渲染之前做输入校验，而不是等代码生成完再靠人眼发现问题。

你可以设计这样一套规则：

• 表必须有表注释，字段必须有字段注释，缺失直接Fail。
• 表名、字段名不匹配命名规范时输出Warning，如果是全团队约定内的例外可以跳过。
• 数据库类型必须命中类型映射表，否则Fail。
• 逻辑删除字段如果在表中存在，必须命名为deleted且类型匹配。

以前我们做出来的Controller经常没有@Tag注解，前端文档页面全是“接口一、接口二”这种，后来就是因为没有在preflight阶段校验“领域描述”。加了这个前置校验之后，这种问题基本绝迹了。把问题拦截在生成前，比生成后再review高效得多。

3. 模板工程化：把模板当作一等代码来养

3.1 从字符串拼接进化到模板项目

我见过一些最原始的代码生成器，本质上是String.replace加一堆字符串拼接。这种方案要么没有模板，要么模板只是散落在代码注释里的“魔法字符串”，改一个缩进都要翻半天代码。

稍微像样一点的团队会用单个模板文件，比如一个entity.java.ftl。再进一步，就该把模板组织成一个模板项目，用目录结构管理。到了这一步，模板就已经不是“静态文本”了，而是跟业务代码一样需要版本管理、Code Review、可测试的工程资产。模板仓库要单独建，跟生成器引擎源码分开。模板的变更也要像代码变更一样走评审，不要谁都能直接往库存里塞。

3.2 模板里写死什么、抽象什么、可配什么

这是我在内部评审模板时经常要问的问题。一个好看的模板，必须明确划分三种内容：

• 写死的部分：语言语法骨架、文件折叠规范、缩进风格、换行规则。这部分不应该暴露配置项，否则一百个人能产生一百种风格。
• 抽象的部分：公共父类、统一返回结构、BaseMapper、BaseService。公共结构不要在每份生成文件里重复出现一大段，而是通过模板片段复用。
• 可变的部分：模块名、表名、字段列表、注释、需要生成的方法集。这些必须来自渲染上下文，而不是模板里的字符串字面量。

如果你发现模板里出现了某个具体的表名或模块名，那一定是有问题的。这类业务信息必须通过参数传入，否则模板根本没法复用。

3.3 让模板保持“哑巴”，逻辑都挪到渲染上下文

模板引擎本身不是为复杂逻辑设计的，硬塞的话调试会非常痛苦。我见过一个Freemarker模板，里面有十几层if嵌套，判断不同数据库类型的映射关系。结果出了bug，只能通过看渲染日志排查，一行一行猜，效率极低。

后来我们把类型映射的规则全部写进生成器代码，用普通的编程语言实现，并配上了单元测试。模板最终只剩一个${field.javaType}。这样模板几乎不可能出错，就算出错，也只是循环输出层面的问题，看一眼就能定位。

记住一个原则：模板里只做循环和取值，不做业务判断。所有需要判断的逻辑，都在生成器代码里事先计算好，放进渲染上下文。

3.4 分层模板：基础层、业务层、定制层

好的模板仓库应该像一个代码项目一样分层。我的建议是最少三层：

templates/ ├── base/ # 基础层：所有模块通用的骨架 │ ├── entity.java.ftl │ ├── service.java.ftl │ └── mapper.java.ftl ├── biz/ # 业务层：按业务形态区分 │ ├── tree/ # 树形结构 │ ├── master-detail/ # 主子结构 │ └── stateflow/ # 状态流转 └── custom/ # 定制层：团队个性化规范 ├── api-response.java.ftl └── log-aspect.java.ftl

基础层解决“所有模块长得一样”的问题，业务层解决“不同类型模块有差异”的问题，定制层解决“团队有特殊规范”的问题。分层之后，普通业务需求只需要改基础层，复杂场景才会走到业务层，定制层的东西能不动就不动。

模板升级的时候要注意兼容性。你改了基础层模板，已生成的存量代码不会自动变，所以需要有“重新生成演练”的机制，在测试分支上跑一次全量重生成，看看哪些模块能无痛升级、哪些会出现diff。这个后面团队落地那节还会再讲。

4. 生成代码与手写代码的边界：三种共存模式

4.1 全量覆盖为什么是万恶之源

很多团队把代码生成器用砸，根因就是“全量覆盖”这四个字。

生成器第一次跑得很开心，所有文件齐刷刷落盘。但接下来的问题来了：这个Controller我想加一个自定义接口，那个ServiceImpl里我要写一段特殊逻辑。改完之后，数据库结构变了，要不要重新生成？重新生成等于所有手工修改全丢；不重新生成，手头代码又会跟表结构脱节。最后大家只能手动merge，merge多了，就再也没人信任生成器了。

所以优化策略里必须有一件事从一开始就想清楚：哪些文件可以被覆盖，哪些文件是“半自动”的，哪些文件完全不让生成器碰。这个边界不划清，后面所有优化都是空中楼阁。

4.2 模式一：物理隔离，生成代码进generated目录

第一种模式最简单粗暴：生成代码全部放进generated-sources或src/generated目录，这个目录要么不进版本库，要么进版本库但明令禁止手工修改。手写代码通过继承或组合来复用生成代码。

优点非常明显：无论怎么重生成，手工代码都安全，团队心理负担为零。但缺点也很现实：为了扩展一个简单字段，你可能要继承一个父类，再覆写一个方法，调用链长，结构复杂。对简单项目或基础CRUD场景还好，一旦业务复杂起来，很容易出现“为了不动生成代码而设计过度”的荒唐局面。

4.3 模式二：Diff合并与标记区域

第二种模式更精细，核心思路是“生成区受控，保护区自由”。

我们可以约定，在一个Java文件里，用固定的标记注释划出生成区域：

// [GENERATED_START] // 此区域内容会在重新生成时被覆盖 public void save(UserDTO dto) { ... } // [GENERATED_END] // 此区域以外的内容会保留 public void saveWithExtra(UserDTO dto) { // 手工实现 }

生成工具执行时，先读取现有文件，把非生成区域的代码提取出来暂存，然后渲染新的内容，最后把保护区内容拼接回去。如果模板结构发生大变化，比如整个方法签名都变了，那就不要自动合并，输出一份diff报告让开发人员来做决定。

这种模式比物理隔离灵活，但实现有一定成本，而且对模板变更特别敏感。格式化差异、注释位置的改动，都可能让diff算法误判，所以需要做好配套工具。

4.4 模式三：伪生成，只输出参考片段

第三种模式可能被很多人忽略，但它很好用：生成器不直接写文件，只是把代码片段输出到终端或者剪贴板，由开发者决定要把哪些内容粘贴到自己的代码里。

我一般会在模板探索期或者老项目重构期用这个模式。因为这两个阶段团队对“生成器是否可靠”还没有信心，直接让生成器往项目里写文件，一旦出了问题大家会抵触。而“伪生成”的方式让人感觉像在IDE里复制一段示例代码，心理负担小得多。缺点也很明显：效率低，没法自动化，也不适合生成大量文件，所以只能作为过渡和辅助手段。

4.5 我的选择：混合策略

在实践中我不会只选一种模式，而是按“会不会被手工修改”来分类：

• 实体类、DTO、Mapper接口、基础SQL脚本：这类文件几乎不会被手工改，全量覆盖没问题，放进generated目录。
• Service实现、Controller、复杂查询实现：这类文件几乎一定会被手工改，生成骨架后进入版本库，人工继续完善。
• 再次重生成时，对这类文件不整文件覆盖，而是走增量生成，只把新增的方法补进去，并且严格遵守生成区域标记。

这样做的好处是，简单文件可以痛快覆盖，复杂文件又有足够自由度。团队不用天天跪在继承体系面前，也不会因为怕丢代码而不敢重生成。混合策略看起来没有某一种模式“纯粹”，但它最接近真实开发节奏。

5. 生成引擎的性能与运行机制：从能用到好用

5.1 什么时候性能才是真瓶颈

我不太赞成团队一上来就给代码生成器做“高性能设计”。大家想想，单个模块、几十张表，生成一次几秒钟，这有什么性能问题？

但有几类场景确实需要认真看性能。第一，生成器进入了CI流程，每次合并前都要跑一遍，代码量一大，每次多等几分钟，团队就会开始骂人。第二，一次要生成上千张表，比如数据中台项目里元数据模型几百上千张，全量生成的文件数量非常可观。第三，生成逻辑里包括了大量元数据分析、SQL解析、跨表关系推断，这部分往往比模板渲染更耗时。

所以正确的姿态是：先加日志、统计耗时，找到真正的瓶颈，再干活。别为不存在的问题提前优化。

5.2 渲染引擎选型：从模板引擎到AST

选型这件事，很多团队一开始没太在意，等到发现模板里塞不下复杂逻辑时才开始后悔。我的建议是：

• 如果生成的是结构规整的文本代码，用模板引擎就够了，比如FreeMarker、Velocity、Jinja、Handlebars。
• 如果需要在生成过程中做类型推导、自动import、语法级的重构，模板引擎就会很吃力。这时候应该考虑用AST工具库，比如后端用JavaParser，前端用TypeScript Compiler API，直接在语法树层面构造代码。

模板引擎适合“套壳子”，AST适合“做手术”。以Java为例，模板引擎生成代码后，经常出现import缺失、泛型截断、格式不一致的问题，而JavaParser能直接解析既有代码，在AST层面插入方法、补import、重排结构，可靠性高一个量级。

当然AST方案学习成本更高，所以我的建议是“能靠模板解决的先用模板”，碰到模板没法解决的问题再上AST，不要反过来。

5.3 批量生成的三个优化点：并发、缓存、增量输出

如果真到了要优化引擎层的地步，我建议按下面的顺序排查。

先看缓存。模板解析结果是天然可以缓存的，整个生成过程中不要反复读取模板文件并重新解析。数据库元数据、字段映射结果也可以缓存，尤其当多张表共用一个公共字段集合时，复用效果非常明显。

再看并发。模板引擎实例要注意线程安全，不要每次都new一个Engine。如果用了FreeMarker，记得它的Configuration可以线程安全地复用。文件写入操作只要目录不冲突，完全可以并行。线程数取CPU核心数左右就比较合适，不需要太激进。

最后看增量输出。生成器不要无脑覆盖所有文件，先比较旧文件内容和新渲染结果，内容一致就不写。这样一来，文件系统的写入次数大幅减少，CI里因为“生成代码文件被无谓更新而触发的全量构建”也会少很多。

5.4 一组可参考的实测数据

给你一组我自己的实测数据做参考。场景是300张表，每张表生成6个文件，合计约1800个文件。

优化前：单线程渲染，每次全量写盘，耗时大概3分钟。优化后：模板解析缓存加数据库元数据缓存，并发8线程，只输出发生变化或新增的文件，耗时降到20秒左右。这中间大概有三分之二的优化来自缓存，其余的来自并发和增量输出。

每台机器的数据都不一样，但这组实验很能说明问题：很多生成器慢不是因为渲染本身有多重，而是因为它反复在做重复劳动。缓存和增量输出永远是性价比最高的两个优化点。

6. 给生成代码上质量门禁：生成不等于免检

6.1 为什么必须给生成代码设门禁

我发现一个挺普遍的心态：因为是机器生成的代码，所以大家天然觉得“它应该是没问题的”，Review的时候轻松放过。但真实情况恰恰相反，生成代码一旦出错，影响面往往比手写代码更大，因为它是成批成批复制到几十个模块里的。

我见过最典型的问题，是一条错误的类型映射规则导致所有金额字段生成成了Float，然后线上金额对账出现精度问题。如果当时生成代码能过一道强制的类型断言检查，这个问题早就被拦住了。生成代码必须有自己的质量门禁，不能因为“自动化”就豁免。

6.2 生成后立即编译、Lint、格式化

门禁的第一道卡口应该在生成阶段，生成结束立即执行编译和静态检查。后端项目生成完之后直接跑一次mvn compile，如果有编译错误，直接阻断，不让产物进入提交环节。前端项目生成完毕后跑eslint --fix和prettier，确保格式统一。

另外可以用checkstyle或spotless这类工具统一代码格式。生成代码是程序写出来的，格式混乱完全可以用工具避免，不应该等人工来吐槽“这片代码缩进太怪了”。

6.3 针对生成代码的测试策略

这里说的不是“生成器本身的单元测试”，而是针对“生成出来的代码”的测试。

一种做法是给每个生成的CRUD接口做一次冒烟测试，至少验证路径、请求参数、返回结构是通的。第三种做法是给Mapper接口做一条基础CRUD集成测试，确认它能查、能插、能删。如果全量跑测试成本太高，可以按模块抽样，比如“每次生成刷新后，随机抽10%的模块执行冒烟测试”，这样既控制了成本，又能对生成质量形成连续监控。

很多团队不愿意给生成代码写测试，觉得多此一举。但你想，生成代码一旦出问题，就是几十个文件一起出问题，这本身就是高风险资产。测试不是给生成器面子，是给系统兜底。

6.4 反馈闭环：让“生成结果不对”能回到模板

质量门禁的另一半是反馈闭环。团队里最怕出现的情况是：开发发现某处生成代码不对，这次自己手动改掉了，然后就没有然后了。大家都不反馈，模板永远不修正，下一批新模块还是同样的问题，继续各自手改一遍。

我们后来立了一个规矩：任何人发现生成结果有问题，必须提交一个最小可复现样例，包含输入表和生成产物，而不是口头描述。生成器维护者定期批量审查这些样例，把根因归到输入层、模板层还是引擎层，再决定修哪里。另外可以统计一个指标：手工二次修改率。如果生成的代码被手工修改得越多，说明生成器离团队真实需求越远，这就是最直接的优化信号。

7. 团队落地：好策略也得有人愿意用

7.1 开发者体验：把命令做得足够好用

一个没人用的生成器，内部设计得再精巧也没价值。

我的体会是，开发者体验的核心不是写文档，而是把命令做得足够顺手。至少要做到：有清晰的CLI命令，而不是让大家去翻wiki；有--dry-run参数，先生成预览，让同事知道这个命令会创建哪些文件、改动哪些文件，再决定要不要执行；有可解释的错误信息，别一出错就抛一堆调用栈；生成前能自动备份或提示冲突，降低大家的恐惧心理。

举个例子，一个好的命令大概长这样：

gen --module=user --tables=sys_user,sys_role --dry-run

跑完之后告诉你“将新增4个文件、修改0个文件、跳过2个未变化的文件”，这比任何文档都能建立信任。

7.2 配置即治理：用配置文件取代各写各的模板

团队里的另一种失控，是每个人都想拥有一套“我的模板”。今天这个人改一下缩进，明天那个人加一个注解，最后模板仓库里十几个fork，没人知道哪个是准的。

我的解决办法是用一个集中的配置文件来收敛个性化需求。模板仓库只保留一套，所有模块级差异都通过配置表达。下面是一个简化的示例：

module: user tables: - sys_user - sys_role package: base: com.example biz: user generation: mode: incremental generatedDir: src/generated overwrite: safe ignoreTables: - sys_log_2024

配置文件的变更同样走PR评审。这样谁能改什么、改了什么都清清楚楚，模板本身保持稳定，也就不会出现“一个团队有八种代码风格”的局面。

7.3 灰度推广与周期重生成演练

代码生成器要落地，跟发布新框架一样，不建议一刀切全量推。我的经验是：

先选一个中低风险的模块试点，比如一个普通的CRUD模块，把从生成、编译、测试到Code Review的完整流程走一遍。试点的时候要特别注意记录大家的不满，这些不满就是下一轮优化的输入项。跑通之后再做一次技术分享，让其他团队看到真实效果。最后把“生成器使用手册”和命名规范、输入规范一起写进团队约定，让生成流程成为唯一的入口。

还有一件事非常重要：定期做一次“周期重生成演练”。在测试分支上强制全量重新生成，然后跑编译和测试，看有多少模块能零手工diff通过。这个演练能提前暴露模板升级带来的兼容性问题，也能让团队对自己的生成流程保持信心。频率不高，每个迭代或每两个月做一次就够。

最后分享一个我自己一直在用的自检法。当你觉得生成器“难用”的时候，先别急着抱怨，把你最近碰到的五六个问题写下来，然后逐个归类到输入层、模板层、引擎层、产物层。比如“生成的Controller没有注释”，大概率是输入层的问题；“一改模板就导致几百个文件乱掉”，大概率是模板层和增量合并的问题；“生成一次要五分钟”，才是引擎层的优化空间。归完类你会发现，很多你以为是生成器自身的问题，其实根源在输入规范和工程边界上。把这层窗户纸捅破，优化方向就清楚了。