生成即规范：代码生成器内部设计与AI协作实践

第三十三弹了。这个系列断断续续写了快三年，后台最常见的一条私信是：为什么一直盯着“代码生成器”这个方向写？我的答案始终没变——只要把规范前置，很多重复劳动和技术债就能从源头消掉。CleanCode、AI编程、代码生成器、技术债，这四个词现在常常被放在一起聊，看起来像四件事，其实是一件事：AI大规模参与写代码的今天，怎么让生产出来的代码依然整齐、可测、好维护。这一弹我不想铺开讲什么宏大理念，就说点实在的：一个以“生成即规范”为原则的代码生成器，内部到底应该怎么设计，落地时会踩哪些坑，以及怎么跟AI编程工具配合，而不是被AI带偏风格。

1. 先聊清楚：所谓“生成即规范”，到底把规范放在了哪里

1.1 技术债的本质是“规范被打破的时刻”

很多人一提技术债就想到代码混乱、缺注释、结构失衡，这些都是表象。我自己的理解是：技术债是“规范被打破的时刻”的累加。今天有人把业务逻辑写进了Controller，明天有人直接在页面里拼SQL，每一处“例外”单独看都不致命，但累积起来，系统就变成了一个需要靠人肉记忆才能运行的复杂体。

代码生成器解决的是这个问题的最前端：它不跟你谈“以后要注意”，而是让不合规的写法根本无法出现。比如说，一个规范的后端模块应该有Controller、Service、Repository、DTO、异常处理这五层。如果靠人写，总有人图省事跳过Repository层，直接连数据库。但生成器生成的就是完整骨架，你拿到的第一版代码已经是标准分层结构。这就是“生成即规范”——不是事后检查，而是事前定型。

1.2 代码生成器和AI编程不是竞争关系，而是上下层关系

近两年AI编程工具渗透得很猛，很多人都已经习惯让AI直接生成一个函数、一个模块甚至整个项目的初版。效果确实惊艳，但也带来了一个隐蔽问题：AI写的代码风格可能很统一，未必符合你们团队的规范。准确地说，AI擅长“生成”，不擅长“遵守你们项目里那条不成文的规矩”。

代码生成器这时候的价值就体现出来了。它跟AI不是二选一，而是上下层关系：生成器负责把项目骨架、目录结构、分层边界、依赖注入方式、异常处理框架全部定死，AI在生成器铺好的轨道里做“填空”。你会发现，当轨道足够清晰时，AI的自由发挥空间被收窄，它犯错的概率直线下降。反过来，没有轨道的AI编程就像让一个很有才华的新人直接上手老项目，写出来的东西可能局部很漂亮，但整体不搭。

1.3 为什么这一弹叫“第三十三弹”

这个系列里我几乎每弹都在把同一条主线往前推进一步：先做标准分层，再做模板系统，再做自动检查，再接入AI编程提示链。到这一弹，很多当初手工拼装的部分已经固化成了一个小工具链。这个“不断演进”的状态本身就是最值得分享的。代码生成器不是一次性交付的软件，它是一个需要跟随团队认知持续打磨的“活系统”。三十三弹对我来说不只是一个数字，更像是在反复强调一句话：规范这东西，需要靠工具去固化和传承，而不是靠文档去宣贯。

2. 核心机制拆解：一个标准代码生成器内部的四个关键开关

2.1 分层模板：项目骨架、模块种子、文件级片段

设计代码生成器，第一个要决策的是模板粒度。我个人的习惯是把模板分成三层。

项目骨架层负责整个仓库的初始结构，包括CI配置、容器化配置、依赖管理文件、统一的目录层级。这一层的典型场景是“新建一个微服务”，一条命令跑完之后，这个服务的基础设施就已经齐了。模块种子层负责单个业务域的生成，比如生成一个“订单模块”，它会连带生成Controller、Service、Repository、Entity、DTO、异常类，甚至基础的单测骨架。文件级片段层则解决的是局部复用，比如统一的分页对象、统一的返回结果包装类、统一的错误码枚举。某一个具体文件想单独生成时，也能做到。

三层各司其职，生成时的自由度也完全不同。项目骨架层基本不给选项，模块种子层可以允许少量选择，文件级片段层的灵活性最高。灵活度越高，越要靠约束元数据去兜底，这是下一节要讲的。

2.2 约束元数据：把规范写进配置，而不是写进文档

很多团队做代码生成器，最容易犯的错误是把规范写进文档，然后让生成器“尽量按文档来”。这么做效果非常差，因为文档和代码天然会漂移。我的建议是：把规范抽取成元数据，直接以结构化配置的形式交给生成器。

举个例子，后端项目里最基础的规范是“类名风格”和“目录映射规则”。在配置里可以这样表达：

