开始使用 TypeScript 创建项目使用本地tsc和 cdk 管理 AWS 构造库模块在中管理依赖关系 TypeScript AWS CDK 中的成语 TypeScript 构建、合成和部署

使用 AWS CDK in TypeScript

TypeScript 是完全支持的客户端语言，被认为是 AWS Cloud Development Kit (AWS CDK) 稳定的。 TypeScript 使用 AWS CDK in 使用熟悉的工具，包括微软的 TypeScript 编译器 (tsc)、Node.js 和 Node Package Manager (npm)。如果你愿意，也可以使用 Yarn，尽管本指南中的示例使用 NPM。构成 AWS 构造库的模块通过 NPM 存储库 npmjs.org 分发。

您可以使用任何编辑器或 IDE。许多 AWS CDK 开发人员使用 V isual Studio Code（或其开源等效物 vsCodium），它具有出色的支持。 TypeScript

开始使用 TypeScript

要使用 AWS CDK，您必须拥有 AWS 账户和凭证，并已安装 Node.js 和 AWS CDK Toolkit。请参阅开始使用 AWS CDK。

您还需要 TypeScript 自身（3.8 或更高版本）。如果您还没有，则可以使用进行安装npm。


npm install -g typescript

注意

如果您遇到权限错误，并且在系统上拥有管理员访问权限，请尝试sudo npm install -g typescript。

随时了解 TypeScript 最新动态npm update -g typescript.

注意

第三方语言弃用：语言版本仅在供应商或社区共享的 EOL（生命周期结束）之前才受支持，如有更改，恕不另行通知。

创建项目

您可以通过在空目录cdk init中调用来创建新 AWS CDK 项目。使用该--language选项并指定typescript：


mkdir my-project
cd my-project
cdk init app --language typescript

创建项目还会安装aws-cdk-lib模块及其依赖关系。

cdk init使用项目文件夹的名称来命名项目的各种元素，包括类、子文件夹和文件。文件夹名称中的连字符将转换为下划线。但是，除此之外，名称应遵循 TypeScript 标识符的形式；例如，名称不应以数字开头或包含空格。

使用本地`tsc`和 `cdk`

在大多数情况下，本指南假设您在全局安装 TypeScript CDK Toolkit (npm install -g typescript aws-cdk)，并且提供的命令示例（例如cdk synth）遵循此假设。这种方法可以很容易地使两个组件保持最新状态，并且由于两者都对向后兼容性采取了严格的方法，因此始终使用最新版本通常风险很小。

有些团队更喜欢在每个项目中指定所有依赖关系，包括 TypeScript 编译器和 CDK Toolkit 等工具。这种做法允许您将这些组件固定到特定版本，并确保团队中的所有开发人员（以及您的 CI/CD 环境）都完全使用这些版本。这消除了可能的变更来源，有助于使构建和部署更加一致和可重复。

CDK 在 TypeScript 项目模板中包含两者的依赖关系 TypeScript 和 CDK Toolkitpackage.json，因此，如果您想使用这种方法，则无需对项目进行任何更改。你所需要做的就是使用稍微不同的命令来构建应用程序和发出cdk命令。

操作	使用全局工具	使用本地工具
初始化项目	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
构建	`tsc`	`npm run build`
运行 CDK 工具包命令	`cdk ...`	`npm run cdk ...` or `npx aws-cdk ...`

npx aws-cdk运行当前项目中本地安装的 CDK Toolkit 版本（如果有），则回退到全局安装（如果有）。如果不存在全局安装，则npx下载 CDK Toolkit 的临时副本并运行该副本。您可以使用@语法指定 CDK 工具包的任意版本：pr npx aws-cdk@2.0 --version in 2.0.0 ts。

提示

设置别名，这样你就可以在安装本地 CDK Toolkit 时使用该cdk命令。

管理 AWS 构造库模块

使用 Node Package Manager (npm) 安装和更新 C AWS onstruct Library 模块以供您的应用程序使用，以及您需要的其他软件包。（npm如果你愿意，你可以yarn改用。） npm还会自动安装这些模块的依赖关系。

大多数 AWS CDK 构造都位于名为 CDK 的主包中aws-cdk-lib，这是由创建的新项目中的默认依赖项。cdk init“实验性” AWS 构造库模块（其中更高级别的构造仍在开发中）被命名为。@aws-cdk/SERVICE-NAME-alpha服务名称带有 a ws- 前缀。如果您不确定某个模块的名称，请在 NPM 上进行搜索。

注意

CDK API 参考还显示了软件包名称。

例如，以下命令安装的实验模块 AWS CodeStar。


