从复制粘贴到模板驱动：t3code代码生成器实战

t3code 这个项目，是我半年多前被一份 800 行的重复代码逼出来的。当时给一个后台管理系统补模块，每个模块至少要生成 7 个文件：数据库实体、Mapper 接口、Service 实现、Controller、前端 API 封装、表单校验、路由注册。名字不一样，字段不一样，其余结构几乎完全一样。复制粘贴十分钟，改名字四十分钟，最要命的是漏改一处字段名，编译直接红一片。于是我把这堆重复劳动拆成三步：提取模板、转换变量、追踪输出，项目代号就叫 t3code——template、transform、track。

如果你是前端、全栈，或者平时只写脚本的人，只要也被“新模块 = 复制旧模块再全局替换”折磨过，这篇复盘值得看看。用 t3code 的思路，你可以把一套 CRUD 从半小时压缩到半分钟，而且生成结果和你手工写得一模一样。我会把选型原因、引擎实现、真实踩坑都写清楚，模板和代码可以直接抄走改。下面进入正题。

1. t3code 的由来：不是造轮子，是被重复劳动逼出来的

1.1 痛点场景：复制粘贴那套 CRUD，为什么总是出错

先说一个具体的场景。假设要新增一个“用户模块”，后端通常要配套这些文件：

• UserEntity.java：数据库实体
• UserMapper.java：MyBatis 或 JPA 的 Mapper 接口
• UserService.java：业务逻辑
• UserController.java：对外接口
• 前端src/api/user.ts：请求封装
• 前端views/user/List.vue、Edit.vue：页面

这些文件里的命名规则差异很大：Java 类名要UserEntity，包目录要用user，数据库表名要user，前端 API 文件叫user.ts，页面目录叫user。靠人工改，最典型的问题就是复制出来的UserService.java里 import 了UserDto，但实际 DTO 文件叫UserInfoDTO，等编译才发现。

// 某次复制粘贴后出现的真实错误 import com.example.modules.UserDto; // 实际类名是 UserInfoDTO public UserDto getUserById(Long id) { return mapper.selectById(id); }

表面上看只是一行 import 写错了，背后其实是“找出哪里需要变”这个过程特别容易漏。更麻烦的是，团队里每个人风格不一样：有人把表字段叫create_time，有人叫createdAt，生成出来的代码进了仓库就变成历史遗留问题。

复制粘贴最大的成本从来不是粘贴本身，而是“心算哪些地方要改”。t3code 想解决的就是这件事：把命名规则固化到模板里，把变量交给引擎统一处理，人只需要输入moduleName=user和字段列表，剩下的路径、类名、包名、前端变量名都自动算好。

1.2 为什么不用现成的 Plop、Hygen 或 Yeoman

说实话，在动手写 t3code 之前，我先后试过 Plop、Hygen，也看过 Yeoman。它们都是好工具，但我用下来总觉得差一点。

不是说这些工具不好，而是我的场景里最痛的不是“缺工具”，而是缺一个能把“命名规则”固化下来的东西。t3code 的核心定位非常窄：

• 模板即文件：templates目录下摆什么结构，生成出来就是什么结构
• 变量由引擎预处理：camelCase、pascalCase、snakeCase这些转换统一在引擎层做
• 输出路径由模板自己声明：每个模板文件头部写output字段，支持变量

这点很重要。很多脚手架把“输入变量”和“输出路径”拆成两套配置，结果变量一多就找不到对应关系。t3code 直接把路径写进模板，看到模板第一眼就知道它会生成到哪里。

2. 技术选型与工程结构：为什么是 Node.js + TypeScript

2.1 Node.js 是我唯一没纠结的选项

确定要自研之后，技术栈几乎没有第二种选择。原因很实际：

