t3code：用模板与校验解决TypeScript复制粘贴型开发

如果你写过一段时间的 TypeScript，大概率经历过这种场景：新需求只是往模块里加一条字段，但你要打开四个文件，把类型定义、接口响应、服务方法和页面展示各改一遍，再顺手复制一份老模块改名成新模块。前期很爽，后期代码库里到处都是彼此的影子，改一个公共类型要在一堆文件里追着跑。这就是我折腾 t3code 的起点。t3code 不是什么大团队压下来的宏大框架，它是一套围绕“模板 + 校验”思路做的代码生成与规范校验工具链，核心思想很朴素：把结构性高度相似的模块交给模板生成，再用自动校验把命名约定和类型问题兜住。

整套工具链拆开看其实就三件事：第一，根据目录结构自动生成符合团队规范的模块骨架；第二，在提交前完成命名、类型、接口一致性的自动校验；第三，输出每一轮生成的变更报告，让代码创建过程可回溯。它适合前端或全栈团队的技术负责人、饱受复制粘贴折磨的核心开发者，也适合所有想把工程规范从口头约定变成自动化约束的人。接下来我把这套系统的设计思路、核心细节、完整实现和踩坑记录一次性摊开讲，你可以直接照着搭一版。

1. 内容整体设计与思路拆解

1.1 为什么叫 t3code：T3 不是版本号

t3code 里的 T3 不是版本号，也不是某个流行技术套餐的缩写。我在最初设计时把它定义成三个词的组合：TypeScript First、Template + Transform、Testable & Traceable。

第一个词决定工具链的基调：团队主力语言是 TypeScript，生成的文件必须是.ts，不能退化成面向字符串拼凑的脚本。第二个词决定生成方式：不做黑盒代码生成器，而是“模板文件 + 轻量转换器”，让经验丰富的开发者能把代码控制力握在自己手里。第三个词决定交付质量：每一次生成都要可测试、可追踪，不能生成完就拍拍手结束。所以 t3code 对外表现出来就是一个命令行工具加一套约定的目录规则，核心代码量不大，但设计维度被刻意拉高，确保它能在真实项目里持续立得住。

这套工具链针对的并不是“所有代码生成”这个宏大命题，而是划定了一个很小的边界：结构性很强、逻辑相对稀少的模块代码，由模板生成；真正复杂的业务逻辑，仍然交给开发者手写。比如一个典型的用户模块包含 types、service、controller、schema，四个文件之间的引用关系和命名规则高度相似，手写很枯燥，出错的概率也集中在复制改名这一步。用 t3code 处理这类素材，创建时间可以从十分钟压缩到几秒钟，同时保证每个文件的头部注释、导出风格、命名方式甚至在编辑器里的结构都保持一致。

这里有一个很容易犯的错误：试图把生成器做成“万能脚手架”，用户输入几个关键词，整个业务代码都自动生成。我见过不少内部工具死在这个方向上，因为业务逻辑一旦复杂，模板会失控，生成结果反而不如手写清爽。t3code 的取舍很明确——初始阶段只做模块骨架和约定校验，先把重复劳动里最枯燥的 20% 吃掉，确保这 20% 是稳定、可信任的。后续如果团队真的在某个领域积累了稳定模式，再逐步往模板里增加内容，这样工具和项目是同步生长的，而不是工具一出生就脱离了现实。我在实际使用中发现，把生成器控制在小范围内，它反而能被团队坚持用下去。

1.2 先解决复制粘贴型开发的问题

复制粘贴在中小团队里几乎是常态，新模块往往不是从零开始，而是“照着一个顺眼的旧模块改”。这样做的好处是快，坏处是旧模块里的历史包袱会被一起搬过来。我见过一个服务文件里带着三个已经废弃的业务分支判断，就是因为当初复制模板时没删干净，后面的人又不敢动它，只能像地质层一样一层层堆着。t3code 想做的第一件事，就是让“创建新模块”不再依赖某个人对旧代码的记忆，而是由一份集中维护的模板和一套显式规则来兜底。

我做过一次简单的对比，同一批 20 个模块，手工复制改名平均每个需要 8 到 12 分钟，其中包括反复确认文件名是否一致、接口是否导出、引用路径是否对得上；而用 t3code 生成每个模块骨架，平均耗时在 5 秒以内，剩下的时间只有少量文件需要人工填业务逻辑。更重要的是，生成的文件在命名、引用、类型签名上是“可预期”的，代码评审看到 diff 时不需要花时间去辨认哪些是误改、哪些是拷贝残留。下面这个表格能说明问题：

