1. 项目缘起与核心定位

第一次看到“t3code”这个名字，我下意识地把它拆成了两个部分：t3和code。在开发者圈子里，这种命名方式其实挺常见的——前缀往往代表某种特定的技术栈、工具链或者运行环境，后缀则直接点明了它的核心功能。结合我这些年接触过的各种开发工具和框架，我判断 t3code 大概率是一个与代码生成、代码管理或者某种特定编码规范相关的项目。后来经过一番摸索和实际使用，基本印证了这个判断：t3code 是一套面向开发者的轻量级代码组织与生成方案，它的核心目标很明确——让开发者用更少的重复劳动，写出结构更清晰、维护成本更低的代码。

为什么我会对这个项目产生兴趣？原因很简单。在日常开发中，我们经常会遇到一些“重复但又不得不写”的代码：比如 CRUD 接口、数据模型的转换层、配置文件的解析逻辑、前端组件的样板结构等等。这些东西写起来不复杂，但架不住量大，而且一旦业务逻辑有调整，散落在各处的相似代码就得一个个去改，稍不留神就漏掉一处，留下隐患。t3code 试图解决的，正是这类“结构性重复”的问题。它不是那种大而全的低代码平台，也不是要取代你现有的技术栈，而是像一个代码层面的脚手架和规范约束工具，帮你把那些有规律可循的部分自动化掉，同时把剩下的精力留给真正需要思考的业务逻辑。

那么，t3code 适合谁来用？我的判断是三类人。第一类是中小型项目的独立开发者或小团队，人手有限，既要快速出活又要保证代码质量，t3code 能帮你在前期省下大量搭建基础结构的时间。第二类是正在做技术栈统一或代码规范落地的团队负责人，t3code 提供了一套可配置的代码生成规则，你可以把它当成团队内部编码规范的“执行者”，减少代码评审时因为风格不一致产生的摩擦。第三类是刚入行不久、想学习工程化思维的开发者，通过阅读 t3code 的配置和生成逻辑，你能比较直观地理解一个项目从“能跑”到“好维护”之间需要补上哪些环节。

需要提前说明的是，t3code 并不是一个孤立的工具，它更像是一个约定优于配置的实践集合。它的设计哲学里带着明显的“务实”色彩：不追求花哨的功能，而是把几个高频场景做深做透。接下来的内容，我会从整体设计思路、核心细节、实操过程、常见问题几个维度，把我这段时间使用 t3code 的经验和踩过的坑完整地分享出来。无论你是刚听说这个项目，还是已经尝试过但遇到了一些困惑，希望都能从中找到对你有用的东西。

2. 整体设计思路与方案选型拆解

2.1 为什么是“约定优于配置”而不是“全自动生成”

t3code 最核心的设计理念，用一句话概括就是：用约定来减少决策，用配置来保留灵活。这个思路其实在业界已经被验证过很多次了，从 Ruby on Rails 的“约定优于配置”到各种现代框架的 CLI 工具，本质上都是在解决同一个问题——开发者每天要做太多微小的决策了，变量怎么命名、文件放哪个目录、接口返回什么结构，这些决策单个看都不难，但累积起来会消耗大量精力，而且容易导致项目内部不一致。

t3code 的做法是，先给你一套默认约定。比如它默认认为你的项目会按照功能模块划分目录，每个模块下会有model、service、controller这样的分层结构，数据模型的字段命名会遵循小驼峰，接口返回会统一包裹一层{ code, data, message }的结构。这些约定不是随便定的，而是从大量实际项目中提炼出来的“最常见形态”。你如果认同这套约定，那基本上不需要写什么配置，直接用它提供的命令就能生成符合规范的代码骨架。

但现实情况是，每个团队、每个项目都有自己的特殊情况。所以 t3code 在约定之上留了配置层。你可以通过一个配置文件来覆盖默认约定，比如修改目录结构、调整命名规则、指定不同的模板文件等等。这种“默认能用，需要时可改”的设计，比那种一上来就让你填一大堆配置的工具要友好得多，也比那种完全固定、无法调整的工具要实用。

