Angular Public API 接口设计

JerryWang_汪子熙 - 2021-11-17 08:55:17

按照 Angular 官方 Github repo的定义，Angular 的 semver、定时发布周期和弃用政策目前适用于这些 npm 包：

@angular/animations@angular/core@angular/common@angular/elements@angular/forms@angular/platform-browser@angular/platform-browser-dynamic@angular/platform-server@angular/upgrade@angular/router@angular/service-worker

此列表中有意省略的一个是 @angular/compiler，它目前被认为是低级 api，可能会进行内部更改。这些更改不会影响使用更高级别 api（命令行界面或通过 @angular/platform-browser-dynamic 进行 JIT 编译）的任何应用程序或库。只有非常具体的用例需要直接访问编译器 API（主要是 IDE、linter 等的工具集成）。

包 @angular/bazel 目前是一个 Angular Labs 项目，不在公共 API 保证范围内。

此外，仅涵盖了@angular/compiler-cli 的命令行使用（不是直接使用 API）。

Angular 团队开发的其他项目，如 angular-cli、Angular Material，将来随着它们的成熟，将包含在这些或类似的保证中。

在支持的软件包中，Angular 提供以下保证：

(1) 通过主入口点（例如@angular/core）和测试入口点（例如@angular/core/testing）导出的符号。这适用于运行时 JavaScript 值和 TypeScript 类型。

(2) 通过全局命名空间 ng 导出的符号（例如 ng.core）

(3) 位于 npm 包的 bundles/ 目录中的包（例如@angular/core/bundles/core.umd.js）

以下并非 Angular public API surface：

(1) 我们包中的任何文件/导入路径，除了 /、/testing 和 /bundles/* 以及其他记录的包入口点。
(2) 可注入类（服务和指令）的构造函数 - 请使用 DI 获取这些类的实例
(3) 任何标记为私有的类成员或符号，或以下划线 (_)、禁止拉丁语 o (ɵ) 和双禁止拉丁语 o (ɵɵ) 为前缀。
(4) 扩展我们的任何类，除非 API 文档中专门记录了对此的支持
(5) Angular 编译器生成的代码的内容和 API 表面（有一个明显的例外：保证从生成的代码导出的 NgModuleFactory 实例的存在和名称）

Angular peer dependencies（例如 TypeScript、Zone.js 或 RxJS）不被视为 Angular API 表面的一部分，但它们包含在我们的 SemVer 政策中。如果更新不会对 Angular 应用程序造成重大更改，我们可能会在次要版本中更新任何这些依赖项的所需版本。导致重大破坏性更改的对等依赖项更新必须推迟到主要的 Angular 版本。

Extending Angular classes

除非在 API 文档中明确说明，否则 Angular 公共 API 中的所有类都是 final 的（不应扩展它们）。

不支持扩展此类最终类，因为受保护的成员和内部实现可能会在主要版本之外发生变化。

Golden files

Angular 在黄金文件中跟踪公共 API 的状态，该文件由一个称为公共 API 防护的工具维护。如果您在受支持的公共包之一中修改公共 API 的任何部分，则 PR 可能无法通过 CI 中的测试并显示一条错误消息，指示您接受黄金文件。

公共 API 守卫提供了一个 Bazel 目标，用于更新给定包的当前状态。如果您以任何方式添加或修改公共 API，您必须使用 yarn 在您选择的终端 shell 中执行 Bazel 目标（推荐使用最新版本的 bash）。

特别申明：本文内容来源网络，版权归原作者所有，如有侵权请立即与我们联系（cy198701067573@163.com），我们将及时处理。

上一篇： SAP Spartacus module 层级结构设计的一种实践

下一篇：使用脚本进行 SAP Spartacus 安装工作