这个对比不是说生成器比手写更聪明，而是说它把人类容易疲劳、容易出错的环节替换成了确定性流程。每次生成都会把输入参数、模板版本、输出文件列表写进一份变更记录，哪怕三十天后有人问起某批模块是怎么来的，依然能还原当时的场景。这种可追溯性在团队人员流动、需求追责复盘时非常有用，也让“代码是怎么来的”这个问题不再依赖人的记忆。

1.3 三段式流水线：解析、生成、校验

很多自建工具会在一个脚本里连写带校验，出问题时只能整个脚本硬着头皮调。t3code 从一开始就拆成三个独立阶段：parse（解析）、generate（生成）、verify（校验）。解析阶段只负责读取目录结构和配置文件，把它转换成一个内部数据模型，比如模块名、路径、需要生成的模板列表；生成阶段只负责把模板和数据模型渲染成文本，按规划好的路径写入；校验阶段只对生成结果做静态检查，比如文件名是否符合命名规范、导出接口是否齐全、有没有 ESLint 和 Prettier 的遗留问题。

这个拆法最大的收益是定位问题快。生成结果乱套，先看是 parse 的数据模型有误，还是模板渲染出错，还是校验规则写得太严格，三个阶段互相隔离，不会出现“一个模板里的变量拼错，结果报错信息却指向配置文件”的情况。同时每个阶段都能单独写测试，我可以把一小段固定目录当作 fixture，验证 parse 结果是否稳定；也可以把渲染函数抽出来直接做单元测试，传一个假数据进去看输出的代码对不对。这些让 t3code 在团队里能像正常工程一样持续演进，而不是变成某个开发者手里的“黑魔法”。

2. 核心细节解析与实操要点

2.1 语义化目录识别：让目录结构自己说话

t3code 默认接受一个约定：模块结构通过目录和文件名来表达，而不是通过额外的对话框让用户描述“我要一个什么模块”。例如一个用户模块的路径通常是这样的：

src/modules/user ├── user.schema.ts ├── user.service.ts ├── user.controller.ts └── user.types.ts

工具读入这个目录后，会从“user”这个目录名派生出多种命名形式，再根据文件后缀判断每个文件的角色，schema、service、controller、types 分别对应模板里不同的职责。这样一来，生成新模块只需要提供两个信息：目标目录名和模板类型，其余全部通过规则推导。我给这个步骤起了个名字叫“目录即配置”，这和传统意义上把所有参数堆在命令行里是相反思路，因为目录结构本身已经在传达语义，再让用户重复输入一遍反而容易出错。

目录名的解析逻辑其实非常简单，核心就是一个把连字符和点号统一转换的函数：

function toVariants(input: string) { const segments = input.split(/[-_.\s]+/).filter(Boolean); const pascal = segments.map((s) => s[0].toUpperCase() + s.slice(1)).join(""); const camel = pascal[0].toLowerCase() + pascal.slice(1); const kebab = segments.map((s) => s.toLowerCase()).join("-"); const constant = segments.map((s) => s.toUpperCase()).join("_"); return { pascal, camel, kebab, constant }; }

例如输入order-history，得到的结果如下表：

这些变体会被注入到渲染上下文中，模板里用到变量名、文件名、导入路径时都直接引用它们，避免了手工拼接大小写导致的不一致。这里有一条实操经验：不要试图在目录名里支持太多特殊字符，比如空格、中文、连续多个点，这些都会让命名派生变得难以预测，最终工具会因为“边角情况”被使用者悄悄抛弃。我目前只支持字母、数字、连字符和下划线，遇到其他字符直接报错并提示合法命名格式，宁可严格一点，也不要隐式魔法。

2.2 模板引擎选型与模板边界

t3code 的模板采用了一个非常轻量的渲染层，内部基于 Eta 风格的模板语法，而不是引入 React 或 Vue 这类重量级渲染框架。原因很实际：模板的核心目的是输出静态的代码骨架，真正的控制流和逻辑应该留在生成脚本里，而不是跑进模板里。一个模板里如果出现复杂的循环判断，基本说明这个模块的抽象还没有到位，应该回到数据模型层面去找共通点，而不是试图用模板语法把所有个案都揉进去。