我个人的体会是，这种设计特别适合项目初期快速搭建和中期规范化改造两个场景。初期搭建时，你直接用默认约定，几分钟就能把项目骨架跑起来；中期改造时，你可以逐步把团队的特殊规范写进配置，让 t3code 慢慢适应你的项目，而不是反过来。

2.2 模板引擎的选择与取舍

t3code 在代码生成环节使用了一套轻量级的模板引擎。我研究了一下它的实现，发现它没有选择那些功能特别强大的模板语言，而是用了一种接近原生字符串拼接但增加了条件判断和循环能力的简化方案。这个选择乍看有点“简陋”，但仔细想想其实很合理。

功能强大的模板引擎往往意味着更陡峭的学习曲线和更复杂的调试过程。对于代码生成这个场景来说，模板本身不应该成为负担。开发者需要的是“我写一个大概的样子，然后把变量填进去”，而不是“我要先学一门模板语言才能生成代码”。t3code 的模板语法基本上就是占位符替换加上简单的逻辑控制，比如{{name}}表示插入变量，{{#if condition}}...{{/if}}表示条件渲染，{{#each list}}...{{/each}}表示循环。这种程度的表达能力，对于生成 CRUD 代码、组件骨架、配置文件这些任务来说已经完全够用了。

另一个值得注意的取舍是，t3code 的模板文件是纯文本的，不强制要求特定的文件扩展名，也不要求模板必须放在某个固定目录。你可以把模板放在项目里的任何位置，只要在配置里指向它就行。这个设计给了团队很大的自由度——你可以把模板和项目代码一起版本控制，也可以单独维护一套模板库供多个项目共享。

提示：如果你打算在团队内部推广 t3code，建议把模板文件纳入代码评审流程。模板一旦写错，生成出来的代码会批量出错，而且因为生成过程是自动的，很容易被忽略。

2.3 与现有工具链的集成策略

t3code 在设计上刻意避免了“自成一体”的倾向。它没有自己的包管理器，没有自己的构建流程，也没有自己的运行时。它就是一个命令行工具，通过读取配置和模板，在指定位置生成文件。生成完之后，这些文件就完全属于你的项目了，你可以用任何你习惯的工具去构建、测试、部署。

这种“生成后即脱离”的策略，我觉得是 t3code 最聪明的地方之一。很多代码生成工具试图在生成之后继续“管理”这些代码，结果就是工具本身变成了项目的一个强依赖，升级工具版本时提心吊胆，生怕生成逻辑变了导致代码被覆盖。t3code 的做法是：生成一次，之后这些代码就是你的了。你可以随意修改，工具不会再来碰它们。如果你需要重新生成，那也是你主动发起的操作，而且工具会提示你哪些文件已经存在、是否要覆盖。

这种策略带来的另一个好处是，t3code 可以很容易地集成到现有的开发流程中。你可以在项目初始化脚本里调用它，也可以在 CI 流程里用它来检查代码结构是否符合约定，甚至可以把它包装成一个 npm script 或者 Makefile 目标，让团队成员用统一的方式调用。

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

3.1 配置文件的结构与关键字段

t3code 的配置文件是整个工具运转的中枢。默认情况下，它会在项目根目录寻找t3code.config.js或t3code.config.json文件。我建议用.js格式，因为可以在配置里写注释和简单的逻辑，可读性更好。配置文件的核心结构大致分为三块：路径配置、命名规则、模板映射。

路径配置决定了生成的文件放在哪里。比如你可以定义modelPath、servicePath、controllerPath分别指向不同的目录。这里有个细节需要注意：t3code 支持在路径中使用变量占位符，比如src/modules/{{moduleName}}/model，这样生成时会自动根据模块名创建对应的子目录。这个功能在多模块项目中特别有用，能避免所有文件都堆在一个目录里。

命名规则配置决定了生成的变量名、文件名、类名等采用什么风格。t3code 内置了几种常见的命名风格：camelCase、PascalCase、snake_case、kebab-case。你可以为不同的实体指定不同的风格，比如文件名用 kebab-case，类名用 PascalCase，变量名用 camelCase。这里我的经验是，尽量和项目现有的命名风格保持一致，不要因为引入了新工具就改变整个项目的命名习惯，那样只会增加团队的认知负担。

模板映射配置是连接“你要生成什么”和“用什么模板生成”的桥梁。你可以定义多个生成器，每个生成器有自己的名称、模板文件路径、输出路径规则。比如定义一个叫crud的生成器，它会同时生成 model、service、controller 三个文件，分别使用三个不同的模板。

// t3code.config.js 示例 module.exports = { paths: { model: 'src/modules/{{moduleName}}/model', service: 'src/modules/{{moduleName}}/service', controller: 'src/modules/{{moduleName}}/controller', }, naming: { file: 'kebab-case', class: 'PascalCase', variable: 'camelCase', }, generators: { crud: { templates: [ { template: 'templates/model.tpl', output: '{{paths.model}}/{{fileName}}.js' }, { template: 'templates/service.tpl', output: '{{paths.service}}/{{fileName}}.js' }, { template: 'templates/controller.tpl', output: '{{paths.controller}}/{{fileName}}.js' }, ], }, }, };

上面这个配置示例展示了一个典型的 CRUD 生成器。当你运行t3code generate crud --name user时，它会在三个目录下分别生成user.js文件，每个文件的内容由对应的模板决定。

3.2 模板文件的编写技巧与变量注入

模板文件是 t3code 的灵魂。写模板的过程，本质上是在抽象一类代码的共同结构。我刚开始用的时候，总想把模板写得特别通用，结果就是模板里塞满了条件判断，可读性极差，维护起来比手写代码还累。后来我调整了策略：一个模板只负责一种明确的场景，如果需要生成差异较大的代码，就写多个模板，而不是在一个模板里用大量if-else去覆盖所有情况。

t3code 在渲染模板时会注入一批内置变量，这些变量可以直接在模板里使用。常用的内置变量包括：

除了内置变量，你还可以在命令行通过--set key=value的方式传入自定义变量。比如t3code generate crud --name order --set withPagination=true，然后在模板里用{{#if withPagination}}...{{/if}}来控制是否生成分页相关的代码。

写模板时有一个很容易踩的坑：空格和换行。模板里的缩进和空行会原样输出到生成的文件里。如果模板写得比较随意，生成出来的代码格式就会很乱。我的做法是，在模板里严格按照目标代码的格式来写，该缩进的地方缩进，该空行的地方空行。虽然写模板的时候稍微麻烦一点，但生成出来的代码直接就能用，不需要再手动格式化。

注意：t3code 默认不会对生成的文件做格式化处理。如果你希望生成后自动格式化，可以在生成命令后面接一个格式化命令，比如t3code generate crud --name user && prettier --write src/modules/user。这样能保证生成代码和手写代码在格式上完全一致。

3.3 生成器的组合与复用策略

随着项目变大，你可能会发现单个生成器不够用了。比如你既需要生成基础的 CRUD，又需要生成带缓存逻辑的 CRUD，还需要生成只读的查询接口。这时候如果每个场景都写一套独立的模板，维护成本会很高。t3code 提供了生成器组合的能力，你可以把一些通用的模板片段抽出来，然后在不同的生成器里引用它们。

具体做法是，在配置里定义一个partials字段，里面存放可复用的模板片段。然后在主模板里用{{> partialName}}的方式引入。比如你可以把“数据库连接获取”这段逻辑抽成一个 partial，在所有的 service 模板里都引入它。这样当数据库连接方式发生变化时，只需要改一个地方。

另一个实用的技巧是生成器继承。你可以定义一个基础生成器，包含所有生成器都需要的模板（比如日志、错误处理），然后让其他生成器继承它，再追加自己特有的模板。这样既能保证基础逻辑的一致性，又能让不同生成器有自己的特色。

我自己的项目里就用了这种组合策略。基础生成器负责生成 model 和基础的 service 方法，然后crud生成器继承它并追加 controller 和路由配置，api生成器继承它并追加 API 文档相关的注释。这样一套组合下来，新增一个模块只需要跑一条命令，生成出来的代码结构统一，后续维护也方便。

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

4.1 从零搭建一个 t3code 项目的完整流程

假设你现在要开始一个新项目，并且打算用 t3code 来管理代码生成。下面是我实际操作的完整流程，你可以直接照着做。

第一步：初始化项目并安装 t3code

mkdir my-project && cd my-project npm init -y npm install t3code --save-dev

这里我把 t3code 装成了开发依赖，因为它只在开发阶段使用，不应该出现在生产环境的依赖里。安装完成后，你可以运行npx t3code --version来确认安装成功。

第二步：创建配置文件

在项目根目录创建t3code.config.js。我建议从最小配置开始，只定义最基础的路径和命名规则，后面有需要再逐步添加。

module.exports = { paths: { model: 'src/models', service: 'src/services', controller: 'src/controllers', }, naming: { file: 'kebab-case', class: 'PascalCase', variable: 'camelCase', }, };

第三步：编写第一个模板

在项目根目录创建templates目录，然后在里面创建model.tpl：

// {{className}} Model // Generated at {{timestamp}} const {{variableName}}Schema = { id: { type: 'string', required: true }, name: { type: 'string', required: true }, createdAt: { type: 'number', default: Date.now }, }; module.exports = {{variableName}}Schema;

这个模板很简单，但它展示了模板的基本写法：用{{className}}插入类名，用{{variableName}}插入变量名，用{{timestamp}}插入生成时间。

第四步：配置生成器

在配置文件里添加生成器定义：

generators: { model: { templates: [ { template: 'templates/model.tpl', output: '{{paths.model}}/{{fileName}}.js' }, ], }, },

第五步：运行生成命令

npx t3code generate model --name user

执行后，你会在src/models/user.js看到生成的文件。打开检查一下，确认变量替换和格式都符合预期。

第六步：逐步扩展

当基础流程跑通后，你可以继续添加 service 模板、controller 模板，把生成器从单个文件扩展到多个文件。每添加一个模板，都建议先手动运行一次生成命令，确认输出正确后再继续。

4.2 参数计算与命名转换的底层逻辑

t3code 在生成文件之前，会先根据你传入的--name参数和配置里的命名规则，计算出一组派生变量。这个过程看起来简单，但里面有一些细节值得展开说说。

假设你传入的--name是user-profile。t3code 首先会把它拆分成单词数组['user', 'profile']。拆分规则是：遇到连字符、下划线、空格就分割，遇到大写字母也分割（但连续大写字母视为一个整体，比如APIKey会拆成['API', 'Key']）。拆分完成后，再根据配置的命名风格重新组合。

这个转换逻辑在大多数情况下都能正确工作，但有几个边界情况需要注意。第一，如果名称里包含数字，比如user2profile，t3code 会把数字当作单词的一部分，不会在数字前后分割。第二，如果名称里包含连续的大写字母，比如APIKey，它会尽量保持缩写词的完整性，拆成API和Key而不是A、P、I、K、e、y。第三，如果名称里包含特殊字符，比如user@profile，特殊字符会被当作分隔符处理。

提示：如果你发现自动转换的结果不符合预期，可以在命令行用--set手动覆盖某个派生变量。比如--set className=UserProfileV2，这样模板里用到的className就会是你指定的值，而不是自动计算出来的。

4.3 生成结果的验证与回滚机制

代码生成最怕的是什么？是生成了一堆文件，结果发现模板写错了，或者配置不对，需要一个个手动删除。t3code 在这方面提供了一些保护机制，但需要你主动去用。

首先，t3code 在生成文件之前会检查目标路径是否已经存在同名文件。如果存在，它会默认跳过并给出提示，而不是直接覆盖。这个行为可以通过--force参数改变，加上--force后它会直接覆盖已有文件。我的建议是，除非你确定要重新生成，否则不要轻易加--force。因为生成的文件可能已经被你手动修改过，直接覆盖会丢失这些修改。

其次，t3code 支持--dry-run模式。在这个模式下，它只会打印出将要生成的文件列表和内容摘要，不会真正写入磁盘。这个功能在调试模板时特别有用。你可以先跑一次--dry-run，看看生成的内容对不对，确认无误后再去掉--dry-run正式生成。

如果你已经生成了一批文件，后来发现需要回滚，t3code 本身没有提供回滚命令。但你可以结合 git 来操作：在生成之前先提交一次代码，生成之后如果发现问题，用git checkout或者git clean来撤销。我自己的习惯是，每次批量生成之前都确保工作区是干净的，这样万一出问题，回滚成本最低。

还有一个实用的小技巧：把生成的文件和手写的文件分开管理。比如生成的文件统一放在src/generated目录下，手写的业务逻辑放在src/modules目录下。这样即使生成的文件需要重新生成，也不会影响到手写代码。t3code 的路径配置支持这种分离，你只需要把paths里的路径指向src/generated下的对应子目录即可。

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

5.1 模板渲染结果不符合预期的排查思路

这是使用 t3code 时最常见的一类问题。你运行了生成命令，文件也生成了，但打开一看，某些地方不对——可能是变量没替换，可能是条件判断没生效，也可能是格式乱了。遇到这种情况，我一般按照下面的顺序来排查。

第一，检查变量名是否拼写正确。t3code 在渲染模板时，如果遇到未定义的变量，默认会保留原样输出（即输出{{variableName}}本身），而不是报错。这个设计有利有弊：好处是不会因为一个变量没定义就中断整个生成过程，坏处是错误容易被忽略。所以当你看到生成的文件里有{{...}}这样的残留时，第一反应应该是去检查这个变量名是否在配置或命令行参数里定义了。

第二，检查条件判断的语法。t3code 的条件判断语法是{{#if condition}}...{{/if}}。这里有个细节：condition的值如果是空字符串、0、null、undefined或者空数组，都会被判定为假。如果你传入的变量是字符串"false"，它会被判定为真，因为非空字符串在布尔转换时是true。这个坑我踩过，当时传入了一个字符串类型的布尔值，结果条件判断一直走的是真分支，排查了半天才发现是类型问题。

第三，检查模板文件的编码和换行符。如果模板文件保存成了带 BOM 的 UTF-8，或者换行符是 Windows 风格的\r\n，生成出来的文件可能会在开头多出不可见字符，或者在某些编辑器里显示异常。建议统一使用无 BOM 的 UTF-8 和 Unix 换行符。

第四，用--dry-run加--verbose查看详细日志。t3code 在 verbose 模式下会打印出每个模板的渲染过程，包括注入了哪些变量、条件判断走了哪个分支。这些信息对于定位问题非常有帮助。

5.2 生成文件与现有代码冲突的处理方式

在已有项目中引入 t3code 时，很容易遇到生成的文件和现有文件冲突的情况。比如你已经有src/models/user.js了，现在想用 t3code 重新生成一个符合新规范的版本。这时候直接生成会被跳过（因为文件已存在），加--force又会覆盖掉原有内容。

我的处理方式是先对比，再决定。具体操作是：先用--dry-run生成一份临时文件到其他目录，然后和现有文件做 diff。如果现有文件里有业务逻辑是模板无法生成的，那就保留现有文件，只把模板里新增的部分手动合并进去。如果现有文件本身就是模板生成的旧版本，没有手动修改过，那就直接--force覆盖。

为了减少这种冲突，我建议在项目初期就引入 t3code，而不是等到项目中期再补。初期引入时，生成的文件都是全新的，不存在冲突问题。中期引入时，最好先花点时间把现有代码的结构梳理一遍，看看哪些部分适合用模板生成，哪些部分必须保留手写，然后再设计模板和生成器。

另一个技巧是给生成的文件加标记。在模板的开头加一行注释，比如// @generated by t3code。这样你一眼就能看出哪些文件是生成的，哪些是手写的。在代码评审时，生成的代码可以快速略过，评审精力集中在手写代码上。

5.3 性能优化与批量生成的注意事项

当项目模块数量增多时，批量生成可能会变得比较慢。我实测下来，生成 100 个模块（每个模块 3 个文件）大约需要 10 到 15 秒。这个速度对于日常开发来说可以接受，但如果你在 CI 流程里频繁调用，就需要考虑优化了。

优化的第一个方向是减少不必要的文件读写。t3code 在生成每个文件时都会先检查目标路径是否存在，这个检查本身是文件系统操作，有一定开销。如果你确定目标目录是空的，可以在配置里关掉存在性检查（如果 t3code 支持这个选项的话），或者直接用--force跳过检查。

第二个方向是并行生成。t3code 默认是串行生成文件的，如果你有大量文件需要生成，可以考虑用 shell 脚本把生成任务拆分成多个批次，并行执行。比如按模块名首字母分组，每组起一个 t3code 进程。不过要注意，并行写入同一个目录时可能会有竞争问题，建议每组输出到不同的临时目录，最后再合并。

第三个方向是缓存模板解析结果。如果你在同一个会话里多次调用 t3code，模板文件的解析结果是可以复用的。不过这个需要 t3code 本身支持，目前我用的版本还没有这个功能，所以只能靠减少调用次数来优化。

注意：批量生成时一定要先备份或者确保代码已提交。我曾经因为一个模板里的循环变量写错了，导致批量生成的 50 多个文件全部内容错乱，幸好当时工作区是干净的，直接git checkout .就恢复了。如果没有版本控制，那场面就不好收拾了。

5.4 常见问题速查表

6. 进阶用法与扩展思路

6.1 把 t3code 集成到 CI 流程中

t3code 除了在本地开发时使用，还可以集成到 CI 流程里，用来做代码结构一致性检查。具体做法是：在 CI 脚本里运行一次生成命令，输出到一个临时目录，然后和项目里的实际代码做 diff。如果 diff 结果不为空，说明有人手动修改了生成的文件，或者新增的模块没有按照规范生成。这时候 CI 可以给出警告，提醒开发者检查。

这个检查特别适合那些对代码结构一致性要求较高的团队。比如你们规定所有的 service 层必须包含某些基础方法，那么如果有人新建了一个 service 文件但漏掉了这些方法，CI 就能通过 diff 发现这个问题。

实现这个检查的脚本大概长这样：

#!/bin/bash # ci-check-generated.sh # 生成到临时目录 npx t3code generate all --output /tmp/t3code-check # 对比生成结果和实际代码 diff -r /tmp/t3code-check src/ > /tmp/t3code-diff.txt if [ -s /tmp/t3code-diff.txt ]; then echo "发现生成代码与实际代码不一致：" cat /tmp/t3code-diff.txt exit 1 fi echo "代码结构一致性检查通过"

这个脚本的思路是，如果生成结果和实际代码完全一致，说明没有人手动修改过生成的文件，也没有遗漏生成步骤。如果有差异，就把差异打印出来，让开发者判断是应该更新模板还是应该重新生成。

6.2 自定义模板库的维护与共享

当团队里多个项目都在用 t3code 时，维护一套共享的模板库就很有必要了。我的做法是单独建一个 git 仓库，专门存放模板文件和基础配置。然后在各个项目的t3code.config.js里通过相对路径或包名引用这个模板库。

共享模板库的好处是，当团队规范调整时，只需要改一个地方，所有项目都能受益。但也要注意版本管理的问题：如果模板库直接改了，所有项目下次生成时都会用新模板，可能会影响正在开发中的项目。所以建议给模板库打上版本标签，项目里引用时指定版本号，需要升级时再手动切换。

模板库的目录结构可以这样组织：

t3code-templates/ ├── base/ │ ├── model.tpl │ ├── service.tpl │ └── controller.tpl ├── variants/ │ ├── with-cache/ │ │ └── service.tpl │ └── with-pagination/ │ └── controller.tpl ├── partials/ │ ├── db-connection.tpl │ └── error-handler.tpl └── config/ └── base.config.js

项目里引用时，可以这样配置：

const baseConfig = require('t3code-templates/config/base.config'); module.exports = { ...baseConfig, templates: { ...baseConfig.templates, model: 'node_modules/t3code-templates/base/model.tpl', }, };

这种组织方式让模板的复用和定制都变得很清晰。基础模板放在base目录，变体模板放在variants目录，可复用的片段放在partials目录。项目可以根据自己的需要选择引用哪些模板。

6.3 从代码生成到代码规范的延伸

用了一段时间 t3code 之后，我逐渐意识到它的价值不仅仅在于“生成代码”这个动作本身。更重要的是，它迫使团队去明确和固化代码规范。因为你要写模板，就必须先想清楚：一个标准的 model 应该包含哪些字段？一个 service 方法应该有什么样的签名？controller 的返回值应该是什么结构？这些问题在平时可能被忽略，但在写模板的过程中必须给出明确答案。

所以我的建议是，把 t3code 的模板文件当作团队代码规范的活文档来维护。每当团队讨论出一个新的规范，就同步更新到模板里。新加入的成员通过阅读模板，就能快速理解团队的编码习惯。代码评审时，如果发现生成代码和手写代码风格不一致，也可以反过来推动模板的改进。

这种“规范驱动开发”的思路，我觉得是 t3code 这类工具最大的长期价值。它不只是一个提效工具，更是一个团队协作的锚点，把那些口口相传的隐性规范变成显性的、可执行的模板。

7. 个人实操心得与避坑建议

7.1 模板不要写得太“聪明”

我刚开始写模板时，总想用各种条件判断和循环把模板写得特别灵活，一个模板恨不得覆盖十种场景。结果就是模板本身变得极其复杂，可读性差，调试困难，而且每次新增场景都要在模板里加逻辑，维护成本越来越高。

后来我转变了思路：模板应该简单直接，一个模板只做一件事。如果两个场景差异较大，就写两个模板，而不是在一个模板里用if-else去区分。虽然模板数量多了，但每个模板都很简单，修改起来不容易出错，新人也能快速看懂。

这个经验其实适用于很多代码生成场景。模板的复杂度应该和它要生成的代码复杂度相匹配，而不是试图用模板的复杂度去覆盖所有可能的变体。变体应该通过组合不同的模板来实现，而不是通过在一个模板里堆砌条件逻辑。

7.2 生成时机比生成内容更重要

很多人关注的是“生成什么”，但我发现“什么时候生成”同样重要，甚至更重要。我的经验是：在结构确定之后、业务逻辑填充之前生成。也就是说，当你已经想清楚一个模块需要哪些文件、每个文件的职责是什么、它们之间怎么交互，但还没有开始写具体的业务代码时，是运行生成器的最佳时机。

如果生成得太早，结构还没想清楚，生成出来的文件可能很快就要调整，反而浪费了生成的时间。如果生成得太晚，业务逻辑已经手写了一大半，再生成就会和现有代码冲突，合并成本很高。

另外，我建议把生成命令固化到项目脚本里。比如在package.json里加一个"gen": "t3code generate"的脚本，团队成员统一用npm run gen来调用。这样既能保证大家用的命令一致，也方便在命令里预设一些常用参数。

7.3 不要用生成器替代思考

最后说一个心态层面的问题。代码生成工具很容易让人产生一种“有了它就不用动脑子”的错觉。但实际上，生成器只能帮你处理那些你已经想清楚的结构性重复。如果结构本身没想清楚，生成出来的代码只是把混乱从手写转移到了模板里，问题并没有解决。

我见过一些团队，引入代码生成工具后，反而写出了更多低质量的代码，因为生成太方便了，大家就不假思索地批量生成，结果项目里充斥着大量结构相似但职责不清的模块。这种情况下的问题不在工具，而在于使用工具的人没有先做好设计。

所以我的建议是：把 t3code 当作一个执行工具，而不是设计工具。用它来落实你已经想清楚的规范，而不是用它来替你想清楚规范。每次运行生成命令之前，先花几分钟确认一下：这个模块的职责是什么？它需要哪些文件？这些文件之间怎么交互？想清楚这些，再让 t3code 去生成，效果会好很多。

这个内容后续还可以这样扩展：如果你用的是 TypeScript，可以在模板里加入类型定义的生成逻辑；如果你有 API 文档生成的需求，可以在模板里加入 JSDoc 或 OpenAPI 注释；如果你需要生成测试文件，也可以为测试单独写一套模板。t3code 的扩展性其实比它表面看起来要强，关键在于你愿不愿意花时间去设计模板和配置。