Angular CLI构建器

2022-07-15 11:04 更新

Angular CLI 构建器(Builder)

很多 Angular CLI 命令都要在你的代码上执行一些复杂的处理,比如风格检查(lint)构建或测试。这些命令会通过一个叫做建筑师(Architect)的内部工具来运行 CLI 构建器,而这些构建器会运用一些第三方工具来完成目标任务。

在 Angular 的版本 8 中,CLI 构建器的 API 是稳定的,想要通过添加或修改命令来自定义 Angular CLI 的开发人员可以使用它。比如,你可以提供一个构建器来执行全新的任务,或者更改一个现有命令所使用的第三方工具。

本文档介绍了 CLI 构建器是如何与工作区配置文件集成的,还展示了如何创建你自己的构建器。

可以在这个 GitHub 仓库中的例子中找到代码。

CLI 构建器

内部建筑师工具会把工作委托给名叫构建器的处理器函数。处理器函数接收两个参数:一组 ​options ​输入(JSON 对象)和一个 ​context​(​BuilderContext ​对象)。

这里对关注点的分离和原理图中是一样的,它也适用于其它要接触(touch)代码的 CLI 命令(比如 ​ng generate​)。

  • 此 ​options ​对象是由本 CLI 的用户提供的,而 ​context ​对象则由 CLI 构建器的 API 提供
  • 除了上下文信息之外,此 ​context ​对象(它是 ​BuilderContext ​的实例)还允许你访问调度方法 ​context.scheduleTarget()​。调度器会用指定的目标配置来执行构建器处理函数。

这个构建器处理函数可以是同步的(返回一个值)或异步的(返回一个 Promise),也可以监视并返回多个值(返回一个 Observable)。最终返回的值全都是 ​BuilderOutput ​类型的。该对象包含一个逻辑字段 ​success ​和一个可以包含错误信息的可选字段 ​error​。

Angular 提供了一些构建器,供 CLI 命令使用,如 ​ng build​ 和 ​ng test​ 等。这些内置 CLI 构建器的默认目标配置可以在工作区配置文件 ​angular.json​ 的 ​architect ​部分找到(并进行自定义)。可以通过创建自己的构建器来扩展和自定义 Angular,你可以使用 ​ng run​ CLI 命令来运行你自己的构建器。

构建器的项目结构

构建器位于一个 ​project ​文件夹中,该文件夹的结构类似于 Angular 工作区,包括位于顶层的全局配置文件,以及位于工作代码所在源文件夹中的更具体的配置。比如,​myBuilder ​文件夹中可能包含如下文件。

文件

用途

src/my-builder.ts

这个构建器定义的主要源码。

src/my-builder.spec.ts

测试的源码。

src/schema.json

构建器输入选项的定义。

builders.json

测试配置。

package.json

依赖包。参阅 https://docs.npmjs.com/files/package.json

tsconfig.json

TypeScript 配置文件

将此构建器发布到 ​npm​。如果你将其发布为 ​@example/my-builder​,请使用以下命令安装它。

npm install @example/my-builder

创建构建器

举个例子,让我们创建一个用来复制文件的构建器。要创建构建器,请使用 CLI 构建器函数 ​createBuilder()​,并返回一个 ​Promise<BuilderOutput>​ 对象。

import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
import { JsonObject } from '@angular-devkit/core';

interface Options extends JsonObject {
  source: string;
  destination: string;
}

export default createBuilder(copyFileBuilder);

async function copyFileBuilder(
  options: Options,
  context: BuilderContext,
): Promise<BuilderOutput> {
}

现在,让我们为它添加一些逻辑。下列代码会从用户选项中获取源文件和目标文件的路径,并且把源文件复制到目标文件(使用 NodeJS 内置函数copyFile()的 Promise 版本)。如果文件操作失败了,它会返回一个带有底层错误信息的 error 对象。

import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
import { JsonObject } from '@angular-devkit/core';
import { promises as fs } from 'fs';

interface Options extends JsonObject {
  source: string;
  destination: string;
}

export default createBuilder(copyFileBuilder);

