這是 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 來保留您的資源，同時更新其邏輯 IDs。

`cdk refactor` 可讓您：
+ 重新命名建構以更清楚說明程式碼基底，而不會造成資源替換。
+ 在堆疊之間移動資源，以改善組織和分離問題。
+ 重新組織建構階層 （例如在新的 L3 建構下將 AWS 資源分組），同時保留基礎雲端資源。
+ 安全地升級或切換建構程式庫，包括第三方相依性，而不會在版本之間變更邏輯 IDs 時觸發資源替換。

此命令會分析您的變更、顯示將變更位置 （堆疊和邏輯 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。  
您可以指定多個堆疊 IDs，將重構操作集中在這些堆疊上。如果資源正在堆疊之間移動，且未明確包含其中一個堆疊，Refactor 命令會自動在 操作中包含額外的堆疊。  
如果您未提供任何堆疊 IDs，應用程式中的所有堆疊都會考慮進行重構。  
 *類型：*字串  
 *必要*：否

## 選項
<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>`   
還原先前的重構。您必須提供具有資源映射的覆寫檔案。  
這不會完全復原先前的重構操作。若要完全還原重構，您需要將應用程式復原至先前的狀態，然後再次執行重構程序。