在做开发这几年里我反复被同一个问题烦到每次接到一个新功能总要花不少时间在“搭架子”上。新建文件、写循环样板、补测试用例、对齐代码风格这些事单独看都不难但一天内反复做上十几遍人很容易烦躁。所以我动手做了 T3Code——一个很小的命令行工具。它的定位不是框架也不是全家桶脚手架而是把我日常开发里最重复的三个环节生成代码骨架、跑通最小测试、检查基础质量压缩成一条命令。T3Code 的核心方法是把“写出符合规范的代码”这件有点虚的事拆成 Template、Test、Tune 三个阶段再用 Node.js 把它们串成可执行的流程。如果你经常写小工具、处理临时脚本或者团队里的工程规范一直靠口头提醒来维持那这套思路应该能对你有直接帮助。这周末我把整个搭建过程重新整理了一遍从“为什么需要它”到“怎么落地”再到“踩过的坑”都会摊开讲清楚。整篇文章按可复现的标准来写想自己动手做类似工具的读者可以直接照着思路落地。1. T3Code 的定位与设计思路1.1 开发效率的隐形杀手重复决策技术债大家都熟悉代码写烂了迟早要还。但真正让我难受的其实不是技术债而是“每次都要重新想一遍流程”。举个例子团队里每个新模块都约定要有入口文件、类型定义、测试文件和一段简单的 README。按理说这个约定很清楚可实际执行时每个人还是会问目录要不要加深一层入口文件叫 index.ts 还是 userService.ts测试用例先覆盖哪个边界这些决策本身很小但每次做决策都会打断我思考业务逻辑时间一长一天下来的精力损耗非常可观。心理学里把这叫“决策疲劳”意思是每一次选择都在消耗有限的自控力和注意力。代码生成工具存在的价值恰恰是把这些不重要的选择从脑子里移除。T3Code 的定位就是这个它把目录结构、文件命名、测试放置位置这类决策全部固化成模板。模块被生成之后我看到什么文件心里都有数不用再去猜直接打开入口文件写业务逻辑就行。一个工具如果能减少决策次数它的价值比“帮你多写几行代码”要大得多。1.2 三个“T”分别解决什么问题T3Code 名字里的 T3我拆解成三个阶段。这不仅是概念命名每个阶段都对应一条可以单独执行的命令Template生成。它负责把预设模板渲染成实际代码文件包括入口文件、类型声明、测试文件和一个最短可用的 README。Test验证。针对刚生成的模块自动补一个最小测试用例并执行。此时不会验证业务逻辑是否正确只验证“文件能编译、函数存在、基本行为符合预期”。Tune优化。根据简单的扫描规则找出显而易见的代码问题比如未使用的变量、多余的日志输出、残留的 TODO、过长的函数。三个阶段刻意设计成可拆开的。默认情况下 t3 new 只执行生成如果加上 --with-test 或者 --with-tune工具就会自动把后续阶段串起来。为什么这么设计因为生成是高频动作要求快测试和优化要看具体场景。如果每次生成都强制跑全套命令会变得又慢又重用户反而不愿意用。工具做出来是给自己和团队用的顺手比完整重要。1.3 技术选型Node.js 不是唯一解但最均衡最开始我也想过用 Shell 脚本或者 Python 快速糊一个。Shell 处理“建目录、拷贝文件”确实很直接但有几个问题绕不过去模板一复杂条件判断和循环的写法就很难看日常开发里不是每个人都装了 Python跨平台行为更是不可控。Mac 上跑得好好的脚本换到 Windows 的 cmd 或 PowerShell 上经常因为引号、编码、路径分隔符出各种怪事。所以最终选了 Node.js TypeScript配套用 commander 做命令解析、ejs 做模板渲染、execa 做子进程调用。TypeScript 在这里不是噱头。CLI 工具的输入输出特别依赖“数据类型明确”参数是字符串还是数组、返回结果是成功还是失败、错误信息可选字段是什么这些用类型定义好之后后续排查问题的时间能省一大半。结构定了接下来就落到具体命令实现上。2. 三条核心子命令的实现原理2.1 t3 new模板引擎如何保证生成结果可控t3 new 是整套命令集里最常用的一条典型用法是这样t3 new user-service -t feature它会读取 templates/feature 目录下的全部模板文件把参数渲染成真实内容再写入当前目录下新建的 user-service 文件夹。这里的核心不是“拷贝文件”而是“用参数生成文件”。我选了 ejs 作为模板引擎理由很实际它支持% %这种逻辑块可以实现条件判断和循环又不像其他重型模板引擎那样上手成本高。一个模板文件的示例大致长这样// % moduleName %/index.ts export function % methodName %() { return % moduleName % initialized; }渲染时我会准备两类变量。一类是用户显式传入的参数比如模块名、类型另一类是派生参数比如把 user-service 转成 userServicecamelCase、UserServicepascalCase和 USER_SERVICEupperSnakeCase。这个转换逻辑我专门放进 naming.ts而不是写在模板里。原因是同一套命名规则会在生成入口文件、测试文件、导出名时反复用到写在模板里既重复又难测。容易被忽略的是文件名本身也可能需要“模板化”。比如某个模块叫 user-service生成出来的控制器文件要叫 user-service.controller.ts模块名换成 order-service文件名也要跟着变。所以我在写入文件之前会先用同一组数据把文件名也渲染一遍再组装完整路径。这一步不做工具就只适用于固定文件名灵活性会大打折扣。2.2 t3 test让生成代码一出生就有安全网t3 test 的重点不是“替你写测试”而是“在代码刚生成时就证明它至少能编译、能执行”。生成代码最常见的问题不是业务逻辑错而是最基础的问题拼写导致导入路径不对、模板变量漏替换导致 undefined、某条导出语句写成了语法错误。这些问题如果等写完业务再发现排查成本会成倍增加。针对一个 TypeScript 模块默认测试模板大概是这样的import { describe, it, expect } from vitest; import { createUserService } from ./index; describe(user-service, () { it(createUserService 应该返回一个对象, () { const service createUserService(); expect(typeof service).toBe(object); expect(service).toHaveProperty(create); }); });这个测试没有深度但覆盖面刚好适合模板能抓住“导出的函数不存在”“语法错误”“返回类型完全不对”这三类问题。生成时用户可以用 --exports create,list,remove 指定要导出的方法或者依赖模块模板里的默认导出清单测试文件会自动跟随这些信息生成。执行测试我用 execaimport { execa } from execa; export async function runTests(cwd: string) { try { const { stdout, stderr } await execa(node, [node_modules/vitest/vitest.mjs, run], { cwd }); return { success: true, output: stdout stderr }; } catch (error) { return { success: false, output: error.stderr || error.stdout || error.message }; } }这里直接调用 node 执行 vitest 的入口文件而不是用 npx vitest run原因后面会在踩坑章节细说。简单讲就是跨平台兼容性更好也少一次 npx 的解析开销。2.3 t3 tune不做 AST 也能发现大部分问题t3 tune 没有做成完整的静态分析引擎那是 ESLint 的领域重复造轮子没有意义。我的目标很朴素发现几类高频出现、一眼就能看出来的问题。目前内置了四条扫描规则未使用变量用启发式规则检测函数体内只出现一次、且没有调用迹象的标识符。多余的 console.log统计非注释行里 console. 的出现次数超过阈值就提示。TODO/FIXME 标记直接按行搜索注释文本汇总文件和行号。函数过长简单数大括号包裹的最大跨度超过 80 行给警告。这类检查一定有误报所以 t3 tune 默认只输出建议不做任何自动修改。输出格式我尽量贴近 ESLint 的“文件路径:行号 提示信息”这样在编辑器的终端面板里可以直接点击跳转。实际用下来发现最高频被触发的是 TODO 扫描。它的价值在于把手头没完成的东西一次性集中暴露出来比翻遍每个文件找注释靠谱得多。3. 完整搭建过程从 npm init 到可用命令3.1 初始化项目与依赖选择创建一个 Node.js CLI 项目其实没有特别的仪式核心是先想清楚“运行时入口”和“bin 命令映射”。我的初始化命令是mkdir t3code cd t3code npm init -y npm install commander ejs execa npm install -D typescript tsx vitest types/node依赖的角色很清晰commander 负责解析命令行参数和子命令ejs 负责模板渲染execa 负责在子进程里执行测试tsx 让我在开发阶段直接运行 TypeScript 源码不用每次编译vitest 是测试模板里默认引用的测试框架也是执行测试的底层依赖。package.json 里有几个字段决定了这个工具的“CLI 属性”{ name: t3code, version: 0.1.0, bin: { t3: ./dist/cli.js }, scripts: { build: tsc, dev: tsx src/cli.ts } }bin 字段是关键。它把全局命令 t3 映射到构建产物 dist/cli.js。开发阶段我可以先用 npm run dev 跑原型发布时再执行 npm run build 生成真正的执行文件。第一次写好之后记得运行 npm link这样命令行里能直接调用 t3不然每次都得 node dist/cli.js 全路径调试效率会很差。3.2 命令解析层让参数输入符合直觉CLI 工具的参数设计直接决定用户愿不愿意用。T3Code 的命令解析用 commander 搭了这么一层import { Command } from commander; const program new Command(); program .name(t3) .description(T3Code生成、测试、优化一体化的小工具) .version(0.1.0); program .command(new) .description(生成新的模块骨架) .argument(name, 模块名称) .option(-t, --type type, 模块类型feature/script/lib, feature) .option(--exports list, 导出的函数列表逗号分隔) .option(--with-test, 生成后自动执行测试) .option(--with-tune, 生成后自动执行优化检查) .action(runNew); program.parse(process.argv);注意 argument 和 option 的区别模块名是这条命令的动态主体应该用 argument 定义type、exports、--with-test 这些是修饰主体行为的选项应该用 option 定义。这个区分不仅影响帮助手册的展示也让用户形成稳定的直觉先给一个名字再决定怎么生成。commander 还帮我处理了“-t 和 --type 的简写”“参数缺失时的报错”这些琐碎工作。自己手写 process.argv 解析不是不行但要处理缩写、默认值、帮助说明写起来都是时间而且容易有歧义。3.3 模板渲染与目录写入的实现细节模板渲染这段代码本身不长但我按功能拆成了两个函数。第一个是单文件内容渲染import ejs from ejs; import { readFile } from node:fs/promises; export async function renderTemplate(templatePath: string, data: Recordstring, unknown) { const source await readFile(templatePath, utf-8); return ejs.render(source, data, { rmWhitespace: true }); }rmWhitespace 选项值得留意。它会把模板里逻辑标签周围多余的空行和缩进清理掉否则生成出来的源码会带很多奇怪的空白行视觉上非常不专业。第二个函数负责把整个模板目录复制到目标路径。处理方式是递归遍历 templates 目录遇到 .template.ts、.template.ejs 这类文件先渲染内容再改名遇到纯静态文件比如 .gitignore直接拷贝。遍历时用绝对路径定位模板目录避免“程序在哪个目录运行就找不到模板”这种常见错误。模板目录的定位建议用 import.meta.url 计算而不是依赖 process.cwd()。3.4 测试调度与结果归集第 2.2 节已经展示了 runTests 的核心代码这里补充一个容易被小看的设计归集结果。我要求 t3 test 无论测试通过还是失败都必须返回结构化的结果对象而不是只在终端里打印一串输出。这样上层命令才能根据 success 字段决定后续动作。比如 t3 new --with-test 时如果测试失败工具会在当前目录保留生成的代码但同时给出明确警告和测试摘要而不是把整个过程静默吞掉。结果归集要同时处理两种情况命令执行成功但测试本身失败命令执行失败比如 node 路径不对。execa 对这两类情况的行为不一样前者会抛错后者也会抛错但错误上的 stdout 和 stderr 字段内容差异很大。所以我用 try/catch 把两者都收回来统一成 output 字符串避免上层判断逻辑被底层细节干扰。4. 踩坑记录与问题排查实录4.1 EJS 默认转义生成源码时最容易中的招T3Code 踩过的最大一个坑和模板引擎的安全机制有关。EJS 默认的% %标签会对输出内容做 HTML 转义这在生成网页时是好事但在生成代码时就是灾难。比如模板里有这么一行const greeting % greeting %;如果变量 greeting 的值是 Hello, worldEJS 会把它渲染成Hello, quot;worldquot;生成的源码直接语法错误。问题更隐蔽的地方在于不是每次都会触发只有当用户输入恰好包含引号或尖括号时才出错。平时一切正常关键时刻狠狠来一下非常难排查。解决方案是把所有输出标签从%改成%-也就是 EJS 里“不做转义”的原始输出标签。如果个别场景确实需要转义再单独调用 escape 函数。这个坑提醒我模板引擎的安全默认值是为 HTML 设计的做代码生成工具时必须意识到这个假设和场景并不匹配。4.2 执行测试进程时的 stdio 与入口选择第一次实现 t3 test 时我用 stdio: inherit 执行测试好处是输出会实时显示在终端里看起来没毛病。但真正集成进 t3 new --with-test 之后才发现问题输出直接流向终端程序就拿不到完整内容无法判断测试到底过了几个、failed 在哪一行。所以最终回归到默认的 pipe 模式让 stdout 和 stderr 都回到程序内部。另一个和 npx 有关的问题是 Windows 平台。npx 在 Windows 下是一个 .cmd 脚本某些 Node 版本下手写 execa 直接调它容易在命令解析层面出错。我的解决办法是绕过 npx直接定位 node_modules 里的 vitest 入口文件用 node 执行。node 本身是真正的可执行文件这样就从根源上避开了跨平台命令解析的坑。4.3 路径分隔符差异模板文件在 Windows 上“消失”了跨平台问题还有一个非常隐蔽的细节路径分隔符。最开始遍历模板目录时我习惯性用 path.join 拼接 glob 模式在 macOS 上一切正常一到 Windows 环境发现模板文件经常匹配不到生成出来的目录是空的。排查之后发现glob 模式内部对路径分隔符有严格的约定Windows 的反斜杠会被当成转义字符处理。修复方案是glob 模式统一用正斜杠拿到文件路径之后再用 path.resolve 把相对路径转成当前平台绝对路径。做跨平台工具一旦涉及文件路径就要默认“输入输出分离”用户输入接口上统一使用正斜杠底层操作文件系统时再用平台原生的路径不要在中间状态里混用两种形式。4.4 体验优化彩色输出、错误分类与加载反馈CLI 工具很容易进入“能用但难用”的状态功能没问题但用起来不舒服。T3Code 在体验上做了三个小改动实际提升比想象中明显阶段标签用不同颜色标记。生成阶段用蓝字测试通过用绿字发现问题用黄色提醒硬错误用红字。扫一眼就知道当前走到哪一步。错误信息分级。用户写错参数、模板缺失这类问题给出简短提示和修复建议程序内部异常才打印完整堆栈。这样日志不会动不动糊满一屏。长任务加加载反馈。测试首次跑的时候要等依赖初始化快则几秒慢则十几秒不加提示用户很容易认为工具卡死了。加上一个简单的旋转 loading 后体验立刻正常了。这些改动没有一个涉及核心逻辑但直接影响工具的留存率。自己做工具尤其容易忽视这一层总想着功能优先结果做出来连自己都嫌糙。4.5 常见问题速查现象可能原因处理方式生成文件里出现 等字符EJS 默认转义将%换成%-t3 命令找不到模板目录用 process.cwd() 定位模板改用 import.meta.url 计算绝对路径Windows 下跑测试报 ENOENTnpx 是 .cmd 脚本绕过 npx直接执行 node vitest 入口测试输出不回传程序stdio 设置为 inherit恢复默认 pipe 模式并读取输出生成的源码空行特别多模板渲染未清理空白开启 ejs 的 rmWhitespace 选项这张表是我整理给团队用的你来复刻时大概率也会碰到其中一两条。提前留个心眼省一次深夜排查。用了一段时间之后我对 T3Code 的感受发生了很明显的变化它省下的不只是那几分钟而是让我面对新需求时的第一反应从“又要从零开始了”变成“先建骨架再填逻辑”。流程一旦稳定真正需要动脑的就只剩业务本身。T3Code 并不是一个多么了不起的开源项目它更像是我给自己的开发习惯打的一个补丁。但我特别建议你也试试这个思路与其等一个完美的脚手架工具出现不如花半天时间给自己写一个。最初版本可以很糙重要的是它按照你的习惯生长这种“顺手”的感觉是任何通用工具都给不了的。