async function copyFileBuilder(
  options: Options,
  context: BuilderContext,
): Promise<BuilderOutput> {
  try {
    await fs.copyFile(options.source, options.destination);
  } catch (err) {
    return {
      success: false,
      error: err.message,
    };
  }

  return { success: true };
}

处理输出

默认情况下,​copyFile()​ 方法不会往标准输出或标准错误中打印任何信息。如果发生了错误,可能很难理解构建器到底做了什么。可以使用 ​Logger ​API 来记录一些额外的信息,以提供额外的上下文。这样还能让构建器本身可以在一个单独的进程中执行,即使其标准输出和标准错误被停用了也无所谓(就像在 Electron 应用中一样)。

你可以从上下文中检索一个 ​Logger ​实例。

import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
import { JsonObject } from '@angular-devkit/core';
import { promises as fs } from 'fs';

interface Options extends JsonObject {
  source: string;
  destination: string;
}

export default createBuilder(copyFileBuilder);

async function copyFileBuilder(
  options: Options,
  context: BuilderContext,
): Promise<BuilderOutput> {
  try {
    await fs.copyFile(options.source, options.destination);
  } catch (err) {
    context.logger.error('Failed to copy file.');
    return {
      success: false,
      error: err.message,
    };
  }

  return { success: true };
}

进度和状态报告

CLI 构建器 API 包含一些进度报告和状态报告工具,可以为某些函数和接口提供提示信息。

要报告进度,请使用 ​context.reportProgress()​ 方法,它接受一个当前值(value)、一个(可选的)总值(total)和状态(status)字符串作为参数。总值可以是任意数字,比如,如果你知道有多少个文件需要处理,那么总值可能是这些文件的数量,而当前值是已处理过的数量。除非传入了新的字符串,否则这个状态字符串不会改变。

你可以看看 ​tslint ​构建器如何报告进度的例子

在我们的例子中,这种复制操作或者已完成或者正在执行,所以不需要进度报告,但是可以报告状态,以便调用此构建器的父构建器知道发生了什么。可以用 ​context.reportStatus()​ 方法生成一个任意长度的状态字符串。

注意:
无法保证长字符串会完全显示出来,可以裁剪它以适应界面显示。

传入一个空字符串可以移除状态。

import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
import { JsonObject } from '@angular-devkit/core';
import { promises as fs } from 'fs';

interface Options extends JsonObject {
  source: string;
  destination: string;
}

export default createBuilder(copyFileBuilder);

async function copyFileBuilder(
  options: Options,
  context: BuilderContext,
): Promise<BuilderOutput> {
  context.reportStatus(`Copying ${options.source} to ${options.destination}.`);
  try {
    await fs.copyFile(options.source, options.destination);
  } catch (err) {
    context.logger.error('Failed to copy file.');
    return {
      success: false,
      error: err.message,
    };
  }

  context.reportStatus('Done.');
  return { success: true };
}

构建器的输入

你可以通过 CLI 命令间接调用一个构建器,也可以直接用 Angular CLI 的 ​ng run​ 命令来调用它。无论哪种情况,你都必须提供所需的输入,但是可以用特定目标中预配置的值作为其默认值,然后指定一个预定义的、指定的配置进行覆盖,最后在命令行中进一步覆盖这些选项的值。

对输入的验证

你可以在该构建器的相关 JSON 模式中定义构建器都有哪些输入。建筑师工具会把解析后的输入值收集到一个 ​options ​对象中,并在将其传给构建器函数之前先根据这个模式验证它们的类型。(Schematics 库也对用户输入做了同样的验证)。

对于这个范例构建器,你希望 ​options ​的值是带有两个键的 ​JsonObject​:一个是 ​source​,一个是 ​destination​,它们都是字符串。

你可以提供如下模式来对这些值的类型进行验证。

{
  "$schema": "http://json-schema.org/schema",
  "type": "object",
  "properties": {
    "source": {
      "type": "string"
    },
    "destination": {
      "type": "string"
    }
  }
}

这是一个非常简单的例子,但这种模式验证也可以非常强大。欲知详情,参阅 JSON 模式网站

