TypeScript AST 变换实战：用代码改写代码的工程方案

TypeScript AST 变换实战用代码改写代码的工程方案一、批量重构的困局正则替换的脆弱与手动改写的低效代码库演进到一定规模批量重构不可避免。框架升级要改 API 调用方式。规范调整要统一命名与导入风格。旧代码迁移要把 CommonJS 改成 ES Module。这类改动动辄涉及几百上千个文件。手动改写既慢又容易漏。工程师盯着相似的代码机械重复注意力一散就出错。正则替换看起来快实则脆弱至极。代码的语法结构远比字符串匹配复杂。正则分不清字符串里的代码和真实代码。分不清注释里的require和调用语句。分不清嵌套作用域里的同名变量。一次全量替换下来CI 红一片回滚都难。真正可靠的方案是 AST 变换。把源码解析成抽象语法树在树结构上做语义级改写再生成回代码。改的是语法节点不是文本片段。该改的精准命中不该改的纹丝不动。TypeScript Compiler API 提供了完整的 AST 能力。既能解析也能变换还能保留类型信息。配合 codemod 模式可以做到一次编写批量执行。本文探讨在 TypeScript 上落地 AST 变换工具的工程方案。二、AST 变换的机制解析、遍历、改写、回生AST 变换分四个阶段。解析把源码变成语法树。遍历找到目标节点。改写替换为新节点。回生把树重新生成成代码。每个阶段都有讲究。解析阶段要决定用哪种语法。TypeScript 自带createSourceFile支持 TS 与 JS。也可借助 babel 解析器生态更丰富但类型信息弱。解析时要带正确的 LanguageVersion 与 ScriptTarget。否则现代语法会被误判为错误。遍历阶段用 visitor 模式。对每种节点类型注册回调访问到时触发。TypeScript 的forEachChild是基础工具。更高层可用 ts-morph 简化 API。改写阶段要谨慎。AST 是不可变结构不能直接修改原节点。要用updateXxx系列工厂方法创建新节点。父节点引用也要级联更新。回生阶段用createPrinter把树打回文本。默认会重新格式化可能与原文件风格不一致。要保留原格式需配合 SourceMap 与保留 trivia。整体链路如下flowchart LR A[源码文本] -- B[解析成 AST] B -- C[遍历定位目标节点] C -- D[构造新节点替换] D -- E[回生成新代码] E -- F[写回文件] F -- G[跑测试验证] style B fill:#e1f5fe style D fill:#fff3e0 style G fill:#e8f5e9变换的安全性来自两处。一是类型信息TS 能区分同名不同作用域的标识符。二是测试覆盖每个 codemod 配套快照测试确保只改预期部分。缺了这两层AST 变换也会变成高级正则。三、生产级实现CommonJS 到 ES Module 的变换工具下面用 TypeScript 实现一个真实场景的变换。把const fs require(fs)改写成import fs from fs。含类型检查、错误处理与变换前后校验。import * as ts from typescript; import * as fs from fs; /** * 把 CommonJS 的 require 调用改写为 ES import * 仅处理 const x require(y) 这类典型形态 * 复杂形态动态 require、解构 require需扩展 */ function transformCommonJsToEsm(sourceText: string, fileName: string): string { // 解析源码为 AST带类型信息以便后续校验 const sourceFile ts.createSourceFile( fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS ); // 记录所有需要替换的节点与对应的新 import 语句 const replacements: Array{ oldNode: ts.VariableStatement; newStatement: ts.ImportDeclaration; } []; function visit(node: ts.Node) { // 匹配 const xxx require(yyy) 模式 if ( ts.isVariableStatement(node) node.declarationList.declarations.length 1 ) { const decl node.declarationList.declarations[0]; const call decl.initializer; if ( decl.name ts.isIdentifier(decl.name) call ts.isCallExpression(call) ts.isIdentifier(call.expression) call.expression.text require call.arguments.length 1 ts.isStringLiteral(call.arguments[0]) ) { const varName decl.name.text; const modulePath (call.arguments[0] as ts.StringLiteral).text; // 构造等价的 import 语句 // 用工厂方法而非直接修改原节点保证 AST 不可变性 const importDecl ts.factory.createImportDeclaration( undefined, ts.factory.createImportClause( false, ts.factory.createIdentifier(varName), undefined ), ts.factory.createStringLiteral(modulePath) ); replacements.push({ oldNode: node, newStatement: importDecl }); } } ts.forEachChild(node, visit); } visit(sourceFile); if (replacements.length 0) { // 没有匹配项原样返回避免无谓的格式重排 return sourceText; } // 用 transformation context 做一次正式的树变换 const result ts.transform(sourceFile, [ (context) (rootNode) { function visitor(node: ts.Node): ts.Node { const matched replacements.find((r) r.oldNode node); if (matched) { return matched.newStatement; } return ts.visitEachChild(node, visitor, context); } return ts.visitNode(rootNode, visitor) as ts.SourceFile; }, ]); // 打印回代码保留原始引号风格 const printer ts.createPrinter({ newLine: ts.NewLineKind.LineFeed }); const output printer.printNode( ts.EmitHint.Unspecified, result.transformed[0], sourceFile ); result.dispose(); return output; } /** * 对单个文件做变换并写回带异常隔离 * 单文件失败不阻断整批迁移 */ function transformFile(filePath: string): boolean { try { const src fs.readFileSync(filePath, utf-8); const transformed transformCommonJsToEsm(src, filePath); if (transformed ! src) { fs.writeFileSync(filePath, transformed, utf-8); console.log([ok] ${filePath}); return true; } return false; } catch (e) { // 记录失败文件便于人工复查 // 不直接抛出保证批量任务的鲁棒性 console.error([fail] ${filePath}: ${(e as Error).message}); return false; } } // 命令行入口node dist/codemod.js file1.ts file2.ts if (require.main module) { const files process.argv.slice(2); if (files.length 0) { console.error(usage: codemod file...); process.exit(1); } let ok 0; for (const f of files) { if (transformFile(f)) ok; } console.log(done: ${ok}/${files.length} transformed); }真实工程会据此扩展。支持动态 require 的告警与跳过。处理require(x).foo这类链式调用。集成 ts-morph 简化 API降低心智负担。配套快照测试每次变换前后跑一遍断言。四、TypeScript AST 变换实战的代价与边界AST 变换强大但不是万能。类型信息不全。纯 JS 项目没有类型AST 无法区分同名变量。变换可能误改外层作用域的同名标识符。对 JS 项目要先补类型声明或限制变换范围。格式丢失。默认 printer 会重新格式化整个文件。团队的代码风格、注释位置、空行节奏可能被打乱。需要保留 trivia 或配合 prettier 二次格式化。否则 PR diff 会爆炸review 不可读。语义漂移。变换后的代码语法正确语义未必等价。比如require是同步的import是静态的。动态 require 改成 import 后可能报错。必须配套语义级测试而非只看语法。复杂度爆炸。变换逻辑越复杂越容易引入 bug。一个 codemod 最好只做一件事。多个变换串联执行每步都有测试。AST 变换的可逆性要提前规划。批量改写一旦上线回滚就是又一次批量改写成本翻倍。建议先在分支上跑全量变换配合完整测试套件验证再合并主分支。另一个常被忽视的点是变换工具自身的测试codemod 也是代码它本身的逻辑错误会导致全库被错误改写配套快照测试比业务代码更严格。最后AST 变换不是一次性工具要沉淀为项目内的 codemod 集合随着框架升级持续复用否则下次迁移又得从零开始。五、总结AST 变换的本质是把代码改写从文本匹配提升到语义理解。机制上靠解析、遍历、改写、回生四阶段配合类型信息保证精度。工程上靠不可变节点、异常隔离与快照测试守住安全边界。落地路线先用 TypeScript Compiler API 跑通最小变换封装异常隔离的批量执行器配套快照测试覆盖每种模式最后沉淀为可复用的 codemod 集合。代码改代码准比快更重要。