naming: class_prefix: "" class_suffix: controller: Controller service: Service repository: Repository entity: Entity dto: DTO directories: controller: adapter/controller service: application/service repository: infrastructure/repository entity: domain/entity dto: application/dto error_handling: global_exception: true error_code_enum: common/constant/ErrorCode.java

生成器读取这套配置，输出的文件就天然满足团队规范。当团队决定把Repository从dao目录迁移到infrastructure/repository时，只需改一处配置，然后统一重新生成。这就是“易维护”的第一层含义：所有规范变化，收敛到一个能被机器读取和理解的地方。

2.3 生成后流水线：格式化、静态检查、测试套件联动

代码生成器只是起点，不是终点。生成的代码如果不经过校验就进入仓库，那“生成即规范”就只是句口号。所以我的生成器默认内置一条“生成后流水线”，每次跑完生成命令，会依次执行格式化、静态检查、快速测试三件事。

格式化和静态检查大家都熟，这里不多说。真正重要的一环是“单测骨架联动”。比如生成一个业务模块时，顺手生成对应的单元测试骨架，测试里用Mock对象把边界条件标出来，关键的异常路径也预设成TODO。这样生成的代码进入开发流程后，开发者要做的不是从零写测试，而是在骨架的基础上补充真实业务断言。我自己的经验是，这套做法能让模块的测试覆盖率在第一个迭代周期内就稳定在70%以上。毕竟测试框架搭好了，写断言比搭框架轻松得多。

2.4 生成能力的回写闭环：模板反哺与缺陷修复同步

代码生成器能不能长期活得越来越好，取决于一个机制：当发现生成的代码有问题时，修复动作是落到生成器模板上，还是落到某个项目里手工改。凡是落到项目里手工改，这个生成器就会慢慢失效；凡是落到模板上，生成器就会越用越顺。

我见过太多团队，生成器上线三个月后被人悄悄弃用，核心原因就是“生成的代码不对，还是得手改”。要解决这个问题，必须建立一条硬性约束：任何人在任何项目里发现了生成代码的缺陷，修复的PR必须同时更新生成器模板，否则不接受。这个约束一开始会觉得繁琐，但跑顺之后，团队所有人的生产力都会明显提升。因为每一个缺陷的修复，都意味着未来所有新模块不会再踩同一个坑。回写闭环，才是生成器“易维护”的第二层含义。

3. 落地实操：从零构建一个轻量级CleanCode生成器的完整路线

3.1 技术选型：模板引擎、CLI脚手架与结构化生成

市面上现成的脚手架工具不少，但我建议团队初期先别急着追求重型平台，从轻量级技术栈起步更可持续。我自己在用的组合是：Node.js CLI + 模板引擎 + 配置文件解析器。模板引擎我推荐EJS或Handlebars，语法简单，团队成员几乎零成本上手。如果想要更工程化的体验，也可以用plop或hygen这类现成工具做基础壳，把自定义模板往里填。这里有一个选型判断标准：工具链的学习成本，必须远低于它节省的成本。如果团队为了用生成器先花两周学新框架，那大概率推行不下去。

CLI的设计也很关键。形态上我建议做成gen命令，支持几个核心操作：

gen init --template spring-boot-service # 初始化整个项目骨架 gen module --name order --type business # 生成一个业务模块 gen file --name PageResult --type common # 生成一个公共文件

这三个操作覆盖了绝大多数日常开发场景。更重要的是，CLI要把“交互式问答”压到最少。每多问一个问题，使用者的心智负担就多一分，最后往往就绕过了工具。能根据上下文推断的参数，尽量自动推断。

3.2 实操示例：一个标准业务模块的生成过程

这里拿一个典型的订单模块举例，生成的目录结构大致是这样的：

order ├── adapter │ └── controller │ └── OrderController.java ├── application │ ├── dto │ │ ├── OrderCreateDTO.java │ │ └── OrderQueryDTO.java │ └── service │ ├── OrderService.java │ └── impl │ └── OrderServiceImpl.java ├── domain │ └── entity │ ├── OrderEntity.java │ └── OrderStatus.java └── infrastructure ├── repository │ ├── OrderRepository.java │ └── impl │ └── OrderRepositoryImpl.java

这个结构本身没有多稀罕，但关键是生成器产出的每个文件里都已经写好了“规范样板”。比如OrderServiceImpl里已经包含了事务注解、参数校验入口、日志埋点，异常会转换成统一错误码。开发者要做的事是在标注了// TODO: 实现业务逻辑的地方填充代码，除此之外不需要动任何结构。

模块生成完成后，CLI还会自动执行格式化、编译检查，并生成对应的单元测试骨架测试OrderServiceImplTest，里面已经Mock好了Repository层。整个过程如果不算填充业务逻辑，从执行命令到拿到可编译的模块，一分钟都不到。这就是“易调测”的日常化体验。

