配置 API 报告

本文继续介绍了 "调用 API 提取器" 页面上的教程。建议从那里开始。

API 报告文件配置相对简单。两个最有趣的设置是

• apiReport.enabled - 是否要生成报告
• apiReport.reportFolder - 报告将存储的文件夹

对于单个项目，将报告保存在默认位置 "<projectFolder>/etc/" 中是可以的。而如果您在具有多个项目的 monorepo 中工作，您可能更倾向于将所有 API 报告文件写入一个中心位置，例如 rushstack 存储库中使用的 common/reviews/api，其中开发了 API 提取器。

报告文件应由 Git 跟踪，以便对 API 签名的更改将在创建拉取请求 (PR) 时显示为差异。

rushstack 存储库使用 .github/CODEOWNERS 文件来要求更改 API 时来自特定人员列表的批准。根据您的流程，此批准可以更正式或更不正式。

将警告重定向到 API 报告文件

顺便说一下，API 报告文件也可以用来跟踪特定的警告类型。例如，虽然 ae-forgotten-export 验证通常很有用，但假设在某些情况下您故意不想导出声明。

通常警告会打印到控制台，如下所示

Warning: (ae-forgotten-export) The symbol "IWidget" needs to be exported by
the entry point index.d.ts

控制台警告会导致 api-extractor 工具返回非零退出代码，这将导致生产构建失败。但是，使用 addToApiReportFile 设置，您可以配置将警告添加到 API 报告文件而不是控制台。您将在此处添加一个类似的节到 api-extractor.json 文件中

awesome-widgets/config/api-extractor.json

  . . .
  "messages": {
    "extractorMessageReporting": {
      "ae-forgotten-export": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
    },
    . . .
  },
  . . .

您将在报告文件中看到类似的东西，而不是将警告打印到控制台

awesome-widgets/etc/api-extractor.api.md

// Warning: (ae-forgotten-export) The symbol "IWidget" needs to be exported
// by the entry point index.d.ts
//
// @public
export class Widget implements IWidget {}

如果您查看 api-extractor-defaults.json，您将看到 API 提取器默认情况下已经为许多消息类型执行了此操作。一般来说，它默认为 true，适用于任何消息，其中问题并不严重，但修复可能需要非平凡的努力或对您的 API 产生非平凡的后果。