一个典型的 controller 模板大概是这样的：

// GET /api/<%= it.camel %>/list import { <%= it.pascal %>Service } from "./<%= it.kebab %>.service"; import { type <%= it.pascal %>Input } from "./<%= it.kebab %>.types"; export function list<%= it.pascal %>(input: <%= it.pascal %>Input): <%= it.pascal %>[] { return <%= it.camel %>Service.list(input); }

注意这里模板里没有任何 for 循环和 if 判断，所有变量都来自 parse 阶段的数据模型。模板文件统一放在.t3code/templates/目录下，扩展名用.eta而不是.ts，这样 IDE、Prettier、ESLint 都不会误以为是待编译的源码。这个细节很重要，我一开始把模板直接命名为controller.ts.eta，虽然避免了误处理，但编辑器里高亮并不理想。后来统一放到 templates 目录并用.eta后缀，才能真正让模板和产物从视觉到工具链都隔离干净。

关于模板数量，我一开始贪多，一口气写了十几个模板，包括列表页、详情页、表单页、弹窗页，结果维护成本很高，而且很多模板之间差异只是几个字段名。后来我把模板砍到只剩三类：route 类、service 类、schema 类型类，每一个都经过至少三次真实项目复用检验才允许留在库里。一个新模板要被采纳，必须回答一个问题：它真的比手写快很多吗？如果答案不是毫不犹豫的“是”，就不该进入模板库。这个标准帮我挡住了大量“看起来有用但实际很鸡肋”的设计。

2.3 类型安全双保险：编译期和运行前

t3code 对类型安全的关注体现在两个层面。第一个层面是编译期，所有生成的文件都被纳入 tsconfig 的 include 范围，tsc --noEmit会检查出类型不匹配、接口漏导、引用路径错误等基础问题。第二个层面是运行前，也就是数据进入模块边界前，通过一个轻量校验器做运行时兜底。这里我选择的是 zod，因为它的类型推导与 TypeScript 配合非常顺畅，而且 schema 定义本身就是天然的运行时类型。

一个典型的 schema 文件模板生成结果类似这样：

import { z } from "zod"; export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.email(), }); export type User = z.infer<typeof userSchema>;

在 service 入口处加一行校验，就能把“编译期正确但运行时脏数据”的问题提前拦截住：

