這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 AWS CDK 程式庫
<a name="work-with"></a>

匯入並使用 AWS 雲端開發套件 (AWS CDK) 程式庫，以[支援的程式設計語言](languages.md)定義您的 AWS 雲端基礎設施。

## 匯入 AWS CDK 程式庫
<a name="work-with-library"></a>

[AWS CDK](libraries.md) Library 通常由其 TypeScript 套件名稱 所參考`aws-cdk-lib`。實際套件名稱會因語言而異。以下是如何安裝和匯入 CDK 程式庫的範例：

**Example**  


|  |  | 
| --- |--- |
|   **安裝 **   |   `npm install aws-cdk-lib`   | 
|   **Import (匯入)**   |   `import * as cdk from 'aws-cdk-lib';`   | 


|  |  | 
| --- |--- |
|   **安裝 **   |   `npm install aws-cdk-lib`   | 
|   **Import (匯入)**   |   `const cdk = require('aws-cdk-lib');`   | 


|  |  | 
| --- |--- |
|   **安裝 **   |   `python -m pip install aws-cdk-lib`   | 
|   **Import (匯入)**   |   `import aws_cdk as cdk`   | 


|  |  | 
| --- |--- |
|   **在 中`pom.xml`，新增**   |   `Group software.amazon.awscdk; artifact aws-cdk-lib`   | 
|   **Import (匯入)**   |   `import software.amazon.awscdk.App;`   | 


|  |  | 
| --- |--- |
|   **安裝 **   |   `dotnet add package Amazon.CDK.Lib`   | 
|   **Import (匯入)**   |   `using Amazon.CDK;`   | 


|  |  | 
| --- |--- |
|   **安裝 **   |   `go get github.com/aws/aws-cdk-go/awscdk/v2`   | 
|   **Import (匯入)**   |  <pre>import (<br />  "github.com/aws/aws-cdk-go/awscdk/v2"<br />)</pre>  | 

`construct` 基本類別和支援程式碼位於 `constructs`程式庫中。實驗建構，其中 API 仍在進行精簡，會以個別模組的形式分佈。

## 使用 AWS CDK API 參考
<a name="work-with-library-reference"></a>