要把构建器的实现与它的模式和名称关联起来,你需要创建一个构建器定义文件,可以在 ​package.json​ 中指向该文件。

创建一个名为 ​builders.json​ 文件,它看起来像这样。

{
  "builders": {
    "copy": {
      "implementation": "./dist/my-builder.js",
      "schema": "./src/schema.json",
      "description": "Copies a file."
    }
  }
}

在 ​package.json​ 文件中,添加一个 ​builders ​键,告诉建筑师工具可以在哪里找到这个构建器定义文件。

{
  "name": "@example/copy-file",
  "version": "1.0.0",
  "description": "Builder for copying files",
  "builders": "builders.json",
  "dependencies": {
    "@angular-devkit/architect": "~0.1200.0",
    "@angular-devkit/core": "^12.0.0"
  }
}

现在,这个构建器的正式名字是 ​@example/copy-file:copy​。第一部分是包名(使用 node 方案进行解析),第二部分是构建器名称(使用 ​builders.json​ 文件进行解析)。

使用某个 ​options ​是非常简单的。在上一节,你就曾用过 ​options.source​ 和 ​options.destination​。

context.reportStatus(`Copying ${options.source} to ${options.destination}.`);
try {
  await fs.copyFile(options.source, options.destination);
} catch (err) {
  context.logger.error('Failed to copy file.');
  return {
    success: false,
    error: err.message,
  };
}

context.reportStatus('Done.');
return { success: true };

目标配置

构建器必须有一个已定义的目标,此目标会把构建器与特定的输入配置和项目关联起来。

目标是在 CLI 配置文件 ​angular.json​ 中定义的。目标用于指定要使用的构建器、默认的选项配置,以及指定的备用配置。建筑师工具使用目标定义来为一次特定的执行解析输入选项。

angular.json​ 文件中为每个项目都有一节配置,每个项目的 ​architect ​部分都会为 CLI 命令(比如 ​build​、​test ​和 ​lint​)配置构建器目标。默认情况下,​build ​命令会运行 ​@angular-devkit/build-angular:browser​ 构建器来执行 ​build ​任务,并传入 ​angular.json​ 中为 ​build ​目标指定的默认选项值。

