這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS CDK 參考 本節包含 AWS 雲端開發套件 (AWS CDK) 的參考資訊。 ## API 參考 [API 參考](https://docs.aws.amazon.com/cdk/api/v2)包含 AWS 建構程式庫和 AWS 雲端開發套件 (AWS CDK) 提供的其他 APIs 的相關資訊。大多數 AWS 建構程式庫都包含在名為 TypeScript 名稱的單一套件中：`aws-cdk-lib`。實際套件名稱會因語言而異。針對每個支援的程式設計語言提供個別版本的 API 參考。 CDK API 參考會組織成子模組。每個 AWS 服務都有一或多個子模組。 每個子模組都有概觀，其中包含如何使用其 APIs的相關資訊。例如，[S3](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3-readme.html) 概觀示範如何在 Amazon Simple Storage Service (Amazon S3) 儲存貯體上設定預設加密。 # AWS CDK 版本控制 本主題提供 AWS Cloud Development Kit (AWS CDK) 如何處理版本控制的參考資訊。 版本編號由三個數字版本部分組成： *major*.*minor*.*patch*，並廣泛遵循[語意版本控制](https://semver.org)原則，其中包含[AWS 建構程式庫語意版本控制說明](https://docs.aws.amazon.com/cdk/v2/guide/versioning.html#aws-construct-lib-semver)中所述的一些注意事項。這表示我們認為穩定的 APIs 中斷變更僅限於主要版本。 次要和修補程式版本可回溯相容。在相同主要版本的先前版本中寫入的程式碼，可以在相同主要版本中升級至較新的版本。它將繼續建置和執行，產生功能上同等的結果。對於某些進階使用案例，將需要對程式碼進行小幅變更，如下一個主題所述。 ## AWS CDK Toolkit 相容性 主 AWS 建構程式庫 (`aws-cdk-lib`) 的每個版本都與建構程式庫發行時的 AWS CDK Toolkit CLI (`aws-cdk-cli`) 和 Toolkit Library (`@aws-cdk/toolkit-lib`) AWS 版本相容。它也與任何較新版本的 AWS CDK Toolkit 相容。 AWS 建構程式庫的每個版本都會維持此相容性，直到程式庫的*生命週期結束日期*為止。因此，只要您使用支援的 AWS 建構程式庫版本，升級 AWS CDK Toolkit 版本一律是安全的。 每個 AWS 版本的建構程式庫也可能使用比 AWS 建構程式庫發行時最新版本舊的 AWS CDK Toolkit 版本。不過，我們無法保證這一點。相容性取決於 AWS Construct Library 的雲端組件結構描述版本。 AWS CDK 會在合成期間產生雲端組件，而 AWS CDK Toolkit 會使用它來進行部署。定義雲端組件格式的結構描述會嚴格指定和版本化。因此，較舊版本的 AWS CDK Toolkit 需要支援 AWS 建構程式庫的雲端組件結構描述版本，才能相容。 當 AWS Construct Library 所需的雲端組件版本與 AWS CDK Toolkit 支援的版本不相容時，您會收到類似以下的錯誤訊息： ``` Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0. Please upgrade your CLI in order to interact with this app. ``` 若要解決此錯誤，請將 AWS CDK Toolkit 更新至與所需雲端組件版本相容的版本，或更新至最新的可用版本。通常不建議使用替代 （降級應用程式使用的 AWS Construct Library 模組）。 **注意** 如需可搭配使用之版本確切組合的詳細資訊，請參閱 *aws-cdk-cli GitHub 儲存庫*中的[相容性資料表](https://github.com/aws/aws-cdk-cli/blob/main/COMPATIBILITY.md)。 ## AWS 建構程式庫版本控制 在從概念開發到成熟 API 的過程中， AWS 建構程式庫中的模組會經過各種階段。不同階段在 AWS CDK 的後續版本中提供不同程度的 API 穩定性。 除了下一個主題中記錄的警告適用的情況之外，主 AWS 建構程式庫 (`aws-cdk-lib`) APIs 是穩定的，程式庫大致遵循語意版本控制原則。程式庫包含所有 AWS 服務的 AWS CloudFormation (L1) 建構，這些服務會從 [CloudFormation 資源提供者結構描述](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/resource-type-schemas.html)自動產生，有時可能包含回溯不相容的更新。它還包含更高層級 (L2 和 L3) 建構和核心 CDK 類別，例如 `App`和 `Stack`，這些都是穩定的。APIs CDK 的下一個主要版本之前，API 將不會從此套件中移除 （雖然可能已棄用）。當穩定 API 需要重大變更時，將會新增全新的 API。 已納入 之服務開發中的新 APIs `Beta` 會使用尾碼`aws-cdk-lib`識別，其中 會從 1 `N`開始，並隨著新 API 的每次重大變更而遞增。 `Beta`APIs永遠不會移除，只會棄用，因此您現有的應用程式會持續使用較新版本的 `aws-cdk-lib`。當 API 視為穩定時，會新增不含`Beta`尾碼的新 API。 當更高階 (L2 或 L3) APIs 開始針對先前只有 L1 APIs AWS 的服務進行開發時，這些 APIs一開始會分散在不同的套件中。這類套件的名稱具有「Alpha」尾碼，且其版本符合`aws-cdk-lib`其與`alpha`子版本相容的第一個版本。當模組支援預期的使用案例時，其 APIs會新增至 `aws-cdk-lib`。 ## AWS 建構程式庫語意版本控制說明 雖然 AWS Construct Library 廣泛遵循語意版本控制原則，但實作有一些特定的重要注意事項。一般而言， AWS 建構程式庫可維持 API 取用者的穩定性，但有時會增加建構作者的額外負擔，以啟用架構的必要演變。 + **影響安全性的變更** 為了符合我們的安全列，我們可能需要以回溯不相容的方式變更 APIs或將其完全移除。這可防止使用受影響的 APIs，並強制更新實作。 + **特徵由意圖描述** 我們的目標是將非預期的變更降至最低，但將偏好*意圖而非實作穩定性*。 AWS 建構程式庫不保證建構一律合成至完全相同的 CloudFormation 範本，或使用完全相同的資源集。這尤其適用於更高層級的建構，其中通常可以透過不同的方式實現相同的目標。 + **實作界面和抽象類別** AWS Construct Library 中的界面和抽象類別對於**消費者**來說是穩定的，但對於**實作器**而言不是穩定的。這表示您可以安全地依賴 等界面`s3.IBucket`，提供至少與您開始取用界面或抽象類別時相同的功能 (AWS 建構程式庫版本）。不過，新的 （抽象） 成員會定期新增至界面和抽象類別。對於**實作**它們的任何人，這會產生升級時需要考慮的額外實作負擔，因為實作尚未實作新的成員。嚴格地將實作器的介面和抽象類別的新增視為重大變更會過度限制 AWS Construct Library 的揮發性。在大多數情況下，實作器應該偏好擴展具體類別，例如 `s3.Bucket`。 + **L1 建構、產生的程式碼和其他標示為外部APIs ** AWS 建構程式庫的一部分是從直接來自 AWS 服務的資料來源產生。為了讓這些 APIs 與現實保持一致，產生的程式碼可能包含回溯不相容的變更。大多數情況下，資料來源都會更新，以正確反映實際情況並修正不正確的表示。*IDE 的 IntelliSense 會顯示具有`@stability — external`註釋APIs。* + **僅以語意方式更正程式** 我們確保正確的程式可以繼續使用較新的版本。正式不正確但由於實作詳細資訊而運作的程式不會涵蓋在內。例如，如果您的程式依賴 [TypeScript 的結構輸入規則](https://www.typescriptlang.org/docs/handbook/type-compatibility.html)來傳遞非預期的物件類型，或成功合成，但產生無法部署的 CloudFormation 範本，我們可能會引入導致這些程式失敗的變更，而不考慮它們中斷變更。 + **特定語言繫結** 在極少數情況下，語言繫結可包含回溯不相容的變更。這些都是由上游類型變更造成的，這些變更在其他支援的語言中向後相容。允許這些類型的變更，否則會嚴重限制程式庫的揮發性。 下列清單說明所有已知的執行個體： + **Golang - 從類型配量變更為任何配量：**單一類型的清單會變更為多種類型的清單 (TypeScript 中的聯合類型）。在 中`Go`，這些會輸入為任何 () 的配量`*[]any`。由於 Go 的輸入指派規則，從 變更為 `*[]string ` `` 不是自動轉換。因此，此類型加寬需要變更取用者程式碼。請參閱[使用策略的任何配量](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-go.html#go-cdk-idioms)。 ## 語言繫結穩定性 隨著時間的推移，我們可能會為 AWS CDK 新增對其他程式設計語言的支援。雖然所有語言中描述的 API 都相同，但表達 API 的方式會因語言而異，並且可能會隨著語言支援的發展而變更。因此，語言繫結會被視為實驗性一段時間，直到它們被視為準備好供生產使用為止。 | Language | 穩定性 | | --- | --- | | TypeScript | 穩定 | | JavaScript | 穩定 | | Python | 穩定 | | Java | 穩定 | | C\$1/。NET | 穩定 | | Go | 穩定 | # AWS CDK 支援的 Node.js 版本 AWS 雲端開發套件 (AWS CDK) 依賴 Node.js 的功能。這包括核心 CDK 元件，例如 AWS CDK CLI (`aws-cdk-cli`)Projen、 AWS Construct Library (`aws-cdk-lib`)，以及更廣泛的工具，例如 JSII、 和 CDK8s。此頁面記錄與 AWS CDK 相容的 Node.js 執行期版本，協助您維護支援的開發環境。 AWS CDK 旨在維持與主動支援的 Node.js 長期支援 (LTS) 版本的相容性。隨著 Node.js 版本達到end-of-life， AWS CDK 也會逐步淘汰對這些版本的支援，以確保安全性、效能和最新功能的存取。 將 CDK 元件和工具保留在支援的 Node.js 版本上，可確保您收到安全性更新、錯誤修正，以及存取最新的 CDK 功能和改進。 ## Node.js 版本支援時間軸 AWS CDK 支援 Node.js 超過其正式End-of-Life(EOL) 日期的版本，讓您有時間升級環境。此支援會延長 6 個月 （例如，當 Node.js 版本在 4 月達到 EOL 時，支援會持續到 10 月）。以下版本支援時間軸資料表會記錄決定的特定 CDK 支援結束日期。此方法可讓您定義時段來規劃和實作版本升級，同時維持對 CDK 功能和更新的存取。 | Node.js 版本 | 節點 EOL 日期 | CDK 支援狀態 | | --- | --- | --- | | 22.x | 2027-04-30 | 截至 2027 年 10 月為止的支援。 | | 20.x | 2026-04-30 | 截至 2026 年 10 月為止的支援。 | | 18.x | 2025-05-30 | 支援將於 2025-11-30 結束。 | | 16.x | 2023-09-11 | 支援將於 2025-05-30 結束。 | | 14.x | 2023-04-30 | 支援將於 2025-05-30 結束。 | # AWS CDK 影片資源 享受 AWS CDK 團隊成員提供的這些影片。 **注意** 由於 AWS CDK 不斷發展，因此這些影片中呈現的某些程式碼可能無法像錄製影片一樣運作。對於當時處於作用中開發狀態的模組來說尤其如此。自此之後，我們也可能會新增更好的方法來達成相同的結果。如需up-to-date，請參閱本開發人員指南和 [AWS CDK API 參考](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)。 ## 基礎設施*是*具有 AWS CDK 的程式碼 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/ZWCvNFUN-sU?rel=0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/ZWCvNFUN-sU?rel=0) ## 深入了解 AWS 雲端開發套件 (AWS CDK) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/9As_ZIjUGmY?rel=0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/9As_ZIjUGmY?rel=0) ## 為 AWS 建構程式庫做出貢獻 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/LsYlf7ggyrY?rel=0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/LsYlf7ggyrY?rel=0) ## 使用 CDK 管道加快部署速度 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/1ps0Wh19MHQ?rel=0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/1ps0Wh19MHQ?rel=0) ## 如何使用 GitPod 對 AWS CDK 做出貢獻 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/u6XcIgs-Nok?rel=0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/u6XcIgs-Nok?rel=0)