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

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

# AWS CDK 版本控制
<a name="versioning"></a>

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

版本号由三个数字版本部分组成：*major*.*minor*.*patch*，大致遵循[语义版本控制](https://semver.org)原则，但也存在 [AWS Construct Library semantic versioning clarifications](https://docs.aws.amazon.com/cdk/v2/guide/versioning.html#aws-construct-lib-semver) 中所述的一些例外情况。这意味着 APIs 我们认为稳定的重大更改仅限于主要版本。

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

## AWS CDK 工具包兼容性
<a name="cdk-toolkit-versioning"></a>

主 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 存储库*中的[兼容性表](https://github.com/aws/aws-cdk-cli/blob/main/COMPATIBILITY.md)。

## AWS 构造库版本控制
<a name="aws-construct-lib-stability"></a>

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

除了下一个主题中记录的注意事项适用的场景外， APIs 主 AWS 构造库 (`aws-cdk-lib`) 是稳定的，并且该库大致遵循语义版本控制原则。该库包括所有 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。

对于已经包含在中的服务， 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 构造库语义版本控制说明
<a name="aws-construct-lib-semver"></a>

虽然 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`注释。*
+  **仅限语义正确的程序** 

  我们确保正确的程序可以继续使用较新的版本。不涵盖形式上不正确但由于实施细节而恰好起作用的程序。例如，如果您的程序依赖[结构类型规则来传递意想不到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)。

## 语言绑定稳定性
<a name="aws-construct-lib-versioning-binding"></a>

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


| 语言 | 稳定性 | 
| --- | --- | 
|  TypeScript  |  稳定  | 
|  JavaScript  |  稳定  | 
|  Python  |  稳定  | 
|  Java  |  稳定  | 
|  C\$1/.NET  |  稳定  | 
|  Go  |  稳定  |