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

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

重构 CDK 代码时保留已部署的资源

借助 C AWS loud Development Kit (AWS CDK) 重构，您可以重构您的 CDK 代码，例如重命名构造、在堆栈之间移动资源以及重组应用程序，同时保留已部署的资源而不是替换它们。此功能可帮助您保持良好的软件工程最佳实践，而不会导致意外的资源替换。

什么是具有资源保留的 CDK 重构？

部署 CDK 应用程序时，会根据资源的逻辑 IDs来 AWS CloudFormation 识别资源。 AWS CDK IDs 根据构造 ID 及其在构造树中的路径生成这些逻辑。如果您更改构造的 ID 或将其移至代码中的其他位置， AWS CloudFormation 通常会将其解释为请求创建新资源并删除旧资源。对于数据库、存储桶或队列等有状态资源，这种替换可能会导致服务中断或数据丢失。

CDK 重构通过以下方式解决此问题：

您可以使用 CDK CLI cdk refactor 命令或 CDK 工具包库的 refactor 操作来执行 CDK 重构。本指南主要讨论 CLI 方法，但基本原则适用于这两种方法。有关使用工具包库的信息，请参阅使用 CDK 工具包库执行编程操作。

CDK 重构的好处

CDK 重构为 CDK 开发者提供了以下好处 AWS ：

CDK CLI cdk refactor 命令的工作原理

首先，部署初始 CDK 应用程序以在 AWS 账户中建立基准资源。重构 CDK 代码（例如，重命名构造或在堆栈之间移动资源）后，使用 cdk refactor 命令开始重构已部署资源的过程。

当您运行重构命令时，CDK CLI 会将当前代码与已部署状态进行比较，从而检测本地更改。它验证您的 CDK 应用程序是否包含与已部署状态完全相同的资源集，只是它们在构造树中的位置不同。然后，CDK CLI 会生成一个重构计划来将旧资源位置映射到新位置。CDK CLI 会向您显示建议的更改，并在您确认后，使用 AWS CloudFormation其重构 API 更新资源的逻辑 IDs 而无需替换它们。

在后台，CDK CLI 通过比较资源的属性和依赖项来确定哪些资源已移动，识别功能等效但在构造树中的路径不同的资源。如果检测到任何资源添加、删除或修改，则重构操作将被拒绝并显示一条错误消息。

重构 CDK 代码时保留资源的示例

在此示例中，我们使用 CDK CLI cdk refactor 命令重构 CDK 代码，同时保留已部署的资源。

我们的示例 CDK 应用程序由包含 S3 存储桶、 CloudFront 分配和 Lambda 函数的单个堆栈组成。构造树的结构如下：

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

下面是我们的应用程序代码示例：

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

现在，假设您想重构此代码来实现以下目的：

重构后，构造树将如下所示：

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

重构后的代码如下：

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

如果没有 CDK 重构，这些更改将 AWS CloudFormation 导致创建新资源并删除旧资源，因为逻辑 IDs 会发生变化：

通过 CDK 重构，CDK CLI 可以检测到这些路径变化，并使用其重构功能 AWS CloudFormation来保留底层资源。运行 cdk refactor 后，CLI 会显示它将进行的更改：

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

输入 y 确认后，CDK CLI 会显示重构操作的进度：

Refactoring...
✅  Stack refactor complete

确认后，CDK CLI 将运行重构操作，保留这两个资源，同时更新其逻辑 IDs 以匹配您的新代码结构。

cdk diff 命令的输出也会显示相同映射，按堆栈进行组织：

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

开始使用 CDK 重构

要开始重构，请完成下面的先决条件：

使用覆盖文件来解决重构中的歧义

CDK CLI 会根据您的代码与已部署资源的比较结果自动计算所有资源映射。大多数情况下，这种自动检测效果很好，但有时 CLI 可能会遇到它自己无法解决的歧义。要为 CDK CLI 提供指导，请使用覆盖文件。

跨多个环境重构堆栈

一个 CDK 应用程序可以包含部署到不同环境（AWS 账户和区域）的多个堆栈。在重构此类应用程序期间，为了保留资源，CDK CLI 会以特定方式处理环境：

这种行为可确保资源保留在其原始 AWS 账户和区域内，这是必要的，因为 CloudFormation 资源无法在账户或区域边界之间实际移动。

例如，如果您的 CDK 应用程序针对开发环境和生产环境都定义了堆栈，则重构操作将在每个环境中独立执行。资源可以在开发环境或生产环境内的堆栈之间移动，但不能从开发环境移动到生产环境，反之亦然。

处理需要替换的资源

某些 CDK 构造依赖于 CloudFormation的资源替换行为作为其设计的一部分。例如，API Gateway 的 Deployment 和 Lambda 的 Version 构造都旨在当资源属性发生变化时创建新资源。

重构时，请勿进行任何会导致资源替换的更改。否则，CDK CLI 可能会检测到并保留这些资源。这意味着需要替换的资源必须与重构操作分开处理。

要正确管理需要替换的资源，请执行以下操作：

这种两步法确保需要替换的资源得到正确处理，同时还能让您从其他资源的 CDK 重构中受益。

一般注意事项和限制

在 CDK 重构期间保留资源时，请记住以下注意事项：

使用管道进行重构 CI/CD

要在 CI/CD 管道中使用重构功能，您需要能够将 CDK CLI 作为管道的一部分运行。以下是将重构集成到工作流程中的 CI/CD 一些重要注意事项。

相关资源

有关 CDK CLI cdk refactor 命令的选项和参数的信息，请参阅 cdk refactor 。

要开始使用 CDK 工具包库的 refactor 操作，请参阅使用 CDK 工具包库执行编程操作。