Angular 17+ 高级教程 – NgModule

ng g m dialog;
ng g c dialog/dialog --standalone false -m dialog;
ng g c dialog/dialog-public --standalone false -m dialog;
ng g c dialog/dialog-private --standalone false -m dialog;

yarn run ngc -p tsconfig.json

递归执行第二轮 walkProviderTree 函数

递归执行第三轮 walkProviderTree 函数

流程总结：

1. 创建 Root Injector

2. 从 class AppComponent 递归到 class TestModule 收集出 App Standalone Injector 的所以 providers。

   App Definition.dependencies -> Child Definition.dependencies -> TestModule.ɵinj.providers-> TestService

3. 创建 App Standalone Injector 

逻辑总结：

1. 每一个组件 Template 里使用到的其它组件，都会被记入到组件 Definition.dependencies。

   比如：App Definition.dependencies = [ChildComponent]。

2. 组件如果有 import Module，Module 也会被记入到组件 Definition.dependencies。

   比如：Child Definition.dependencies = [TestModule]。

3. Module 如果有 import 其它 Module，它们会被记入到 Module.ɵinj.imports。

4. Module 如果有 providers，它们会被记入到 Module.ɵinj.providers。

5. 从 App Definition.dependencies 出发，递归一直找，可以找到：

   a. 整个项目所有用到的组件

   b. 所有组件 import 的 Module

   c. 所有 Module import 的 Module

   d. 所有 Module 的 providers

揭秘：

1. 为什么 NgModule 需要被 import 后，providers 才能用?

   因为 App Standalone Injector 收集 providers 的递归查找的路线是 Component Definition.dependencies。

   如果 NgModule 没有被 import，它就不会出现在 dependencies 里。

   那查找过程就会找不到，找不到就不会被 provide to App Standalone Injector，也就 inject 不到了。

2. NgModule providers 是给了哪一个 Injector？

   严格来说是 App Standalone Injector。

   App Standalone Injector 的 parent 才是 Root Injector。

   但通常我们不会刻意区分它们俩，所以把它理解为 NgModule providers is provide to Root Injector 也是可以的。

我该使用 NgModule 管理 Provider 吗？

Angular 官方文档

Angular 不推荐我们使用 NgModule 管理 Provider。有好几个原因：

1. NgModule providers 对 Tree Shaking 不友好。

2. NgModule 管理 Provider 和管理组件的逻辑不一致，这很容易造成混淆。

3. providedIn: 'root' 完全可以取代 NgModule Provider，它俩唯一的区别是 NgModule 需要一个 “激活动作” -- import NgModule。

总结：除非你真的需要有一个 "激活" 概念来管理你的 Provider，否组请坚定的使用 providedIn: 'root' 就好。

当 NgModule 遇上 Dynamic Component 和 Dynamic Import (lazyload)

不熟悉 Dynamic Component 的朋友，可以看这篇 Component 组件 の Dynamic Component 动态组件 复习一下。

当 NgModule 遇上 Dynamic Component 和 Dynamic Import 时，会产生一系列的化学反应，我们需要搞清楚它们，不然一不小心就会掉坑了。

ng serve Compilation Error

理论上来讲，在 Compilation 后 NgModule (without providers) 和 Standalone Component 是一样的，所以即便遇上 Dynamic Component 也不应该会出现问题。

但是！我却遇到了 Compilation Error。提交了 Github Issue，不过 Angular Team 一如既往的没有给出任何解释，而我又懒惰翻 ngtsc 源码，所以这里记入一下就好呗。

我们来 reproduction 这个 Compilation Error。

首先，创建 TestModule、Test1 组件、Test2 组件

ng g m test;
ng g c test/test1 --standalone=false -m=test;
ng g c test/test2 --standalone=false -m=test;

在 Test2 Template 使用 Test1 组件

在 TestModule export Test1 和 Test2 组件

在 App 组件使用 createComponent 函数动态创建 Test2 组件。

ng serve 启动项目

竟然报错了😲 (注：这个错误来自 ngtsc 的 typecheck，执行 ng serve 或 ng build 都会报错，但执行 yarn run ngc -p tsconfig.json 则不会，我猜是因为 ngc 跳过了 typecheck)

其实只要 import test2.component 哪怕没有使用里面的 class Test2Component

import './test/test2/test2.component';

它就会报错了。

解决方法也很简单

import test.module，哪怕没有使用里面的 class TestModule

import './test/test.module';

它就不会报错了。

另外，如果 Test2 Template 没有使用 Test1 组件，那完全不会有 Compilation Error 的问题。

