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

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

配置 CDK 工具包编程操作

AWS CDK 工具包库为应用程序生命周期操作（例如合成、部署和堆栈管理）提供编程接口。本指南说明如何在代码中使用每个操作。

使用 synth 生成云程序集

synth 操作会根据您的云程序集源生成云程序集。有关合成的更多信息，请参阅配置和执行 CDK 堆栈合成。云程序集包含以下来自 CDK 应用程序的部署构件：

下面介绍了如何使用 synth 操作创建云程序集：

// Create a toolkit instance
const toolkit = new Toolkit();

// Create a cloud assembly source from a TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");

// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);

// Use the cloud assembly for operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
await toolkit.diff(cloudAssembly);

// Query information from the cloud assembly
const template = cloudAssembly.getStack("my-stack").template;

使用 list 查看堆栈信息

list 操作会检索 CDK 应用程序中堆栈的相关信息，包括其依赖项和当前状态。使用此操作可在部署前检查基础设施或生成报告。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Get information about specific stacks
const stackDetails = await toolkit.list(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"], // Only include stacks matching this pattern
  }
});

// Process the returned stack information
for (const stack of stackDetails) {
  console.log(`Stack: ${stack.id}, Dependencies: ${stack.dependencies}`);
}

使用 deploy 预置基础设施

deploy 操作使用合成期间生成的云程序集在 AWS 中预置或更新您的基础设施。有关部署的介绍，请参阅部署 AWS CDK 应用程序。您可以控制堆栈选择、参数值和回滚行为等部署选项。

// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

部署操作支持不同的部署方法以适应各种工作流。对于大多数场景，尤其是在生产环境中，我们建议使用默认部署方法，其使用 CloudFormation 更改集。对于迭代速度很重要的开发环境，您可以使用热交换等替代方法。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Deploy using default deployment method (recommended for production)
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

// For development environments only: Deploy with hotswap for faster iterations
// Note: We recommend using default deployment methods for production environments
await toolkit.deploy(cloudAssemblySource, {
  deploymentMethod: { method: "hotswap", fallback: true }, // Faster but introduces drift
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"]
  }
});

使用 refactor 保留已部署的资源

refactor 操作可在您重构 CDK 代码（例如，重命名构造或在堆栈之间移动构造）时保留已部署的资源。如果没有此功能，这些更改将导致 CloudFormation 替换资源，进而可能导致服务中断或数据丢失。

refactor 操作会将当前代码与已部署状态进行比较，从而自动计算映射。它验证您的 CDK 应用程序是否包含与已部署状态完全相同的资源集，只是它们在构造树中的位置不同。如果检测到任何资源添加、删除或修改，则重构操作将被拒绝并显示一条错误消息。

计算映射后，refactor 操作会使用 CloudFormation 的重构 API 来更新资源的逻辑 ID，而无需替换资源本身。如果遇到模糊映射（存在多个可能的映射），您可以提供显式覆盖来解决这些歧义。

// Perform refactoring operation to preserve resources
await toolkit.refactor(cloudAssemblySource);

// With optional overrides to resolve ambiguities
await toolkit.refactor(cloudAssemblySource, {
  overrides: {
    "environments": [
      {
        "account": "123456789012",
        "region": "us-east-2",
        "resources": {
          "StackA.OldName": "StackA.NewName"
        }
      }
    ]
  }
});

使用 rollback 恢复失败的部署

当部署失败且无法自动撤消时，rollback 操作会将堆栈恢复到其最后一个稳定状态。使用此操作可从需要人工干预的失败部署中恢复。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Roll back stacks to their last stable state
await toolkit.rollback(cloudAssemblySource, {
  orphanFailedResources: false, // When true, removes failed resources from CloudFormation management
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["failed-stack"]
  }
});

使用 watch 监控更改

watch 操作会持续监控 CDK 应用程序的本地文件更改，并自动执行部署或热交换。这将创建一个文件监视器，该监视器会一直运行，直到您的代码退出或终止。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Start watching for changes
const watcher = await toolkit.watch(cloudAssemblySource, {
  include: ["lib/**/*.ts"], // Only watch TypeScript files in the lib directory
  exclude: ["**/*.test.ts"], // Ignore test files
  deploymentMethod: { method: "hotswap" }, // This is the default, shown here for clarity
  stacks: {
    strategy: StackSelectionStrategy.ALL // Watch all stacks
  }
});

// Later in your code, you can explicitly stop watching:
// await watcher.dispose();

watch 函数会返回一个 IWatcher 对象，允许您显式控制何时停止监视。当您想要结束监视进程时，请对此对象调用 dispose() 方法。

使用 destroy 移除基础设施

destroy 操作会从 AWS 中移除 CDK 堆栈及其关联资源。当不再需要资源时，可使用此操作清理资源。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Remove specific stacks and their resources
await toolkit.destroy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"], // Only destroy stacks matching this pattern
  }
});