企业官网建设流程全解析

有一段时间，我对代码生成器是排斥的。原因很朴素：早年间用过几个前端脚手架，生成的东西永远带着一股模板味，变量命名奇奇怪怪，项目稍微一改动，整个结构就崩给你看。所以当手底下的服务从十几个接口慢慢膨胀到上百个接口时，我依然坚持手写 CRUD，直到某天下午连续改了四遍同样的 Controller、Service、DTO，我才第一次认真考虑：也许该把这件事交给工具了。

“交给工具”不是打开某个网页把文件复制进来，而是要有一个能进到团队工作流里的命令行工具。于是我花了两个周末，把之前的 CodeMagician 重做了一版，代号 CodeMagicianT，也就是社区里说的 T补。T 并不是某个单词的缩写那么简单，它至少包含三层意思：Template 模板、Type 类型、Toolkit 工具集。至于“补”，是因为这个项目是原版能力的补全，不是推倒重来。

这篇文章会把 CodeMagicianT 从设计到落地全部拆开讲。如果你想做脚手架、代码生成器，或者正被重复性开发折磨，可以参考这套思路；如果你只是想找一个能安全改造存量代码的工具，第二、四两节的配置思路和踩坑记录应该能帮你少走弯路。

1. 项目定位与核心设计思路

1.1 为什么叫“T补”：三层含义拆解

原版 CodeMagician 是一个专注“根据模板生成新模块”的小工具。定位很单纯，就是给新项目或新模块搭骨架。用起来也简单，写一个模板文件，填几个变量，运行后把文件落地。但它的问题也很明显：模板引擎比较简陋，只有占位符替换和简单循环，复杂逻辑要写在 JS 脚本里。生成出来的代码虽然能跑，但团队里一致性的问题并没有真正解决。

T补正好补在这三个短板上。

第一层，Template，补的是模板能力。我引入了 Nunjucks 作为底层模板引擎，支持继承、宏、循环、条件、过滤器。你可以在模板里定义公共片段，交给不同规则复用，也可以把版权头、import 语句、装饰器封装成宏。这解决的不只是“能不能写复杂模板”的问题，更重要的是让模板本身变得可维护。以前那种整段复制粘贴的模板，改一个公共头部要全量替换，现在只需要改一个宏。

第二层，Type，补的是类型能力。原版工具对目标语言类型一无所知，生成 TypeScript 接口时字段类型靠人传参，传错也没有报错。T补 内置了一个类型解析层，可以从 OpenAPI Schema、JSON Schema、DDL 片段里提取字段和类型，渲染时把类型信息直接喂给模板。生成 TypeScript 接口、Java DTO、数据库迁移脚本的时候，字段类型不再是手工维护的字符串，而是从源头解析出来的第一手数据。

第三层，Toolkit，补的是工具链能力。包括 dry-run 预览、生成报告、批量改造、插件机制、diff 导出。这些能力实际上是围绕“生成结果可审查、可回滚、可持续维护”设计的。原版工具只管把文件写出来，写完就结束；T补 把整个过程拆成可观察的步骤，每一步都可以单独检查和干预。

至于名字里的“补”字，是我刻意保留的。它想传达的是：这个项目不打算新造框架，不定义一套和现有架构强耦合的规范，它只是在原版 CodeMagician 的基础上补齐缺口。你要升级原有模板，不需要推翻重来；你不想用 AST 改造，可以继续只做模板生成。这样“补”的姿态，反而让团队接受起来更顺。

1.2 核心问题：新项目要快，存量项目要稳

我在设计 T补 的时候，把问题分成两类：新文件通过模板生成，存量文件通过 AST 规则修改。这两个思路完全不同，如果混在一起处理，很快就会失控。

新文件生成的核心诉求是“快”。新模块要落地，你需要的是标准化的 Controller、Service、DTO、Mapper，这些文件内容高度相似，差别只在模块名、字段名和少数业务方法。用模板生成，最大的好处是不用再复制旧模块然后全局替换变量，也不会出现“上一个模块叫 orderItem，这次替换成 userOrder”时把数据库列名也一起换了的尴尬。

