这是 AWS CDK v2 开发者指南。较旧的 CDK v1 于 2022 年 6 月 1 日进入维护阶段,并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
与 AWS CDK 图书馆合作
导入并使用该 AWS Cloud Development Kit (AWS CDK) 库使用支持的编程语言来定义您的 AWS Cloud 基础架构。
导入 AWS CDK 库
AWS CDK 库通常用其TypeScript软件包名称来表示aws-cdk-lib
。实际的软件包名称因语言而异。以下是如何安装和导入CDK库的示例:
- TypeScript
-
安装 |
npm install aws-cdk-lib |
Import |
import * as cdk from 'aws-cdk-lib'; |
- JavaScript
-
安装 |
npm install aws-cdk-lib |
Import |
const cdk = require('aws-cdk-lib'); |
- Python
-
安装 |
python -m pip install aws-cdk-lib |
Import |
import aws_cdk as cdk |
- Java
-
在pom.xml ,添加 |
群组software.amazon.awscdk ;工件 aws-cdk-lib |
Import |
import software.amazon.awscdk.App; |
- C#
-
安装 |
dotnet add package Amazon.CDK.Lib |
Import |
using Amazon.CDK; |
- Go
-
安装 |
go get github.com/aws/aws-cdk-go/awscdk/v2 |
Import |
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
)
|
construct
基类和支持代码在constructs
库中。实验构造(API仍在改进中)作为单独的模块分发。
使用 AWS CDK API参考文献
在开发时使用AWS CDK API参考资料 AWS CDK。
每个模块的参考资料分为以下几节。
-
概述:使用中的服务需要了解的入门材料 AWS CDK,包括概念和示例。
-
构造:表示一个或多个具体 AWS 资源的库类。这些是 “精选”(L2)资源或模式(L3 资源),它们提供了具有合理默认值的高级接口。
-
类:非构造类,提供模块中构造使用的功能。
-
结构:定义复合值结构的数据结构(属性包),例如属性(构造的props
参数)和选项。
-
接口:名称均以 “I” 开头的接口,定义相应构造或其他类的绝对最低功能。CDK使用构造接口来表示在 AWS CDK 应用程序外部定义并由诸如之类的方法引用的 AWS 资源Bucket.fromBucketArn()
。
-
枚举:用于指定某些构造参数的命名值的集合。使用枚举值CDK允许在合成过程中检查这些值的有效性。
-
CloudFormation 资源:这些 L1 结构的名称以 “Cfn” 开头,它们完全代表规范中定义的资源。 CloudFormation 它们是在每个CDK版本中根据该规范自动生成的。每个 L2 或 L3 结构都封装了一个或多个资源。 CloudFormation
-
CloudFormation 属性类型:定义每个 CloudFormation 资源属性的命名值的集合。
接口与构造类的比较
它们以一种特定的方式 AWS CDK 使用接口,即使您熟悉接口作为编程概念,这种方式也可能并不明显。
AWS CDK 支持使用诸如之类的方法使用CDK应用程序外部定义的资源Bucket.fromBucketArn()
。外部资源无法修改,也可能无法提供CDK应用程序中使用Bucket
类等定义的资源的所有功能。因此,接口代表了给定 AWS 资源类型(包括外部资源)中可用的最低限度功能。CDK
因此,在CDK应用中实例化资源时,应始终使用具体的类,例如。Bucket
在您自己的构造中指定要接受的参数类型时,请使用接口类型,例如IBucket
您准备好处理外部资源(也就是说,您无需更改它们)。如果您需要CDK定义的构造,请指定可以使用的最通用的类型。
有些接口是与特定类相关的属性或选项包的最低版本,而不是构造。当子类化以接受要传递给父类的参数时,这样的接口可能很有用。如果您需要一个或多个其他属性,则需要从该接口或更具体的类型中实现或派生。
支持的某些编程语言 AWS CDK 没有接口功能。在这些语言中,接口只是普通的类。你可以通过它们的名字来识别它们,名称遵循首字母 “I” 的模式,然后是其他构造的名称(例如IBucket
)。同样的规则适用。
管理依赖关系
您的 AWS CDK 应用程序或库的依赖项使用包管理工具进行管理。这些工具通常与编程语言一起使用。
通常, AWS CDK 支持该语言的标准或官方软件包管理工具(如果有)。否则, AWS CDK 将支持该语言最受欢迎或最广泛支持的语言。您也可以使用其他工具,特别是当它们与支持的工具配合使用时。但是,官方对其他工具的支持是有限的。
AWS CDK 支持以下软件包管理器:
Language |
支持的包管理工具 |
TypeScript/JavaScript |
NPM(节点 Package Manager)或 Yarn |
Python |
PIP(适用于 Python 的 Package 安装程序) |
Java |
Maven |
C# |
NuGet |
Go |
Go 模块 |
使用 AWS CDK CLIcdk init
命令创建新项目时,会自动指定CDK核心库和稳定构造的依赖关系。
有关管理支持的编程语言依赖关系的更多信息,请参阅以下内容:
与其他 AWS CDK 语言TypeScript进行比较
TypeScript 是开发 AWS CDK 应用程序时支持的第一种语言。因此,编写了大量的示例CDK代码 TypeScript。如果您正在使用另一种语言进行开发,那么将 AWS CDK 代码的实现方式 TypeScript 与您选择的语言进行比较可能会很有用。这可以帮助你在整个文档中使用示例。
导入模块
- TypeScript/JavaScript
-
TypeScript 支持导入整个命名空间或从命名空间导入单个对象。每个命名空间都包含用于给定 AWS 服务的构造和其他类。
// Import main CDK library as cdk
import * as cdk from 'aws-cdk-lib'; // ES6 import preferred in TS
const cdk = require('aws-cdk-lib'); // Node.js require() preferred in JS
// Import specific core CDK classes
import { Stack, App } from 'aws-cdk-lib';
const { Stack, App } = require('aws-cdk-lib');
// Import AWS S3 namespace as s3 into current namespace
import { aws_s3 as s3 } from 'aws-cdk-lib'; // TypeScript
const s3 = require('aws-cdk-lib/aws-s3'); // JavaScript
// Having imported cdk already as above, this is also valid
const s3 = cdk.aws_s3;
// Now use s3 to access the S3 types
const bucket = s3.Bucket(...);
// Selective import of s3.Bucket
import { Bucket } from 'aws-cdk-lib/aws-s3'; // TypeScript
const { Bucket } = require('aws-cdk-lib/aws-s3'); // JavaScript
// Now use Bucket to instantiate an S3 bucket
const bucket = Bucket(...);
- Python
-
比如 TypeScript,Python 支持命名空间模块导入和选择性导入。Python 中的命名空间看起来像 aws_cdk。 xxx,其中 xxx 表示 AWS 服务名称,例如亚马逊 S3 的 s3。(这些示例中使用了 Amazon S3)。
# Import main CDK library as cdk
import aws_cdk as cdk
# Selective import of specific core classes
from aws_cdk import Stack, App
# Import entire module as s3 into current namespace
import aws_cdk.aws_s3 as s3
# s3 can now be used to access classes it contains
bucket = s3.Bucket(...)
# Selective import of s3.Bucket into current namespace
from aws_cdk.s3 import Bucket
# Bucket can now be used to instantiate a bucket
bucket = Bucket(...)
- Java
-
Java 的导入工作方式与 TypeScript's 不同。每个 import 语句要么从给定包中导入单个类名,要么导入该包中定义的所有类(使用*
)。可以单独使用类名(如果已导入)或包括其包在内的限定类名来访问类。
库的命名与 AWS 构造库类似software.amazon.awscdk.services.xxx
(主库是software.amazon.awscdk
)。 AWS CDK 软件包的 Maven 群组 ID 是software.amazon.awscdk
。
// Make certain core classes available
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.App;
// Make all Amazon S3 construct library classes available
import software.amazon.awscdk.services.s3.*;
// Make only Bucket and EventType classes available
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.s3.EventType;
// An imported class may now be accessed using the simple class name (assuming that name
// does not conflict with another class)
Bucket bucket = Bucket.Builder.create(...).build();
// We can always use the qualified name of a class (including its package) even without an
// import directive
software.amazon.awscdk.services.s3.Bucket bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
// Java 10 or later can use var keyword to avoid typing the type twice
var bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
- C#
-
在 C# 中,您可以使用using
指令导入类型。有两种风格。一个允许你使用普通名称访问指定命名空间中的所有类型。对于另一个,你可以使用别名来引用命名空间本身。
包的命名与 AWS 构Amazon.CDK.AWS.xxx
造库包类似。(核心模块是Amazon.CDK
。)
// Make CDK base classes available under cdk
using cdk = Amazon.CDK;
// Make all Amazon S3 construct library classes available
using Amazon.CDK.AWS.S3;
// Now we can access any S3 type using its name
var bucket = new Bucket(...);
// Import the S3 namespace under an alias
using s3 = Amazon.CDK.AWS.S3;
// Now we can access an S3 type through the namespace alias
var bucket = new s3.Bucket(...);
// We can always use the qualified name of a type (including its namespace) even without a
// using directive
var bucket = new Amazon.CDK.AWS.S3.Bucket(...)
- Go
-
每个 AWS 构造库模块都以 Go 包的形式提供。
import (
"github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
"github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
// now instantiate a bucket
bucket := awss3.NewBucket(...)
// use aliases for brevity/clarity
import (
cdk "github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
bucket := s3.NewBucket(...)
实例化构造
AWS CDK 构造类在所有支持的语言中都具有相同的名称。大多数语言都使用new
关键字来实例化类(Python 和 Go 不使用)。此外,在大多数语言中,关键字this
指的是当前实例。(self
按照惯例,Python 使用。) 您应该将对当前实例的引用作为scope
参数传递给您创建的每个构造。
AWS CDK 构造的第三个参数是props
,一个包含构建构造所需的属性的对象。这个参数可能是可选的,但是当需要时,支持的语言会以惯用方式处理它。属性的名称也适用于该语言的标准命名模式。
- TypeScript/JavaScript
-
// Instantiate default Bucket
const bucket = new s3.Bucket(this, 'MyBucket');
// Instantiate Bucket with bucketName and versioned properties
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'my-bucket',
versioned: true,
});
// Instantiate Bucket with websiteRedirect, which has its own sub-properties
const bucket = new s3.Bucket(this, 'MyBucket', {
websiteRedirect: {host: 'aws.amazon.com'}});
- Python
-
Python 在实例化类时不使用new
关键字。属性参数使用关键字参数表示,参数使用命名snake_case
。
如果 props 值本身就是一组属性,则它由一个以该属性命名的类表示,该类接受子属性的关键字参数。
在 Python 中,当前实例作为第一个参数传递给方法,self
按照惯例命名。
# Instantiate default Bucket
bucket = s3.Bucket(self, "MyBucket")
# Instantiate Bucket with bucket_name and versioned properties
bucket = s3.Bucket(self, "MyBucket", bucket_name="my-bucket", versioned=true)
# Instantiate Bucket with website_redirect, which has its own sub-properties
bucket = s3.Bucket(self, "MyBucket", website_redirect=s3.WebsiteRedirect(
host_name="aws.amazon.com"))
- Java
-
在 Java 中,props 参数由一个名为的类表示XxxxProps
(例如,BucketProps
用于Bucket
构造的道具)。你可以使用生成器模式构建 props 参数。
每个XxxxProps
类都有一个生成器。每个构造都有一个方便的构建器,可以一步构建 props 和构造,如以下示例所示。
道具的命名与中的相同 TypeScript,使用camelCase
。
// Instantiate default Bucket
Bucket bucket = Bucket(self, "MyBucket");
// Instantiate Bucket with bucketName and versioned properties
Bucket bucket = Bucket.Builder.create(self, "MyBucket")
.bucketName("my-bucket").versioned(true)
.build();
# Instantiate Bucket with websiteRedirect, which has its own sub-properties
Bucket bucket = Bucket.Builder.create(self, "MyBucket")
.websiteRedirect(new websiteRedirect.Builder()
.hostName("aws.amazon.com").build())
.build();
- C#
-
在 C# 中,prop 是使用名为的类的对象初始化器指定的XxxxProps
(例如,BucketProps
用于Bucket
构造的 props)。
道具的命名方式与类似 TypeScript,唯一的不同是使用PascalCase
。
在实例化构造时使用var
关键字很方便,因此无需键入类名两次。但是,您的本地代码风格指南可能会有所不同。
// Instantiate default Bucket
var bucket = Bucket(self, "MyBucket");
// Instantiate Bucket with BucketName and Versioned properties
var bucket = Bucket(self, "MyBucket", new BucketProps {
BucketName = "my-bucket",
Versioned = true});
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
var bucket = Bucket(self, "MyBucket", new BucketProps {
WebsiteRedirect = new WebsiteRedirect {
HostName = "aws.amazon.com"
}});
- Go
-
要在 Go 中创建构造,请调用函数,NewXxxxxx
其中Xxxxxxx
是构造的名称。构造的属性被定义为一个结构。
在 Go 中,所有构造参数都是指针,包括数字、布尔值和字符串等值。使用诸如创建这些指针之类jsii.String
的便捷函数。
// Instantiate default Bucket
bucket := awss3.NewBucket(stack, jsii.String("MyBucket"), nil)
// Instantiate Bucket with BucketName and Versioned properties
bucket1 := awss3.NewBucket(stack, jsii.String("MyBucket"), &awss3.BucketProps{
BucketName: jsii.String("my-bucket"),
Versioned: jsii.Bool(true),
})
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
bucket2 := awss3.NewBucket(stack, jsii.String("MyBucket"), &awss3.BucketProps{
WebsiteRedirect: &awss3.RedirectTarget{
HostName: jsii.String("aws.amazon.com"),
}})
访问成员
通常会引用构造和其他 AWS CDK 类的属性或属性,并将这些值用作构建其他构造的输入。前面描述的方法命名差异也适用于此处。此外,在 Java 中,不可能直接访问成员。相反,提供了一个获取器方法。
- TypeScript/JavaScript
-
名字是camelCase
。
bucket.bucketArn
- Python
-
名字是snake_case
。
bucket.bucket_arn
- Java
-
为每个属性提供了一个 getter 方法;这些名称是camelCase
。
bucket.getBucketArn()
- C#
-
名字是PascalCase
。
bucket.BucketArn
- Go
-
名字是PascalCase
。
bucket.BucketArn
枚举常量
枚举常量的作用域仅限于一个类,并且在所有语言中都具有大写名称和下划线(有时称为)。SCREAMING_SNAKE_CASE
由于类名在除 Go 之外的所有支持的语言中也使用相同的大小写,因此这些语言中的限定枚举名称也相同。
s3.BucketEncryption.KMS_MANAGED
在 Go 中,枚举常量是模块命名空间的属性,其写法如下。
awss3.BucketEncryption_KMS_MANAGED
对象接口
AWS CDK 使用 TypeScript 对象接口来表示一个类实现了一组预期的方法和属性。您可以识别对象接口,因为它的名称以开头I
。具体类使用implements
关键字表示它实现的接口。
- TypeScript/JavaScript
-
JavaScript 没有接口功能。您可以忽略implements
关键字及其后面的类名。
import { IAspect, IConstruct } from 'aws-cdk-lib';
class MyAspect implements IAspect {
public visit(node: IConstruct) {
console.log('Visited', node.node.path);
}
}
- Python
-
Python 没有接口功能。但是,对于这些来说, AWS CDK 你可以通过装饰你的类来表示接口的@jsii.implements(interface)
实现。
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
- Java
-
import software.amazon.awscdk.IAspect;
import software.amazon.awscdk.IConstruct;
public class MyAspect implements IAspect {
public void visit(IConstruct node) {
System.out.format("Visited %s", node.getNode().getPath());
}
}
- C#
-
using Amazon.CDK;
public class MyAspect : IAspect
{
public void Visit(IConstruct node)
{
System.Console.WriteLine($"Visited ${node.Node.Path}");
}
}
- Go
-
Go 结构不需要明确声明它们实现了哪些接口。Go 编译器根据结构上可用的方法和属性来确定实现。例如,在以下代码中,MyAspect
实现该IAspect
接口,因为它提供了一种采用构造Visit
的方法。
type MyAspect struct {
}
func (a MyAspect) Visit(node constructs.IConstruct) {
fmt.Println("Visited", *node.Node().Path())
}