{
  "myApp": {
    …
    "architect": {
      "build": {
        "builder": "@angular-devkit/build-angular:browser",
        "options": {
          "outputPath": "dist/myApp",
          "index": "src/index.html",
          …
        },
        "configurations": {
          "production": {
            "fileReplacements": [
              {
                "replace": "src/environments/environment.ts",
                "with": "src/environments/environment.prod.ts"
              }
            ],
            "optimization": true,
            "outputHashing": "all",
            …
          }
        }
      },
      …

该命令会给构建器传递 options 节中指定的一组默认选项。如果你传入了 --configuration=production 标志,它就会使用 production 备用配置中指定的值进行覆盖。可以在命令行中单独指定其它选项进行覆盖,还可以为 build 目标添加更多备用配置,以定义其它环境,比如 stage 或 qa

目标字符串

通用的 ​ng run​ CLI 命令将以下格式的目标字符串作为其第一个参数。

project:target[:configuration]

详情

项目(project)

与此目标关联的 Angular CLI 项目的名称。

目标

angular.json 文件 architect 下的指定构建器配置。

配置(configuration)

(可选)用于覆盖指定目标的具体配置名称,如 angular.json 文件中的定义。

如果你的构建器调用另一个构建器,它可能需要读取一个传入的目标字符串。可以使用 ​@angular-devkit/architect​ 中的工具函数 ​targetFromTargetString()​ 把这个字符串解析成一个对象。

调度并运行

建筑师会异步运行构建器。要调用某个构建器,就要在所有配置解析完成之后安排一个要运行的任务。

在调度器返回 ​BuilderRun ​控件对象之前,不会执行该构建器函数。CLI 通常会通过调用 ​context.scheduleTarget()​ 函数来调度任务,然后使用 ​angular.json​ 文件中的目标定义来解析输入选项。

建筑师会接受默认的选项对象来解析指定目标的输入选项,然后覆盖所用配置中的值(如果有的话),然后再从传给 ​context.scheduleTarget()​ 的覆盖对象中覆盖这些值。对于 Angular CLI,覆盖对象是从命令行参数中构建的。

建筑师会根据构建器的模式对生成的选项值进行验证。如果输入有效,建筑师会创建上下文并执行该构建器。

你还可以通过调用 ​context.scheduleBuilder()​ 从另一个构建器或测试中调用某个构建器。你可以直接把 ​options ​对象传给该方法,并且这些选项值会根据这个构建器的模式进行验证,而无需进一步调整。
只有 ​context.scheduleTarget()​ 方法来解析这些配置和并通过 ​angular.json​ 文件进行覆盖。

默认建筑师配置

让我们创建一个简单的 ​angular.json​ 文件,它会把目标配置放到上下文中。

你可以把这个构建器发布到 npm,并使用如下命令来安装它:

npm install @example/copy-file

如果用 ​ng new builder-test​ 创建一个新项目,那么生成的 ​angular.json​ 文件就是这样的,它只有默认的构建器参数。

{
  // …
  "projects": {
    // …
    "builder-test": {
      // …
      "architect": {
        // …
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            // … more options…
            "outputPath": "dist/builder-test",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "src/tsconfig.app.json"
          },
          "configurations": {
            "production": {
              // … more options…
              "optimization": true,
              "aot": true,
              "buildOptimizer": true
            }
          }
        }
      }
    }
  }
  // …
}

添加一个目标

添加一个新的目标,来运行我们的构建器以复制文件。该目标告诉构建器,复制 ​package.json​ 文件。

你需要更新 ​angular.json​ 文件,把这个构建器的目标添加到新项目的 ​architect ​部分。

  • 我们会为项目的 ​architect ​对象添加一个新的目标小节
  • 名为 ​copy-package​ 的目标使用了我们的构建器,它发布到了 ​@example/copy-file​。
  • 这个配置对象为我们定义的两个输入提供了默认值:​source​(你要复制的现有文件)和 ​destination​(你要复制到的路径)
  • 这些配置键都是可选的,但我们先不展开
{
  "projects": {
    "builder-test": {
      "architect": {
        "copy-package": {
          "builder": "@example/copy-file:copy",
          "options": {
            "source": "package.json",
            "destination": "package-copy.json"
          }
        },
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist/builder-test",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "src/tsconfig.app.json"
          },
          "configurations": {
            "production": {
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "optimization": true,
              "aot": true,
              "buildOptimizer": true
            }
          }
        }
      }
    }
  }
}

运行这个构建器

要想使用这个新目标的默认配置运行我们的构建器,请使用以下 CLI 命令。

ng run builder-test:copy-package

这将把 ​package.json​ 文件复制成 ​package-copy.json​。

你可以使用命令行参数来覆盖已配置的默认值。比如,要改用其它 ​destination ​值运行,请使用以下 CLI 命令。

ng run builder-test:copy-package --destination=package-other.json

这将把此文件复制为 ​package-other.json​ 而不再是 ​package-copy.json​。因为我们没有覆盖 source 选项,所以它仍然会从 ​package.json​ 文件复制(提供给该目标的默认值)。

测试一个构建器

对构建器进行集成测试,以便你可以使用建筑师的调度器来创建一个上下文,就像这个例子中一样。

  • 在构建器的源码目录下,你创建了一个新的测试文件 ​my-builder.spec.ts​。该代码创建了 ​JsonSchemaRegistry​(用于模式验证)、​TestingArchitectHost​(对 ​ArchitectHost ​的内存实现)和 ​Architect ​的新实例。
  • 我们紧挨着这个构建器的 ​package.json​ 文件添加了一个 ​builders.json​ 文件,并修改了 ​package.json​ 文件以指向它。

下面是运行此复制文件构建器的测试范例。该测试使用该构建器来复制 ​package.json​ 文件,并验证复制后的文件内容与源文件相同。

import { Architect } from '@angular-devkit/architect';
import { TestingArchitectHost } from '@angular-devkit/architect/testing';
import { schema } from '@angular-devkit/core';
import { promises as fs } from 'fs';