存量文件改造的核心诉求是“稳”。实际开发中，大部分重复工作恰恰发生在存量代码上：给现有 Controller 加统一鉴权、给 Service 方法加日志、把旧的异步回调改成 Promise、把一坨手写的参数校验替换成统一注解。这些事情如果用文本替换来做，很容易误伤字符串、注释、甚至同名但不同作用的局部变量。T补 引入了 AST 变更器，它先把目标文件解析成语法树，再在语法树层面做修改，最后序列化回代码。这样改动的位置是结构化的，不会因为一个字符串出现在注释里就被误改。

1.3 适用场景与设计边界

为了说清楚这个工具适合干什么，不适合干什么，我列一个简单的对照表。

边界也很清楚：T补 不做运行时增强，不拦截编译，不替代代码评审。它只负责在文件落地之前和落地瞬间做该做的事。落到团队里，它就是一把“代码前置处理器”，模板和规则由熟悉架构的人维护，普通开发者在命令行里填参数就能得到符合规范的文件。

2. 整体架构与工作流程

2.1 核心模块划分

CodeMagicianT 没有用复杂的微服务架构，就是一个普通 Node.js CLI，但内部模块拆得比较清楚。

模块之间靠数据流连接：config-loader 读配置，variable-resolver 产出渲染上下文，template-engine 和 ast-mutator 分别处理不同来源的变更，最后统一交给 output-writer 落盘。这样每个环节都能单独测试，排查问题的时候也容易定位。

2.2 一条生成命令背后的执行链路

一次cmt run的执行链路，我拆成七个阶段，每个阶段都有明确产物。

1. 加载配置：先读当前目录的codemagiciant.yaml，再递归合并用户主目录的全局配置。项目配置覆盖全局配置，命令行参数覆盖项目配置。这个顺序很重要，可以保证团队里有一套默认基线，个人又能在本地覆盖。
2. 解析变量：把配置里声明的variables和命令行传入的参数合并，缺失必填变量直接报错。变量类型支持 string、number、boolean、array、object，也可以配置正则校验。
3. 构建渲染上下文：除了用户变量，还会注入系统变量（当前时间、git 用户、项目名）和 type-resolver 解析出的类型信息。
4. 渲染模板：template-engine 逐个渲染配置里声明的模板文件，输出到内存，不直接写磁盘。
5. 应用 AST 变更：如果配置里有astRules，这一步会读入目标文件，解析成 AST，按规则修改，再序列化回代码。
6. 输出与审查：默认情况下先不写入，而是输出一份 diff。用户确认后再写入。写入前会备份原文件，避免覆盖后想回退却找不到原内容。
7. 生成报告：在.cmt-report/目录下生成报告文件，记录本次改动了哪些文件、哪些内容发生变化、耗时多少。后续可以接进 CI，用来追踪模板升级导致的全量变化。

链路顺序不是随意的。模板渲染放在 AST 变更之前，因为模板生成的新文件可能需要被 AST 规则继续处理，比如生成完一个组件文件后，再往它的 import 区域插入一条公共引用。如果顺序反了，awkward 的引用位置会让我多写不少补丁逻辑。

2.3 模板引擎选型与二次封装

模板引擎我一开始想省事，直接找现成的。试用过 Handlebars、EJS、Nunjucks，把条件、循环、宏复用、模板继承几个维度拉出来对比，最后留在项目里的是 Nunjucks。

Handlebars 的优点是语法简单，但遇到复杂逻辑就很别扭，循环套条件写起来像在猜谜。EJS 自由度很高，本质上可以在模板里写 JavaScript，但自由度太高之后，团队成员很容易把业务逻辑塞进模板里，模板慢慢就变成一团乱麻。Nunjucks 在控制流和可维护性之间比较平衡，而且自带宏机制，公共头部、公共 import、公共装饰器都可以收敛到一个宏文件里。

选完引擎，我还在外面包了一层封装，主要是三件事。第一，启用.njk后缀，让编辑器能正确识别模板语法。第二，内置若干业务过滤器，比如lower、camel、pascal，用来统一标识符风格。第三，在渲染之后做一次残留占位符检查，如果模板变量没有传全，渲染结果里还留着{{ xxx }}，直接报错提示，而不是把坏文件写到磁盘上。

