AWS CDK 版本控制 - AWS 雲端開發套件 (AWS CDK) v2
AWS CDK Toolkit 相容性AWS 建構程式庫版本控制AWS 建構程式庫語意版本控制說明語言繫結穩定性

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS CDK 版本控制

本主題提供 AWS Cloud Development Kit (AWS CDK) 如何處理版本控制的參考資訊。

版本編號由三個數字版本部分組成： major.minor.patch，並廣泛遵循語意版本控制原則，其中包含AWS 建構程式庫語意版本控制說明中所述的一些注意事項。這表示，我們認為穩定的 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 儲存庫中的相容性資料表。

AWS 建構程式庫版本控制

在從概念開發到成熟 API 的過程中， AWS 建構程式庫中的模組會經過各種階段。不同階段在 AWS CDK 的後續版本中提供不同程度的 API 穩定性。

除了下一個主題中記錄的警告適用的情況外，主 AWS 建構程式庫 (aws-cdk-lib) APIs 是穩定的，程式庫大致遵循語意版本控制原則。程式庫包含所有 AWS 服務的 AWS CloudFormation (L1) 建構，這些服務是從 CloudFormation 資源提供者結構描述自動產生，有時可能包含回溯不相容的更新。它還包含更高層級 (L2 和 L3) 建構和核心 CDK 類別，例如 App和 Stack，這些都是穩定的。APIs CDK 的下一個主要版本之前，API 將不會從此套件中移除 （雖然可能已棄用）。當穩定 API 需要重大變更時，將會新增全新的 API。

已納入 之服務開發中的新 APIs Beta<N> 會使用尾碼aws-cdk-lib識別，其中 會從 1 N開始，並隨著新 API 的每次重大變更而遞增。 Beta<N>APIs永遠不會移除，只會棄用，因此您現有的應用程式會持續使用較新版本的 aws-cdk-lib。當 API 視為穩定時，會新增不含Beta<N>尾碼的新 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。

  • 特定語言繫結

    在極少數情況下，語言繫結可包含回溯不相容的變更。這些都是由上游類型變更造成的，這些變更在其他支援的語言中向後相容。允許這些類型的變更，否則會嚴重限制程式庫的揮發性。

    下列清單說明所有已知的執行個體：

    • Golang - 從類型配量變更為任何配量：單一類型的清單會變更為多種類型的清單 (TypeScript 中的聯合類型）。在 中Go，這些會輸入為任何 () 的配量*[]any。由於 Go 的輸入指派規則，從 變更為 *[]string 不是自動轉換。因此，此類型加寬需要變更取用者程式碼。請參閱使用策略的任何配量。

語言繫結穩定性

隨著時間的推移，我們可能會為 AWS CDK 新增對其他程式設計語言的支援。雖然所有語言中描述的 API 都相同，但表達 API 的方式會因語言而異，並且可能會隨著語言支援的發展而變更。因此，語言繫結會被視為實驗性一段時間，直到它們被視為準備好供生產使用為止。

語言 穩定性

TypeScript

穩定

JavaScript

穩定

Python

穩定

Java

穩定

C#/。NET

穩定

Go

穩定