TypeScript 编译器 API：精通 AST 操作与代码转换

TypeScript 编译器 API 提供了一个强大的接口，用于分析、操作和生成 TypeScript 及 JavaScript 代码。其核心是抽象语法树 (Abstract Syntax Tree, AST)，它是源代码的一种结构化表示。理解如何使用 AST 可以解锁构建高级工具的能力，例如代码检查器 (linter)、代码格式化器、静态分析器和自定义代码生成器。

什么是 TypeScript 编译器 API？

TypeScript 编译器 API 是一组 TypeScript 接口和函数，它暴露了 TypeScript 编译器的内部工作原理。它允许开发者以编程方式与编译过程进行交互，而不仅仅是编译代码。您可以用它来：

• 分析代码：检查代码结构，识别潜在问题，并提取语义信息。
• 转换代码：修改现有代码，添加新功能，或自动重构代码。
• 生成代码：根据模板或其他输入从头创建新代码。

这个 API 对于构建能够提高代码质量、自动化重复任务和提升开发者生产力的高级开发工具至关重要。

理解抽象语法树 (AST)

AST 是代码结构的树状表示。树中的每个节点代表一个语法结构，例如变量声明、函数调用或控制流语句。TypeScript 编译器 API 提供了遍历 AST、检查其节点并进行修改的工具。

请看下面这段简单的 TypeScript 代码：

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("World"));

这段代码的 AST 将表示函数声明、返回语句、模板字面量、console.log 调用以及代码的其他元素。可视化 AST 可能具有挑战性，但像 AST explorer (astexplorer.net) 这样的工具可以提供帮助。这些工具允许您输入代码并以用户友好的格式查看其对应的 AST。使用 AST Explorer 将帮助您理解将要操作的代码结构类型。

关键的 AST 节点类型

TypeScript 编译器 API 定义了多种 AST 节点类型，每种类型代表一个不同的语法结构。以下是一些常见的节点类型：

• SourceFile: 代表整个 TypeScript 文件。
• FunctionDeclaration: 代表一个函数定义。
• VariableDeclaration: 代表一个变量声明。
• Identifier: 代表一个标识符（例如，变量名、函数名）。
• StringLiteral: 代表一个字符串字面量。
• CallExpression: 代表一个函数调用。
• ReturnStatement: 代表一个返回语句。

每种节点类型都有提供相应代码元素信息的属性。例如，一个 `FunctionDeclaration` 节点可能包含其名称、参数、返回类型和主体的属性。

开始使用编译器 API

要开始使用编译器 API，您需要安装 TypeScript 并对 TypeScript 语法有基本的了解。这里有一个简单的例子，演示如何读取一个 TypeScript 文件并打印其 AST：

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015, // Target ECMAScript version
  true // SetParentNodes: true to retain parent references in the AST
);

function printAST(node: ts.Node, indent = 0) {
  const indentStr = "  ".repeat(indent);
  console.log(`${indentStr}${ts.SyntaxKind[node.kind]}`);

  node.forEachChild(child => printAST(child, indent + 1));
}

printAST(sourceFile);

代码说明：

1. 导入模块：导入 `typescript` 模块和用于文件系统操作的 `fs` 模块。
2. 读取源文件：读取名为 `example.ts` 的 TypeScript 文件的内容。您需要创建一个 `example.ts` 文件才能让此代码工作。
3. 创建 SourceFile：创建一个 `SourceFile` 对象，它代表 AST 的根节点。`ts.createSourceFile` 函数会解析源代码并生成 AST。
4. 打印 AST：定义一个递归函数 `printAST`，它会遍历 AST 并打印每个节点的类型 (kind)。
5. 调用 printAST：调用 `printAST` 从根节点 `SourceFile` 开始打印 AST。

要运行此代码，请将其保存为 `.ts` 文件（例如 `ast-example.ts`），创建一个包含一些 TypeScript 代码的 `example.ts` 文件，然后编译并运行代码：

tsc ast-example.ts
node ast-example.js

这会将 `example.ts` 文件的 AST 打印到控制台。输出将显示节点的层次结构及其类型。例如，它可能会显示 `FunctionDeclaration`、`Identifier`、`Block` 等节点类型。

遍历 AST

编译器 API 提供了几种遍历 AST 的方法。最简单的是使用 `forEachChild` 方法，如前例所示。此方法访问给定节点的每个子节点。

