AWS CDK 应用程序 - AWS Cloud Development Kit (AWS CDK) v2
定义应用程序构造树应用程序生命周期

这是 AWS CDK v2 开发者指南。较旧的 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS CDK 应用程序

AWS Cloud Development Kit (AWS CDK) 应用程序或应用程序是一个或多个 CDK 堆栈的集合。堆栈是一个或多个构造的集合，用于定义 AWS 资源和属性。因此，堆栈和构造的整体分组被称为 CDK 应用程序。

定义应用程序

您可以通过在项目的应用程序文件中定义应用程序实例来创建应用程序。为此，您需要导入并使用App构造库中的 AWS 构造。该App构造不需要任何初始化参数。它是唯一可以用作根的构造。

AWS 构造库中的App和Stack类是唯一的构造。与其他结构相比，它们不会自行配置 AWS 资源。相反，它们用于为您的其他构造提供上下文。所有代表 AWS 资源的构造都必须在Stack构造的范围内直接或间接地定义。 Stack构造是在App构造的范围内定义的。

然后对应用程序进行合成，为您的堆栈创建 AWS CloudFormation 模板。以下是 示例：

TypeScript
const app = new App();
new MyFirstStack(app, 'hello-cdk');
app.synth();
JavaScript
const app = new App();
new MyFirstStack(app, 'hello-cdk');
app.synth();
Python
app = App()
MyFirstStack(app, "hello-cdk")
app.synth()
Java
App app = new App();
new MyFirstStack(app, "hello-cdk");
app.synth();
C#
var app = new App();
new MyFirstStack(app, "hello-cdk");
app.Synth();
Go
app := awscdk.NewApp(nil)
            
MyFirstStack(app, "MyFirstStack", &MyFirstStackProps{
  awscdk.StackProps{
    Env: env(),
  },
})

app.Synth(nil)

单个应用程序中的堆栈可以轻松引用彼此的资源和属性。推 AWS CDK 断堆栈之间的依赖关系，以便可以按正确的顺序部署堆栈。您只需一个cdk deploy命令即可在应用程序中部署任何或全部堆栈。

构造树

构造是使用传递给每个构造的scope参数在其他构造中定义的，该参数以App类为根。通过这种方式， AWS CDK 应用程序定义了称为构造树的构造层次结构。

这棵树的根是你的应用程序，它是该App类的一个实例。在应用程序中，您可以实例化一个或多个堆栈。在堆栈中，你可以实例化构造，这些构造本身可以实例化资源或其他构造，依此类推。

构造总是在另一个构造的范围内明确定义的，这会在构造之间建立关系。几乎总是应传递this（在 Python 中self）作为作用域，表示新构造是当前构造的子构造。预期的模式是你从中派生构造 Construct，然后实例化它在构造函数中使用的构造。

显式传递作用域允许每个构造将自身添加到树中，这种行为完全包含在Construct基类中。它在支持的每种语言中的工作方式都是一样的， AWS CDK 并且不需要额外的自定义。

重要

从技术上讲，除了实例化构造this时之外，还可以传递一些作用域。你可以在树中的任何地方添加构造，甚至可以在同一个应用程序的另一个堆栈中添加构造。例如，你可以编写一个 mixin 风格的函数，将构造添加到作为参数传入的作用域中。这里的实际困难在于，你无法轻易地确保为构造选择的 ID 在其他人的范围内是唯一的。这种做法还会使你的代码更难理解、维护和重用。在不诉诸滥用论点的情况下，找到一种表达意图的方法几乎总是更好的scope。

AWS CDK 使用从树根到每个子构造的路径中所有构造的 ID 来生成所需的唯一 ID。 AWS CloudFormation这种方法意味着构造 ID 只需要在其范围内保持唯一性，而不是像在原生版本中那样在整个堆栈中保持唯一性 AWS CloudFormation。但是，如果您将构造移到不同的作用域，则其生成的堆栈唯一 ID 会发生变化，并且 AWS CloudFormation 不会将其视为同一个资源。

构造树与您在 AWS CDK 代码中定义的构造是分开的。但是，它可以通过任何构造的node属性进行访问，该属性是对树中表示该构造的节点的引用。每个节点都是一个Node实例，其属性提供对树根以及该节点的父作用域和子节点的访问权限。

  1. node.children— 构造的直接子代。

  2. node.id— 构造在其作用域内的标识符。

  3. node.path— 构造的完整路径，包括其所有父项的 ID。

  4. node.root— 构造树（应用程序）的根。

  5. node.scope— 构造的作用域（父级），如果节点是根，则为未定义。

  6. node.scopes— 构造的所有父级，直到根部。

  7. node.uniqueId— 树中此构造的唯一字母数字标识符（默认情况下，由哈希生成）。node.path

构造树定义了一种隐式顺序，在该顺序中，将构造合成最终 AWS CloudFormation 模板中的资源。其中一个资源必须在另一个资源之前创建， AWS CloudFormation 或者 AWS 构造库通常会推断依赖关系。然后，他们会确保按正确的顺序创建资源。

您也可以使用在两个节点之间添加显式依赖关系node.addDependency()。有关更多信息，请参阅 AWS CDK API 参考中的依赖关系。

