Rush Stack商店博客活动
跳至主要内容

调用 API Extractor

听起来很棒！那么…我们究竟如何为一个新项目启用 API Extractor？

通过命令行调用​

调用 API Extractor 最简单的方法是通过命令行。

1. 为您的项目配置 TypeScript 编译器​

对于本教程，假设我们有一个假设的库项目，其 **package.json** 文件如下所示

awesome-widgets/package.json

{
  "name": "awesome-widgets",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "typings": "./lib/index.d.ts"
}

这里我们假设库的主入口点是 **awesome-widgets/src/index.ts**，它编译后生成上面看到的 **index.js** 和 **index.d.ts** 文件。在您的 **tsconfig.json** 文件中，您应该启用以下设置

  • "declaration": true - 这将启用生成 API Extractor 将分析的 .d.ts 文件。设计上，TypeScript 源文件不会被直接分析，而是必须先由您的编译器进行处理。

  • "declarationMap": true - 这将启用生成 .d.ts.map 文件，这些文件允许 API Extractor 错误使用来自您原始源文件的行号进行报告；没有它，错误位置将改为引用生成的 .d.ts 文件。

我们的示例 **tsconfig.json** 文件可能如下所示

awesome-widgets/tsconfig.json

{
  "$schema": "http://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "sourceMap": true,
    "declarationMap": true,
    "types": [
    ],
    "lib": [
      "es5"
    ],
    "outDir": "lib"
  },
  "include": [
    "src/**/*.ts"
  ]
}

2. 安装 API Extractor​

要在全局环境中安装 NPM 包，请使用以下命令

$ npm install -g @microsoft/api-extractor

假设您的 PATH 环境变量设置正确，您现在应该能够从 shell 中调用 api-extractor 工具。

3. 创建一个模板配置文件​

接下来，我们需要为您的项目创建一个配置文件 api-extractor.json。以下命令将创建一个 模板文件，其中显示了所有设置及其默认值

$ api-extractor init

我们建议将此模板用于您的真实配置文件。但是，由于模板相当冗长，在本教程中我们将展示没有额外注释的简化文件。此页面 详细解释了每个设置。

JSON 文件中的注释

严格来说，JSON 最初是作为一种机器交换格式设计的，因此它没有正式支持代码注释。近年来，JSON 作为一种人为编辑的配置文件格式越来越流行，这显然需要注释。因此，大多数严肃的 JSON 库都可以毫无问题地处理注释。（一个显著的例外是 JSON.parse()；不要使用它 - 它无法验证模式，并且错误报告很差。）

VS Code 默认情况下将 JSON 注释突出显示为错误，但它提供了一个可选的 "带注释的 JSON" 模式。要启用此功能，请将以下行添加到 VS Code 的 **settings.json** 中

"files.associations": { "*.json": "jsonc" }

GitHub 默认情况下也会将注释突出显示为错误。要解决此问题，请将以下行添加到您的 **.gitattributes** 文件中

*.json  linguist-language=JSON-with-Comments

有关其他一些可能性的讨论，请参见 问题 #1088。

我们的约定是将配置文件放在 "config" 子文件夹中，因此文件夹树可能如下所示

  • awesome-widgets/package.json
  • awesome-widgets/tsconfig.json
  • awesome-widgets/config/api-extractor.json
  • awesome-widgets/lib/index.d.js
  • awesome-widgets/lib/index.js.map
  • awesome-widgets/lib/index.d.ts
  • awesome-widgets/lib/index.d.ts.map
  • awesome-widgets/src/index.ts

如果您的项目不使用 "config" 子文件夹约定，您也可以将 **api-extractor.json** 放在您的项目文件夹中。API Extractor 将在两个位置都查找它。

在接下来的几页中，我们将更详细地查看各个设置。现在，我们应该确保 mainEntryPointFilePath 与我们上面 **package.json** 文件中的 "typings" 字段匹配。模板将其分配为以下形式

  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",

