什么是 TypeScript 的 module augmentation

Module Augmentation（模块扩展）在 TypeScript 中是一个非常有用的特性，特别是当我们使用与第三方库进行集成或者对现有库进行扩展的时候。模块扩展允许开发人员在 TypeScript 中向已经声明的模块添加新的属性、方法或者增强其类型定义。这是一种非常灵活的方式，可以在不修改原始库源码的前提下增强和定制库的功能。

module augmentation 的使用场合有很多种，常见的包括：

1. 为第三方库添加扩展功能；
2. 向第三方库添加自定义类型；
3. 扩展库的接口或类，以满足特定需求；
4. 用来修正打包库中存在的类型问题；
5. 与第三方库或内部库进行深度集成。

下面是一个简单的例子，通过 module augmentation 向一个已经存在的库添加新的功能。假设我们正在使用一个第三方库 lodash，并且我们希望向其添加一个自定义的函数 multiply：

import _ from 'lodash';

// 使用 module augmentation
declare module 'lodash' {
  interface LoDashStatic {
    multiply: (a: number, b: number) => number;
  }
}

// 实现我们自己的 multiply 函数并将其集成到 lodash 中
_.multiply = function(a: number, b: number): number {
  return a * b;
};

// 现在我们可以使用 lodash 的 multiply 函数了
console.log(_.multiply(2, 3)); // 输出 6

在这个例子中，我们首先导入了 lodash 库，然后使用 declare module 语法声明我们要扩展的模块。接着，我们在模块的静态接口 LoDashStatic 中添加了一个 multiply 函数。最后，我们实现了这个函数并将其添加到 _（lodash 的实例）对象中。这样，我们就完成了对 lodash 的扩展。

module augmentation 在 Angular 项目中也非常有用。假设我们正在创建一个 Angular 应用，并想扩展 Router 对象以支持额外的路由信息。通常，Angular 的 Router 对象包含基本的路由配置和导航功能。但我们可能需要在其中添加一些自定义的属性或方法来增强其功能。

以下是一个应用 module augmentation 扩展 Angular 的例子：

首先，安装 Angular 和 RxJS：

ng new my-angular-app
cd my-angular-app
npm install rxjs

接下来，在 Angular 项目中为 Router 添加扩展。假设我们想向 Router 添加一个名为 getCustomRouteData 的新方法，该方法返回路由的自定义数据。

首先，我们创建一个自定义模块文件夹，并在其中定义扩展：

文件路径：src/app/custom-router-augmentation.ts

import { Router } from '@angular/router';

// 定义扩展模块
declare module '@angular/router' {
  interface Router {
    getCustomRouteData: (route: string) => any;
  }
}

// 实现自定义扩展方法
Router.prototype.getCustomRouteData = function(route: string): any {
  // 这里可以自定义返回特定路由的额外数据
  const customData = {
    'home': { title: 'Home Page', description: 'This is the home page' },
    'about': { title: 'About Us', description: 'Learn more about us' }
  };
  return customData[route];
};

在扩展应用到项目中时，你需要确保这个扩展模块被导入到项目的入口文件。如下是确保扩展文件被 Angular 的根模块引入：

文件路径：src/app/app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule, Router } from '@angular/router';

import { AppComponent } from './app.component';
import './custom-router-augmentation'; // 引入自定义扩展

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    RouterModule.forRoot([
      { path: 'home', component: HomeComponent },
      { path: 'about', component: AboutComponent }
    ])
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {
  constructor(router: Router) {
    console.log(router.getCustomRouteData('home'));  // 输出：{ title: 'Home Page', description: 'This is the home page' }
    console.log(router.getCustomRouteData('about')); // 输出：{ title: 'About Us', description: 'Learn more about us' }
  }
}

这个例子展示了如何使用 module augmentation 向 Angular 的 Router 对象添加自定义功能。这种方法不仅可以用于 Router，对 Angular 的其他服务和组件同样适用。

再来看另一个更复杂的例子，假如我们在项目中使用了 RxJS 来处理异步操作，而你现在需要扩展某些 RxJS 操作符以增加一些自定义的功能，比如日志记录等。你可以方便地通过 module augmentation 实现这一需求。

首先安装 RxJS：

npm install rxjs

然后我们来实现一个自定义的 RxJS 操作符 log，它会在每次流通过的时候打印日志：

文件路径：src/app/rxjs-augmentation.ts

import { Observable } from 'rxjs';

// 定义扩展模块
declare module 'rxjs/internal/Observable' {
  interface Observable<T> {
    log: () => Observable<T>;
  }
}

// 实现自定义操作符
Observable.prototype.log = function() {
  return new Observable(subscriber => {
    const subscription = this.subscribe(
      value => {
        console.log('Log value:', value);
        subscriber.next(value);
      },
      err => subscriber.error(err),
      () => subscriber.complete()
    );

    return () => subscription.unsubscribe();
  });
};

通过这种方式，我们可以在 RxJS 的 Observable 上增加一个 log 方法。在项目的入口文件或者需要用到这个方法的地方引入该扩展：

文件路径：src/app/app.component.ts

import { Component } from '@angular/core';
import { of } from 'rxjs';
import './rxjs-augmentation'; // 引入自定义扩展

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my-angular-app';

  constructor() {
    of(1, 2, 3).log().subscribe(value => {
      console.log('Received value:', value);
    });
  }
}

当你运行这个 Angular 应用时，你会看到控制台输出如下：

Log value: 1
Received value: 1
Log value: 2
Received value: 2
Log value: 3
Received value: 3

这个例子展示了如何通过 module augmentation 将自定义的 log 操作符添加到 RxJS 的 Observable 中，从而方便地对数据流进行日志记录和调试。