从这个解决方案，我们很难猜出它背后的原理，我又实在不想去翻 ngtsc 的源码...

所以大家记起来：每当你要动态创建一个由 NgModule 管理的组件时，你一定要先 import 它的 NgModule，这个 import 指的是 TypeScript import 而不是 @Component.imports 哦。

NgModule providers not provide to Root Injector

依们上一 part 我们观察的源码，NgModule providers 是在创建 App Standalone Injector 之前，

透过递归查找组件 Definition.dependencies 的方式进行收集的。然后，这些 providers 会被放入 App Standalone Injector。

试想想：

假如我有一个动态输出的组件 (Dynamic 组件)，它 import 了带 providers 的 NgModule (TestModule provide TestService)。

由于它是 Dynamic Component，它不会对使用它的组件 (App 组件) 产生 Definition.dependencies。

这就导致在递归查找的过程中，TestModule providers 不会被发现，也不会被收集起来放入 App Standalone Injector。

最终 App 组件将无法注入到 TestService。

我们测试看看：

TestService

import { Injectable } from '@angular/core';

@Injectable()
export class TestService {}

TestModule

import { NgModule } from '@angular/core';
import { TestService } from '../test.service';

@NgModule({
  providers: [TestService],
})
export class TestModule {}

Dynamic 组件

import { Component, inject } from '@angular/core';
import { TestModule } from '../test/test.module';
import { TestService } from '../test.service';

@Component({
  standalone: true,
  imports: [TestModule], // 1. import TestModule
  templateUrl: './dynamic.component.html',
  styleUrl: './dynamic.component.scss',
})
export class DynamicComponent {
  constructor() {
    const testService = inject(TestService, { optional: true }); // 2. 注入 TestService
    console.log('testService', testService);
  }
}

App Template

<button (click)="append()">append</button>
<ng-container #container></ng-container>

App 组件

import { Component, Injector, ViewChild, ViewContainerRef, inject } from '@angular/core';
import { TestService } from './test.service';

@Component({
  selector: 'app-root',
  standalone: true,
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss',
})
export class AppComponent {
  constructor() {
    // 1. 注入 TestService
    const testService = inject(TestService, { optional: true });
    console.log('App 组件尝试注入 TestService', testService);
  }

  @ViewChild('container', { read: ViewContainerRef })
  viewContainerRef!: ViewContainerRef;

  private readonly appNodeInjector = inject(Injector);

  async append() {
    // 2. 动态创建 Dynamic 组件
    console.log('create and append Dynamic 组件');
    const { DynamicComponent } = await import('./dynamic/dynamic.component');
    this.viewContainerRef.createComponent(DynamicComponent);

    setTimeout(() => {
      // 3. 再尝试注入 TestService
      const testService = this.appNodeInjector.get(TestService, null, {
        optional: true,
      });
      console.log('App 组件再一次尝试注入 TestService', testService);
    }, 1000);
  }
}

效果

App 组件始终无法注入到 TestService。

inject 查找图

在创建 Dynamic 组件过程中，递归查找 NgModule providers 再度发生，只是这一次收集到的 providers 是被放入到 Dynamic Standalone Injector 中。

蓝线是 Dynamic 组件 inject TestService 的查找过程，最终在 Dynamic Standalone Injector 找到 TestService。

红线是 App 组件 inject TestService 的查找过程，一直到 NullInjector 都没有找到 TestService，因为它的路线根本就连不到 Dynamic Standalone Injector。

总结：

1. import NgModule 的组件如果不是 Dynamic Component，那 NgModule providers will provide to App Standalone Injector，全世界都可以 inject 到。

2. import NgModule 的组件如果是 Dynamic Component，那 NgModule providers will provide to Dynamic Standalone Injector，只有 under Dynamic 组件才可以 inject 到。

Dynamic Import NgModule

我们的完整需求是：dynamic import and create 一个由 NgModule 管理的组件，并且这个组件内还要注入 NgModule Provider。

创建 DialogModule，Dialog 组件，DialogPublic 组件。

ng g m dialog;
ng g c dialog/dialog --standalone=false -m=dialog;
ng g c dialog/dialog-public --standalone=false -m=dialog;

在 Dialog Template 使用 DialogPublic 组件

我们不需要在 DialogModule export 任何组件，因为我们做的是 Dynamic Component (runtime)，而 export 的目的只是为了让 Angular Langauge Service 做静态分析 (static analysis phase)。

App 组件

import { Component, ViewContainerRef, inject } from '@angular/core';
import './dialog/dialog.module'; // 1. 一定要先 import module，不然 ng serve 会报错！
import { DialogComponent } from './dialog/dialog/dialog.component';

