Angular Public API 接口設計

按照 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）。

8