对于更复杂的遍历场景，您可以使用 `Visitor`（访问者）模式。访问者是一个对象，它定义了针对特定节点类型调用的方法。这允许您自定义遍历过程并根据节点类型执行操作。

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

class IdentifierVisitor {
  visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      console.log(`Found identifier: ${node.text}`);
    }

    ts.forEachChild(node, n => this.visit(n));
  }
}

const visitor = new IdentifierVisitor();
visitor.visit(sourceFile);

代码说明：

1. IdentifierVisitor 类：定义一个 `IdentifierVisitor` 类，其中包含一个 `visit` 方法。
2. Visit 方法：`visit` 方法检查当前节点是否为 `Identifier`。如果是，则打印标识符的文本。然后它递归调用 `ts.forEachChild` 来访问子节点。
3. 创建访问者：创建一个 `IdentifierVisitor` 的实例。
4. 开始遍历：在 `SourceFile` 上调用 `visit` 方法以开始遍历。

此示例演示了如何在 AST 中找到所有标识符。您可以调整此模式以查找其他节点类型并执行不同的操作。

转换 AST

编译器 API 的真正威力在于其转换 AST 的能力。您可以修改 AST 来改变代码的结构和行为。这是代码重构工具、代码生成器和其他高级工具的基础。

要转换 AST，您需要使用 `ts.transform` 函数。该函数接受一个 `SourceFile` 和一个 `TransformerFactory` 函数列表。`TransformerFactory` 是一个函数，它接受一个 `TransformationContext` 并返回一个 `Transformer` 函数。`Transformer` 函数负责访问和转换 AST 中的节点。

这里有一个简单的例子，演示如何在一个 TypeScript 文件的开头添加注释：

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

const transformerFactory: ts.TransformerFactory = context => {
  return transformer => {
    return node => {
      if (ts.isSourceFile(node)) {
        // Create a leading comment
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " This file was automatically transformed ",
          true // hasTrailingNewLine
        );

        return node;
      }

      return node;
    };
  };
};

const { transformed } = ts.transform(sourceFile, [transformerFactory]);

const printer = ts.createPrinter({
  newLine: ts.NewLineKind.LineFeed
});

const result = printer.printFile(transformed[0]);

fs.writeFileSync("example.transformed.ts", result);

代码说明：

1. TransformerFactory：定义一个 `TransformerFactory` 函数，它返回一个 `Transformer` 函数。
2. Transformer：`Transformer` 函数检查当前节点是否为 `SourceFile`。如果是，它会使用 `ts.addSyntheticLeadingComment` 为该节点添加一个前导注释。
3. ts.transform：调用 `ts.transform` 将转换应用于 `SourceFile`。
4. Printer：创建一个 `Printer` 对象，用于从转换后的 AST 生成代码。
5. 打印和写入：打印转换后的代码，并将其写入一个名为 `example.transformed.ts` 的新文件。

这个例子演示了一个简单的转换，但您可以使用相同的模式执行更复杂的转换，例如重构代码、添加日志语句或生成文档。

高级转换技术

以下是您可以与编译器 API 配合使用的一些高级转换技术：

• 创建新节点：使用 `ts.createXXX` 函数创建新的 AST 节点。例如，`ts.createVariableDeclaration` 创建一个新的变量声明节点。
• 替换节点：使用 `ts.visitEachChild` 函数将现有节点替换为新节点。
• 添加节点：使用 `ts.updateXXX` 函数向 AST 添加新节点。例如，`ts.updateBlock` 用新语句更新一个块语句。
• 移除节点：通过从 transformer 函数返回 `undefined` 来从 AST 中移除节点。

代码生成

转换 AST 后，您需要从中生成代码。编译器 API 为此提供了一个 `Printer` 对象。`Printer` 接受一个 AST 并生成代码的字符串表示形式。

`ts.createPrinter` 函数创建一个 `Printer` 对象。您可以使用各种选项配置打印机，例如要使用的换行符以及是否输出注释。

`printer.printFile` 方法接受一个 `SourceFile` 并返回代码的字符串表示形式。然后您可以将此字符串写入文件。

编译器 API 的实际应用

TypeScript 编译器 API 在软件开发中有许多实际应用。以下是一些例子：