@Component({
  selector: 'app-root',
  standalone: true,
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss',
})
export class AppComponent {
  constructor() {
    const hostViewContainerRef = inject(ViewContainerRef);
    // 2. 动态创建和输出 Dialog 组件
    hostViewContainerRef.createComponent(DialogComponent);
  }
}

提醒：记得一定要 import dialog.module 哦

效果

接着创建 DialogService

ng g s dialog/dialog

去除 providedIn: 'root'

import { Injectable } from '@angular/core';

@Injectable()
export class DialogService {}

把 DialogService 添加 DialogModule providers

@NgModule({
  declarations: [DialogComponent, DialogPublicComponent],
  providers: [DialogService],
})
export class DialogModule {}

在 Dialog 组件 inject DialogService

export class DialogComponent {
  constructor() {
    const dialogService = inject(DialogService, { optional: true });
    console.log('Dialog 组件尝试注入 DialogService 的结构：', dialogService);
  }
}

效果

注入失败了，结果是 null，WHY？

依据我们的认知，DialogModule providers 应该会被 provide to Dialog Standalone Injector，然后 Dialog 组件就可以注入到 DialogService 了。

啊！Dialog 不是 Standalone Component，所以不会创建 Dialog Standalone Injector，而 NgModule providers 是在创建 Dialog Standalone Injector 时加进去的，所以注入会失败。

我们上一 part 的例子是：动态创建一个 Standalone Component，该组件 import 了带有 providers 的 NgModule。

而这一 part 的例子是：动态创建一个 NgModule 内的组件，该 NgModule 带有 providers。

这两个情况是不相同的。

怎么破？首先 import DialogModule

import { DialogModule } from './dialog/dialog.module';

接着 create NgModuleRef

export class AppComponent {
  constructor() {
    const environmentInjector = inject(EnvironmentInjector);
    const moduleRef = createNgModule(DialogModule, environmentInjector);
  }
}

createNgModule 函数的源码在 ng_module_ref.ts

它会返回一个 NgModuleRef，这个 NgModuleRef 类型，我们以前见过的。

在 NodeInjector 文章中，我们有一 part 逛了 Angular bootstrapApplication 源码。

在 internalCreateApplication 函数中，创建完 Platform Injector 后，会创建 EnvironmentNgModuleRefAdapter。

它就是一种 NgModuleRef

而 EnvironmentNgModuleRefAdapter.injector 就是 Root Injector。

好，回忆结束。

class NgModuleRef 的源码在 ng_module_ref.ts

createInjectorWithoutInjectorInstances 函数源码在 create_injector.ts

到这里，我们已经看到核心了。NgModuleRef.injector 是一个 R3Injector，它的 providers 便包括了 DialogModule providers。

我们做个测试，验证一下

export class AppComponent {
  constructor() {
    const environmentInjector = inject(EnvironmentInjector);
    const moduleRef = createNgModule(DialogModule, environmentInjector);
    const dialogService = moduleRef.injector.get(DialogService);
    console.log('get DialogService from moduleRef.injector：', dialogService);
  }
}

效果

接着用 Module Injector 作为 Dynamic Component 的 Environment Injector 即可。

export class AppComponent {
  constructor() {
    const environmentInjector = inject(EnvironmentInjector);
    const moduleRef = createNgModule(DialogModule, environmentInjector);
    const hostViewContainerRef = inject(ViewContainerRef);
    hostViewContainerRef.createComponent(DialogComponent, {
      environmentInjector: moduleRef.injector,
    });
  }
}

效果

注入成功🎉，我们再加上 Dynamic Import 看看

export class AppComponent {
  constructor() {
    const hostViewContainerRef = inject(ViewContainerRef);
    const environmentInjector = inject(EnvironmentInjector);
    Promise.all([
      import('./dialog/dialog.module'),
      import('./dialog/dialog/dialog.component'),
    ]).then(([{ DialogModule }, { DialogComponent }]) => {
      const moduleRef = createNgModule(DialogModule, environmentInjector);
      hostViewContainerRef.createComponent(DialogComponent, {
        environmentInjector: moduleRef.injector,
      });
    });
  }
}

总结

当 NgModule 遇上 Dynamic Component 会产生一些化学反应：

1. 动态创建 NgModule 的组件时，记得要 import '/example.module.ts'，不然 ng serve 会报错。

2. 动态创建一个 Standalone Component，该组件 import 了带有 providers 的 NgModule，

   NgModule providers 将会 provide to Dynamic Standalone Injector 而不是 Root Injector。