• 团队前端为主，Node.js 人人能改，Python 和 Go 还需要一部分人额外去学
• Handlebars 在 JS 生态里非常成熟，模板语法、helper 机制都够用
• Commander 做 CLI 参数解析，prompts 做交互式确认，chokidar 做文件监听，全都是现成轮子
• 后续如果要接 VS Code 插件，TypeScript 可以直接复用类型定义，不用再做一层桥

我承认 Go 的编译产物很香，单文件分发、部署简单。但 t3code 是个本地开发工具，不是线上服务，部署成本低一点高一点无所谓，反倒是“改完立刻能跑”的体验更重要。Python 的问题则是环境版本太乱，模板引擎选择也多，反而容易踩坑。

最终依赖极其克制：

{ "name": "t3code", "version": "0.1.0", "bin": { "t3code": "dist/cli.js" }, "scripts": { "build": "tsc", "dev": "ts-node src/cli.ts", "watch": "ts-node-dev --ignore templates --ignore src/generated src/cli.ts" }, "dependencies": { "commander": "^11.0.0", "handlebars": "^4.7.8", "prompts": "^2.4.2", "chokidar": "^3.5.3" }, "devDependencies": { "typescript": "^5.2.0", "@types/node": "^20.0.0" } }

注意watch脚本里的两个--ignore，后面讲坑的时候会专门说，这里先埋个伏笔。

2.2 目录结构：让模板和引擎彻底分离

t3code 的目录结构长这样：

t3code/ ├── src/ │ ├── cli.ts │ ├── config.ts │ └── engine/ │ ├── extract.ts │ ├── render.ts │ └── writer.ts ├── templates/ │ └── crud/ │ ├── entity.java.tpl │ ├── mapper.java.tpl │ ├── service.java.tpl │ ├── controller.java.tpl │ ├── api.ts.tpl │ └── List.vue.tpl ├── .t3code.config.json ├── package.json └── tsconfig.json

src/engine里三个文件各干各的：

• extract.ts：从模板文件里解析出 frontmatter，也就是头部---之间的配置
• render.ts：用 Handlebars 渲染模板主体内容
• writer.ts：负责目录创建、覆盖保护、写文件

templates是纯模板目录，里面不允许写业务逻辑。所有逻辑都在引擎层，模板作者只需要关心“生成出来的文件长什么样”。这种分工很重要，因为模板往往由不同人维护，如果模板里塞太多 helper，最后会变成一锅粥。

2.3 配置协议：少即是多

.t3code.config.json一开始被我想得很复杂，后来删到只剩几个字段：

{ "templateRoot": "templates", "outputRoot": "src/generated", "presets": { "backend": { "outputRoot": "src/main/java/com/example", "template": "crud/**" } } }

• templateRoot：模板根目录，默认templates
• outputRoot：生成根目录，默认src/generated
• presets：预设，可以针对不同工程指定不同输出根目录

为什么这么精简？因为我把“输出路径”放到了模板 frontmatter 里，配置只需要定义“根”就够了。具体每个文件落到哪里，由模板自己声明。这样调整一个模板的生成位置，不需要翻配置；调整一整组模板的输出根目录，才需要碰presets。我踩过的坑是：一开始配置里放了很多format、indent、extension之类的选项，到最后根本没人用，反而让工具变得难理解。

// 一个典型的 presets 用法 { "presets": { "frontend": { "outputRoot": "src/api", "template": "web-api/**" } } }

执行t3code generate web-api/user --preset frontend，就会以templates/web-api下的模板生成，写到src/api下。这样做的好处是：同一个模板目录可以被不同项目复用，只是输出位置不同。

3. 引擎核心：模板语法、变量预处理与批量生成流程

3.1 模板语法：frontmatter + Handlebars

t3code 的模板文件后缀统一用.tpl，内容分两部分：头部 frontmatter 和正文。frontmatter 用---包裹，里面至少要有output字段，指定生成目标路径。

看一个 Java 实体模板：