• 代码检查器 (Linter)：构建自定义 linter 以强制执行编码标准并识别代码中的潜在问题。
• 代码格式化器：创建代码格式化器，以根据特定的样式指南自动格式化您的代码。
• 静态分析器：开发静态分析器以检测代码中的错误、安全漏洞和性能瓶颈。
• 代码生成器：从模板或其他输入生成代码，自动化重复任务并减少样板代码。例如，从描述文件生成 API 客户端或数据库模式。
• 重构工具：构建重构工具以自动重命名变量、提取函数或在文件之间移动代码。
• 国际化 (i18n) 自动化：自动从您的 TypeScript 代码中提取可翻译的字符串，并为不同语言生成本地化文件。例如，一个工具可以扫描代码中传递给 `translate()` 函数的字符串，并自动将它们添加到翻译资源文件中。

示例：构建一个简单的 Linter

让我们创建一个简单的 linter，用于检查 TypeScript 代码中未使用的变量。这个 linter 将识别那些已声明但从未使用过的变量。

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

function findUnusedVariables(sourceFile: ts.SourceFile) {
  const usedVariables = new Set();

  function visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      usedVariables.add(node.text);
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  const unusedVariables: string[] = [];

  function checkVariableDeclaration(node: ts.Node) {
    if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
      const variableName = node.name.text;
      if (!usedVariables.has(variableName)) {
        unusedVariables.push(variableName);
      }
    }

    ts.forEachChild(node, checkVariableDeclaration);
  }

  checkVariableDeclaration(sourceFile);

  return unusedVariables;
}

const unusedVariables = findUnusedVariables(sourceFile);

if (unusedVariables.length > 0) {
  console.log("Unused variables:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("No unused variables found.");
}

代码说明：

1. findUnusedVariables 函数：定义一个 `findUnusedVariables` 函数，它接受一个 `SourceFile` 作为输入。
2. usedVariables Set：创建一个 `Set` 来存储已使用变量的名称。
3. visit 函数：定义一个递归函数 `visit`，它遍历 AST 并将所有标识符的名称添加到 `usedVariables` 集合中。
4. checkVariableDeclaration 函数：定义一个递归函数 `checkVariableDeclaration`，它检查变量声明是否未使用。如果是，则将变量名添加到 `unusedVariables` 数组中。
5. 返回 unusedVariables：返回一个包含所有未使用变量名称的数组。
6. 输出：将未使用的变量打印到控制台。

这个例子演示了一个简单的 linter。您可以扩展它来检查其他编码标准并识别代码中的其他潜在问题。例如，您可以检查未使用的导入、过于复杂的函数或潜在的安全漏洞。关键是要理解如何遍历 AST 并识别您感兴趣的特定节点类型。

最佳实践与注意事项

• 理解 AST：投入时间去理解 AST 的结构。使用像 AST explorer 这样的工具来可视化您的代码的 AST。
• 使用类型守卫：使用类型守卫 (`ts.isXXX`) 来确保您正在处理正确的节点类型。
• 考虑性能：AST 转换的计算成本可能很高。优化您的代码，以尽量减少访问和转换的节点数量。
• 优雅地处理错误：编译器 API 可能会在您尝试对 AST 执行无效操作时抛出异常。
• 充分测试：彻底测试您的转换，以确保它们产生预期的结果并且不会引入新的错误。
• 使用现有库：考虑使用在编译器 API 之上提供更高级别抽象的现有库。这些库可以简化常见任务并减少您需要编写的代码量。例如 `ts-morph` 和 `typescript-eslint`。

结论

TypeScript 编译器 API 是一个用于构建高级开发工具的强大工具。通过理解如何使用 AST，您可以创建 linter、代码格式化器、静态分析器以及其他能够提高代码质量、自动化重复任务和提升开发者生产力的工具。虽然该 API 可能很复杂，但掌握它所带来的好处是巨大的。这份全面的指南为您在项目中有效探索和利用编译器 API 奠定了基础。请记住利用 AST Explorer 等工具，仔细处理节点类型，并彻底测试您的转换。通过实践和专注，您可以释放 TypeScript 编译器 API 的全部潜力，并为软件开发领域构建创新的解决方案。

进一步探索：

• TypeScript 编译器 API 文档：[https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
• AST Explorer：[https://astexplorer.net/](https://astexplorer.net/)
• ts-morph 库：[https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint：[https://typescript-eslint.io/](https://typescript-eslint.io/)