3. 实操：从零搭建一套生成规则

3.1 安装 CLI 与初始化目录

T补 的安装方式很简单，就是一个全局 npm 包。

npm install -g @codemagiciant/cli cmt --version cmt init crud-template cd crud-template

cmt init会生成一个标准模板工程目录，看起来大概是这样：

crud-template/ ├── codemagiciant.yaml ├── templates/ │ ├── _common.njk │ ├── controller.ts.njk │ └── service.ts.njk └── openapi/ └── petstore.json

codemagiciant.yaml是核心配置，templates目录放模板文件，openapi目录放类型来源。你可以把整个目录提交到 git 仓库里，作为团队公共模板库，新成员 clone 下来就能直接使用，不用再花时间搭环境。

3.2 编写 codemagiciant.yaml 配置

我以一个标准 CRUD 模块的生成规则为例，拆解配置文件。

name: crud-module version: 0.1.0 description: 生成一个标准 CRUD 模块 variables: moduleName: type: string require: true validate: "^[a-z][a-zA-Z0-9]+$" needLog: type: boolean default: true templates: - input: templates/controller.ts.njk output: src/modules/{{ moduleName | lower }}/controller.ts strategy: overwrite - input: templates/service.ts.njk output: src/modules/{{ moduleName | lower }}/service.ts strategy: merge-import importDedupe: true

variables部分声明了生成规则的外部输入。moduleName是必填的字符串，还配了一个正则校验，防止有人传中文或者带空格的模块名进去。needLog是一个布尔值，默认 true，用来控制模板里是否生成日志装饰器。把这些参数显式声明出来，等于给生成器定义了一个“接口”，谁调用它，都得按接口来。

templates部分是渲染规则列表。input是模板文件路径，相对于配置文件所在目录。output是目标文件路径，支持模板变量和过滤器。比如{{ moduleName | lower }}会把模块名转成小写，再拼进目录路径。strategy是落盘策略，overwrite表示直接覆盖，merge-import表示如果文件已存在，则只合并 import 语句，不覆盖文件其他内容。importDedupe开启后会自动去重 import，避免同一个包被引入两次。

3.3 模板文件的组织与写法

.njk后缀的模板文件，默认使用 Nunjucks 语法。我建议把公共片段抽到一个单独的_common.njk文件里，用宏来复用。这样主模板只关注业务结构，公共部分统一维护。

下面是一个简化版的 Controller 模板。

