基于AST的CLI代码生成器t3code：终结样板代码，赋能工程化

聊个挺常见的场景技术栈走到一定阶段真正拖慢开发进度的往往不是复杂业务而是那些说不上难、但每次都要重新敲一遍的样板代码。拿我主力用的这套组合——Next.js、TypeScript、Tailwind CSS、tRPC 加 Prisma——来说每加一个数据模块至少得动手改路由、写 tRPC 的 router 定义、补 input 校验、再给前端加查询 hook一来一回四五个文件内容还高度雷同。后来我把这套流程固化成了 t3code一个跑在项目根目录下的命令行工具负责按约定生成这些标准模块跑完直接能编译能调通。这篇不打算只是晒工具而是把设计取舍、核心实现和真实的翻车经历都摊开讲给同样在考虑做工程化沉淀的开发者一些参考。1. 为什么最终选择命令行工具而不是可视化面板1.1 命令行比 UI 面板更适合“代码生成”场景很多人一听“工具”第一反应是做一个网页界面或可视化配置面板。我在早期也犹豫过但最终放弃了 UI 方案。原因很朴素代码生成这个场景的输入输出都是文本UI 在这里只能提供“表单填写 点击按钮”的交互可表单能承载的信息量和命令行参数差不多多一层界面反而增加维护成本。你想想一个生成组件的操作用 CLI 就是一句t3code new component --name UserCard回车出结果换成 UI 就得先打开页面、填五个字段、选一堆下拉框、再等接口回调拖沓太多了。CLI 还有一个 UI 很难替代的优势可以直接在 CI 里跑。生成逻辑能被自动化测试覆盖团队里新来的同事也不会因为找不到某个按钮而卡住。我用 Node.js 的生态做 CLI天然能吃下交互式提示、彩色输出、进度条这些能力开发成本远低于维护一个完整的前端控制台。1.2 先盘清楚 T3 Stack 里最值得自动化的四个环节我得先交代一下我平时项目里的固定结构。所谓 T3 Stack通常指 Next.js TypeScript Tailwind 加上 tRPC数据库层用 Prisma。用这套组合干活时最让人头大的不是写业务本身而是四个高度重复的环节第一数据模型落到 Prisma schema 之后必须手动在 tRPC 侧写对应的 router 和 procedure命名、类型、校验逻辑每次都差不多。第二前端页面要用数据时总要重复写trpc.someRouter.list.useQuery()这类调用代码。第三新增一个业务组件目录、文件名、默认导出、Props 类型定义这些约定全部要手动对齐。第四团队大了以后URL 路由命名和文件名风格很容易飘今天有人用user-card.tsx明天有人用userCard.ts代码评审时吵不完。这四个环节的共同点是人做费神、机器做很稳。t3code 的目标就不是代替你思考业务而是把“确定这套代码长什么样”变成既定事实然后自动化生成。工具本身只做严格的事剩下的空间留给人。2. 安装与核心命令设计init 和 new 的分工2.1 安装方式和运行环境t3code 是基于 Node.js 的 CLI 工具实现上用了 Node 20 内置能力没有引入臃肿的运行时。安装只需要一条命令npm install -g t3code安装后在任意 T3 Stack 项目根目录下执行t3code init它会检查当前项目的依赖版本是否符合预期。生成的代码默认适配 Next.js 14、tRPC 10 和 Prisma 5。如果项目版本跨度比较大可以用--target参数指定目标版本组合t3code init --target next14 trpc10 prisma5第一次运行会创建.t3coderc.json配置文件里面主要记录项目根路径、别名、输出目录这些约定。跑完 init 之后配置接近这样{ projectRoot: ./, pathAlias: , output: { components: src/components, routes: src/routes, serverRoutes: src/server/api/routers }, style: tailwind, stricterTypes: true }这个配置文件是整个工具的行为基准。t3code 默认不做强制约定所有路径都写在配置里这样遇到 monorepo 或者老项目改造时也能适配。2.2 new 命令按类型生成模块并自动串联最常用的命令是t3code new它支持三种目标类型component、route和model。component负责生成组件文件以及配套的 Props 类型定义例如t3code new component --name UserCard --props id: number, name: string执行后会在配置的 components 目录下生成UserCard.tsx内容大致是interface UserCardProps { id: number name: string } export function UserCard({ id, name }: UserCardProps) { return ( div classNamerounded-xl border p-4 h3 classNametext-lg font-medium{name}/h3 /div ) }生成的不是空壳props 类型会直接落进接口定义省掉手工打字。route用于生成 tRPC router 文件。它会读取 Prisma schema 里对应的实体名然后生成 userRouter 这类标准结构。最关键的是它还会自动把 router 挂载到主 router 的合并列表里不需要再手动去调mergeRouters相关的代码。model则是联动命令输入模型名之后它会同时生成 Prisma model 的骨架、tRPC router以及前端查询 hook 的示例调用。这三个文件在语义上是强关联的t3code 会保证它们之间的命名和字段引用一致。为了让生成结果可见跑一次model生成的目录结构类似prisma/ schema.prisma # 增加了 UserLog model src/server/api/routers/ userLog.ts # 标准 CRUD 的 tRPC router src/lib/hooks/ useUserLog.ts # 示例 hook我整理了一张命令速查表方便团队同事快速上手命令作用典型示例t3code init初始化项目约定和版本基准t3code init --target next14t3code new component生成组件和 Props 类型t3code new component --name UserCardt3code new route生成并挂载 tRPC routert3code new route --model AuditLogt3code new model联动生成 model、router、hookt3code new model --name AuditLog --fields ...t3code check扫描目录命名和依赖约束t3code check --dir src/components2.3 为什么把 init 和 new 拆成两条命令顺手说一下为什么不是一条t3code generate全包。核心原因是职责不同init 是修约定new 是产出代码。把修约定做成独立命令意味着新成员加入团队时可以直接完成一次“项目基准对齐”而不是稀里糊涂生成一堆代码之后才发现路径配置错了。init 还会做一件事——把当前依赖版本写进.t3coderc.json的 metadata 字段。这个信息是后面要讲的版本匹配兜底策略的基础。3. 核心生成逻辑为什么用 AST 而不是字符串模板3.1 字符串模板拼接的坑第一版 t3code 其实是用最朴素的字符串模板实现的就是“每个文件一份模板字符串然后 replace 变量名”那种。跑通 demo 时很爽但一碰上真实项目就崩了组件文件里已经有人引入了useState我生成的代码里又要再引入一遍结果出现重复导入某个文件用了 default export我给加的是 named export风格混乱更离谱的是给现有文件追加代码时直接往文件末尾拼字符串到了 ESLint 那里一堆格式错误。这些都是字符串拼接带来的老毛病——你没法感知目标文件的“现状”。3.2 用 TypeScript AST 做安全编辑所以第二版我直接把生成逻辑换成基于 TypeScript 编译 API 的 AST 操作。简单说t3code 会把待编辑文件解析成一棵语法树在语法树层面添加 import、插入函数声明、更新类型导出最后统一用 prettier 再序列化回文本。这样处理有四个直接好处新增 import 时API 会自动判断是否已存在同名导入不会重复。export 风格可以统一按项目已有代码决定追加 named export 还是 default export。插入位置不再是“文件尾巴”而是合理的语法位置比如把 hooks 放到函数组件之前。增量编辑时不会破坏原有代码格式prettier 兜底以后整个文件风格一致。对应的核心代码逻辑并不复杂典型写法类似import ts from typescript export function insertNamedImport( sourceFile: ts.SourceFile, moduleName: string, symbolName: string ): ts.SourceFile { const hasImport sourceFile.statements.some( (stmt) ts.isImportDeclaration(stmt) stmt.moduleSpecifier.getText().includes(moduleName) stmt.importClause?.namedBindings ) if (hasImport) return sourceFile const importDecl ts.factory.createImportDeclaration( undefined, ts.factory.createImportClause( false, undefined, ts.factory.createNamedImports([ ts.factory.createImportSpecifier( false, undefined, ts.factory.createIdentifier(symbolName) ) ]) ), ts.factory.createStringLiteral(moduleName) ) return ts.factory.updateSourceFile(sourceFile, [ ...sourceFile.statements.filter(isImportSection), importDecl, ...sourceFile.statements.filter((stmt) !isImportSection(stmt)) ]) }这样操作的是语法树而不是文本各种边界情况都交给编译器处理稳很多。3.3 路径别名和类型导入比想象中更容易出错AST 方案的另一个关键收益是它能把路径别名解析做得很干净。生成文件时最重要的就是 import 路径要写对。t3code 默认跟随tsconfig.json里的paths配置比如/对应src/。生成src/components/UserCard.tsx时要引入src/lib/types工具会自己算相对路径还是别名路径不用人肉维护。我后来还加了一个“显式类型导入”的开关。配置stricterTypes: true时所有类型导入都写成import type { X }符合 TypeScript 5 之后的 recommended 风格。这个细节看着小在 monorepo 开启 isolatedModules 之后影响很大。4. 三个真实使用场景从生成组件到批量补类型4.1 场景一用一个 model 命令串起完整数据模块我实际跑过最典型的场景是需求里要新加一个“操作日志”的模块。过去我的步骤是先改 Prisma schema然后写 tRPC router再去前端写 hook四个文件里光复制粘贴auditLog这个命名就要重复五六遍。现在执行一条命令t3code new model --name AuditLog --fields userId: string, action: string, ip: string它会自动做三件事。第一往schema.prisma里追加 model 定义第二生成src/server/api/routers/auditLog.ts里面包含基于 tRPC 10 的 CRUD procedure第三生成一个前端 hook 示例。更重要的是命令跑完后会顺手执行prisma format和prisma generate刷新客户端类型。整个流程跑完我能直接启动 dev server 去调接口中间不用手动补一行代码。这里我特别想强调的是“联动”的价值。单个生成器谁都能写难的是让几个动作保持同一套命名和类型引用。t3code 在 model 命令内部维护了一个简单的领域上下文对象里面保存了 model 名、字段列表、路由名、hook 名生成任何一个文件时都从同一个上下文取数据这就杜绝了手写时最容易出现的“router 里叫 auditLoghook 里叫 audit_log”这类低级不一致。4.2 场景二给遗留组件批量补类型导出我们的代码库里有一批老组件当初都是把类型写死在组件文件里没导出。后来要做组件文档和参数面板需要把所有 Props 类型统一导出。逐个文件手动改太蠢了我写了一个临时脚本利用 t3code 的 AST 能力批量处理对每个 tsx 文件找到函数组件声明提取 props 类型改成export interface ...Props并追加到文件导出区。大约一百多个文件几秒钟跑完改动被 git 记录下来是很清晰的 diff。这个场景本身不是 t3code 设计时预期的但因为它暴露了 AST 编辑 API反而成了工具最有用的意外收获。后来我把这段逻辑整理成t3code check --export-types的扩展参数团队里其他项目也能复用。做工具就是这样你永远不知道用户会在什么奇怪的地方发现价值所以 API 的开放性比功能列表更重要。4.3 场景三多人协作里统一命名风格团队里有位同事习惯用 kebab-case 命名文件另一位坚持 camelCase。以前这类问题靠 code review 人工盯效率低还伤感情。后来我用 t3code 的check子命令做约束检查扫描 components、routes、hooks 目录不符合约定的直接报错并给出改名建议。check 命令进 CI 之后这类争执基本消失了因为机器定的规矩比人吵有效得多。这个场景也验证了一个观点工具不一定要生成新东西才有价值约束存量代码的一致性同样能省下大量沟通成本。t3code 的 check 子命令本质上就是把团队规范固化成可执行规则让“标准”不再依赖某个人的记忆力。5. 踩坑实录版本、别名和文件监听这三道坎5.1 依赖版本漂移生成的代码编译不过第一次小范围试用时有同事反馈t3code 生成的 router 文件在本地编译失败提示TRPCError导入方式不对。排查后发现他项目里的 tRPC 还是 v9而我的模板默认按 v10 生成。v9 的initTRPC用法、error type 的导入路径和 v10 完全不同两边是兼容断裂的重写。具体定位过程我简单说一下。先复现问题用npm ls trpc/server查看项目版本发现是 9.x。再对比t3code new route生成的 import 语句用的是trpc/server里的initTRPC这是 v10 才有的 API。所以不是 ESLint 配置问题就是版本错配。这个教训让我意识到生成工具的假设必须显式化。现在的做法是init 时记录依赖版本生成代码时按版本分支选模板如果版本组合不在支持列表里直接拒绝生成并提示升级。宁可不出活也不能出错的代码。下面是我维护的一份版本对照表目标组合Next.jstRPCPrisma说明next1414.x10.x5.x当前主力模板legacy13.x9.x4.x仅存量项目使用canary15.x11.x6.x实验性支持5.2 路径别名在 AST 编辑中连续翻车前面说 AST 比字符串拼接强但它也有自己的坑。最典型的是有些项目用components这种别名实际指向src/components可tsconfig里配了不止一个 baseUrl 层级。生成文件时我一开始直接读paths的第一个映射值结果在某个 monorepo 里拿到的是另一个 package 的路径生成的 import 指向了完全错误的位置。后来改成优先取相对路径相对路径算不出来才用别名并且解析前先判断目标文件是否真的存在。这个改动看着小但几乎消灭了“生成后打开文件全是红色波浪线”的投诉。另外还要注意paths的 key 可能带通配符比如/*直接用字符串替换会出问题必须用tsconfig-paths那套解析逻辑做完整匹配。5.3 watch 模式下的文件监听冲突t3code 后来加了一个watch功能配合开发流程监听 schema 文件变化然后自动重生成。但它和 Next.js 自带的文件监听产生了冲突两边同时监听、同时写文件偶尔会出现“改一次 schema生成两遍代码”的重复改动。排查过程比较折腾一度以为是 t3code 的 bug。我用fs.watch的日志打印对比才发现是 Next.js dev server 的 watcher 和 t3code 的 watcher 在 Linux 的 inotify 上出现了竞争。最终的解决办法不是增加延迟而是让 t3code 在生成代码时写一个临时文件然后原子 rename并且只在自己负责的目录上加 watcher避开 Next.js 的 watch 范围。这种问题工具文档里基本不会写纯靠实际踩坑才明白。6. 性能优化与后续扩展方向6.1 生成速度AST 虽稳但不算快AST 操作比字符串拼接慢多了这是事实。生成一个 model 的三个文件AST 方式的耗时要到几百毫秒对 CLI 来说完全可以接受但如果在 watch 模式下频繁触发还是能感觉到闪烁。目前的做法是加了 crc32 文件内容对比内容没变的文件不写盘减少无关 diff。实测下来这个优化能过滤掉大量无效写入尤其在团队多人并行改 schema 时效果很明显。6.2 插件化让团队定制自己的生成器单一工具的模板能力终归有限下一步计划是把生成器改造成插件机制。团队可以注册自定义生成器比如有人想统一生成 API 测试的 mock 文件写一个小插件挂到 model 命令后处理即可。插件本质上就是一个函数接收解析好的上下文对象包括配置、AST toolset、当前项目版本返回要写入的文件列表。这样工具本身保持轻量能力则由团队自己去扩展。我在实际打磨过程中最深的体会是做工程化工具最大的成本不在第一版写出来而在后续对“假设”的维护。你假设了路径结构就要处理 monorepo你假设了 tRPC 版本就得处理升级断裂你假设了 watch 机制就得处理和其他工具打架。好在这套东西跑到现在稳定性已经有明显改善生成出的代码被团队直接合入的比例也越来越高。如果你也在类似的技术栈里反复处理样板代码我的建议是先别急着做一套大而全的平台用 CLI 把最痛的那一两个生成场景跑通收益立竿见影而且后续想扩展CLI 的演进路径非常平滑。