3.3 与AI编程配合的提示词模板与上下文注入

这一节是这弹的重点，因为纯模板生成的代码解决的是“框架问题”，但业务逻辑还得人来写。AI编程工具可以极大加速“写业务逻辑”这个过程，但前提是提示词要跟生成器的约束保持一致。

我实际在用的做法是：在生成器模板里预留一个AI_PROMPT.md文件，里面写清楚当前模块的规范和上下文。当开发者用AI编程工具填充TODO时，直接把这份文件内容喂给AI当作上下文。以下是我常用的提示词模板：

你正在填充一个订单模块的业务逻辑代码。 技术栈: Java 17 + Spring Boot 3.x 架构约束: - 所有业务逻辑必须写在 application/service 层，禁止在 Controller 层写业务。 - 方法命名必须符合规范：查询用 get/find 前缀，创建用 create，更新用 update，删除用 delete。 - 数据访问只允许通过 Repository 接口，禁止直接注入数据源连接。 - 返回给前端的对象必须是 DTO，禁止直接返回 Entity。 - 所有异常必须翻译为业务异常码，错误码定义见 ErrorCode 枚举。 - 若某方法实现超出代码骨架需求，请用 TODO 注释标记，不要擅自扩展目录结构。 当前文件: OrderServiceImpl.java 请实现文件中标记为 TODO 的方法，保持现有导入和类结构不变。

实际跑下来效果很明显。没有这段约束时，AI常常会顺手引入一些额外的依赖，或者直接把Repository实现细节写在Service里。加了这段提示词后，AI的“越界行为”少了很多。我自己的经验是：不是AI不可控，而是你没有告诉它边界在哪。生成器恰好是那个“边界定义器”。

3.4 生成模块的调测流程：如何判断生成的代码“合格”

生成的代码“合格”的定义，不是能编译就算数。我给自己定的验收清单是：单元测试能跑通、契约测试通过、静态检查无新增告警、模块可以独立启动并访问一个示例接口。

所以生成器内部会跑一条完整的调测链路：单元测试用Maven或Gradle直接执行，集成测试用Testcontainers拉起一个嵌入式数据库，最后再启动应用，请求一次/health和生成模块里的占位接口。全部通过后，CLI才提示生成成功。这一套流程的意义在于，生成环节就完成了“可测性验证”。如果模板本身有问题，在生成环节就会被拦住，而不是等业务代码都写完后再返工。这是我强调“易调测”的第三个维度：调测不是事后行为，而是生成流程的组成部分。

4. 多环境落地：从个人项目、小团队到平台化的三种打法

4.1 个人开发者的轻量方案：脚本+模板

如果你是个人开发者，或者团队还处在两三人的早期项目阶段，没必要一上来就搞一个多端平台。我的建议是：一套CLI脚本加上一份模板目录，放在Git仓库里就够了。个人场景下，生成器最大的受益点是“一致性”：每次新建模块时，拿到的都是同一套代码风格，长期下来，即使只有你一个人维护老项目，追溯和定位问题也会轻松很多。

我个人的早期项目就是这么跑过来的。那时候生成器还没有什么图形界面，就是一套Shell脚本加EJS模板，每次新建模块执行一下。现在回看，这个“笨拙”的方案帮我省下了大量格式化目录、整理依赖的时间。如果你现在还没有任何代码生成器，我强烈建议从这一步开始，花一下午时间，把你的“标准项目结构”沉淀成第一版模板。

4.2 小团队的规范化落地：生成器+CodeReview+CI检查

团队到5到10个人的规模，问题就开始变化了：不只是“我自己的代码乱不乱”，而是“不同人的代码风格能不能统一”。单纯靠代码评审，很难每次都拦住细节问题；单纯靠生成器，又无法处理那些生成器覆盖不到的增量改动。正确的姿势是生成器、CodeReview、CI三者各管一段。

生成器负责把存量部分规范化，CI负责拦截规范化之外的“意外”，CodeReview则聚焦在业务逻辑有没有问题，而不是纠结命名规范和目录摆放。实际操作中，CI里可以加一个自定义检查脚本：读取团队的规范配置，扫描新增和变更的文件，看命名、目录、分层是否匹配。如果发现违规直接让流水线失败。这样一来，生成器管住源头，CI管住增量，评审回归到业务本身，团队的协作质量会明显上一个台阶。

4.3 平台化：当生成器变成内部工具门户

当团队规模到了几十人，或者开始有多个技术栈并行时，CLI工具的局限性就出现了：每次更新模板，每个人都得手动更新本地版本。这时候需要考虑平台化。平台化不等于要做一个大而全的网站，核心是把模板中心和生成服务集中化。