使用 [AWS CDK 開發時，請使用 CDK API 參考](libraries.md#libraries-reference)。 AWS 

每個模組的參考資料會分成下列各節。
+  *概觀*：在 AWS CDK 中使用服務時，您需要知道的簡介資料，包括概念和範例。
+  *建構*：代表一或多個具體 AWS 資源的程式庫類別。這些是「策劃」(L2) 資源或模式 (L3 資源），可提供具有軟體預設值的高階界面。
+  *類別*：提供模組中建構所使用的功能的非建構類別。
+  *結構*：定義複合值結構的資料結構 （屬性套件），例如屬性 （建構的`props`引數） 和選項。
+  *界面*：名稱全部以「I」開頭的界面，定義對應建構或其他類別的絕對最小功能。CDK 使用建構界面來表示在 AWS CDK 應用程式外部定義並由 等方法參考 AWS 的資源`Bucket.fromBucketArn()`。
+  *列舉*：用於指定特定建構參數的具名值集合。使用列舉值可讓 CDK 在合成期間檢查這些值的有效性。
+  *CloudFormation 資源*：這些 L1 建構名稱以 "Cfn" 開頭，完全代表 CloudFormation 規格中定義的資源。每個 CDK 版本都會自動從該規格產生。每個 L2 或 L3 建構會封裝一或多個 CloudFormation 資源。
+  *CloudFormation 屬性類型*：指定值的集合，可定義每個 CloudFormation 資源的屬性。

## 與建構類別比較的界面
<a name="work-with-library-interfaces"></a>

 AWS CDK 會以特定方式使用界面，即使您熟悉界面做為程式設計概念，這些方式可能不明顯。

 AWS CDK 支援使用 CDK 應用程式外部定義的資源，例如 `Bucket.fromBucketArn()`。外部資源無法修改，而且可能不具備 CDK 應用程式中使用 `Bucket`類別定義之資源的所有可用功能。然後，界面代表指定 AWS 資源類型的 CDK 中可用的裸機最小功能，*包括外部資源*。

在 CDK 應用程式中執行個體化資源時，您應該一律使用具體類別，例如 `Bucket`。在您自己的其中一個建構中指定您接受的引數類型時，請使用界面類型，例如，`IBucket`如果您準備好處理外部資源 （也就是說，您不需要變更它們）。如果您需要 CDK 定義的建構，請指定您可以使用的最一般類型。

有些界面是與特定類別相關聯的屬性或選項套件的最小版本，而不是建構函數。這類界面在子類別接受您將傳遞至父類別的引數時非常有用。如果您需要一或多個額外的屬性，建議您實作或衍生自此界面，或更具體的類型。

**注意**  
 AWS CDK 支援的某些程式設計語言沒有界面功能。在這些語言中，介面只是一般類別。您可以依名稱來識別它們，其遵循初始 "I" 的模式，後面接著其他建構的名稱 （例如 `IBucket`)。適用相同的規則。

## 管理相依性
<a name="work-with-cdk-dependencies"></a>

 AWS CDK 應用程式或程式庫的相依性會使用套件管理工具進行管理。這些工具通常與程式設計語言搭配使用。

一般而言，如果有， AWS CDK 支援語言的標準或官方套件管理工具。否則， AWS CDK 將支援語言最熱門或廣泛支援的語言。您也可以使用其他工具，尤其是使用支援的工具時。不過，其他工具的官方支援受到限制。

 AWS CDK 支援下列套件管理員：


| 語言 | 支援的套件管理工具 | 
| --- | --- | 
|  TypeScript/JavaScript  |  NPM （節點套件管理員） 或 Yarn  | 
|  Python  |  PIP (Package Installer for Python)  | 
|  Java  |  Maven  | 
|  C\$1  |  NuGet  | 
|  Go  |  Go 模組  | 

當您使用 AWS CDK CLI `cdk init`命令建立新專案時，會自動指定 CDK 核心程式庫和穩定建構的相依性。

如需管理支援程式設計語言相依性的詳細資訊，請參閱下列內容：
+  在[ TypeScript 中管理相依性](work-with-cdk-typescript.md#work-with-cdk-typescript-dependencies)。
+  在[ JavaScript 中管理相依性](work-with-cdk-javascript.md#work-with-cdk-javascript-dependencies)。
+  在 [Python 中管理相依性](work-with-cdk-python.md#work-with-cdk-python-dependencies)。
+  在 [Java 中管理相依性](work-with-cdk-java.md#work-with-cdk-java-dependencies)。
+  在 [C\$1 中管理相依性](work-with-cdk-csharp.md#work-with-cdk-csharp-dependencies)。
+  在 [Go 中管理相依性](work-with-cdk-go.md#work-with-cdk-go-dependencies)。

## 比較 TypeScript 中的 AWS CDK 與其他語言
<a name="work-with-cdk-compare"></a>

TypeScript 是開發 AWS CDK 應用程式支援的第一個語言。因此，大量的範例 CDK 程式碼是以 TypeScript 撰寫。如果您使用其他語言進行開發，比較 TypeScript 中如何實作 AWS CDK 程式碼與您選擇的語言可能很有用。這可協助您在整個文件中使用範例。

## 匯入模組
<a name="work-with-cdk-compare-import"></a>

**Example**  
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(...);
```
如同 TypeScript，Python 支援命名空間模組匯入和選擇性匯入。Python 中的命名空間看起來像 **aws\$1cdk.** *xxx*，其中 *xxx* 代表 AWS 服務名稱，例如 **s3** for Amazon 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 的匯入運作方式與 TypeScript 不同。每個匯入陳述式會從指定的套件匯入單一類別名稱，或匯入該套件中定義的所有類別 （使用 `\*`)。如果已匯入類別名稱，或包含其套件的*合格*類別名稱，則可以單獨使用類別名稱來存取類別。  
程式庫的命名方式與 AWS Construct Library `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\$1 中，您可以使用 `using`指令匯入類型。有兩種樣式。一個 可讓您使用其純名稱來存取指定命名空間中的所有類型。使用另一個，您可以使用別名來參考命名空間本身。  
套件的命名方式與 AWS Construct Library 套件`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(...);
```
每個 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(...)
```

## 執行個體化建構
<a name="work-with-cdk-compare-class"></a>

 AWS CDK 建構類別在所有支援的語言中具有相同的名稱。大多數語言都使用 `new`關鍵字來執行個體化類別 (Python 和 Go 不會）。此外，在大多數語言中，關鍵字`this`是指目前的執行個體。(Python `self` 依慣例使用。) 您應該將參考傳遞給目前的執行個體，做為您所建立的每個建構的 `scope` 參數。

 AWS CDK 建構的第三個引數是 `props`，此物件包含建置建構所需的屬性。此引數可能是選用的，但當需要時，支援的語言會以慣用方式處理。屬性的名稱也會適應語言的標準命名模式。

**Example**  

```
// Instantiate default Bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket');

// Instantiate Bucket with bucketName and versioned properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
  bucketName: 'amzn-s3-demo-bucket',
   versioned: true,
});

// Instantiate Bucket with websiteRedirect, which has its own sub-properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
  websiteRedirect: {host: 'aws.amazon.com'}});
```
Python 在執行個體化類別時不會使用`new`關鍵字。屬性引數是使用關鍵字引數來表示，而引數是使用 來命名`snake_case`。  
如果 props 值本身是屬性的套件，則會由以 屬性命名的類別表示，該類別接受子屬性的關鍵字引數。  
在 Python 中，目前執行個體會傳遞至 方法做為第一個引數，以`self`慣例命名。  

```
# Instantiate default Bucket
bucket = s3.Bucket(self, "amzn-s3-demo-bucket")

# Instantiate Bucket with bucket_name and versioned properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket", versioned=true)

# Instantiate Bucket with website_redirect, which has its own sub-properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", website_redirect=s3.WebsiteRedirect(
            host_name="aws.amazon.com"))
```
在 Java 中，props 引數由名為 的類別表示 `Bucket` `XxxxProps`（例如，`BucketProps`針對建構的 props)。您可以使用建置器模式建置 props 引數。  
每個`XxxxProps`類別都有建置器。每個建構也有一個方便的建置器，可在一個步驟中建置道具和建構，如下列範例所示。  
Props 的名稱與 TypeScript 中的名稱相同，使用 `camelCase`。  

```
// Instantiate default Bucket
Bucket bucket = Bucket(self, "amzn-s3-demo-bucket");

// Instantiate Bucket with bucketName and versioned properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
                      .bucketName("amzn-s3-demo-bucket").versioned(true)
                      .build();

# Instantiate Bucket with websiteRedirect, which has its own sub-properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
                      .websiteRedirect(new websiteRedirect.Builder()
                          .hostName("aws.amazon.com").build())
                      .build();
```
在 C\$1 中，props 會使用 物件初始化器指定為名為 的類別 `Bucket` `XxxxProps`（例如，`BucketProps`針對建構的 props)。  
Props 的命名方式與 TypeScript 類似，但使用 除外`PascalCase`。  
在執行個體化建構時方便使用`var`關鍵字，因此您不需要輸入類別名稱兩次。不過，您的本機程式碼樣式指南可能會有所不同。  

```
// Instantiate default Bucket
var bucket = Bucket(self, "amzn-s3-demo-bucket");

// Instantiate Bucket with BucketName and Versioned properties
var bucket =  Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
                      BucketName = "amzn-s3-demo-bucket",
                      Versioned  = true});

// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
                      WebsiteRedirect = new WebsiteRedirect {
                              HostName = "aws.amazon.com"
                      }});
```
若要在 Go 中建立建構，請呼叫 函數，`NewXxxxxx`其中 `Xxxxxxx`是建構的名稱。建構的屬性定義為結構。  
在 Go 中，所有建構參數都是指標，包括數字、布林值和字串等值。使用 之類的便利函數`jsii.String`來建立這些指標。  

```
	// Instantiate default Bucket
	bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), nil)

	// Instantiate Bucket with BucketName and Versioned properties
	bucket1 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
		BucketName: jsii.String("amzn-s3-demo-bucket"),
		Versioned:  jsii.Bool(true),
	})

	// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
	bucket2 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
		WebsiteRedirect: &awss3.RedirectTarget{
			HostName: jsii.String("aws.amazon.com"),
		}})
```

## 存取成員
<a name="work-with-cdk-compare-members"></a>

通常參考建構函數和其他 AWS CDK 類別的屬性或屬性，並使用這些值做為例如建立其他建構函數的輸入。先前針對方法所述的命名差異也適用於此處。此外，在 Java 中，無法直接存取成員。而是提供 getter 方法。

**Example**  
名稱為 `camelCase`。  

```
bucket.bucketArn
```
名稱為 `snake_case`。  

```
bucket.bucket_arn
```
每個屬性都會提供 getter 方法；這些名稱為 `camelCase`。  

```
bucket.getBucketArn()
```
名稱為 `PascalCase`。  

```
bucket.BucketArn
```
名稱為 `PascalCase`。  

```
bucket.BucketArn
```

## 列舉常數
<a name="work-with-cdk-compare-enums"></a>

列舉常數的範圍是類別，且具有大寫名稱和所有語言的底線 （有時稱為 `SCREAMING_SNAKE_CASE`)。由於類別名稱也在 Go 以外的所有支援語言中使用相同的大小寫，因此這些語言中的合格列舉名稱也相同。

```
s3.BucketEncryption.KMS_MANAGED
```

在 Go 中，列舉常數是模組命名空間的屬性，寫入方式如下。

```
awss3.BucketEncryption_KMS_MANAGED
```

## 物件界面
<a name="work-with-cdk-compare-object"></a>

 AWS CDK 使用 TypeScript 物件界面來指示類別實作預期的一組方法和屬性。您可以辨識物件界面，因為其名稱開頭為 `I`。具體類別表示其使用 `implements`關鍵字實作的界面。

**Example**  
JavaScript 沒有界面功能。您可以忽略`implements`關鍵字和其後的類別名稱。

```
import { IAspect, IConstruct } from 'aws-cdk-lib';

class MyAspect implements IAspect {
  public visit(node: IConstruct) {
    console.log('Visited', node.node.path);
  }
}
```
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)
```

```
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());
    }
}
```

```
using Amazon.CDK;

public class MyAspect : IAspect
{
    public void Visit(IConstruct node)
    {
        System.Console.WriteLine($"Visited ${node.Node.Path}");
    }
}
```
Go 結構不需要明確宣告其實作的界面。Go 編譯器會根據結構上可用的方法和屬性來決定實作。例如，在下列程式碼中， 會`MyAspect`實作 `IAspect` 界面，因為它提供採用建構`Visit`的方法。  

```
type MyAspect struct {
}

func (a MyAspect) Visit(node constructs.IConstruct) {
	fmt.Println("Visited", *node.Node().Path())
}
```