illegalCreed

中文

English

中文

English

Appearance

三大功能：API 报告 / .d.ts rollup / 文档模型 ​

基于 @microsoft/api-extractor 7.58.9 编写

速查 ​

  • 官方原话：API Extractor “produces three different output types”——三类输出相互独立、按需开关
  • API 报告：apiReport.enabled → 产 .api.md（公共 API 快照，进 Git，PR 出 diff 做评审门禁）
  • .d.ts rollup：dtsRollup.enabled → 把多文件 .d.ts 合并成单个发布声明，可按发布标签裁剪
  • API 文档模型：docModel.enabled → 产 .api.json（默认 temp/<unscopedPackageName>.api.json），喂给 api-documenter
  • rollup ≈ Webpack：官方说像 Webpack roll up JS 那样把 TS 声明合并成单个 .d.ts
  • 三者共用同一次分析（同一入口 .d.ts、同一份 TSDoc 解析），产物互不强制

① API 报告（.api.md） ​

把项目从入口导出的全部公共 API 签名抽成一个 Markdown 文件。它用伪代码列出每个导出，并以注释标注可见性 / 文档状态。

md
## API Report File for "my-library"

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

// @public
export class Widget {
    draw(): void;
    // (undocumented)
    id: string;
}

要点：

  • 顶部固定有 API Report File for ... 与 Do not edit this file ——它是机器生成的产物，手改会被下次构建覆盖
  • // @public / // @beta 等标注该成员的发布等级；// (undocumented) 表示缺 TSDoc 文档注释
  • 官方：“The report file should be tracked by Git, so that changes to an API signature will appear as diffs when a pull request (PR) is created.”——提交进仓库后，API 一变 PR 里就出现 diff

它治理的是"源码契约"而非"运行行为"

API 报告把公共 API 序列化成快照，靠 快照 + diff + 人审（或 CODEOWNERS 审批） 在评审期拦截破坏性变更，全程与运行时无关。

② .d.ts rollup（合并声明文件） ​

官方类比：“Similar to how Webpack can 'roll up' all your JavaScript files into a single bundle for distribution, API Extractor can roll up your TypeScript declarations into a single .d.ts file.”

价值：库编译后往往散落多个 .d.ts，rollup 把它们合并成一个发布用声明文件，简化分发，并能按发布标签产出不同裁剪档。

jsonc
"dtsRollup": {
  "enabled": true,
  // 未裁剪基线：含全部（含 @internal）
  "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
  // 只含 @public：对外发布
  "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
}
  • omitTrimmingComments: true → 被裁剪的声明直接删除，而非以注释占位（官方：removes trimmed declarations instead of commenting them）
  • bundledPackages → 列出"应当作本包一部分"的 npm 包，其类型声明会被内联进 rollup（适合把随包发布、不希望使用者单独安装的内部依赖类型打进单一声明）

裁剪等级详见 发布标签与评审工作流。

③ API 文档模型（.api.json） ​

开启 docModel.enabled 后，AE 产出结构化的 API 模型 JSON。官方：默认写到 "<projectFolder>/temp/<unscopedPackageName>.api.json"，可用 docModel.apiJsonFilePath 自定义。

jsonc
"docModel": {
  "enabled": true,
  "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
}
  • .api.json 含每个 API 成员的签名 + TSDoc 文档，是给程序消费的中间数据，不是给人直接读的
  • 由 api-documenter 消费出 Markdown / DocFX；也可用 @microsoft/api-extractor-model 编程读取（反序列化成 ApiPackage / ApiClass 等对象模型）

三者对照 ​

功能开关产物典型场景
API 报告apiReport.enabled.api.md破坏性变更评审门禁
.d.ts rollupdtsRollup.enabled单个 .d.ts发布单一声明、按等级裁剪
文档模型docModel.enabled.api.json喂 api-documenter 出文档

下一步：api-extractor.json 配置 · 发布标签与评审工作流