describe('Copy File Builder', () => {
  let architect: Architect;
  let architectHost: TestingArchitectHost;

  beforeEach(async () => {
    const registry = new schema.CoreSchemaRegistry();
    registry.addPostTransform(schema.transforms.addUndefinedDefaults);

    // TestingArchitectHost() takes workspace and current directories.
    // Since we don't use those, both are the same in this case.
    architectHost = new TestingArchitectHost(__dirname, __dirname);
    architect = new Architect(architectHost, registry);

    // This will either take a Node package name, or a path to the directory
    // for the package.json file.
    await architectHost.addBuilderFromPackage('..');
  });

  it('can copy files', async () => {
    // A "run" can have multiple outputs, and contains progress information.
    const run = await architect.scheduleBuilder('@example/copy-file:copy', {
      source: 'package.json',
      destination: 'package-copy.json',
    });

    // The "result" member (of type BuilderOutput) is the next output.
    const output = await run.result;

    // Stop the builder from running. This stops Architect from keeping
    // the builder-associated states in memory, since builders keep waiting
    // to be scheduled.
    await run.stop();

    // Expect that the copied file is the same as its source.
    const sourceContent = await fs.readFile('package.json', 'utf8');
    const destinationContent = await fs.readFile('package-copy.json', 'utf8');
    expect(destinationContent).toBe(sourceContent);
  });
});

在你的仓库中运行这个测试时,需要使用 ts-node 包。你可以把 ​index.spec.ts​ 重命名为 ​index.spec.js​ 来回避它。

监视(watch)模式

建筑师希望构建器运行一次(默认情况下)并返回。这种行为与那些需要监视文件更改的构建器(比如 Webpack)并不完全兼容。建筑师可以支持监视模式,但要注意一些问题。

  • 要在监视模式下使用,构建器处理函数应返回一个 Observable。建筑师会订阅这个 Observable,直到这个 Observable 完成(complete)为止。此外,如果使用相同的参数再次调度这个构建器,建筑师还能复用这个 Observable。
  • 这个构建器应该总是在每次执行后发出一个 ​BuilderOutput ​对象。一旦它被执行,就会进入一个由外部事件触发的监视模式。如果一个事件导致它重启,那么此构建器应该执行 ​context.reportRunning()​ 函数来告诉建筑师再次运行它。如果调度器还计划了另一次运行,就会阻止建筑师停掉这个构建器。

当你的构建器通过调用 ​BuilderRun.stop()​ 来退出监视模式时,建筑师会从构建器的 Observable 中取消订阅,并调用构建器的退出逻辑进行清理。(这种行为也允许停止和清理运行时间过长的构建。)

一般来说,如果你的构建器正在监视一个外部事件,你应该把你的运行分成三个阶段。

阶段

详情

运行

比如 webpack 编译。这会在 webpack 完成并且你的构建器发出 BuilderOutput 对象时结束。

监视

在两次运行之间监视外部事件流。比如,webpack 会监视文件系统是否发生了任何变化。这会在 webpack 重启构建时结束,并调用 context.reportRunning()。这样就会再回到第 1 步。

完成

任务完全完成(比如,webpack 应运行多次),或者构建器停止运行(使用 BuilderRun.stop())。你的退出逻辑被调用了,建筑师也从你的构建器的 Observable 中取消了订阅。

总结

CLI 构建器 API 提供了一种通过构建器执行自定义逻辑,以改变 Angular CLI 行为的新方式。

  • 构建器既可以是同步的,也可以是异步的,它可以只执行一次也可以监视外部事件,还可以调度其它构建器或目标
  • 构建器在 ​angular.json​ 配置文件中指定了选项的默认值,它可以被目标的备用配置覆盖,还可以进一步被命令行标志所覆盖
  • 建议你使用集成测试来测试建筑师的构建器。还可以用单元测试来验证这个构建器的执行逻辑。
  • 如果你的构建器返回一个 Observable,你应该在那个 Observable 的退出逻辑中进行清理


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号