AWS CDK 提供了一种简单的方法来访问构造树中的每个节点并对每个节点执行操作。有关更多信息，请参阅 方面。

应用程序生命周期

部署 CDK 应用程序时，将进行以下几个阶段。这就是所谓的应用程序生命周期：

AWS CDK 应用程序在其生命周期中会经历以下几个阶段。

  • 构造（或初始化）-您的代码实例化所有已定义的构造，然后将它们链接在一起。在这个阶段，所有的构造（应用程序、堆栈及其子构造）都被实例化并执行构造器链。您的大部分应用程序代码都是在此阶段执行的。

  • 准备 — 所有实现了该prepare方法的构造都将参与最后一轮修改，以设置其最终状态。准备阶段是自动进行的。作为用户，您看不到此阶段的任何反馈。很少需要使用 “准备” 挂钩，通常不建议使用。在此阶段更改构造树时要非常小心，因为操作顺序可能会影响行为。

  • 验证 — 所有实现了该validate方法的构造都可以进行自我验证，以确保它们处于可以正确部署的状态。在此阶段发生的任何验证失败时，您将收到通知。通常，我们建议尽快执行验证（通常是在收到一些输入后立即执行），并尽早抛出异常。尽早执行验证可以提高可靠性，因为堆栈跟踪将更加准确，并确保您的代码可以继续安全地执行。

  • 合成 — 这是 AWS CDK 应用程序执行的最后阶段。它由对的调用触发app.synth()，它遍历构造树并在所有构造上调用该synthesize方法。实现的构造synthesize可以参与合成并向生成的云程序集发射部署工件。这些工件包括 AWS CloudFormation 模板、 AWS Lambda 应用程序包、文件和Docker图像资产以及其他部署工件。 云端程序集描述了此阶段的输出。在大多数情况下，您不需要实现该synthesize方法。

  • 部署-在此阶段， AWS CDK CLI获取综合阶段生成的部署工件云组件，并将其部署到 AWS 环境中。它将资产上传到 Amazon S3 和 Amazon ECR，或者他们需要去的任何地方。然后，它开始 AWS CloudFormation 部署以部署应用程序并创建资源。

AWS CloudFormation 部署阶段开始时，您的 AWS CDK 应用程序已经完成并退出。这具有以下意义：

  • AWS CDK 应用程序无法响应部署期间发生的事件，例如正在创建的资源或整个部署已完成。要在部署阶段运行代码，必须将其作为自定义资源注入到 AWS CloudFormation 模板中。有关向应用程序添加自定义资源的更多信息，请参阅AWS CloudFormation 模块或自定义资源示例。

  • 该 AWS CDK 应用程序可能必须使用在运行时无法知道的值。例如，如果 AWS CDK 应用程序使用自动生成的名称定义了一个 Amazon S3 存储桶，而您检索了 bucket.bucketName (Python:bucket_name) 属性，则该值不是已部署存储桶的名称。相反，你会得到一个Token值。要确定特定值是否可用，请调用 cdk.isUnresolved(value) (Python:is_unresolved)。有关详细信息，请参阅 令牌。

云端程序集

调用app.synth()是告诉从 AWS CDK 应用程序合成云程序集的原因。通常，您不会直接与云程序集交互。这些文件包含将应用程序部署到云环境所需的一切。例如，它包含应用程序中每个堆栈的 AWS CloudFormation 模板。它还包括您在应用程序中引用的任何文件资产或 Docker 镜像的副本。

有关如何格式化云程序集的详细信息，请参阅云装配规范。

要与您的 AWS CDK 应用程序创建的云程序集进行交互，您通常使用 AWS CDK CLI. 但是，任何可以读取云端汇编格式的工具都可用于部署您的应用程序。

运行你的应用程序

CDK CLI 需要知道如何执行您的 AWS CDK 应用程序。如果您使用cdk init命令从模板创建项目，则您的应用程序cdk.json文件将包含app密钥。此键为编写应用程序的语言指定必要的命令。如果您的语言需要编译，则命令行会在运行应用程序之前执行此步骤，因此您不能忘记执行此操作。

TypeScript
{
  "app": "npx ts-node --prefer-ts-exts bin/my-app.ts"
}
JavaScript
{
  "app": "node bin/my-app.js"
}
Python
{
    "app": "python app.py"
}
Java
{
  "app": "mvn -e -q compile exec:java"
}
C#
{
  "app": "dotnet run -p src/MyApp/MyApp.csproj"
}
Go
{
  "app": "go mod download && go run my-app.go"
}

如果您不是使用 CDK 创建项目CLI，或者想要覆盖中给出的命令行cdk.json，则可以在发出cdk命令时使用该--app选项。

$ cdk --app 'executable' cdk-command ...

该命令的可执行部分表示应运行哪个命令来执行 CDK 应用程序。如图所示使用引号，因为此类命令包含空格。cdk 命令是一个类似于synth或的子命令deploy，它告诉 CDK 你想用你的应用程序做CLI什么。接下来是该子命令所需的任何其他选项。

AWS CDK CLI也可以直接与已经合成的云组件进行交互。为此，请传递存储云程序集的目录--app。以下示例列出了存储在下的./my-cloud-assembly云组件中定义的堆栈。

$ cdk --app ./my-cloud-assembly ls