3. 动态创建一个 NgModule 内的组件，该 NgModule 带有 providers，

   我们需要 create NgModuleRef，把 NgModuleRef.injector 用于创建 Dynamic Component。

   这样 Dynamic Component 才能 inject 到 NgModule providers。

第二和第三条都和 NgModule providers 有关，所以奉劝大家谨用 NgModule providers。

Bootstrap Root NgModule

如果有一个项目，大部分的组件都使用 NgModule 做管理，只有少数的 Standalone Component，

那我们可能会为了要达到统一规范，硬硬替这些 Standalone Component wrap 上一层 NgModule。

像这样

ng g m test; 
ng g c test --standalone=false -m=test

一般的组件 wrap 一层 NgModule 不会有多大的影响，但是 App 组件可不同了，因为 App 组件是 Root Component 丫。

创建一个 NgModule 的项目。

ng new play-module --standalone=false --ssr=false --routing=false --skip-tests --st
yle=scss

关键是 --standalone=false

Different between NgModule and Standalone Component on bootstrap phase

NgModule 和 Standalone Component 项目在 boostrap 阶段有几个不同之处

下图是 Standalone Component 的 boostrap

下图是 NgModule 的 boostrap

我们稍做对比

bootstrapApplication 我们在 NodeInjector 文章中研究过，它前期的步骤如下：

1. 创建 Platform Injector

2. 创建 EnvironmentNgModuleRefAdapter (NgModuleRef)

   EnvironmentNgModuleRefAdapter.injector 就是 Root Injector

3. 如果 App 是 Standalone Component 那就创建 App Standalone Injector

4. ApplicationRef.bootstrap(AppComponent)

Platform Injector Phase

platformBrowserDynamic、platformCoreDynamic、platformCore 函数都是通过 createPlatformFactory 函数创建出来的，它们的区别只是名字和参数三的 providers。

createPlatformFactory 函数的源码在 platform.ts

createPlatform 相等于 bootstrapApplication 中用到的 createOrReusePlatformInjector

createPlatformInjector 在 bootstrapApplication 中也有用到。

结论：platformBrowserDynamic 等同于 bootstrapApplication 的第一个阶段 -- 创建 Platform Injector。

NgModuleRef Phase

先看 AppModule 里面有什么，用在哪里

bootstrap: [AppComponent] 等同于 bootstrapApplication(AppComponent)

import BrowserModule 是必须的哦，BrowserModule provider 了 BROWSER_MODULE_PROVIDERS

BrowserModule 等同于 bootstrapApplication 中调用的 createProvidersConfig 函数，它们负责提供 BROWSER_MODULE_PROVIDERS。

PlatformRef.bootstrapModule 方法的源码在 platform_ref.ts。

bootstrapModuleFactory

createNgModuleRefWithProviders 函数的源码在 ng_module_ref.ts

NgModuleRef 我们上面研究过，它可以递归找出 AppModule 所有的 providers 用于创建 NgModuleRef.injector。

结论：bootstrapModule 等同于 bootstrapApplication 的第二个阶段 -- 创建 EnvironmentNgModuleRefAdapter。

App Standalone Injector Phase

NgModule 没有这个阶段。

Standalone 阶段负责递归出 App 组件 import 的 NgModule providers 然后创建 App Standalone Injector。

NgModule 在上一个阶段已经做到了这一点，它递归了 AppModule providers 然后创建了 Root Injector (NgModuleRef.injector 和 EnvironmentNgModuleRefAdapter.injector 就是 Root Injector)

Boostrap AppComponent Phase

bootstrapModuleFactory 继续往下

_moduleDoBootstrap 方法

moduleRef._bootstrapComponents 就是 AppModule Definition.boostrap，也就是我们在 @NgModule 声明的 boostrap: [AppComponent]

结论：

bootstrapModuleFactory 上半部分负责创建 NgModuleRef 等同于 bootstrapApplication 的第二个阶段 -- 创建 EnvironmentNgModuleRefAdapter。

下半部分负责执行 ApplicationRef.boostrap 等同于 bootstrapApplication 的第四个阶段 -- ApplicationRef.bootstrap(AppComponent)。

总结

NgModule 替 Angular Learning Curve 贡献了很多坑，尤其是 NgModule 管理 Provider 的部分。

幸好，后来有了 providedIn: 'root' 和 Standalone Component，大家才可以脱离泥沼。

这篇比较深入的讲解了有重大设计缺陷的 NgModule providers 也是想让大家感受一下一个设计缺失可以造成多大的伤害，

还有 Angular Team 如何在这种情况下一点一点的矫正它。