npm install @aws-cdk/aws-codestar-alpha

某些服务的构造库支持位于多个命名空间中。例如，此外aws-route53，还有另外三个 Amazon Route 53 命名空间，aws-route53-targetsaws-route53-patterns、和。aws-route53resolver

您的项目的依赖关系在中维护package.json。您可以编辑此文件以将部分或全部依赖项锁定到特定版本，或者允许在特定条件下将其更新到较新的版本。要根据您在以下中指定的规则，将项目的 NPM 依赖项更新到允许的最新版本：package.json


npm update

在中 TypeScript，您可以将模块导入到代码中，其名称与使用 NPM 安装模块时使用的名称相同。在应用程序中导入 AWS CDK 类和 AWS 构造库模块时，我们建议采用以下做法。遵循这些准则将有助于使您的代码与其他 AWS CDK 应用程序保持一致并更易于理解。

请使用 ES6 风格的import指令，不是。require()
通常，从中导入单个类aws-cdk-lib。
```
import { App, Stack } from 'aws-cdk-lib';
```
如果您需要来自的许多类aws-cdk-lib，则可以使用命名空间别名来cdk代替导入各个类。避免两者兼而有之。
```
import * as cdk from 'aws-cdk-lib';
```
通常，导入 AWS 服务结构使用短命名空间别名。
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```

在中管理依赖关系 TypeScript

在 TypeScript CDK 项目中，依赖关系是在项目主目录package.json的文件中指定的。核心 AWS CDK 模块位于名为的单个NPM包中aws-cdk-lib。

当你使用安装软件包时npm install，NPM 会package.json为你记录该软件包。

如果你愿意，你可以用 Yarn 代替 NPM。但是，CDK 不支持 Yarn plug-and-play 模式，这是 Yarn 2 中的默认模式。将以下内容添加到您的项目.yarnrc.yml文件中以关闭此功能。


nodeLinker: node-modules

CDK 应用程序

以下是该cdk init --language typescript命令生成的示例package.json文件：


{
  "name": "my-package",
  "version": "0.1.0",
  "bin": {
    "my-package": "bin/my-package.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "cdk": "cdk"
  },
  "devDependencies": {
    "@types/jest": "^26.0.10",
    "@types/node": "10.17.27",
    "jest": "^26.4.2",
    "ts-jest": "^26.2.0",
    "aws-cdk": "2.16.0",
    "ts-node": "^9.0.0",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "aws-cdk-lib": "2.16.0",
    "constructs": "^10.0.0",
    "source-map-support": "^0.5.16"
  }
}

对于可部署的 CDK 应用程序，aws-cdk-lib必须在的dependencies部分中指定。package.json你可以使用尖号 (^) 版本号说明符来表示你将接受比指定版本更高的版本，前提是它们位于同一个主版本内。

对于实验构造，请为 alpha 构造库模块指定确切版本，这些模块的 API 可能会发生变化。请勿使用 ^ 或 ~，因为这些模块的更高版本可能会带来的 API 更改，从而导致您的应用程序中断。

在的devDependencies部分中指定测试您的应用程序所需的库和工具版本（例如，jest测试框架）package.json。（可选）使用 ^ 指定可接受更高版本的兼容版本。

第三方构造库

如果您正在开发构造库，请使用peerDependencies和devDependencies部分的组合来指定其依赖关系，如以下示例package.json文件所示。


{
  "name": "my-package",
  "version": "0.0.1",
  "peerDependencies": {
    "aws-cdk-lib": "^2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "10.0.0",
    "jsii": "^1.50.0",
    "aws-cdk": "^2.14.0"
  }
}

在中peerDependencies，使用尖号 (^) 指定您的库aws-cdk-lib所使用的最低版本。这样可以最大限度地提高您的库与一系列 CDK 版本的兼容性。为 alpha 构造库模块指定确切版本，这些模块的 API 可能会发生变化。使用peerDependencies可以确保node_modules树中只有一个所有 CDK 库的副本。

在中devDependencies，指定测试所需的工具和库，也可以使用 ^ 表示可以接受更高版本的兼容版本。准确指定（不带 ^ 或 ~）你宣传的库aws-cdk-lib与之兼容的其他 CDK 软件包的最低版本和其他 CDK 软件包。这种做法可确保您的测试针对这些版本运行。这样，如果您无意中使用了仅在新版本中找到的功能，则您的测试可以捕捉到它。

警告

peerDependencies仅由 NPM 7 及更高版本自动安装。如果您使用的是 NPM 6 或更早版本，或者使用的是 Yarn，则必须在中devDependencies包含依赖项的依赖关系。否则，它们将无法安装，并且您将收到有关未解决的对等依赖关系的警告。

安装和更新依赖关系

运行以下命令来安装项目的依赖项。

要更新已安装的模块，可以使用前面的npm install和yarn upgrade命令。任一命令都会将软件包更新node_modules到满足中规则的最新版本package.json。但是，它们不会package.json自行更新，您可能需要这样做来设置新的最低版本。如果您在上托管软件包 GitHub，则可以将 De pendabot 版本更新配置为自动更新。package.json或者，请使用 npm-check-updates。

重要

根据设计，当您安装或更新依赖项时，NPM 和 Yarn 会选择满足中指定要求的每个软件包的最新版本。package.json这些版本总是存在损坏的风险（无论是意外还是故意）。更新项目的依赖关系后，请进行全面测试。

AWS CDK 中的成语 TypeScript

道具

所有 C AWS onstruct Library 类都使用三个参数进行实例化：定义构造的作用域（构造树中的父级）、id 和 props。Argument props 是一组键/值对，构造使用这些键/值对来配置其创建的 AWS 资源。其他类和方法也使用 “属性包” 模式作为参数。

在中 TypeScript，的形状props是使用一个接口定义的，该接口告诉你必填参数和可选参数及其类型。这样的接口是为每种props参数定义的，通常特定于单个构造或方法。例如，Bucket 构造（在aws-cdk-lib/aws-s3 module）指定了一个符合BucketProps接口的props参数。

如果一个属性本身就是一个对象，例如的 WebsiteRedire ct 属性BucketProps，则该对象将拥有自己的接口，在这种情况下 RedirectTarget，其形状必须符合该接口。

如果要子类化一个 C AWS onstruct Library 类（或重写采用类似 props 的参数的方法），则可以从现有接口继承来创建一个新接口来指定代码所需的任何新道具。在调用父类或基方法时，通常可以传递收到的整个 props 参数，因为对象中提供但未在接口中指定的任何属性都将被忽略。

future 版本 AWS CDK 可能会巧合地添加一个新属性，其名称是你用于自己的财产。然后，将您收到的值向上传递继承链可能会导致意外行为。如果你的属性被移除或设置为，那么传递一份你收到的道具的浅层副本会更安全。undefined例如：


super(scope, name, {...props, encryptionKeys: undefined});

或者，请命名您的属性，使其清楚地表明它们属于您的构造。这样，它们就不太可能在 future AWS CDK 版本中与属性发生冲突。如果其中有很多，请使用一个适当命名的对象来存放它们。

缺失值

对象（例如 props）中的缺失值具有undefined中的值。 TypeScript该语言的3.7版本引入了简化处理这些值的运算符，从而更容易指定默认值，并在达到未定义的值时使用 “短路” 链接。有关这些功能的更多信息，请参阅 TypeScript 3.7 版本说明，特别是前两个功能，可选链接和 Nullish Coalescing。

构建、合成和部署

通常，在构建和运行应用程序时，您应该位于项目的根目录中。

Node.js 无法 TypeScript 直接运行；相反，您的应用程序会转换为 JavaScript 使用编 TypeScript译器tsc。然后执行生成的 JavaScript 代码。

每当需要运行您的应用程序时，它都会 AWS CDK 自动执行此操作。但是，手动编译以检查错误和运行测试可能很有用。要手动编译您的 TypeScript 应用程序，请发出npm run build。您也可以发出npm run watch进入监视模式的命令，在这种模式下，每当您保存对源文件所做的更改时， TypeScript编译器都会自动重建您的应用程序。

可以使用以下命令合成 AWS CDK 应用程序中定义的堆栈并单独或一起部署。通常，当你发布它们时，你应该在项目的主目录中。

cdk synth：从应用程序中的一个或多个堆栈中 AWS CDK 合成一个 AWS CloudFormation 模板。
cdk deploy：将您的 AWS CDK 应用程序中的一个或多个堆栈定义的资源部署到。 AWS

您可以在单个命令中指定要合成或部署的多个堆栈的名称。如果您的应用程序只定义了一个堆栈，则无需指定该堆栈。


cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

您也可以使用通配符 *（任意数量的字符）和? （任何单个字符），用于按模式识别堆栈。使用通配符时，请用引号将模式括起来。否则，在将文件传递到 T AWS CDK oolkit 之前，shell 可能会尝试将其扩展为当前目录中的文件名。


cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

提示

在部署堆栈之前，您无需显式合成堆栈；请cdk deploy执行此步骤以确保部署最新的代码。

有关该cdk命令的完整文档，请参阅AWS CDK 工具包（cdk命令）。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

与... 合作 AWS CDK

在 JavaScript