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

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

# `cdk refactor`
<a name="ref-cli-cmd-refactor"></a>

**重要**  
`cdk refactor` 命令目前为预览版，可能会发生变化。  
使用此命令时必须提供 `--unstable=refactor` 选项。

在 AWS 云开发工具包 (AWS CDK) 应用程序中重构代码时，请保留已部署的资源。

当您在 CDK 代码中重命名构造或将其跨堆栈移动时，CloudFormation 通常会将这些构造视为新资源，导致可能引起服务中断或数据丢失的替换。`cdk refactor` 命令会智能地检测这些更改，并与 CloudFormation 的重构 API 配合使用，以便在更新资源的逻辑 ID 时保留资源。

通过使用 `cdk refactor`，您可以：
+ 重命名构造以提高代码库的清晰度，而不会导致资源替换。
+ 在堆栈之间移动资源，以改善问题的组织和分离。
+ 重组构造层次结构（例如，将 AWS 资源分组到新的 L3 构造下），同时保留底层云资源。
+ 安全地升级或切换构造库（包括第三方依赖项），而不会在版本之间的逻辑 ID 更改时触发资源替换。

此命令会分析您的更改，向您显示将更改位置的资源列表（堆栈和逻辑 ID），并处理更新 CloudFormation 资源的复杂过程，同时保持其身份和状态。

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

映射计算完成后，该命令会显示建议的更改，并在用户确认后应用重构。如果检测到歧义（存在多个有效映射），您可以提供一个包含显式映射的覆盖文件来解决这些情况。

有关介绍，请参阅[重构 CDK 代码时保留已部署的资源](refactor.md)。

## 使用量
<a name="ref-cli-cmd-refactor-usage"></a>

```
$ cdk refactor <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-refactor-args"></a><a name="ref-cli-cmd-refactor-args-stack-id"></a>

 **CDK 堆栈 ID**   
应用中要重构的 CDK 堆栈的构造 ID。  
您可以指定多个堆栈 ID，以便将重构操作集中在这些堆栈上。如果资源在堆栈之间移动，并且其中一个堆栈没有明确包含，则重构命令会自动在操作中包含额外的堆栈。  
如果您不提供任何堆栈 ID，则将考虑对应用程序中的所有堆栈进行重构。  
 *类型*：字符串  
 *必需*：否

## 选项
<a name="ref-cli-cmd-refactor-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-refactor-options-dry-run"></a>

 `--dry-run`   
将映射打印到控制台，但不应用该映射。  
此选项对于在实际执行重构之前验证更改非常有用，尤其是在使用复杂的应用程序时。它会在不修改任何资源的情况下，准确地显示将要进行的更改。<a name="ref-cli-cmd-refactor-options-force"></a>

 `--force`   
继续进行重构，但在不提示用户确认。  
在交互式环境中，如果您对更改充满信心，这非常有用。在 CI/CD 管线等非交互式环境中，CDK CLI 会在不提示的情况下自动继续运行，因此不需要此选项。<a name="ref-cli-cmd-refactor-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk refactor` 命令的命令参考信息。<a name="ref-cli-cmd-refactor-options-override-file"></a>

 `--override-file <FILE>`   
当 CDK CLI 无法确定资源的重构解析时，提供替换。此文件包含 JSON 格式的资源映射。以下是示例：  

```
{
    "environments": [
        {
            "account": "123456789012",
            "region": "us-east-2",
            "resources": {
                "StackA.OldName": "StackB.NewName",
                "StackC.Foo": "StackC.Bar"
            }
        }
    ]
}
```<a name="ref-cli-cmd-refactor-options-revert"></a>

 `--revert <FILE>`   
恢复以前的重构。您必须提供包含资源映射的覆盖文件。  
这不会完全撤消以前的重构操作。要完全恢复重构，您需要将应用程序回滚到以前的状态，然后再次运行重构过程。