…这与上面的 **package.json** "typings" 字段匹配。

4. 运行工具​

现在我们准备调用 **api-extractor** 命令行。对于本地（非生产）构建，您将使用以下 shell 命令

$ cd awesome-widgets

# First invoke the TypeScript compiler to make the .d.ts files
$ tsc

# Next, we invoke API Extractor
$ api-extractor run --local --verbose

如果您遇到问题，--diagnostics 选项会打印更多信息，有助于诊断问题。

# Print troubleshooting logs
$ api-extractor run --local --diagnostics

编译器版本不兼容性

当 API Extractor 调用编译器引擎来分析您的项目时，它使用的是自己的 TypeScript 版本。它无法使用您的工具链的版本，因为编译器引擎 API 可能不兼容。这有时会导致 API Extractor 由于 TypeScript 版本之间系统类型差异而报告编译器错误。您可以通过指定 --typescript-compiler-folder 命令行选项（API 中的 IExtractorInvokeOptions.typescriptCompilerFolder）来避免这种情况。这使 API Extractor 能够使用来自您的工具链 TypeScript 文件夹的系统类型。

如果问题是您的工具链使用的是比 API Extractor 引擎更新的编译器版本，请打开一个 GitHub 问题请求升级 API Extractor 的编译器。我们尽量保持最新状态。

从构建脚本调用​

如果您的项目使用用 TypeScript 编写的自定义工具链构建，您也可以以编程方式调用 API Extractor 引擎。

有很多选项，但这是一个最基本的示例

import * as path from 'path';
import { Extractor, ExtractorConfig, ExtractorResult } from '@microsoft/api-extractor';

const apiExtractorJsonPath: string = path.join(__dirname, '../config/api-extractor.json');

// Load and parse the api-extractor.json file
const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(apiExtractorJsonPath);

// Invoke API Extractor
const extractorResult: ExtractorResult = Extractor.invoke(extractorConfig, {
  // Equivalent to the "--local" command-line parameter
  localBuild: true,

  // Equivalent to the "--verbose" command-line parameter
  showVerboseMessages: true
});

if (extractorResult.succeeded) {
  console.log(`API Extractor completed successfully`);
  process.exitCode = 0;
} else {
  console.error(
    `API Extractor completed with ${extractorResult.errorCount} errors` +
      ` and ${extractorResult.warningCount} warnings`
  );
  process.exitCode = 1;
}

如果您对单个 **tsconfig.json** 环境调用 API Extractor 多次，这种方法还允许您在多个调用之间重复使用相同的 CompilerState 对象。这可能是一个显著的性能优化，因为 TypeScript 编译器分析相对昂贵。看看 api-extractor-scenarios/src/runScenarios.ts 测试运行器，了解如何实现这一点的实际示例。

跨项目重复使用设置​

**api-extractor.json** 文件内容完全由 IConfigFile 接口描述，您可以使用它来构造 ExtractorConfig 对象。使用这种方法，可以完全避免创建 **api-extractor.json** 文件，但我们通常建议不要这样做。当开发人员在排查问题时，将您的实际配置表示在一个人们可以检查和调整的标准配置文件中非常有用。此外，如果您需要调试 API Extractor 本身，调试隔离的 api-extractor 进程可能比调试复杂的工具链更容易，但您将为此需要 **api-extractor.json** 文件。

那么…如果您在一个具有许多不同项目的现代单体存储库中工作，如何在没有大量复制粘贴 **api-extractor.json** 文件的情况下确保它们具有一致的 API Extractor 设置？遵循 **tsconfig.json** 和 **tslint.json** 的约定，API Extractor 支持 "extends" 字段，允许您的 **api-extractor.json** 文件从共享模板文件继承其配置。请参阅此处 以获取详细信息。

现在我们已经运行起来，让我们看看如何配置三种不同的输出类型…