解读 @angular/core 公开 API 全景：基于 Angular 仓库 Public API Goldens 清单的深度技术导览

本文以 Angular 官方仓库中的核心包公开 API 清单 goldens/public-api/core/index.api.md 为主线，系统梳理 @angular/core 对外暴露的全部公共符号——从信号体系、资源异步加载、依赖注入，到组件指令、应用引导与变更检测。读者读完本文后，将能像阅读 API 报告一样快速定位任一核心 API 的签名、状态（@public / @deprecated）与职责边界，并理解这份清单如何通过 API Extractor 与 Bazel 测试守护 Angular 的公共 API 稳定性。

一、这份文档是什么：API Report 与 Public API Golden 机制

goldens/public-api/core/index.api.md 本质上是 API Extractor 自动生成的 API Report 文件（文档头部明确标注 "Do not edit this file. It is a report generated by API Extractor"）。它的作用是：

• 充当公共 API 的"黄金快照"（Golden）：goldens/ 目录下按包组织（如 animations、common、router 等），每个包的公开符号签名都固化在这里；
• 驱动 API 守卫测试：仓库根目录的 goldens/public-api/manage.js 通过 Bazel 查询 kind(js_test, //packages/...) intersect attr("tags", "api_guard", //packages/...) 收集所有 api_guard 测试目标，并提供 accept（接受新基线）与 test（校验当前代码与基线一致）两个命令。也就是说，任何人改动 @angular/core 的公开 API 签名，都必须同步更新这份清单并通过测试，否则构建失败；
• 作为开发者/工具链的权威索引：文档、编译器插件、代码生成器都可以基于它判断哪些符号属于稳定的公开契约。

文档中每个条目带有的 // @public、// @deprecated 注释，正是 API Extractor 对 API 可见性与生命周期的标注，它们是阅读这份清单的第一把钥匙。

二、信号体系：从 signal 到 effect 的响应式核心

@angular/core 的信号 API 是当前（Zone 可选的）响应式模型基石，清单中呈现了完整家族：

2.1 基础三件套：signal / computed / effect

// @public
export function signal<T>(initialValue: T, options?: CreateSignalOptions<T>): WritableSignal<T>;
// @public
export function computed<T>(computation: () => T, options?: CreateComputedOptions<T>): Signal<T>;
// @public
export function effect(effectFn: (onCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): EffectRef;

• WritableSignal<T> 提供 set、update、asReadonly 三个写入/投影方法，底层是 packages/core/primitives/signals/src/signal.ts 中的 createSignal 工厂——它基于 SIGNAL_NODE 原型创建响应式节点，存储 value 与 equal 比较函数，配合 producerAccessed、producerNotifyConsumers 等图算法完成依赖追踪；
• CreateSignalOptions<T> / CreateComputedOptions<T> 均支持 debugName（便于 DevTools 调试）与 equal（自定义相等性判定，默认 defaultEquals）；
• effect 的回调接收 EffectCleanupRegisterFn（注册清理函数），CreateEffectOptions 支持 injector、manualCleanup、debugName，其中的 allowSignalWrites 已被标记 @deprecated——说明信号写入限制的新模型已经成熟；
• EffectRef 暴露唯一的 destroy() 用于手动销毁副作用。

2.2 派生信号：linkedSignal 与 untracked

// @public
export function linkedSignal<D>(computation: () => D, options?: {...}): WritableSignal<D>;
// @public
export function linkedSignal<S, D>(options: { source: () => S; computation: (source, previous?) => D; ... }): WritableSignal<D>;
// @public
export function untracked<T>(nonReactiveReadsFn: () => T): T;

linkedSignal 提供了"由其他信号派生、又允许被外部写入"的可写信号，previous 参数可拿到上一次的 source 与 value，适合实现"重置式"状态；untracked 则用于在响应式上下文中执行一次不建立依赖关系的读取，避免多余的重算。

2.3 渲染后钩子：afterRender / afterNextRender / afterRenderEffect

// @public
export function afterNextRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
// @public
export function afterNextRender<E, W, M>(spec: { earlyRead?; write?; mixedReadWrite?; read? }, options?): AfterRenderRef;
// @public
export function afterEveryRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
// @public
export function afterRenderEffect(callback: (onCleanup) => void, options?: AfterRenderOptions): AfterRenderRef;

• afterNextRender 只在下一次渲染完成后执行一次，适合操作 DOM 或测量布局；afterEveryRender 则每次渲染后都会执行；
• 带 spec 的重载把回调划分为 earlyRead（最早读取）、write（写 DOM）、mixedReadWrite、read 四个阶段，配合 ɵFirstAvailable 类型保证阶段间数据可用性，这是 Angular 为规避"读写抖动"（layout thrashing）提供的显式阶段模型；
• afterRenderEffect 让副作用在渲染后以信号响应式方式运行；
• AfterRenderOptions 支持 injector 与 manualCleanup，返回值 AfterRenderRef 通过 destroy() 手动注销。

2.4 查询信号：viewChild / viewChildren / contentChild / contentChildren

清单同时保留了传统的 ViewChild / ViewChildren / ContentChild / ContentChildren 装饰器，以及新一代的函数式信号查询：

// @public
export const viewChild: ViewChildFunction;
// @public
export function viewChildren<LocatorT>(locator: ProviderToken<LocatorT> | string, opts?): Signal<ReadonlyArray<LocatorT>>;
// @public
export const contentChild: ContentChildFunction;

函数式查询返回 Signal<T | undefined>，并提供 .required 变体（确保非空，缺失即报错）；ViewChildFunction.required 直接返回 Signal<T>。信号查询与装饰器查询可混合使用，是逐步迁移到 signal-based 风格的官方路径。

2.5 信号化输入输出：input / output / model

// @public
export const input: InputFunction;        // input<T>(), input(initialValue, opts), input.required<T>()
// @public
export function output<T = void>(opts?: OutputOptions): OutputEmitterRef<T>;
// @public
export const model: ModelFunction;        // 双向绑定信号

• InputFunction 的重载覆盖了"无初值可空"、"带初值"、"带 transform"（InputOptionsWithTransform）等场景，InputOptions 支持 alias、debugName、transform；
• input 返回的 InputSignal / InputSignalWithTransform 本质是 Signal<T> 的子类型（文档可见其品牌属性 [SIGNAL]、[ɵINPUT_SIGNAL_BRAND_READ_TYPE]）；
• ModelSignal<T> 同时实现 WritableSignal<T>、InputSignal<T>、OutputRef<T>，一个符号集齐"可读、可写、可对外发射"三种能力，配合 model.required<T>() 使用；
• 传统的 Input / Output 装饰器依旧保留（InputDecorator、OutputDecorator，Output 仅 alias 一个配置项），OutputEmitterRef 提供 emit 与 subscribe，其订阅返回 OutputRefSubscription（含 unsubscribe）。

三、异步与资源加载：resource、debounced 与 onIdle

这是清单中信息量最大的领域之一，反映了 Angular 将异步数据获取纳入响应式信号体系的最新设计：

3.1 resource 与 ResourceRef

// @public
export function resource<T, R>(options: ResourceOptions<T, R> & { defaultValue: NoInfer<T> }): ResourceRef<T>;
// @public
export function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined>;

• Resource<T> 暴露 value、error、isLoading、status、snapshot 五个只读信号，status 取值枚举为 'idle' | 'error' | 'loading' | 'reloading' | 'resolved' | 'local'（ResourceStatus 类型）；
• ResourceOptions 是 PromiseResourceOptions（loader: ResourceLoader<T,R>）与 StreamingResourceOptions（stream: ResourceStreamingLoader<T,R>）的联合，二者互斥（loader?: never / stream?: never）；
• ResourceLoaderParams<R> 提供 abortSignal（销毁或请求变更时自动取消在途加载）、params、previous；源码 packages/core/src/resource/resource.ts 的注释明确说明：resource 面向读操作，加载基于 AbortSignal 取消，且其实现依赖 PendingTasks、DestroyRef、TransferState 与 linkedSignal 协同；
• ResourceRef 额外提供 set / update / reload / asReadonly / destroy，reload(): boolean 用于手动刷新；
• 派生辅助：debounced(source, wait, options) 对资源做防抖，wait 可为毫秒数或函数 (value, lastValue) => ...（DebounceTimer<T>）；resourceFromSnapshots(source) 从既有资源的 snapshot 派生出新资源，实现资源链式传递；
• 错误模型：ResourceDependencyError（携带 dependency 字段）用于资源间依赖异常，ResourceParamsStatus.IDLE / LOADING 描述参数计算状态。

3.2 onIdle 与 IdleService

// @public
export function onIdle(options?: { timeout?: number }): Promise<void>;
// @public
export interface IdleService {
  requestOnIdle(callback: (deadline?: IdleDeadline) => void, options?: IdleRequestOptions): number;
  cancelOnIdle(id: number): void;
}

onIdle 返回在浏览器空闲时段 resolve 的 Promise，可配 timeout 兜底；IdleService 提供基于 ID 的注册/取消（适合批量注册后统一清理），并可通过 provideIdleServiceWith(useExisting) 注入自定义实现。它们常被用于在空闲时执行非关键的初始化或上报任务。

3.3 injectAsync 与预取

// @public
export function injectAsync<T>(loader: () => Promise<ProviderToken<T>>, options?: InjectAsyncOptions): () => Promise<T>;
// @public
export interface InjectAsyncOptions { prefetch?: PrefetchTrigger; }
// @public
export type PrefetchTrigger = () => Promise<void>;

injectAsync 支持"先注册后异步解析"的注入方式，prefetch 允许在真正取值前提前触发加载（如 injectAsync 配合模块级预取以摊平加载延迟）。

四、依赖注入体系

4.1 inject 与 Injector

// @public
export function inject<T>(token: ProviderToken<T>): T;
// @public
export function inject<T>(token: ProviderToken<T>, options: InjectOptions): T | null;
// @public
export function inject(token: HostAttributeToken): string;
// @public
export abstract class Injector {
  static create(options: { providers: Array<Provider | StaticProvider>; parent?: Injector; name?: string }): DestroyableInjector;
  static NULL: Injector;
  static THROW_IF_NOT_FOUND: {};
}

• inject 的重载覆盖常规、可选、宿主属性（HostAttributeToken）三种场景，InjectOptions 支持 host / optional / self / skipSelf 四个可见性开关；
• Injector.create 的新签名返回 DestroyableInjector（带 destroy()），旧式 create(providers, parent) 已标记 @deprecated；
• 上下文断言：assertInInjectionContext、assertNotInReactiveContext、runInInjectionContext(injector, fn) 用于确保代码运行在正确的注入/响应式上下文。

4.2 令牌与 Provider 全家桶

• InjectionToken<T> 构造函数支持 providedIn: Type<any> | 'root' | 'platform' | 'any' | null 与 factory，清单中的内置令牌包括 APP_ID、APP_BOOTSTRAP_LISTENER、APP_INITIALIZER（已废弃）、DOCUMENT、LOCALE_ID、PLATFORM_ID、CSP_NONCE、DEFAULT_CURRENCY_CODE、ANIMATION_MODULE_TYPE、HOST_TAG_NAME、REQUEST、REQUEST_CONTEXT、RESPONSE_INIT、TRANSLATIONS、TRANSLATIONS_FORMAT、MAX_ANIMATION_TIMEOUT、COMPILER_OPTIONS 等；
• Provider 类型体系完整呈现：ValueProvider / ClassProvider / ConstructorProvider / ExistingProvider / FactoryProvider（以及各自的 *SansProvider 底层形态），全部支持 multi?: boolean；StaticProvider 是上述五类的子集并含 any[]；Provider 则是 TypeProvider | ValueProvider | ... | any[] 的联合；
• EnvironmentProviders 作为品牌类型（ɵbrand: 'EnvironmentProviders'）存在，makeEnvironmentProviders、importProvidersFrom、mergeApplicationConfig 用于组装环境级 Provider。

4.3 生命周期与作用域

• DestroyRef 提供 onDestroy(callback): () => void（返回退订函数）与 destroyed 标志，是组件/服务级清理的标准入口；
• EnvironmentInjector 提供 destroy() 与按令牌解析的重载；
• 装饰器 Inject / Optional / Self / SkipSelf / Host 与 HostAttributeToken（读取宿主元素属性值）并存，forwardRef / resolveForwardRef 处理循环引用。

4.4 类装饰器的新形态

// @public
export const Injectable: InjectableDecorator;
// @public
export const Service: ServiceDecorator;

• Injectable 支持 providedIn: Type<any> | 'root' | 'platform' | 'any' | null；
• 新出现的 Service 装饰器提供 autoProvided（默认 true）与 factory 选项，autoProvided: false 时声明"不自动注入"——从签名推断这是面向新型依赖解析方式（如属性化服务）的入口，属于较新 API。

五、组件、指令、管道与查询

5.1 装饰器与元数据

// @public
export interface Component extends Directive {
  changeDetection?: ChangeDetectionStrategy;
  encapsulation?: ViewEncapsulation;
  imports?: (Type<any> | ReadonlyArray<any>)[];
  standalone?: boolean;
  styles?: string | string[];
  styleUrl?: string;
  styleUrls?: string[];
  template?: string;
  templateUrl?: string;
  viewProviders?: Provider[];
  // @deprecated animations?: any[];
}
// @public
export interface Directive {
  selector?: string; exportAs?: string;
  host?: { [key: string]: string };
  hostDirectives?: (Type<unknown> | { directive; inputs?; outputs? })[];
  inputs?: ({ name; alias?; required?; transform? } | string)[];
  outputs?: string[]; providers?: Provider[]; standalone?: boolean; jit?: true;
}
// @public
export interface Pipe { name: string; pure?: boolean; standalone?: boolean; }

要点：

• Component.inputs 的完整对象语法（name + alias + required + transform）说明装饰器与信号化 input() 共享同一套元数据语义；
• ChangeDetectionStrategy 枚举包含 Default = 1（已废弃）、Eager = 1、OnPush = 0，Eager 是 Default 的新名称；
• ViewEncapsulation 枚举为 Emulated = 0、ExperimentalIsolatedShadowDom = 4、None = 2、ShadowDom = 3；
• HostBinding / HostListener 装饰器对应 hostPropertyName 与 eventName + args；
• PipeTransform 要求实现 transform(value, ...args)。

5.2 生命周期钩子

清单完整列出全部钩子接口：OnChanges（ngOnChanges(changes: SimpleChanges)）、OnInit、DoCheck、OnDestroy、AfterContentInit、AfterContentChecked、AfterViewInit、AfterViewChecked，以及模块引导接口 DoBootstrap（ngDoBootstrap(appRef)）。SimpleChange<T> 携带 previousValue / currentValue / firstChange 与 isFirstChange()，SimpleChanges 类型还针对 signal input 做了键类型推导（通过 ɵINPUT_SIGNAL_BRAND_READ_TYPE 提取值类型）。

5.3 视图与渲染引用

• ViewContainerRef：createComponent（支持 index、injector、environmentInjector、projectableNodes、directives、bindings）、createEmbeddedView、insert / move / detach / remove / clear、get / indexOf / length、element / injector；
• TemplateRef<C>：createEmbeddedView(context, injector?) 与 elementRef；
• ComponentRef<C>：instance、location、injector、hostView、changeDetectorRef、componentType，setInput(name, value) 与 onDestroy(callback)；
• ViewRef extends ChangeDetectorRef，EmbeddedViewRef<C> 增加 context 与 rootNodes；
• QueryList<T> 提供 changes 可观察对象及 first / last / length / toArray / filter / find / map / reduce / some / forEach 等集合操作；
• reflectComponentType 返回 ComponentMirror<C>，可反射读取 selector、inputs（含 transform 与 isSignal）、outputs、isStandalone、ngContentSelectors、type。

5.4 动态创建与渲染器

• createComponent(component, options) 需要显式传入 environmentInjector，这是独立于组件树的命令式创建入口；
• Renderer2 抽象类列出全部渲染原语（createElement / createText / setProperty / setAttribute / listen / setStyle / selectRootElement 等），listen 支持 ListenerOptions（capture / once / passive）；RendererFactory2 负责创建渲染器；RendererStyleFlags2 含 Important = 1、DashCase = 2；
• Sanitizer（sanitize(context, value)）配合 SecurityContext 枚举（NONE=0、HTML=1、STYLE=2、SCRIPT=3、URL=4、RESOURCE_URL=5、ATTRIBUTE_NO_BINDING=6）构成安全清洗模型。

六、应用引导、平台与稳定性

6.1 引导 API

• ApplicationRef：bootstrap<C>(component, options?)（新重载支持 hostElement、directives、bindings）、attachView / detachView、tick()、destroy()、onDestroy、isStable / whenStable、viewCount、components、componentTypes、injector；
• PlatformRef：bootstrapModule / bootstrapModuleFactory（已废弃）、destroy、onDestroy、injector；platformCore 创建核心平台；assertPlatform、getPlatform、createPlatform、createPlatformFactory、destroyPlatform 组成平台生命周期工具集；
• ApplicationConfig 仅含 providers: Array<Provider | EnvironmentProviders>，mergeApplicationConfig(...configs) 按顺序合并多个配置；
• ApplicationInitStatus（done、donePromise）与 ApplicationModule 是内部引导机制的一部分。

6.2 初始化与特性提供函数

清单罗列了一批 provide* 函数，构成了"特性化配置"的标准形态：

函数	签名要点	用途
provideZonelessChangeDetection	(): EnvironmentProviders	关闭 Zone.js，启用基于信号的变更检测
provideZoneChangeDetection	(options?: NgZoneOptions): EnvironmentProviders	保留 Zone，eventCoalescing / runCoalescing 控制合并策略
provideAppInitializer	(initializerFn): EnvironmentProviders	应用初始化（替代已废弃的 APP_INITIALIZER）
provideEnvironmentInitializer	(initializerFn: () => void)	环境级初始化
providePlatformInitializer	(initializerFn: () => void): StaticProvider	平台级初始化
provideCheckNoChangesConfig	({ exhaustive: false }) 或 ({ interval?, exhaustive: true })	配置变更检测校验（无 Zone 模式下的定期校验）
provideBrowserGlobalErrorListeners	(): EnvironmentProviders	注册浏览器全局错误监听
provideStabilityDebugging	(): EnvironmentProviders	稳定性调试辅助
provideNgReflectAttributes	(): EnvironmentProviders	暴露 Ng 反射属性
provideIdleServiceWith	(useExisting: AbstractType<IdleService> | InjectionToken<IdleService>)	自定义空闲服务实现
provideExperimentalWebMcpTools	(tools: WebMcpToolDescriptor[])	向页面注入实验性 Web MCP 工具

NgZone 类提供 run / runGuarded / runOutsideAngular / runTask 及 isStable、onMicrotaskEmpty、onStable、onError 等事件；NgZoneOptions 与 BootstrapOptions（ngZone、事件/运行合并，均已废弃）共同构成 Zone 兼容面。

6.3 稳定性与状态传递

• PendingTasks：add(): () => void 与 run(fn: () => Promise<unknown>): void，用于把异步任务挂到"应用稳定"判定上（whenStable 会等待）；
• TransferState：set / get / hasKey / remove / onSerialize / toJson / isEmpty，配合 makeStateKey<T>(key): StateKey<T> 完成 SSR 状态从服务端到客户端的序列化传递（StateKey 是带品牌标记的字符串类型）；
• enableProdMode()、isDevMode()、enableProfiling()（返回停止函数）控制运行模式；ErrorHandler.handleError 是全局错误处理扩展点；
• VERSION（Version 类：full / major / minor / patch）供运行时读取版本信息。

七、工具函数与类型守卫

• 属性转换：booleanAttribute(value): boolean（HTML 布尔属性语义：存在即 true）、numberAttribute(value, fallbackValue?): number；
• 类型工具：Type<T>、AbstractType<T>、ProviderToken<T>、DefaultExport<T>、ValueEqualityFn<T>、TrackByFunction<T>、Predicate<T>、NgIterable<T>；
• 断言与状态：isSignal、isWritableSignal、isStandalone、isDevMode；
• 测试与调试：DebugElement / DebugNode / DebugEventListener、getDebugNode、asNativeElements、setTestabilityGetter、Testability / TestabilityRegistry、GetTestability（用于 AngularJS 桥接与 E2E 稳定性检测）；
• 变更检测差异器：IterableDiffers / KeyValueDiffers 及其 ChangeRecord/Changes 接口、DefaultIterableDiffer（已废弃）；
• 事件发射：EventEmitter<T>（实现 Subject<T> 与 OutputRef<T>，构造函数 isAsync 控制异步发射）；
• 模式开关：ChangeDetectionStrategy、MissingTranslationStrategy（Error=0、Warning=1、Ignore=2）、NO_ERRORS_SCHEMA / CUSTOM_ELEMENTS_SCHEMA、Attribute 装饰器。

八、已废弃 API 速查（迁移避坑清单）

文档中的 @deprecated 标注直接指向应避免的新代码写法：

• APP_INITIALIZER → 使用 provideAppInitializer；ENVIRONMENT_INITIALIZER → provideEnvironmentInitializer；PLATFORM_INITIALIZER → providePlatformInitializer；
• Compiler / CompilerFactory / NgModuleFactory / getModuleFactory / PlatformRef.bootstrapModuleFactory → 现代 Ivy 已不需要显式编译器，createNgModule 即可；
• BootstrapOptions（含 ngZone 字段）→ 由 provideZonelessChangeDetection / provideZoneChangeDetection 取代；
• ChangeDetectionStrategy.Default → 更名为 Eager（枚举值仍为 1）；
• EffectOptions.allowSignalWrites → 信号写入限制机制已演进；
• Injector.create(providers, parent) 旧签名 → 使用对象签名以支持 DestroyableInjector；
• EnvironmentInjector.runInContext 与字符串令牌式 get → 由新签名取代；
• DefaultIterableDiffer、Component.animations、InjectionToken 的 providedIn: 'any' 组合亦在废弃之列。

九、如何高效使用这份清单

1. 作为 API 检索表：按符号名快速查找签名。文档按字母序排列，搜索 export function、export class、export const 即可定位目标；
2. 判断 API 生命周期：看条目上方注释——@public 表示稳定契约，@deprecated 表示已进入淘汰流程，无 @packageDocumentation 注释说明包级文档缺失（文档结尾有明确标注）；
3. 对照源码加深理解：例如信号实现可深入 packages/core/primitives/signals/src/signal.ts（createSignal 的响应式节点与相等性比较逻辑），资源 API 可深入 packages/core/src/resource/resource.ts（其 JSDoc 明确 resource 仅面向读操作、基于 AbortSignal 取消在途请求，且标注 @publicApi 22.0 表明该 API 的公开版本起点）；
4. 参与 API 治理：改动 @angular/core 公开签名后，通过 goldens/public-api/manage.js 运行 node goldens/public-api/manage.js test 校验、node goldens/public-api/manage.js accept 更新基线；
5. 按模块延伸阅读：同目录下还提供了 errors.api.md（核心错误码）、testing.api.md、rxjs-interop（toObservable / toSignal）、primitives/signals 与 primitives/di 等子包清单，可拼出完整的 core 公共面。

十、结语

goldens/public-api/core/index.api.md 不仅是 CI 守护公共 API 的"黄金基线"，更是一份按字母序组织的、可机器检索的 @angular/core 能力总览。它以 2178 行精炼签名浓缩了信号体系、资源加载、依赖注入、组件渲染、应用引导与平台抽象的完整契约——理解它，就等于拿到了阅读整个 Angular 核心源码与迁移新版本文档的索引地图。后续阅读任何 Angular 新特性时，先回到这份清单确认 API 的状态与签名，再深入对应源码，是最高效的研究路径。