{# templates/controller.ts.njk #} {% import "_common.njk" as common %} import { Controller, Get, Post } from "@nestjs/common"; import { {{ moduleName }}Service } from "./{{ moduleName | lower }}.service"; @Controller("{{ moduleName | lower }}s") export class {{ moduleName | pascal }}Controller { constructor(private readonly service: {{ moduleName | pascal }}Service) {} @Get() list() { return this.service.list(); } {{ common.standardPost(moduleName) | safe }} }

公共宏文件长这样。

{% macro standardPost(name) %} @Post() create(@Body() dto: Create{{ name | pascal }}Dto) { return this.service.create(dto); } {% endmacro %}

宏里的name是传入参数，通过| pascal过滤器转换成大驼峰命名。这样 Controller 里那些重复的端点定义就收敛到了一个地方。以后要统一加鉴权装饰器，只需要改宏文件，所有引用它的模板都会跟着变。

这里有一个必须注意的坑：Nunjucks 默认开启了 autoescape，会把 HTML 特殊字符转义。虽然生成代码场景一般不太会遇到<和>，但如果你在模板里写了泛型，比如List<Foo>，就可能在渲染后变成List<Foo>。遇到这种情况，需要在变量或宏调用后面加| safe，告诉引擎这段内容是可信的，不要转义。

3.4 生成、预览与校验

模板写好后，先不要急着全量生成，先跑一遍 dry-run。

cmt run --dry-run -v moduleName=order -v needLog=true

dry-run 会在内存里完成所有渲染和 AST 变更，但不会写任何文件。输出会以 diff 形式展示每个文件的改动，新增的文件显示全部内容，被修改的文件只显示变化的部分。这一步是审查模板结果的最快方式。

确认 diff 没问题后，再正式执行：

cmt run -v moduleName=order -v needLog=true

执行完成后，可以用cmt verify做一次静态检查。verify 会检查生成的文件里有没有残留的模板变量、有没有明显不平衡的括号、有没有重复的 import。它不会替代编译器和 linter，但能在早期拦住一批低级错误。我们团队现在把 verify 挂在了生成流程的末尾，跑完生成立即检查，发现问题马上改配置，而不是等到编译阶段才发现。

4. 核心功能拆解：批量补全与存量改造

4.1 AST 改造：给所有 Service 方法加日志埋点

模板生成解决的是“新文件怎么来”的问题，但真正体现 T补 价值的，是它对存量代码的结构化改造能力。这里我用一个实际场景说明：给项目里所有 Service 方法加日志埋点。

用正则做这件事，最经典的结果就是误伤。比如方法里有一行const hint = "deleteUser called";，正则可能把字符串里的deleteUser called也当成方法调用改了；再比如注释里写了一段示例代码，正则同样分不清。AST 方案不存在这个问题，因为它的修改对象是已经解析好的语法树，不会跑到字符串和注释内部去乱改。

在 T补 里，对应的配置长这样：

astRules: - target: "src/modules/**/*.service.ts" visitor: MethodDeclaration action: type: insertStatementBefore code: | this.logger.log("enter {{ methodName }}");

target用 glob 表达式圈定要处理的目标文件。visitor表示要访问的 AST 节点类型，这里用的是 TypeScript 的 MethodDeclaration，也就是类中的方法声明。action定义要做什么操作，insertStatementBefore表示把一段代码插入到当前方法体的前面。{{ methodName }}是 AST 节点上下文提供的变量，运行时会被替换成当前方法名。

执行后，所有匹配到的 Service 方法开头都会多一行日志。由于是 AST 层面操作，它只会作用在真正的方法声明上，不会去碰注释、字符串或对象属性。这一点，是正则替换永远做不到的。

4.2 类型联动：从 OpenAPI/DDL 生成第一手类型

类型联动是 T补 里最有意思的部分，也是很多用过原版工具的人觉得“回不去”的功能。以前手写 TypeScript 接口时，最怕后端接口文档更新，字段增删都靠人眼对比，漏一个就只能在运行时被虐。现在可以直接拿接口定义文件生成类型。

cmt typegen openapi/petstore.json --language typescript --validation zod

它会读取 OpenAPI 文件的 schemas 部分，自动生成 TypeScript interface，然后根据 validation 参数再生成对应的 zod 校验 schema。生成的类型字段来自 schema 的 type 定义，必填字段来自 required 数组，枚举值来自 enum 定义。整个过程不存在手工输入，所以也不会有人为遗漏。

实际使用中，这套能力用的最多的场景是：后端先把 OpenAPI 定义好，前端执行一次 typegen，得到类型文件和校验文件，再跑一段模板生成 API 调用层代码。接口字段改了，重新执行一次 typegen，类型跟着变。原来最让人头疼的“前后端类型不一致”问题，就从“靠人盯”变成了“靠工具保证”。

4.3 插件机制与生命周期

T补 的生成本质是一条流水线，插件机制允许你在流水线的关键节点上挂载自定义逻辑。生命周期钩子有四个：beforeRender、afterRender、beforeWrite、afterWrite。

module.exports = { name: "copyright", beforeRender(ctx) { ctx.variables.year = new Date().getFullYear(); }, afterWrite(ctx) { if (ctx.platform === "git") { ctx.exec("git add -A"); } }, };

这个插件的逻辑很直接：渲染前把当前年份注入到变量里，供模板使用；写入后如果检测到当前是 git 仓库，就把生成的文件自动 add 进暂存区。ctx是一个上下文对象，里面有变量、模板路径、写入结果、平台信息等数据。插件文件可以放在项目的.codemagiciant/plugins/目录下，也可以全局安装。

插件机制让工具不至于越做越重。有些团队可能希望生成完后自动跑 prettier，有些团队希望自动发一条飞书通知，这些需求如果全部内置，CLI 的复杂度会失控。做成插件以后，内置功能只保留最核心的执行引擎，剩下的按需加载。不过我要提醒一句：不要在 afterWrite 里做太重的操作，比如拉全量依赖、跑完整测试，这种事情会拖慢生成流程，也容易把一次简单的代码生成演变成一次发布流程。

5. 踩坑记录与问题排查

5.1 高频问题速查表

工具落地过程中踩过不少坑，有些是文档里根本查不到的。我把高频问题整理成一个速查表，方便排查。

速查表不能解决所有问题，但大部分日常报错都可以从这几类里找到影子。

5.2 两个必须提前躲开的坑

第一个坑是 Windows 路径分隔符。Node.js 在 Windows 上使用path.join时会生成反斜杠，这本身没问题，但如果你把路径拼到 import 语句里，比如import { orderService } from "./services\\orderService"，在跨平台项目里就是灾难。我的解决方式是在 output-writer 里统一做了一次路径规范化，所有输出到代码里的路径都替换成/。如果你在自己写的插件里处理路径，也一定要注意这个点，否则同一份模板在不同同事电脑上会生成风格不一致的代码。

第二个坑是 Nunjucks 对代码模板的转义。Nunjucks 的 autoescape 默认开启，它主要转义 HTML，对代码生成影响不大。但 JavaScript 模板字符串里的${}不是 HTML 实体，不会被转义，所以不存在被转义的问题。真正的坑在于{% raw %}块。如果你在模板里写了一段包含{{ variable }}的参考示例代码，但这段代码本来不打算作为变量渲染，你必须把它包裹进{% raw %}和{% endraw %}之间。否则 Nunjucks 会尝试解析它，找不到变量就抛异常，或者渲染成空串。这类问题排查起来很费时间，因为报错信息往往只提示模板第几行有问题，不会告诉你哪个变量拼错了。

5.3 调试三板斧

遇到生成结果和预期不符时，我建议按顺序做三件事。

第一，cmt run --dry-run。先不落盘，只输出 diff。这是最快确认问题的手段。很多模板问题在 diff 阶段就能发现，比如某个字段没有值、某段内容整体缺失。

第二，CMT_DEBUG=* cmt run。环境变量会输出每个模块的执行时间、模板路径、渲染上下文快照。有时候模板渲染很慢，打开 debug 能看到具体耗时分布，定位到是哪个模板遍历了大数组。

第三，看.cmt-report/diff.json。工具每次执行都会生成一份结构化的 diff 报告，记录了所有变更前后的内容。当你升级了公共宏，导致生成结果大面积变化时，先看报告再决定要不要全量重新生成，可以避免把不该动的文件也一起覆盖掉。

6. 下一步规划与个人体会

6.1 我还在摸索的几个方向

CodeMagicianT 目前还在持续迭代，我手头有几个方向正在实验。

一个是模板中心。把团队里积累的模板收集到一个可浏览、可检索的仓库里，新项目初始化的时候直接拉取，而不是靠聊天记录转发模板包。另一个是可视化配置。现在codemagiciant.yaml还是手写 YAML，对不太熟悉字段的人来说有门槛。如果能在网页上拖拽配置变量和模板规则，再导出 YAML，团队上手会更容易。

还有一个方向是跟大模型结合，让模型直接根据业务描述生成配置文件甚至模板。但目前试下来，比较适合小项目、小模板，生成复杂模板时还是需要人来调。所以短期内我依然会把重心放在稳定执行引擎和提升模板复用性上。工具这行，花哨功能不如稳。

6.2 关于工具边界的个人体会

我记得第一次把 T补 的规则推给整个小组时，有同事问：这不就是格式化代码吗？我没反驳。因为工具本身不改变编码习惯，它只是把习惯固化成模板，让大家不用每次从零开始，也不用在 Code Review 时反复纠正命名和结构。

真正让流程走得顺的，不是命令跑得多快，而是模板谁在维护、变更怎么走评审。现在我反而觉得，维护模板比写业务代码更费脑子。你每写一个变量，都相当于给后人留了一个接口，写死了就是债，写活了才是资产。根据我的经验，工具落地的关键不是功能数量，而是“生成的结果是否可信”和“出了问题能否快速回退”。只要这两点做到位，团队自然愿意用。