一个比较经济实惠的路径是：把模板仓库单独拆出来，模板的版本号由npm包或Maven坐标管理。各开发者的CLI工具通过拉取最新模板版本实现自动更新。再进一步，可以搭一个简单的内部页面，让产品经理也能通过网页表单填写模块信息，后台调用生成服务，把生成好的代码打包下载。这种形态特别适合中台团队服务多个业务线：业务线不关心生成器底层实现，只需在页面上选好模块类型，拿到的代码天然满足中台规范。平台化的本质不是炫技，而是把规范发布、模板更新、使用入口三者彻底解耦。

5. 常见问题与排查技巧实录

5.1 代码能生成，但编译不过的排查顺序

生成器生成代码后编译不过，是高频问题，尤其出现在模板版本升级之后。我的排查顺序固定不变：先看是不是依赖坐标失效，然后看JDK或语言版本是否和模板不兼容，接着查代码中是否引用了不存在的类或方法，最后看是不是模板变量替换出了问题。按照这个顺序，一般三到五分钟内能定位。

这里提醒一个容易忽略的坑：模板里定义的“占位变量”和“实际传入的参数”如果名字对不上，会悄悄生成类似undefined或null的字符串，编译当然报错，而且报错信息往往很迷惑。所以我会在生成器里预留一个“模板变量自检”命令，它会把当前所有可用的模板变量打印出来，和模板文件里的引用做一次比对。这个功能虽然不起眼，但能省下大量查错时间。

5.2 模板漂移问题：项目手改代码和模板脱节怎么办

用生成器一段时间后，一定会出现这类情况：某个项目里因为紧急需求，手工改了某个生成文件的结构，但改完之后没有同步回模板。等下一次新项目再生成，拿到的还是旧规范代码，两边就开始不一致。

我的处理方案是“生成文件头注释标记”。生成器产出的每个文件顶部都会带一段注释，声明该文件由生成器创建，并记录当时的模板版本号。后续如果是规范版本升级，可以用gen sync命令对比当前文件与最新模板的差异，把不属于业务逻辑的部分合并回来。这套机制不追求自动覆盖所有手改内容，但能让“漂移”变得可见、可回溯。对大部分团队来说，“知道哪里漂移了”比“完全不漂移”更重要。

5.3 与AI配合时的典型坑：上下文超限与模型“自由发挥”

把AI引入生成后的填充环节，爽是真爽，坑也是真坑。最常见的三类问题：第一是上下文太长超出模型窗口；第二是模型在实现某个方法时，擅自改了类的既有结构；第三是模型引入不存在的依赖。第一类问题，解法是把提示词里最核心的架构约束抽取成精简版，不要每次把整个项目文档塞进去。第二类问题，我用的是“只允许修改TODO标注区域+禁止增删文件”的约束，并且在提示词开头单独强调。第三类问题，依靠CI的依赖检查，在合并前拦截。

还有一个很实用的小技巧：在生成器里内置一条gen plan命令，它会把当前模块里所有TODO点列出来，并生成一份建议实现顺序。有了这份清单，你可以把它作为AI对话的“工作分解结构”，一次只让AI做一个点。比起一次性让AI写完整个模块，这种小步走、逐步合并的方式，出岔子的概率低很多。

5.4 维护者必读：生成器本身的技术债怎么防

代码生成器自己也是软件，它同样会积累技术债。这一点很多人忽略。生成器的模板会越来越多，CLI代码会越来越复杂，如果生成器本身没有清晰的结构，后期维护会非常痛苦。我维护了三十几弹这个系列，最深的一个体会是：生成器的代码和业务代码一样需要CleanCode，甚至要求更高。

我的维护清单大致如下：

定期整理模板目录、删掉废弃模板、合并重复结构，都是维护者该做的“除草”工作。这些看起来很琐碎，但直接决定了生成器能不能陪团队走很远。我自己现在定了一个节奏：每迭代两周，专门抽出半天来给生成器的模板做一次重构，只清理，不新增功能。这个习惯效果非常好，强烈推荐。

回到最开始的话题，代码生成器不能解决所有工程问题，但它把“规范”从一个抽象概念变成了一个可执行的系统。尤其当AI开始深度参与日常编码之后，一个边界清晰、结构严明的生成器，反而成了约束AI不跑偏的有效工具。如果你也想做一套自己的生成器，不需要在起步阶段就想得特别宏大。先挑你项目里变更最频繁、最容易写错的那一类文件，做一个模板，跑通生成链路，再基于反馈慢慢迭代。三十三弹之后我依然觉得，工具的价值从来不在于它多复杂，而在于它能不能把团队的共识，沉淀成肉眼可见的代码资产。