這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
建構是 AWS Cloud Development Kit (AWS CDK) 應用程式的基本建置區塊。建構是應用程式中代表一或多個 AWS CloudFormation 資源及其組態的元件。您可以透過匯入和設定建構，逐個建置您的應用程式。
匯入和使用建構
建構是您從AWS 建構程式庫匯入 CDK 應用程式的類別。您也可以建立和分發自己的建構，或使用第三方開發人員建立的建構。
建構是建構程式設計模型 (CPM) 的一部分。它們可以與其他工具搭配使用，例如 CDK for Terraform(CDKtf)、CDK for Kubernetes(CDK8s) 和 Projen。
許多第三方也已發佈與 相容的建構 AWS CDK。請造訪 Construct Hub
建構層級
建構程式庫中的 AWS 建構分為三個層級。每個層級提供更高層級的抽象。抽象程度越高，設定就越容易，需要的專業知識也越少。抽象越低，可用的自訂越多，需要更多專業知識。
- 第 1 級 (L1) 建構
-
L1 建構也稱為 CFN 資源，是最低層級的建構，不提供抽象。每個 L1 建構都直接映射到單一 AWS CloudFormation 資源。使用 L1 建構時，您可以匯入代表特定 AWS CloudFormation 資源的建構。然後，您可以在建構執行個體中定義資源的屬性。
當您熟悉 AWS CloudFormation 並需要完全控制定義 AWS 資源屬性時，L1 建構非常適合使用。
在 AWS 建構程式庫中，L1 建構命名為 開頭
Cfn，後面接著其所代表 AWS CloudFormation 資源的識別符。例如，CfnBucket建構是代表AWS::S3::BucketAWS CloudFormation 資源的 L1 建構。L1 建構是從AWS CloudFormation 資源規格產生。如果 資源存在於 中 AWS CloudFormation，則會在 中以 L1 建構 AWS CDK 形式提供。新資源或屬性可能需要一週的時間才能在 AWS 建構程式庫中可用。如需詳細資訊，請參閱AWS CloudFormation 《 使用者指南》中的AWS 資源和屬性類型參考。
- 第 2 級 (L2) 建構
-
L2 建構體，也稱為精選建構體，是由 CDK 團隊精心開發，通常是最廣泛使用的建構體類型。L2 建構直接映射到單一 AWS CloudFormation 資源，類似於 L1 建構。與 L1 建構相比，L2 建構透過直覺式意圖型 API 提供更高層級的抽象。L2 建構包含合理的預設屬性組態、最佳實務安全政策，並為您產生許多樣板程式碼和黏性邏輯。
L2 建構也為大多數資源提供協助程式方法，讓定義屬性、許可、資源之間的事件型互動等更加簡單快速。
s3.Bucket類別是 Amazon Simple Storage Service (Amazon S3) 儲存貯體資源的 L2 建構範例。AWS 建構程式庫包含 L2 建構，其指定為穩定且可供生產使用。對於開發中的 L2 建構，它們被指定為實驗性，並在單獨的模組中提供。
- 第 3 級 (L3) 建構
-
L3 建構也稱為模式，是抽象的最高層級。每個 L3 建構可以包含資源集合，這些資源設定為一起運作，以完成應用程式中的特定任務或服務。L3 建構用於為應用程式中的特定使用案例建立整個 AWS 架構。
為了提供完整的系統設計或更大型系統的實質部分，L3 建構提供意見預設屬性組態。它們是以解決問題和提供解決方案的特定方法為基礎。使用 L3 建構，您可以快速建立和設定多個資源，輸入和程式碼數量最少。
ecsPatterns.ApplicationLoadBalancedFargateService類別是 L3 建構的範例，代表 AWS Fargate 在 Amazon Elastic Container Service (Amazon ECS) 叢集上執行並由應用程式負載平衡器前的服務。與 L2 建構類似，準備好供生產使用的 L3 建構包含在 AWS 建構程式庫中。開發中項目會以不同的模組提供。
定義建構
合成
合成是透過建構定義更高層級抽象的關鍵模式。高階建構可由任意數量的低階建構組成。從由下而上的觀點來看，您可以使用建構來組織要部署的個別 AWS 資源。您可以使用任何對您目的方便的抽象內容，並根據需要盡可能多的關卡。
使用 合成，您可以定義可重複使用的元件，並與任何其他程式碼共用它們。例如，團隊可以定義一個建構，以實作 Amazon DynamoDB 資料表的公司最佳實務，包括備份、全域複寫、自動擴展和監控。團隊可以在內部與其他團隊或公開共用建構。
團隊可以使用與任何其他程式庫套件類似的建構。當程式庫更新時，開發人員可以存取新版本的改進和錯誤修正，類似於任何其他程式庫。
初始化
建構模組在延伸 Construct 基本類別的類別中實作。您可以透過執行個體化 類別來定義建構。所有建構模組在初始化時都採用以下三個參數：
-
範圍 – 建構的父系或擁有者。這可以是堆疊或其他建構。範圍決定建構樹中建構的位置。您通常應該傳遞
this(self中的Python)，其代表範圍的目前物件。 -
id – 範圍內必須是唯一的識別符。識別符可做為建構中定義的所有項目的命名空間。它用於產生唯一識別符，例如資源名稱和 AWS CloudFormation 邏輯 IDs。
識別符僅在範圍內是唯一的。這可讓您執行個體化和重複使用建構，而不必擔心其可能包含的建構和識別符，並啟用將建構組成更高層級的抽象。此外，範圍可以一次參考建構群組。範例包括標記，或指定要部署建構的位置。
-
props – 一組屬性或關鍵字引數，取決於定義建構的初始組態的語言。更高層級的建構提供更多預設值，如果所有 prop 元素都是選用的，您可以完全省略 props 參數。
組態
大多數建構接受 props作為其第三個引數 （或在 Python 中為關鍵字引數），這是定義建構組態的名稱/值集合。下列範例定義已啟用 AWS Key Management Service (AWS KMS) 加密和靜態網站託管的儲存貯體。由於未明確指定加密金鑰，因此建構會定義新的 Bucket kms.Key，並將其與儲存貯體建立關聯。
new s3.Bucket(this, 'MyEncryptedBucket', {
encryption: s3.BucketEncryption.KMS,
websiteIndexDocument: 'index.html'
});
與建構體互動
建構是擴展基礎建構類別的類別。在您執行個體化建構之後，建構物件會公開一組方法和屬性，讓您與建構互動，並將其傳遞為系統其他部分的參考。
AWS CDK 架構不會對建構APIs 施加任何限制。作者可以定義他們想要的任何 API。不過， AWS 建構程式庫中包含的 AWS 建構，例如 s3.Bucket，請遵循準則和常見模式。這在所有 AWS 資源中提供一致的體驗。
大多數 AWS 建構有一組授予方法，您可以用來將建構上的 AWS Identity and Access Management (IAM) 許可授予委託人。下列範例授予 IAM 群組從 Amazon S3 儲存貯體 讀取的data-science許可raw-data。
const rawData = new s3.Bucket(this, 'raw-data');
const dataScience = new iam.Group(this, 'data-science');
rawData.grantRead(dataScience);另一個常見的模式是讓 AWS 建構從其他位置提供的資料設定資源的屬性之一。屬性可以包含 Amazon Resource Name (ARNs)、名稱或 URLs。
下列程式碼會定義 AWS Lambda 函數，並透過環境變數中的佇列 URL，將其與 Amazon Simple Queue Service (Amazon SQS) 佇列建立關聯。
const jobsQueue = new sqs.Queue(this, 'jobs');
const createJobLambda = new lambda.Function(this, 'create-job', {
runtime: lambda.Runtime.NODEJS_18_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('./create-job-lambda-code'),
environment: {
QUEUE_URL: jobsQueue.queueUrl
}
});如需 AWS 建構程式庫中最常見 API 模式的相關資訊，請參閱資源和 AWS CDK。
應用程式和堆疊建構
AWS 建構程式庫中的 App和 Stack類別是唯一的建構。與其他建構相比，它們不會自行設定 AWS 資源。反之，它們會用來為您的其他建構提供內容。所有代表 AWS 資源的建構都必須直接或間接定義在Stack建構的範圍內。Stack建構定義在App建構的範圍內。
若要進一步了解 CDK 應用程式，請參閱 AWS CDK 應用程式。若要進一步了解 CDK 堆疊，請參閱 AWS CDK 堆疊簡介。
下列範例定義具有單一堆疊的應用程式。在堆疊中，L2 建構用於設定 Amazon S3 儲存貯體資源。
import { App, Stack, StackProps } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
class HelloCdkStack extends Stack {
constructor(scope: App, id: string, props?: StackProps) {
super(scope, id, props);
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
}
}
const app = new App();
new HelloCdkStack(app, "HelloCdkStack");使用建構
使用 L1 建構
L1 建構會直接映射到個別 AWS CloudFormation 資源。您必須提供資源所需的組態。
在此範例中，我們使用 CfnBucket L1 建構建立bucket物件：
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket"
});非簡單布林值、字串、數字或容器的建構屬性，會以支援的語言以不同的方式處理。
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket",
corsConfiguration: {
corsRules: [{
allowedOrigins: ["*"],
allowedMethods: ["GET"]
}]
}
});重要
您無法搭配 L1 建構使用 L2 屬性類型，反之亦然。 L1 使用 L1 建構時，請務必使用您所使用的 L1 建構所定義的類型。請勿使用來自其他 L1 建構的類型 （有些可能具有相同的名稱，但不是相同的類型）。
我們的一些語言特定 API 參考目前在 L1 屬性類型的路徑中存在錯誤，或者完全沒有記錄這些類別。我們希望盡快修正此問題。同時，請記住，這類類型一律是與其搭配使用的 L1 建構的內部類別。
使用 L2 建構
在下列範例中，我們透過從 Bucket L2 建構建立物件來定義 Amazon S3 儲存貯體：
import * as s3 from 'aws-cdk-lib/aws-s3';
// "this" is HelloCdkStack
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});MyFirstBucket 不是 AWS CloudFormation 建立的儲存貯體名稱。這是 CDK 應用程式內容中提供給新建構的邏輯識別符。physicalName 值將用於命名 AWS CloudFormation 資源。
使用第三方建構
Construct Hub
撰寫您自己的建構
除了使用現有的建構，您也可以撰寫自己的建構，並讓任何人在應用程式中使用這些建構。中的所有建構在 中相等 AWS CDK。來自 AWS Construct Library 的建構會視為透過 NPM、 Maven或 發佈之第三方程式庫的建構PyPI。發佈到貴公司內部套件儲存庫的建構也會以相同方式處理。
若要宣告新的建構，請在constructs套件中建立延伸建構基礎類別的類別，然後遵循初始化器引數的模式。
下列範例示範如何宣告代表 Amazon S3 儲存貯體的建構。S3 儲存貯體會在每次有人上傳檔案到其中時傳送 Amazon Simple Notification Service (Amazon SNS) 通知。
export interface NotifyingBucketProps {
prefix?: string;
}
export class NotifyingBucket extends Construct {
constructor(scope: Construct, id: string, props: NotifyingBucketProps = {}) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
const topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(topic),
{ prefix: props.prefix });
}
}注意
我們的建構不是繼承自 NotifyingBucket Bucket，而是繼承自 Construct。我們使用合成而非繼承來將 Amazon S3 儲存貯體和 Amazon SNS 主題綁定在一起。一般而言，開發 AWS CDK 建構時，合成優於繼承。
NotifyingBucket 建構函式具有典型的建構簽章：scope、 id和 props。最後一個引數 是選用的 （取得預設值 {})props，因為所有 prop 都是選用的。（基本Construct類別不採用props引數。) 您可以在應用程式中定義此建構的執行個體，而不需要 props，例如：
new NotifyingBucket(this, 'MyNotifyingBucket');或者，您可以使用 props（在 Java 中，另一個參數） 來指定要篩選的路徑字首，例如：
new NotifyingBucket(this, 'MyNotifyingBucket', { prefix: 'images/' });一般而言，您也想要公開建構上的某些屬性或方法。將主題隱藏在建構後面並不實用，因為建構的使用者無法訂閱該主題。新增 topic 屬性可讓消費者存取內部主題，如下列範例所示：
export class NotifyingBucket extends Construct {
public readonly topic: sns.Topic;
constructor(scope: Construct, id: string, props: NotifyingBucketProps) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
this.topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(this.topic), { prefix: props.prefix });
}
}現在，消費者可以訂閱主題，例如：
const queue = new sqs.Queue(this, 'NewImagesQueue');
const images = new NotifyingBucket(this, '/images');
images.topic.addSubscription(new sns_sub.SqsSubscription(queue));進一步了解
下列影片提供 CDK 建構的全面概觀，並說明如何在 CDK 應用程式中使用這些建構。