import { userSchema, type User } from "./user.schema"; export function createUser(input: unknown): User { const parsed = userSchema.parse(input); // 这里再写业务逻辑，入参一定是安全的 return { id: parsed.id, name: parsed.name, email: parsed.email }; }

这看起来很简单，但实际能堵住很多坑。接口返回值、外部调用方、历史接口字段都可能带进类型系统看不见的脏数据，编译期再强也不能保证运行时不翻车。双保险的意义在于把“信任”分成了两层：编译期信任类型推导，运行前信任 schema 校验。很多团队只做第一层，直到线上出现一个 undefined 才回头补第二层，t3code 把第二层作为生成模块的标准姿势，等于把这条经验直接固化到了流程里。

2.4 CLI 交互设计：能默认就不要弹窗

早期版本的 t3code 交互非常丰富，有交互式表格、有颜色高亮、有各种选择器，看起来高级但用起来很累。后来我把版本重写，CLI 的设计原则改成一句话：能默认就不要弹窗。使用者只需要知道两个必填参数和几个可选参数，剩下的交给工具自动判断。

一个实际命令长这样：

npx t3code generate --name order-history --template crud

可选参数包括--dir（默认src/modules）、--dry-run（只预览不写盘）、--verbose（输出更多日志）、--no-verify（跳过校验）。为什么不做成交互式问答？因为在持续集成和脚本编排里，非交互式命令才能真正被自动化；而且交互式界面很容易被新同学误操作，选错了模板反而更乱。参数越少，出错的可能越小，这比界面好看重要得多。如果团队里有人不知道该传什么，直接跑t3code list就能看到所有模板的说明和示例，这比在命令行里一层层试探高效太多。

3. 实操过程与核心环节实现

3.1 环境准备与目录规划

要把 t3code 跑起来，基础环境要求很低：Node.js 18 及以上版本，包管理器我推荐 pnpm，TypeScript 5.0 以上。整个项目目录可以独立成一个仓库，也可以嵌进 monorepo 的一个 packages 子包，关键是把.t3code配置目录和scripts脚本目录固定下来：

t3code-demo ├── .t3code/ │ ├── config.json │ └── templates/ │ ├── route.ts.eta │ ├── service.ts.eta │ └── schema.ts.eta ├── scripts/ │ └── generate.ts ├── src/ │ └── modules/ ├── package.json └── tsconfig.json

config.json管理基础路径、默认模板、校验规则开关，初始状态下非常精简：

{ "sourceDir": "src/modules", "templatesDir": ".t3code/templates", "defaultTemplate": "crud", "validateOnGenerate": true }

安装依赖只需要三个核心包：typescript、eta、zod，再加上一个轻量命令行参数解析工具如 cac 就够了。我故意不引入 commander 这种更重的库，因为 t3code 的命令就两三条，不需要把依赖树撑大。安装命令如下：

pnpm add eta zod cac pnpm add -D typescript @types/node

这段准备过程看着简单，但它决定了后续的可维护性。目录不清楚，模板和产物混在一起，很快就会发生“源文件被误删”这种事。把配置、模板、脚本、产物四个角色分清楚，工具才不会越用越乱。

3.2 核心生成脚本：从解析到落盘

生成脚本核心部分是三个动作：读取配置和目录、渲染模板、写入文件并做备份。简化后的逻辑可以这样看：

import { readdir, readFile, writeFile } from "node:fs/promises"; import { resolve, join } from "node:path"; import { render } from "eta"; import { toVariants } from "./naming.js"; async function generateModule(name: string, dir: string) { const variants = toVariants(name); const targetDir = resolve(dir, name); await makeDirectoryIfMissing(targetDir); const files = await readdir(options.templateDir); for (const templateName of files) { const template = await readFile(join(options.templateDir, templateName), "utf-8"); const output = render(template, variants); const outputFileName = `${variants.kebab}${stripTemplateSuffix(templateName)}`; await writeFile(join(targetDir, outputFileName), output, "utf-8"); console.log(`[t3code] generated ${outputFileName}`); } }

这里面最容易被忽略的是路径处理。我一开始直接用process.cwd()拼路径，结果在 monorepo 根目录跑命令时，生成目录跑到了错误的位置。后来改成resolve(process.cwd(), ...)还不够，还要在启动时记录一次rootDir，所有相对路径都以它为准，这样无论从哪个子目录调用命令，结果都不偏。另一个容易踩的坑是写文件前没有做已存在文件检查，重跑同一模块时会把旧文件覆盖掉，导致手写业务逻辑丢失。我的做法是每次写盘前生成.bak备份，如果文件已经存在，先把旧版本改名备份，再写新版本，等校验通过后由用户手动决定是否删除备份。这个机制成本极低，但确实救过我一次重要分支的代码。

除了生成之外，脚本还会在结束时自动汇总变更记录，记录大概长这样：

这个报告不只给人看，也可以作为 CI 的机器可读输出，方便后续做自动化分析和审计。

3.3 让校验成为提交前的一道闸门

生成只是第一步，规范能不能落得住，靠的是校验。t3code 把校验做成了一条独立命令t3code verify，它不是只检查生成的文件，而是检查整个模块目录，比如文件命名是否符合 kebab-case、每个模块是否包含必须的类型文件、导出接口是否与模板数据模型一致、有没有遗留的TODO或者console.log等标记。校验通过后进程以 0 退出，失败则打印具体文件与规则，非 0 退出，这样它能自然接进任何 CI 或 git hooks。

在团队仓库里，我通常通过 husky 和 lint-staged 把它接到 pre-commit 上：

{ "lint-staged": { "*.ts": [ "eslint --fix", "prettier --write", "t3code verify" ] } }

配合 husky 的 pre-commit 钩子，开发者提交前自动跑一遍。这里有个细节：t3code verify一定要用--staged参数，只校验暂存区里的文件，否则全量扫描大仓库会很慢，开发体验一下就差了。在 CI 上则可以单独跑一次全量校验，作为合并请求的强制检查项。我认为这是整套方案里最有价值的一环，因为它真正把“约定”变成了“门禁”，不是靠文档让人记住，而是靠流程让人必须执行。

3.4 参数计算与命名派生：一个小案例

站在使用者角度看，一次真实生成过程是这样的：我先输入命令npx t3code generate --name order-history --template crud，工具内部拿到order-history后，会执行三个动作。第一是路径补全，自动生成目标目录src/modules/order-history/；第二是命名派生，把order-history转换成OrderHistory、orderHistory、ORDER_HISTORY等变量注入渲染上下文；第三是模板选择，根据crud选择一组模板文件，逐个渲染并写盘。

模板里对变量的引用也很有意思，比如 service 模板里会这样写：

import { <%= it.pascal %>Repository } from "./<%= it.kebab %>.repository"; import { type <%= it.pascal %>Input, type <%= it.pascal %>Output } from "./<%= it.kebab %>.types"; export class <%= it.pascal %>Service { async getList(input: <%= it.pascal %>Input): Promise<<%= it.pascal %>Output[]> { // 生成的骨架，业务逻辑由开发者填充 throw new Error("Not implemented"); } }

生成出来之后就变成OrderHistoryService、order-history.service.ts等名称。这个推导过程虽然简单，但保证了变量、文件名、导入路径三者永远一致，手工操作时最常见的“忘记改掉一个引用”在这套流程里天然不存在。如果使用者想预览效果，可以先加--dry-run，工具只打印结果不写盘，确认没问题再正式生成。对于刚接触这条工具的同事，我一般建议都先来一次 dry-run，心里有数再动手。

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

4.1 我踩过的三个坑

第一个坑是模板里的路径问题。我最开始在模板里直接写了相对路径，生成后文件能创建，但导入关系完全是乱的，因为模板并不知道自己最终会被放在哪个目录。后来我在模板中禁用任何路径硬编码，所有路径引用都通过数据模型传入，渲染时由脚本统一计算相对位置，才算彻底解决。这对团队来说尤其重要，因为一旦有人把绝对路径写进模板，所有生成出来的模块都带着机器相关的路径，换个人跑就出错。

第二个坑是格式化工具与生成工具的冲突。我一开始把生成的.ts文件直接交给 Prettier 格式化，结果模板里的<%= it.pascal %>占位符在渲染前就变成了代码里的真实名称，格式化没问题；但如果把模板文件本身拿去 prettier 检查，就会因为奇怪的尖括号语法报错。解决的办法是把模板目录和.eta后缀加入.prettierignore和.eslintignore，不要让格式化工具处理模板本身，生成完成后再统一对产物做一次格式化。这样两边互不干扰。

第三个坑是 monorepo 下的类型检查失败。在带 TypeScript 的 monorepo 中，某几个子包可能依赖还没有编译的相邻包，直接跑tsc --noEmit会报出一堆“找不到模块”的错误。我一开始以为是模板有问题，查了半天才发现是项目本来的依赖还没有构建。解决方式也很朴素：给 t3code 的校验单独提供一份 tsconfig.extend.json，设置skipLibCheck: true，同时把references暂时关掉，只盯生成文件的类型。这个做法严格来说牺牲了部分跨包类型检查的精度，但能换来生成流程的稳定性。

4.2 问题排查速查表

下面这张表是我在实际维护中沉淀下来的，直接当备忘录用：

这张表最大的用处不是所有人都会遇到所有坑，而是当压力大的时候，有据可查能省下大量翻代码的时间。我每次有同事报问题，都会先拿这个表对一遍，至少能过滤掉 60% 的常规毛病。

4.3 日常使用中沉淀的小技巧

最后分享几个看着不起眼但很提效的小技巧。第一，生成完成后立刻在终端跑一次tsc --noEmit，把反馈闭环压缩到十几秒内，不要攒到提交时才发现类型错误。第二，把模板文件、命名规则、校验规则同步写进 README，并放到.t3code/README.md，因为模板迟早会有人来改，没有说明的模板就是一群等待被误解的字符串。第三，定期做一次“模板使用率”复盘，统计每个模板被生成多少次，半年都没人用的模板直接删掉，别舍不得——工具的价值在于让团队更省力，而不是收藏一堆看起来专业但永远没人碰的模板。

我在实际使用中还有一个体会：再好的生成工具也替代不了人对业务的理解，它能帮我们把重复劳动压缩到几乎为零，但真正决定代码质量的，仍然是填充进骨架里的那部分业务逻辑。所以我始终把 t3code 控制在一个很小的范围内，让它做少一点、做可靠一点。这套工具从第一版到现在，脚本代码加一起不到一千行，但已经帮团队省下了上百个小时的模板工时。如果你也在为复制粘贴型开发头疼，可以先照着这个思路做一个最小版本，跑通了再慢慢加模板，效果远比一开始设计一个万能脚手架要好。