AWS CDK 版本控制 - AWS Cloud Development Kit (AWS CDK) v2
AWS CDK 工具包兼容性AWS 构造库版本控制AWS 构造库语义版本控制说明语言绑定稳定性

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

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

AWS CDK 版本控制

本主题提供有关 C AWS loud Development Kit (AWS CDK) 如何处理版本控制的参考信息。

版本号由三个数字版本部分组成：主版本。 未成年人。 补丁，并广泛遵循语义版本控制原则，并在 Construct Libr ary 语义版本控制说明中AWS 描述了一些注意事项。这意味着 APIs 我们认为稳定的重大更改仅限于主要版本。

次要版本和补丁版本则向后兼容。在具有相同主要版本的先前版本中编写的代码可以升级到相同主要版本内的新版本。它将继续构建和运行，从而产生功能上等同的结果。对于某些高级用例，需要对代码进行细微的更改，如下一主题所述。

AWS CDK 工具包兼容性

主 AWS 构造库 (aws-cdk-lib) 的每个版本都与构造库发布时最新的 AWS CDK Toolkit CLI (aws-cdk-cli@aws-cdk/toolkit-lib) 和 Toolkit Library () 版本兼容。 AWS 它还与任何较新版本的 AWS CDK 工具包兼容。每个版本的 Constru AWS ct Library 都保持这种兼容性，直到库的生命周期终止日期。因此，只要您使用的是受支持的 AWS 构造库版本，那么升级 AWS CDK Toolkit 版本始终是安全的。

每个版本的 AWS 构造库也可能适用于早于 AWS 构造库发布时最新版本的 AWS CDK Toolkit 版本。但是，这并不能保证。兼容性取决于 AWS 构造库的云装配架构版本。 AWS CDK 在合成过程中生成云程序集， AWS CDK 工具包使用它进行部署。定义云程序集格式的架构经过严格指定且受版本控制。因此，旧版本的 AWS CDK Toolkit 需要支持 AWS 构造库的云装配架构版本才能兼容。

当 AWS 构造库所需的云装配版本与 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 构造库模块）。

注意

有关协同工作的版本的确切组合的更多信息，请参阅aws-cdk-cli GitHub 存储库中的兼容性表。

AWS 构造库版本控制

C AWS onstruct Library 中的模块在从概念发展到成熟的 API 时会经历不同的阶段。在后续版本的 AWS CDK 中，不同的阶段提供不同程度的 API 稳定性。

除了下一个主题中记录的注意事项适用的场景外， APIs 主 AWS 构造库 (aws-cdk-lib) 是稳定的，并且该库大致遵循语义版本控制原则。该库包括所有 AWS 服务的 AWS CloudFormation (L1) 结构，这些结构是从CloudFormation 资源提供者架构自动生成的，有时可能包含向后不兼容的更新。它还包括更高级别（L2 和 L3）的构造和核心 CDK 类，例如App和Stack，它们都是稳定的。 APIs 在 CDK 的下一个主要版本发布之前，不会从这个软件包中删除（尽管它们可能会被弃用）。当需要对稳定的 API 进行重大更改时，将添加一个全新的 API。

对于已经包含在中的服务， APIs aws-cdk-lib正在开发的新服务使用Beta<N>后缀进行标识，后缀从 1 N 开始，随着新 API 的每一次重大更改而递增。 Beta<N> APIs 永远不会被移除，只会被弃用，因此您的现有应用程序可以继续使用较新版本的。aws-cdk-lib当认为该 API 稳定时，会添加一个不带 Beta<N> 后缀的新 API。

当 APIs 开始为以前只有 L1 的服务开发更高级别（L2 或 L3）时 APIs， APIs 这些 AWS 服务最初会分发到单独的包中。此类包的名称会带有“Alpha”后缀，其版本与和其兼容的第一个版本的 aws-cdk-lib 相匹配，并带有 alpha 子版本。当模块支持预期用例时， APIs 就会将其添加到aws-cdk-lib。

AWS 构造库语义版本控制说明

虽然 C AWS onstruct 库广泛遵循语义版本控制原则，但我们的实现有一些重要的注意事项。通常， AWS 构造库可以维护 API 使用者的稳定性，但有时会给构造作者增加额外的负担，以实现框架的必要演进。

  • 影响变更的安全性

    为了达到我们的安全标准，我们可能需要以向后不兼容 APIs 的方式进行更改或将其完全删除。这样可以防止使用受影响 APIs 的，并强制更新实现。

  • 功能是按意图描述的

    我们的目标是尽量减少意想不到的变化，但更倾向于意图而不是实现的稳定性。 AWS 构造库不保证构造总是合成到完全相同的 CloudFormation 模板或使用完全相同的资源集。这尤其适用于更高级别的构造，在这些结构中，通常可以通过不同的方式实现相同的目标。

  • 实现接口和抽象类

    AWS 构造库中的接口和抽象类对消费者来说是稳定的，但对实现者来说却不稳定。这意味着你可以放心地依赖接口，比如s3.IBucket提供至少与你开始使用接口或抽象类时（AWS 构造库版本）相同的功能。但是，会定期向接口和抽象类中添加新的（抽象）成员。对于任何实施它们的人来说，这都会带来额外的实施负担，需要在升级时考虑，因为实施还不会实现新成员。严格将对实现者的接口和抽象类的添加视为重大更改会过度限制构造库的可发展性。 AWS 在大多数情况下，实现者应该更喜欢扩展具体的类，比如s3.Bucket.

  • L1 构造、生成的代码和其他 APIs 标记为外部的代码

    AWS 构造库的某些部分由直接来自 AWS 服务的数据源生成。为了使这些内容与现实保持 APIs 一致，生成的代码可能包含向后不兼容的更改。大多数情况下，数据源会进行更新，以正确反映现实情况并纠正错误的表示方式。您的 IDE IntelliSense 将在外部显示 APIs 带有@stability — external注释。

  • 特定语言绑定

    在极少数情况下，语言绑定可能包含向后不兼容的更改。这些问题是由其他支持的语言向后兼容的上游类型更改引起的。允许更改这些类型，否则会严重限制库的可扩展性。

    以下列表描述了所有已知实例：

    • Golang-从类型化切片更改为任何切片：单个类型的列表正在更改为多个类型的列表（中的联合类型 TypeScript）。在中Go，它们被键入为任意 (*[]any) 的片段。由于 Go 的键入分配规则，从更改*[]string 为不是自动转换。因此，这种类型的扩展需要更改消费者代码。有关策略，请参阅使用任何切片。

语言绑定稳定性

随着时间的推移，我们可能会向 AWS CDK 添加对其他编程语言的支持。尽管所有语言中描述的 API 都相同，但 API 的表达方式因语言而异，并且可能会随着语言支持的发展而有所变化。因此，语言绑定会在一段时间内被视为试验性质，直到认为其可以用于生产。

语言 稳定性

TypeScript

稳定

JavaScript

稳定

Python

稳定

Java

稳定

C#/.NET

稳定

Go

稳定