★ FEATURED ARTICLE 1. 从“造轮子”说起t3code 这个项目的来龙去脉先说清楚 t3code 是个什么。简单讲它是一个基于 Node.js 的命令行代码生成工具核心功能是读取一组带有占位符的模板文件结合开发者输入的配置参数批量生成标准化代码文件。我最初做这个小工具纯粹是因为团队里每个新项目都要重复手写 CRUD 接口、数据库模型、DTO 转换类——这些代码的结构高度相似只有字段名和表名在变。手写一遍两遍还能忍受写到第十几个项目的时候我开始意识到这里面有大量的重复劳动。t3code 这个名字没有特别复杂的含义“t3”取自当时项目里约定的三段式模板层级组织方式也就是“基础模板 - 子模板片段 - 变量字典”三层的缩写“code”自然是代码生成的意思。名字叫得朴素但它在团队内部解决的痛点非常实际新项目起步时从零到能跑通第一个接口原本需要约两人天的时间用 t3code 之后压缩到了两小时以内。这篇内容适合谁看我觉得主要是两类人一类是正在为重复性编码工作发愁、想自己搞一个脚手架工具的开发人员另一类是对代码生成技术本身感兴趣的工程师想了解模板引擎、CLI 设计、配置解析这些东西在一个真实项目里是怎么落地的。我不打算写成官方文档式的教程而是把当时做这个工具时的思考过程、踩过的坑、以及最后沉淀下来的实操方法尽量原原本本地讲出来供你参考。2. 整体设计与思路拆解为什么走自定义模板这条路2.1 现有脚手架工具的局限动手写 t3code 之前我其实花了一段时间去对比市面上已有的脚手架工具。最主流的几个方案包括 Yeoman、Plop、Hygen还有各框架官方推荐的 create 系列工具都有自己的特点和优势。Yeoman 功能全面生态成熟但配置项复杂generator 的编写学习成本不低Plop 轻量灵活适合小规模文件生成但遇到稍微复杂的组合场景时内置的模板块逻辑显得不够用Hygen 的结构化程度高但对模板文件的管理方式偏重用在单体项目里有点大材小就。真正推动我自研的核心原因是这样一个细节团队项目里大量生成代码并不只是“新建文件”而是在已有代码的多个文件、多个位置上做增量修改。比如给一个已有的业务模块新增数据权限控制需要同时改动实体类、Mapper 接口、XML 文件、Service 实现这几个不同位置而且不同位置的改动模式还不太一样。这类需求用现成的文件级脚手架工具来做很别扭往往要拆成好几个 generator 配合处理维护成本反而上去了。于是我把需求梳理成了三条明确的要求第一模板体系必须支持分片嵌套同一段公共逻辑只维护一份第二生成过程中要能对多个目标文件做追加、替换、删改操作第三模板之外的能力要能通过自定义 JavaScript 函数扩展因为总有模板语法表达不了的业务逻辑。2.2 三段式模板组织基础模板、子模板片段、变量字典设计模板组织方式时我参考了团队现有代码仓库的目录习惯最终确定了三个层次。基础模板对应一个完整的目标项目形态它定义了整个项目的骨架比如标准目录结构、启动类、配置文件的初始形态子模板片段是更细粒度的可复用单元比如一段通用的分页查询逻辑、一个统一的响应包装类、一段常规的日志打印配置变量字典则集中管理模板中出现的所有占位变量包括变量名、默认值、类型校验规则。这个划分的最大好处是隔离变化。当公共代码需要修改时只动子模板片段由 t3code 在生成时自动将其嵌入到所有引用它的基础模板中不同类型项目之间的差异点则收敛到变量字典和对应的映射配置中。整个生成动作最终被抽象成“输入一个变量字典 选定一批基础模板 输出完整代码”团队成员普遍反馈理解门槛很低。配置层面我也做了简化。t3code 使用一个t3.config.json作为主配置文件里面声明项目类型、模板路径、输出目录、以及生成时需要交互确认的参数列表。变量字典既可以放在配置文件里也可以单独抽成一个参数文件通过命令行参数传入。实际使用下来后者更适合多项目复用的场景配置文件保持干净差异全部收敛到各自的参数文件里。2.3 为什么选择 Node.js 而不是 Python 或 Go技术选型当时也算是一次小型评估。生成器本质上是文本处理工具Python 做文本处理也很顺手Go 编译出来的二进制分发又很方便但我最终还是选了 Node.js主要原因是团队里前端工程师占多数JavaScript/TypeScript 的基础更普遍。任何成员想给 t3code 增加新的模板或者扩展功能不需要跨语言学习。Node.js 生态里现成的依赖帮了大忙。命令行参数解析用 commander交互式问答用 inquirer文件监听和批量操作直接用原生 fs 模块。最重要的模板引擎我选了 Handlebars它语法直观、支持 partial 分片而且可以在模板里注册自定义 helper 函数很好地满足了我对分片嵌套和逻辑扩展的需求。实际上我后来也验证了一件事选 Python 或 Go 并不是不行而是在这个项目的特定语境下Node.js 的团队熟悉度所带来的“可维护性红利”远大于语言本身的性能或分发优势。对于一个内部工具来说大家愿意改、改得动比它跑得快更重要。3. 核心细节解析模板语法与变量注入机制3.1 Handlebars 模板语法与自定义 Helpert3code 的模板目录结构长这样templates/ ├── basic-server/ │ ├── src/ │ │ ├── main.ts.hbs │ │ ├── config/ │ │ │ └── index.ts.hbs │ │ └── modules/ │ │ └── [moduleName]/ │ │ ├── controller.ts.hbs │ │ ├── service.ts.hbs │ │ └── model.ts.hbs │ └── package.json.hbs └── partials/ ├── pagination.ts.hbs ├── response-wrapper.ts.hbs └── logger.ts.hbs模板文件统一使用.hbs后缀这样编辑器能正确识别语法高亮。Handlebars 的基本语法是{{变量名}}t3code 会把变量字典里的所有键值对注入到渲染上下文中。比如变量字典里有moduleName这个键值为user模板里引用{{moduleName}}的位置就会被替换成user。但实际业务中经常需要更复杂的处理。比如模块名需要首字母大写作为类名的前缀直接放两个变量的话变量字典又要膨胀。我的解决方案是在 t3code 初始化时注册一组自定义 HelperHandlebars.registerHelper(pascalCase, (str: string) { return str .split(/[-_]/) .map(s s.charAt(0).toUpperCase() s.slice(1)) .join(); }); Handlebars.registerHelper(camelCase, (str: string) { const pascal str .split(/[-_]/) .map(s s.charAt(0).toUpperCase() s.slice(1)) .join(); return pascal.charAt(0).toLowerCase() pascal.slice(1); });注册之后模板里就可以这样写export class {{pascalCase moduleName}}Controller {而不需要在变量字典里单独维护一个moduleNamePascal变量。这类 Helper 可以无限扩展比如默认值填充、日期格式化、字符串截断、枚举生成等。3.2 分片嵌入与代码块复用子模板片段通过 Handlebars 的 partial 机制来实现复用。在 t3code 启动时我会递归读取partials目录下的所有.hbs文件按文件名注册为 partialfunction registerPartials(partialsDir: string) { const files fs.readdirSync(partialsDir).filter(f f.endsWith(.hbs)); for (const file of files) { const name path.basename(file, .hbs); const content fs.readFileSync(path.join(partialsDir, file), utf-8); Handlebars.registerPartial(name, content); } }基础模板里通过{{ pagination}}这样的语法引入分片。每次生成时partial 片段会按当前上下文中的变量重新渲染这意味着同一个 partial 在不同场景下可以复用并且可以使用不同的变量值。实际项目里response-wrapper这个分片被几乎所有接口类模板引用只维护一份大幅减少了重复代码的维护量。3.3 变量字典的数据结构与校验变量字典本质上是一个 JSON 文件结构如下{ projectName: order-service, moduleName: order, author: zhang san, javaVersion: 17, enableLog: true, controllers: [create, update, delete, query] }在模板渲染之前t3code 会执行一次校验流程。校验规则定义在主配置文件的validation字段中支持必填校验、类型校验和正则匹配校验{ validation: { moduleName: { required: true, pattern: ^[a-z][a-z0-9_-]*$ }, projectName: { required: true, pattern: ^[a-z][a-z0-9-]*$ }, javaVersion: { enum: [8, 11, 17, 21] } } }校验失败的变量会在终端里明确提示错误原因方便使用者快速修正。这里有一个很实际的教训早期版本没有做校验结果有人把模块名填成了UserService这种带大写字母的形式生成的目录结构和代码风格立刻变得乱七八糟排查了半天才发现是输入不规范造成的。现在校验逻辑前置到变量注入之前类似问题基本绝迹。4. 实操过程与核心环节实现从零搭起一个可用版本4.1 初始化项目与依赖安装t3code 本身是一个 npm 包工程结构我用 TypeScript 编写编译输出到dist目录。初始化的时候核心依赖只有三个npm init -y npm install commander inquirer handlebars npm install -D typescript types/node types/inquirerTypeScript 配置里我开启了strict模式模板变量相关的类型定义也一并声明interface TemplateVariable { key: string; value: unknown; } interface GenerateOptions { template: string; output: string; variables: Recordstring, unknown; force?: boolean; }为什么一定要用 TypeScript这个工具虽然不大但涉及到文件路径操作、配置读取、模板渲染多个环节如果用 JavaScript 写对象结构很容易在不知不觉中走样尤其变量字典这种层层嵌套的数据运行时才能发现的类型错误会消耗大量排查时间。TypeScript 能在编译期拦截掉很大一部分问题真正跑起来的时候反而省心。4.2 命令行入口设计t3code 的命令行设计参考了主流 CLI 工具的习惯提供两个核心子命令init用于初始化一个新项目的生成配置generate别名g用于实际执行代码生成。program .name(t3code) .description(三段式代码生成工具) .version(1.0.0); program .command(init) .description(初始化项目模板配置) .argument(projectName, 项目名称) .option(-t, --template name, 使用的基础模板名称, basic-server) .action((projectName, options) { initProject(projectName, options); }); program .command(generate) .description(基于模板和变量生成代码) .alias(g) .option(-t, --template name, 基础模板名称) .option(-o, --output dir, 输出目录, ./dist) .option(-v, --variables json, 变量字典文件路径) .option(--force, 目标文件存在时强制覆盖) .action((options) { generateCode(options); }); program.parse(process.argv);实际使用中最常见的组合是t3code generate -t basic-server -v ./order-service.vars.json -o ./generated如果-v参数没有指定变量文件t3code 会读取当前目录下的t3.vars.json如果文件不存在则进入交互模式通过 inquirer 逐项询问配置信息async function promptVariables(schema: ValidationSchema): PromiseRecordstring, unknown { const questions Object.entries(schema).map(([key, rule]) ({ type: rule.enum ? list : input, name: key, message: 请输入 ${key}${rule.required ? * : }:, choices: rule.enum, validate: (input: string) validateValue(key, input, rule), })); return inquirer.prompt(questions); }交互模式对新成员特别友好不需要记变量字典的字段名跟着提示走就行。4.3 模板渲染与文件输出流程生成的核心逻辑封装在generateCode函数里async function generateCode(options: GenerateOptions) { const templateDir path.resolve(__dirname, ../templates, options.template); const variables await loadVariables(options.variables, templateDir); const outputDir path.resolve(process.cwd(), options.output); const files walkDirectory(templateDir); for (const file of files) { const relativePath path.relative(templateDir, file); const renderedPath renderString(relativePath, variables); const targetPath path.join(outputDir, renderedPath.replace(/\.hbs$/, )); const content renderTemplateFile(file, variables); await writeFileSafe(targetPath, content, options.force); } }这里有两个细节值得展开。第一文件名本身也参与模板渲染。比如模板目录中的[moduleName]-service.ts.hbs当moduleName为user时实际生成的文件名就是user-service.ts。这让我可以用方括号加变量名的方式动态构造目录结构和文件名非常灵活。第二渲染完成后统一做了一次格式规范处理。由于模板里经常有超过两层的缩进空行Handlebars 渲染完会留下不少多余空白行直接产出的话代码风格一团糟。t3code 在写出文件之前会做一次清理把大于两行的连续空行压缩去掉行尾的空格。虽然逻辑很简单但就是这个细节让生成产物和团队既有代码风格保持了一致省去了后续大量手动格式化时间。4.4 增量追加模式处理已有代码的修改前文提到过现有脚手架工具大多只能生成新文件而 t3code 在设计层面加入了针对已有代码的追加模式。这个需求来自一个很常见但容易被忽视的场景给新模块加路由时要在现有的路由注册文件里追加一行注册语句添加新的枚举类时要在现有枚举类中追加一个枚举值。实现上是给 generate 命令增加-m或--mode参数支持create默认和append两种模式。append模式下t3code 不会创建新文件而是在界面中明确规则t3code g -t append-route -v ./user.vars.json -m append -o ./src/routes/index.ts对应的模板内容不再是完整的代码文件而是一个片段{{ route-register controllerPath../modules/{{moduleName}}/controller }}t3code 读取目标文件内容在文件的指定 marker 行之后插入渲染后的片段。团队约定在所有需要动态追加代码的源文件里预留 marker 注释// t3code:route-register这个约定的好处是追加入口稳定、可预测、而且不用解析源码语法。一开始有人提出能不能用 AST 解析实现精准插入但基于 marker 的方案更实用它不需要理解每种语言的语法规则也不依赖额外的解析库只要团队内部保持 marker 规范即可。5. 常见问题与排查技巧实录5.1 模板渲染后大量空白行现象生成的代码文件换行异常密集每个模板块附近都出现连续的空行打包检查时被 lint 规则警告。原因分析Handlebars 的设计会把模板文件里的换行字符原样保留尤其是 partial 引入的位置。比如{{ pagination}}这一行之后原本就跟着一个换行partial 自身末尾也有一个换行两层叠加就出现了空行。这不是 bug是模板引擎的正常行为但确实会污染生成代码。解决办法注册一个striphelper 显式去除空白或者在输出阶段统一处理。t3code 采用的是输出阶段统一处理的方式理由是我希望模板文件本身保持可读性模板作者不用为了控制空白而把所有内容挤在一行里。处理函数的核心逻辑function normalizeWhitespace(content: string): string { let result content.replace(/[ \t]$/gm, ).replace(/\n{3,}/g, \n\n); result result.replace(/^\n/, ).replace(/\n$/, ); return result; }对于生成的代码文件一般在文件头部和尾部保留单行空行即可内部压缩到最多一个连续空行比较符合常规代码风格。5.2 路径穿越风险与模板安全问题这是一个我必须认真提醒的问题。模板文件的文件名是动态拼装出来的如果变量内容里包含了../这样的路径片段就会导致生成文件写到输出目录之外。假设某个使用者不怀好意地传入moduleName: ../../../tmp/evil生成器就可能在他的系统里随意写文件。t3code 的安全处理措施是在写到磁盘之前统一校验目标路径function resolveSafePath(baseDir: string, relativePath: string): string { const resolved path.resolve(baseDir, relativePath); const baseResolved path.resolve(baseDir); if (!resolved.startsWith(baseResolved path.sep) resolved ! baseResolved) { throw new Error(拒绝写入不安全的路径: ${resolved}); } return resolved; }配合上一节讲的变量校验逻辑双保险之下基本杜绝了这个问题。另外还有一个小提醒你的模板本身也不应该引入任何来源不可信的子模板内容这方面团队内部要有一个基本的安全意识不能因为在内部使用就放松警惕。5.3 变量类型被 JSON 转成字符串的问题现象变量字典里写了enableLog: true但模板里{{#if enableLog}}判断总是走不到 true 的分支。原因分析变量字典文件如果内容是用JSON.stringify()之后保存在变量里的布尔值确实会保留但有一种常见的踩坑方式是把变量字典从环境变量里读出来或者经过中间 BFF 层传递时被统一转成了字符串。此时true是一个非空字符串在 Handlebars 里按 truthy 处理应该不会有问题但如果传进来的是false这个字符串它也会被当成 truthy这就错了。解决办法t3code 加载变量文件后增加一个内置的类型纠正阶段专门针对配置里声明为布尔值的字段做字符串向布尔型的转换function coerceTypes(variables: Recordstring, unknown, schema: ValidationSchema) { for (const [key, rule] of Object.entries(schema)) { if (rule.type boolean typeof variables[key] string) { variables[key] variables[key] true; } if (rule.type number typeof variables[key] string) { variables[key] Number(variables[key]); } } }这个问题的教训是数据类型的边界往往不在模板渲染这一层而在变量输入这一层。只要保证变量字典是从严格类型定义的源头加载后面再渲染就干净了。5.4 模板更新后已生成代码的同步问题现象团队维护人员改了一个公共 partial发现所有引用它的项目里之前生成的代码还是旧样式。原因分析这是生成型工具天然的局限——它只在生成时输出一次后续模板变化不会自动回流到已经生成的项目中。解决办法让 t3code 生成时自动产生一份生成日志记录每个目标文件对应的模板来源和模板版本号。我用的方式是在输出目录最顶层生成一个隐藏文件.t3code-manifest.json{ generatorVersion: 1.0.0, generatedAt: 2025-01-18T10:30:00.000Z, files: [ { path: src/modules/order/controller.ts, template: basic-server, templateHash: a3f9... }, { path: src/modules/order/service.ts, template: basic-server, templateHash: b1e4... } ] }后续模板发布新版本时可以写一个小脚本对比templateHash把受影响的文件列表列出来提醒维护者重新生成。这个机制虽然没有实现自动化同步但大幅降低了“模板改了却不记得哪些项目该重新生成”的协作成本。5.5 交互模式在 CI 环境下的处理现象在 Jenkins 或 GitHub Actions 等 CI 环境中直接调用t3code generate且没有提供变量文件时inquirer 的交互提示不会出现进程直接挂起。原因分析CI 环境下没有 TTY 终端inquirer 无法正常渲染交互界面进程会一直等待用户输入。解决办法t3code 检测到环境变量CItrue且没有提供变量文件时抛出明确错误并提示必须传参function detectNonInteractive() { if (process.env.CI !process.env.T3CODE_ALLOW_INTERACTIVE) { throw new Error(CI 环境禁止交互模式请通过 -v 参数传入变量字典文件); } }并且文档中约定所有 CI 流水线调用 t3code 时必须显式传入变量文件禁止依赖交互模式。这个问题的本质是一个工具的使用场景边界要提前想清楚做命令行工具时交互体验固然重要但头等要务是保证非交互环境下能稳定、可预期地执行完成。5.6 文件覆盖风险不敢乱删旧文件如果输出目录里已经存在同名的文件--force参数可以强制覆盖但团队内部有一条铁律不给--force留默认开启的口子。代码生成工具最容易引发的生产事故就是顺手执行时覆盖掉了手改过的文件导致先前的定制逻辑全部丢失。我在设计上做了一个折中默认情况下如果目标文件已存在且内容与模板渲染结果不同t3code 不会自动覆盖而是把新内容写到同名文件的旁边生成一个带时间戳的后缀文件并在终端给出比较提示。只有当使用者人工确认后才用--force真正替换。这条原则虽然让脚本的自动化程度打了点折扣但安全收益在远程协作的场景里完全值得。6. 个人经验沉淀与给同行的几点建议6.1 先把“不做什么”画出来开发 t3code 的过程中我体会最深的一点是工具的价值不取决于它能做多少事而取决于它能稳定、可预期地做好核心场景的几件事。早期我一度想着把代码生成器做成超级平台支持任意语言、任意框架、任意模板结果陷入无休止的抽象层设计中实际产出反而变慢。后来我果断划出一条边界t3code 专注做“基于模板文本的代码生成与增量追加”不涉及自动重构、不解析目标代码 AST、不做运行时脚手架。想清楚“不做什么”并明确同步给团队许多关于工具能力边界的模糊讨论立刻消失了。6.2 模板应该和实际项目代码保持同一仓库团队实践中我们把模板仓库和示例项目放在同一个 Git 仓库里模板更新和示例项目代码更新共享同一套 code review 流程。这样做的直接收益是模板的改动可以立刻通过生成的示例项目来验证不用另起炉灶维护一套“模板测试工程”。代码评审时也能直观看到模板变更对最终生成代码的影响问题暴露得非常早。6.3 一个被验证的扩展方向本地缓存加速最后分享一个小优化。因为模板目录需要在每次生成时扫描和注册 partial当模板数量增长到几十个以后t3code 的启动时间从最初的几百毫秒涨到了两三秒命令行工具一旦要等这么久体验就会明显变差。我后来加了一层基于.t3cache文件的简单缓存根据模板目录的 mtime 总和判断是否重新扫描function shouldRebuildCache(templateDir: string, cacheFile: string): boolean { const latestMtime getLatestMtime(templateDir); const cache JSON.parse(fs.readFileSync(cacheFile, utf-8)); return cache.snapshotMtime ! latestMtime; }缓存有效时启动耗时回落到了五百毫秒以内。这个方案虽然朴素但没有引入额外的复杂依赖缓存失效规则也足够直观。后续如果遇到更复杂的计算需求我会考虑引入内容寻址哈希做细粒度的缓存标记但在当前这个规模下mtime 判断已经够用了。6.4 代码生成器不是银弹还有一点想对同行说的代码生成器能帮你消灭“机械重复”但它不能消灭“设计决策”。t3code 生成出来的代码再怎么标准化业务逻辑的抽象、模块边界的划分、异常处理的取舍依然需要人到现场去做判断。我见过有人期望靠生成器解决一切架构问题结果模板越写越庞大反而成了另一个需要持续维护的“代码怪兽”。作为这套模板体系的维护者我心里有一条自我提醒每次改动公共模板都要问自己一句——“这个改动能造福所有项目的生成产物还是只是在修补某一次生成的局部问题”如果是后者更合适的做法是直接在生成后的代码里改而不是污染模板。6.5 后续还能往哪走目前 t3code 已经稳定服务了团队内的多个项目沉淀下来的模板有二十多个覆盖了常见的业务模块生成、路由追加、枚举更新等场景。后续如果继续迭代我预期会有两个方向一是把变量字典的校验规则和配置从 JSON 升级为 TypeScript 文件借助完整的类型定义享受更好的 IDE 自动补全二是结合团队内部已有的接口文档平台尝试让生成参数直接来自接口定义文件的解析结果省掉手工维护变量字典这一环。这两个方向都不算新潮技术但对这个工具的实际体验会是肉眼可见的提升。
阅读完成 · 觉得有帮助？
