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 版本控制

本主题提供有关 AWS 云开发工具包 (AWS CDK) 如何处理版本控制的参考信息。

版本号由三个数字版本部分组成：major.minor.patch，大致遵循语义版本控制原则，但也存在 AWS Construct Library semantic versioning clarifications 中所述的一些例外情况。这意味着，对于我们认为稳定的 API 的重大更改仅限于主要版本。

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

AWS CDK 工具包兼容性

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

每个版本的 AWS 构造库也可能与早于 AWS 构造库发布时最新版本的 AWS CDK 工具包版本协同工作。但是，这并不能保证。兼容性取决于 AWS 构造库的云程序集架构版本。AWS CDK 框架在合成过程中生成云程序集，然后 AWS CDK 工具包将其用于部署。定义云程序集格式的架构经过严格指定且受版本控制。因此，较旧版本的 AWS CDK 工具包需要支持 AWS 构造库的云程序集架构版本，它们才能兼容。

当 AWS 构造库所需的云程序集版本与 AWS CDK 工具包支持的版本不兼容时，您会收到如下错误消息：

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 工具包更新到与所需云程序集版本兼容的版本，或更新到最新的可用版本。通常不建议使用替代方案（即降级应用程序使用的 AWS 构造库模块）。

注意

有关哪些版本可以协同工作的更多信息，请参阅 aws-cdk-cli GitHub 存储库中的 compatibility table。

AWS 构造库版本控制

AWS 构造库中的模块从概念发展到成熟的 API 经历了各种不同阶段。在 AWS CDK 的后续版本中，不同的阶段提供不同程度的 API 稳定性。

除了下一主题中记录的注意事项适用的场景外，主 AWS 构造库 (aws-cdk-lib) 中的 API 是稳定的，并且该库大致遵循语义版本控制原则。该库包含所有 AWS 服务的 AWS CloudFormation (L1) 构造，这些构造是从 CloudFormation 资源提供程序架构自动生成的，有时可能包含向后不兼容的更新。https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/resource-type-schemas.html它还包括更高级别的（L2 和 L3）构造和核心 CDK 类（如 App 和 Stack），它们都是稳定的。在 CDK 的下一个主要版本发布之前，不会从此程序包中移除 API（即便其可能已被弃用）。当需要对稳定的 API 进行重大更改时，将会添加一个全新的 API。

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

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

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

虽然 AWS 构造库广泛遵循语义版本控制原则，但我们的实现有一些重要的特殊注意事项。一般而言，AWS 构造库对 API 使用者保持稳定性，但有时会给构造作者增加额外负担，以实现框架的必要演进。

  • 影响安全性的变更

    为了满足我们的安全标准，我们可能需要以向后不兼容的方式更改 API 或者完全移除它们。这样可以防止使用受影响的 API 并强制更新实现。

  • 特征通过意图进行描述

    我们的目标是尽量减少意外变更，但会优先考虑意图而非实现稳定性。AWS 构造库不保证构造始终会合成到完全相同的 CloudFormation 模板或使用完全相同的资源集。这尤其适用于更高级别的构造，其中相同目标通常可以通过不同的方式实现。

  • 实现接口和抽象类

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

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

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

  • 特定语言绑定

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

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

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

语言绑定稳定性

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

语言 稳定性

TypeScript

稳定

JavaScript

稳定

Python

稳定

Java

稳定

C#/.NET

稳定

Go（转到）

稳定