--- output: src/main/java/com/{{company}}/modules/{{snakeCase moduleName}}/{{pascalCase moduleName}}Entity.java --- package com.{{company}}.modules.{{snakeCase moduleName}}; import javax.persistence.*; import java.util.Date; @Entity @Table(name = "{{snakeCase moduleName}}") public class {{pascalCase moduleName}}Entity { {{#each fields}} @Column(name = "{{snakeCase this.name}}") private {{this.type}} {{camelCase this.name}}; {{/each}} private Date createdAt; }

注意到没，output本身也用了变量。也就是说，你输入moduleName=user，这个文件会自动生成到src/main/java/com/example/modules/user/UserEntity.java。不用额外写任何路径映射。

提取 frontmatter 的代码很简单，但有个细节值得注意：

// src/engine/extract.ts export function extractFrontmatter(source: string) { if (!source.startsWith('---')) { return { frontmatter: {}, content: source }; } const end = source.indexOf('\n---', 4); if (end === -1) { throw new Error('template frontmatter is not closed: expected "---" on a new line'); } const raw = source.slice(4, end); const content = source.slice(end + 4); const frontmatter: Record<string, string> = {}; for (const line of raw.split('\n')) { const idx = line.indexOf(':'); if (idx > 0) { frontmatter[line.slice(0, idx).trim()] = line.slice(idx + 1).trim(); } } return { frontmatter, content }; }

这里没有用 YAML 解析库，因为 t3code 的 frontmatter 只需要output一个字段，用简单解析就够了。真引一个 YAML 库反而增加维护成本。

3.2 变量预处理：从一条命令参数到一组模板变量

命令行里的原始输入通常是moduleName=user、fields=name:string,age:number。模板里需要的是pascalCase、snakeCase、camelCase各种风格。我的做法是注册全局 Handlebars helper，让模板里直接用{{pascalCase moduleName}}：

// src/engine/render.ts import Handlebars from 'handlebars'; function toCamelCase(value: string): string { return value.replace(/[-_]([a-z])/g, (_, c) => c.toUpperCase()); } function toPascalCase(value: string): string { const camel = toCamelCase(value); return camel.charAt(0).toUpperCase() + camel.slice(1); } function toSnakeCase(value: string): string { return value.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase(); } Handlebars.registerHelper('camelCase', toCamelCase); Handlebars.registerHelper('pascalCase', toPascalCase); Handlebars.registerHelper('snakeCase', toSnakeCase);

字段列表也要在引擎层提前解析好，而不是把"name:string,age:number"一整个字符串丢给模板。原因很简单：模板里要遍历的是一个个字段对象，如果只给字符串，每个模板都得自己 split，重复又容易错。

// 把字段字符串解析成对象数组 function parseFields(input: string) { if (!input) return []; return input.split(',').map((item) => { const [rawName, rawType] = item.split(':'); const name = rawName.trim(); return { name, type: (rawType || 'string').trim(), camelName: toCamelCase(name), pascalName: toPascalCase(name), snakeName: toSnakeCase(name), }; }); }

这样模板里就可以写{{this.pascalName}}、{{this.snakeName}}，不需要再显式套 helper。凡是能用“预计算”解决的问题，就不要在模板里做二次逻辑。这是我做 t3code 得到的最重要的一条经验。

3.3 批量生成主流程：扫描模板、渲染、写文件

生成命令的主流程可以浓缩成这一段：

// src/engine/render.ts import { glob } from 'glob'; import { extractFrontmatter } from './extract'; import { writeWithProtection } from './writer'; export async function generate(templateName: string, variables: Record<string, unknown>) { const pattern = `${config.templateRoot}/${templateName}/**/*.tpl`; const files = await glob(pattern, { posix: true }); if (files.length === 0) { console.error(`[t3code] no templates found under: ${pattern}`); process.exit(1); } for (const file of files) { const source = await fs.promises.readFile(file, 'utf-8'); const { frontmatter, content } = extractFrontmatter(source); const renderContext = { ...variables, fields: parseFields((variables.fields as string) || ''), }; // 用 frontmatter.output 作为目标路径模板 const compiledOutput = Handlebars.compile(frontmatter.output); const targetPath = compiledOutput(renderContext); const rendered = Handlebars.compile(content, { strict: true, })(renderContext); await writeWithProtection(targetPath, rendered); } }

strict: true是我后来加的。默认 Handlebars 对未定义变量会静默渲染成空字符串，这在代码生成场景里非常危险：你漏传一个moduleName，生成出来的文件照样写出去了，只是路径和类名都不对，编译期才炸。开启strict后，一旦变量缺失，渲染阶段就会抛出明确错误：

[Handlebars] "moduleName" not defined in "src/engine/templates/crud/entity.java.tpl"

错误信息里带上模板文件名，定位问题快很多。不过要注意，strict会让#if判断未定义变量时也抛错，所以模板里用条件判断时要把变量默认值都配好，或者先做一层默认值注入。我在实际使用中更推荐在renderContext里把所有变量都显式设置默认值，避免模板作者为了“不报错”而写一堆#if。

3.4 dry-run：只打印不写文件

批量生成很容易发生“一跑就是十几个文件”的情况，如果路径算错了，目录就长歪了。所以我给generate加了一个--dry-run参数：

t3code generate crud --moduleName user --fields name:string,age:number --dry-run

输出：

[t3code] would write: src/main/java/com/example/modules/user/UserEntity.java [t3code] would write: src/main/java/com/example/modules/user/UserMapper.java [t3code] would write: src/main/java/com/example/modules/user/UserService.java [t3code] would write: src/main/java/com/example/modules/user/UserController.java

很多工具的 dry-run 只是把“路径列表”打印出来，没多大用。t3code 的做法是在写文件前把所有模板都渲染出来，然后逐条上报结果，这样能看到每个文件渲染后的大小、行数，甚至可以加上--verbose输出文件内容摘要。这个功能在调整模板结构时帮了我大忙。

4. 实战中踩过的四个坑：覆盖保护、路径分隔符、布尔参数与 watch 循环

4.1 覆盖保护：默认绝对不能直接覆盖

第一次用 t3code 时，我图省事，writeFileSync直接写，结果把一个已经手工调整过的配置文件冲掉了。那次丢的代码不多，但教训很深刻：生成工具一旦开始被团队使用，默认行为应当是“保守”，而不是“高效”。

现在的writeWithProtection是这样：

// src/engine/writer.ts import prompts from 'prompts'; export async function writeWithProtection(targetPath: string, content: string) { const abs = path.resolve(config.outputRoot, targetPath); if (fs.existsSync(abs)) { if (config.overwrite === 'always') { await fs.promises.writeFile(abs, content); return; } const res = await prompts({ type: 'confirm', name: 'value', message: `${targetPath} already exists. Overwrite?`, initial: false, }); if (!res.value) { console.log(`[t3code] skip: ${targetPath}`); return; } } await fs.promises.mkdir(path.dirname(abs), { recursive: true }); await fs.promises.writeFile(abs, content); }

三个具体设计：

• 交互确认的默认值是false，不是true。宁可让人多按一次回车，也不能默认覆盖
• 配置里提供overwrite: "always"的逃生口，但只建议在 CI 或一次性生成时用
• 跳过时不报错，只打印skip，方便在日志里看出哪些文件没动

4.2 Windows 路径分隔符：反斜杠会咬人

这个问题是在前端 API 文件上爆出来的。生成的src/api/user.ts里有一行 import：

import request from '../utils/request';

这个没问题。但有些模板会生成多级目录的引用，比如：

import UserService from '../../../api/user.service';

在 Windows 上，如果目标路径是用path.join拼出来的，就变成了：

import UserService from '..\\..\\..\\api\\user.service';

浏览器和 Node 都不认反斜杠，直接报错。根因在于“文件系统路径”和“代码里的 import 路径”是两回事。文件系统里用path.join没问题，但写到代码里的必须是正斜杠。

解决办法是在所有输出相关的位置统一做一次转换：

function toPosixPath(p: string): string { return p.replace(/\\/g, '/'); }

然后：

• 模板 frontmatter 里写输出路径时，用正斜杠
• 渲染结果里的import字符串，如果是用变量拼的，也必须经过toPosixPath
• glob扫描模板文件时，返回的路径本身就是正斜杠，但用户手输的路径可能是反斜杠，要在入口处统一

我后来加了一条测试用例：在 Windows 和 Linux 上分别跑生成，然后 git diff 生成结果，确保完全一致。这个坑看起来小，但踩一次要花半小时才能定位。

4.3 布尔参数被字符串化："false"也是true

这是 Commander 参数解析的经典坑。我在 CLI 里定义了一个选项，希望用户传布尔值：

t3code generate user --isPublic false

一开始的写法是：

program .command('generate') .requiredOption('--moduleName <name>', 'module name') .option('--isPublic <value>', 'is public flag', false) .action(async (template, options) => { await generate(template, options); });

问题在于：命令行参数永远是字符串，所以options.isPublic的值是字符串"false"，不是布尔值false。而 Handlebars 的#if判断只看 truthy / falsy，字符串"false"是 truthy，于是模板里：

{{#if isPublic}} public class {{pascalCase moduleName}}Service { {{else}} class {{pascalCase moduleName}}Service { {{/if}}

会错误地走public分支。最直接的解决办法是布尔选项不带值，用 flag 形式：

t3code generate user --public

program.option('--public', 'mark as public', false);

--public出现就是true，不出现就是false，根本不存在字符串问题。如果你的场景确实需要接收"true"/"false"字符串，就写一个解析函数：

function parseBoolean(value: string) { return value === 'true' || value === '1' || value === 'yes'; } program.option('--isPublic <value>', 'is public flag', parseBoolean, false);

这个函数要显式处理默认值，别只用Boolean(value)，因为Boolean("false")的结果也是true。

4.4 watch 循环：生成到一半，项目重启了

开发 t3code 时我用的是ts-node-dev，监听src目录，改动引擎代码自动重启。结果第一次跑生成后，程序突然重启了，生成的项目也一直在崩。排查了很久才发现，问题不在于ts-node-dev自己，而在于 watch 的范围没有排除输出目录。

这里有两层坑：

1. 模板目录templates不是源码，但ts-node-dev默认也会监听整个工作目录。模板一改，CLI 重启，代价不大，但很烦。
2. 更严重的是，如果你用chokidar监听源码目录，而outputRoot也在源码目录里，每次生成一批新文件，watch 就会触发一次重新构建，构建再生成文件，无限循环。

解决办法在 package.json 里已经写了：

ts-node-dev --ignore templates --ignore src/generated src/cli.ts

--ignore后面既能跟目录，也能跟 glob。实际团队使用场景里，最好在.t3code.config.json里加一个watchIgnore字段，让不同项目的输出目录不会被引擎自己监听。这个坑在单人开发时不容易暴露，一旦接进 CI 或多人协作，就会出现“生成一次、循环十分钟”的诡异问题。

5. 从单人脚本到团队工具：命令设计、doctor 验证与落地建议

5.1 命令设计：把常用操作收敛成四个动词

t3code 的命令一开始很乱，什么gen、create、new都有，后来收敛成五个：

t3code init t3code generate crud --moduleName user --fields name:string,age:number t3code list t3code doctor t3code generate crud --moduleName user --dry-run

• init：在当前目录生成.t3code.config.json和空模板目录
• generate <template>：按模板生成文件，核心命令
• list：列出templateRoot下所有模板，以及每个模板的 frontmatter 信息
• doctor：检查所有模板的语法、frontmatter 完整性、变量引用是否正确

list看起来简单，但对团队规范很有用。没有这个命令前，新同事得翻模板目录才知道有哪些模板能用。有了list，直接看输出：

[t3code] templates: crud -> 6 files, variables: moduleName, fields web-api -> 2 files, variables: moduleName, fields

这里我特意让list显示“变量列表”，因为很多模板需要的变量比命令行传参里的多，提前展示能减少使用者的试错成本。

5.2 doctor：让模板问题在生成前就暴露

模板语法错误很隐蔽，因为只有真正生成时 Handlebars 才会报错。如果某个模板已经被用了几个月，某个变量名被删了，所有生成都会失败，但没人知道是哪一行的问题。

doctor做的事很简单：遍历所有模板文件，逐个编译，并尝试用一组“空变量”做渲染：

// src/commands/doctor.ts import { glob } from 'glob'; import Handlebars from 'handlebars'; import { extractFrontmatter } from '../engine/extract'; export async function doctor() { const files = await glob(`${config.templateRoot}/**/*.tpl`); let hasError = false; for (const file of files) { const source = await fs.promises.readFile(file, 'utf-8'); const { frontmatter, content } = extractFrontmatter(source); if (!frontmatter.output) { console.error(`[t3code] ${file}: missing frontmatter.output`); hasError = true; } try { Handlebars.compile(content, { strict: true })(emptyVariables()); console.log(`[t3code] ok: ${file}`); } catch (e) { console.error(`[t3code] error: ${file}: ${e.message}`); hasError = true; } } process.exit(hasError ? 1 : 0); }

注意我这里用了一个emptyVariables()，目的是让strict模式把所有缺失变量都“炸”出来。一开始我直接用{}渲染，结果每个模板都报一堆变量不存在，反而看不出真实错误。后来改成：变量缺失时只记录变量名，等所有模板扫完后再汇总。这样 doctor 能一次性列出所有模板的问题，而不是遇到第一个错误就退出。

5.3 如果要把 t3code 用到自己的团队，我的建议

最后分享几条落地经验，都是我自己趟过水以后总结的：

第一，先收集 20 个真实模板，再写引擎。不要一上来就设计抽象的模板语法和插件机制。我第一版引擎做了很多“看起来很强大”的功能，比如多级继承、函数式 helper、动态目录映射，结果实际用到的不到 20%。后来全部删掉，只留了 Handlebars 和 frontmatter。真正有用的工具，往往是那些“看起来平平无奇”的。

第二，模板必须入库，走代码评审。模板一旦成为团队的唯一来源，它的质量直接决定生成代码的质量。建议把templates目录放在项目仓库里，任何修改都走 MR/PR，至少在合并前要看一眼 diff。模板文件不像代码那样有编译期校验，doctor也只能查语法，查不了业务逻辑。

第三，生成结果要给人留后路。我最初的想法是“只要模板对，生成出来的文件不需要再手改”。现实是，总会有人生成后手动改一小段，然后这个文件就不再适合被模板覆盖。所以覆盖保护必须是默认行为，同时要在生成日志里明确提示哪些文件被跳过。不要强行让工具比人更聪明。

第四，dry-run 是团队的必需品。单个开发者可以直接跑；但团队使用，尤其涉及多个模块时，最好让执行者养成先--dry-run看一眼路径和文件数的习惯。一次生成十几个文件，如果路径错了，git 里会多出一大堆垃圾目录，清理起来比写代码还烦。

我在实际使用中还发现一个不错的扩展方向：把 t3code 的生成结果先走一次git diff，确认无误后再真正写入磁盘。这个功能我留在了--dry-run --verbose里，后续可以直接升级成“check 模式”。

最后说一句心里话：t3code 不是那种能改变行业的大项目，它更像是被日常重复劳动逼出来的小工具。但恰恰是这种小工具，让我真正理解了“模板驱动开发”的价值——不是替人写代码，而是替人记住那些本来就不该由人记的规则。如果你也有一个高频重复的代码模式，花半天时间做成模板，长期来看一定回本。