Angular Public API 接口设计

简介: 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

相关文章
|
5月前
|
Web App开发 UED 开发者
谈谈企业级 Angular 应用的二次开发 - 基于 Angular Component 替换的 Extensibility 支持案例介绍
谈谈企业级 Angular 应用的二次开发 - 基于 Angular Component 替换的 Extensibility 支持案例介绍
|
12月前
|
API
Angular 应用里的 public_api.ts 文件的作用
Angular 应用里的 public_api.ts 文件的作用
|
12月前
关于 Angular 应用开发里 Subject 和 BehaviorSubject 的用法一例
关于 Angular 应用开发里 Subject 和 BehaviorSubject 的用法一例
|
12月前
|
设计模式 前端开发 JavaScript
Angular 应用开发中 Injection Token 的使用方法介绍
Angular 应用开发中 Injection Token 的使用方法介绍
|
12月前
|
JavaScript API 开发者
什么是 Angular 的 API Extractor?
什么是 Angular 的 API Extractor?
|
前端开发 API
Angular 中使用 Api 代理
本文使用 angualr 来讲解代理 api 对接的话题。
Angular 中使用 Api 代理
|
资源调度 JavaScript IDE
Angular Public API 接口设计
Angular Public API 接口设计
176 0
Angular Public API 接口设计
Angular 使用 Injector API 人工获取依赖注入的实例
Angular 使用 Injector API 人工获取依赖注入的实例
144 0
Angular 使用 Injector API 人工获取依赖注入的实例
Angular getOrCreateInjectable的实现原理调试
Angular getOrCreateInjectable的实现原理调试
Angular getOrCreateInjectable的实现原理调试