API 报告

这篇文章继续了"什么是 API Extractor？"页面中的教程。建议您从那里开始。

我们将讨论的第一个 API Extractor 输出是“API 报告文件”。由于我们示例库的 NPM 包名称是 @microsoft/sp-core-library，默认 API 报告文件名将是 etc/sp-core-library.api.md。

该报告是一个Markdown 文件，主要包含一个大型伪代码块，简明扼要地总结了 API 签名。（在 API Extractor 7 之前，该报告使用 .api.ts 文件扩展名，但这会导致试图将伪代码解释为真实 TypeScript 代码的工具出现问题。）API 报告内容可能如下所示

etc/sp-core-library.api.md

## API Report File for "@microsoft/sp-core-library"

> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.node.org.cn/).

```ts
// @beta
interface ILogHandler {
  // (undocumented)
  error(source: string, error: Error): void;
  // (undocumented)
  info(source: string, message: string): void;
  // (undocumented)
  verbose(source: string, message: string): void;
  // (undocumented)
  warn(source: string, message: string): void;
}

// @public
class Log {
  // @beta
  public static initialize(logHandler: ILogHandler): void;
  public static error(source: string, error: Error): void;
  public static info(source: string, message: string): void;
  public static verbose(source: string, message: string): void;
  public static warn(source: string, message: string): void;
}
```

报告文件由 Git 跟踪。假设开发人员在其本地 PC 上对 Log 类进行了更改。当他们本地重新构建时（例如，使用 api-extractor 工具的 --local 命令行选项），他们将看到一条消息提醒他们报告文件已更改。

[17:01:21] Starting subtask 'api-extractor'...
[17:01:28] [api-extractor] You have changed the Public API signature for this
project.  Updating 'etc/sp-core-library.api.md'
[17:01:28] Finished subtask 'api-extractor' after 0.54 s

开发人员应该提交更新后的报告文件，并将其作为其拉取请求 (PR) 的一部分。如果他们忘记这样做，PR 验证将失败，因为它执行生产构建（即不使用 --local），不会自动更新报告文件。如果发生这种情况，PR 构建日志将显示类似于以下内容的错误消息

[17:03:37] Starting subtask 'api-extractor'...
[17:03:44] Warning - [api-extractor] You have changed the public API signature for this project.
Please copy the file "temp/sp-core-library.api.md" to "etc/sp-core-library.api.md", or perform
a local build (which does this automatically). See the Git repo documentation for more info.
[17:03:44] Finished subtask 'api-extractor' after 0.56 s

这种设计使我们能够定义一个 PR 分支策略，要求每次 PR 变更集包含 .api.md 文件扩展名时都需要项目利益相关者的批准。琐碎的批准可能令人讨厌，因此 API 报告文件的设计使得只有在发生重大合同更改时才会出现差异。

我们认为哪些是重大更改？从审阅者的角度来看

我们关心函数签名的更改，但我们不想被函数主体（即每一行代码）打扰。
我们想知道导出声明的更改（例如，示例项目中的 Log 和 ILogHandler），但不关心未导出声明（例如，DefaultLogHandler）或私有类成员。
我们关心人们是否编写了文档（例如，“// (undocumented)”警告的存在），但我们不需要知道每次句子更改时都进行通知。
我们关心项目的发布状态（@internal、@alpha、@beta 或 @public），而忽略大多数其他文档注释标签。
通常，我们确实希望监控 @internal 定义，因为它们会影响第一方消费者（但在某些情况下，可以通过 @preapproved 标签来抑制此类监控）。

在这样一个易于审阅的报告中拥有此摘要非常强大。为项目启用 API Extractor 通常是一个发人深省的时刻。（“那个在里面做什么？！这些名称非常令人困惑！为什么没有人写文档？！”）尽管人们每天都在使用项目的源文件，但在没有一种可视化它的方法的情况下，很容易错过全局视角。