這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS CDK 程式庫
匯入並使用 AWS 雲端開發套件 (AWS CDK) 程式庫，以[支援的程式設計語言](languages.md)定義您的 AWS 雲端基礎設施。
## 匯入 AWS CDK 程式庫
[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 (匯入)** | import (
"github.com/aws/aws-cdk-go/awscdk/v2"
)
|
`construct` 基本類別和支援程式碼位於 `constructs`程式庫中。實驗建構，其中 API 仍在進行精簡，會以個別模組的形式分佈。
## 使用 AWS CDK API 參考
使用 [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 資源的屬性。
## 與建構類別比較的界面
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 支援下列套件管理員：
| 語言 | 支援的套件管理工具 |
| --- | --- |
| 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 與其他語言
TypeScript 是開發 AWS CDK 應用程式支援的第一個語言。因此，大量的範例 CDK 程式碼是以 TypeScript 撰寫。如果您使用其他語言進行開發，比較 TypeScript 中如何實作 AWS CDK 程式碼與您選擇的語言可能很有用。這可協助您在整個文件中使用範例。
## 匯入模組
**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(...)
```
## 執行個體化建構
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"),
}})
```
## 存取成員
通常參考建構函數和其他 AWS CDK 類別的屬性或屬性，並使用這些值做為例如建立其他建構函數的輸入。先前針對方法所述的命名差異也適用於此處。此外，在 Java 中，無法直接存取成員。而是提供 getter 方法。
**Example**
名稱為 `camelCase`。
```
bucket.bucketArn
```
名稱為 `snake_case`。
```
bucket.bucket_arn
```
每個屬性都會提供 getter 方法；這些名稱為 `camelCase`。
```
bucket.getBucketArn()
```
名稱為 `PascalCase`。
```
bucket.BucketArn
```
名稱為 `PascalCase`。
```
bucket.BucketArn
```
## 列舉常數
列舉常數的範圍是類別，且具有大寫名稱和所有語言的底線 （有時稱為 `SCREAMING_SNAKE_CASE`)。由於類別名稱也在 Go 以外的所有支援語言中使用相同的大小寫，因此這些語言中的合格列舉名稱也相同。
```
s3.BucketEncryption.KMS_MANAGED
```
在 Go 中，列舉常數是模組命名空間的屬性，寫入方式如下。
```
awss3.BucketEncryption_KMS_MANAGED
```
## 物件界面
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())
}
```
# 在 TypeScript 中使用 AWS CDK
TypeScript 是 AWS 雲端開發套件 (AWS CDK) 完全支援的用戶端語言，且被視為穩定。在 TypeScript 中使用 AWS CDK 會使用熟悉的工具，包括 Microsoft 的 TypeScript 編譯器 (`tsc`)、[Node.js](https://nodejs.org/) 和 Node Package Manager (`npm`)。如果您願意，也可以使用 [Yarn](https://yarnpkg.com/)，但本指南中的範例使用 NPM。構成 AWS 建構程式庫的模組會透過 NPM 儲存庫 https：//[npmjs.org](https://www.npmjs.com/) 進行分發。
您可以使用任何編輯器或 IDE。許多 AWS CDK 開發人員使用 [Visual Studio Code](https://code.visualstudio.com/) （或其開放原始碼同等 [VSCodium](https://vscodium.com/))，其對 TypeScript 有絕佳的支援。
## TypeScript 入門
若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱 [AWS CDK 入門](getting-started.md)。
您也需要 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
```
建立專案也會安裝[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html)模組及其相依性。
`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 Toolkit 的相依性`package.json`，因此如果您想要使用此方法，則不需要對專案進行任何變更。您只需使用稍微不同的命令來建置應用程式和發出`cdk`命令即可。
| 作業 | 使用全域工具 | 使用本機工具 |
| --- | --- | --- |
| **初始化專案** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` |
| **建置** | `tsc` | `npm run build` |
| **執行 CDK Toolkit 命令** | `cdk …` | `npm run cdk …` 或 `npx aws-cdk …` |
`npx aws-cdk` 會執行目前專案中本機安裝的 CDK Toolkit 版本，如果有的話，請返回全域安裝。如果沒有全域安裝， 會`npx`下載 CDK Toolkit 的臨時複本並執行該複本。您可以使用`@`語法指定 CDK Toolkit 的任意版本：`npx aws-cdk@2.0 --version`列印 `2.0.0`。
**提示**
設定別名，以便您可以搭配本機 CDK Toolkit 安裝使用 `cdk`命令。
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## 管理 AWS 建構程式庫模組
使用 Node Package Manager (`npm`) 來安裝和更新 AWS Construct Library 模組，以供您的應用程式以及您需要的其他套件使用。（您可以`yarn`改為使用 。`npm`) `npm`也會自動安裝這些模組的相依性。
大多數 AWS CDK 建構模組位於名為 的主 CDK 套件中`aws-cdk-lib`，這是 所建立新專案的預設相依性`cdk init`。"Experimental" AWS Construct Library 模組，其中更高層級的建構仍在開發中，命名為 `@aws-cdk/-alpha`。服務名稱具有 *aws-* 字首。如果您不確定模組的名稱，[請在 NPM 上搜尋](https://www.npmjs.com/search?q=%40aws-cdk)。
**注意**
[CDK API 參考](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)也會顯示套件名稱。
例如，以下命令會安裝實驗模組 for AWS CodeStar。
```
$ npm install @aws-cdk/aws-codestar-alpha
```
有些服務的建構程式庫支援位於多個命名空間中。例如，除了 之外`aws-route53`，還有三個額外的 Amazon Route 53 命名空間：`aws-route53-targets`、 `aws-route53-patterns`和 `aws-route53resolver`。
專案的相依性會在 中維護`package.json`。您可以編輯此檔案，將部分或全部相依性鎖定至特定版本，或允許在特定條件下將其更新至較新的版本。若要根據您在 中指定的規則，將專案的 NPM 相依性更新為最新允許的版本`package.json`：
```
$ npm update
```
在 TypeScript 中，您可以使用使用 NPM 安裝模組的相同名稱，將模組匯入您的程式碼。我們建議您在應用程式中匯入 AWS CDK 類別和 AWS 建構程式庫模組時採用下列實務。遵循這些準則有助於讓您的程式碼與其他 AWS CDK 應用程式保持一致，並且更容易理解。
+ 使用 ES6-style的`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 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。請勿使用 ^ 或 \$1，因為這些模組的較新版本可能會導致 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 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。使用 `peerDependencies`可確保樹狀目錄中只有一個 CDK `node_modules` 程式庫的副本。
在 中`devDependencies`，指定測試所需的工具和程式庫，選擇性使用 ^ 來表示可接受較新的相容版本。準確指定 （不含 ^ 或 \$1) 您公告程式庫的 `aws-cdk-lib`和其他 CDK 套件的最低版本相容。此實務可確保您的測試會針對這些版本執行。如此一來，如果您不小心使用只在較新版本中找到的功能，您的測試可能會截獲它。
**警告**
`peerDependencies` 僅由 NPM 7 和更新版本自動安裝。如果您使用的是 NPM 6 或更早版本，或者您使用 Yarn，則必須在 中包含相依性的相依性`devDependencies`。否則，不會安裝它們，而且您將收到有關未解決對等相依性的警告。
### 安裝和更新相依性
執行下列命令來安裝專案的相依性。
**Example**
```
# Install the latest version of everything that matches the ranges in 'package.json'
npm install
# Install the same exact dependency versions as recorded in 'package-lock.json'
npm ci
```
```
# Install the latest version of everything that matches the ranges in 'package.json'
$ yarn upgrade
# Install the same exact dependency versions as recorded in 'yarn.lock'
$ yarn install --frozen-lockfile
```
若要更新已安裝的模組，可以使用上述 `npm install`和 `yarn upgrade`命令。任一命令都會將 中的套件更新`node_modules`為符合 中規則的最新版本`package.json`。不過，它們不會更新`package.json`本身，您可能想要這樣做來設定新的最低版本。如果您在 GitHub 上託管套件，您可以設定 [Dependabot 版本更新](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates)以自動更新 `package.json`。或者，使用 [npm-check-updates](https://www.npmjs.com/package/npm-check-updates)。
**重要**
根據設計，當您安裝或更新相依性時，NPM 和 Yarn 會選擇符合 中指定需求的每個套件的最新版本`package.json`。這些版本一律會有損壞的風險 （意外或刻意）。在更新專案的相依性後徹底測試。
## AWS TypeScript 中的 CDK 慣用詞
### Props
所有 AWS 建構程式庫類別都會使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*id* 和 *props*。Argument *props* 是一組鍵/值對，建構用來設定其建立 AWS 的資源。其他類別和方法也會針對引數使用「屬性組合」模式。
在 TypeScript 中， 的形狀`props`是使用界面來定義，該界面會告訴您必要和選用的引數及其類型。這類界面會針對每種`props`引數定義，通常是針對單一建構或方法。例如，建構 （在`aws-cdk-lib/aws-s3`模組中） [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) 指定符合[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html)界面的`props`引數。
如果屬性本身是物件，例如 的 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect) 屬性`BucketProps`，則該物件會有其形狀必須符合的專屬界面，在此情況下為 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html)。
如果您要將 AWS 建構程式庫類別子類別 （或覆寫採用類似 props 引數的方法），您可以從現有界面繼承，以建立新的界面，指定程式碼所需的任何新 props。呼叫父類別或基礎方法時，通常您可以傳遞您收到的整個 props 引數，因為在 物件中提供但未在界面中指定的任何屬性都會遭到忽略。
AWS CDK 的未來版本可能會同時新增具有您用於自有屬性名稱的新屬性。然後，傳遞您收到的繼承鏈值可能會導致意外行為。將屬性移除或設定為 時收到的道具淺複本傳遞更安全`undefined`。例如：
```
super(scope, name, {...props, encryptionKeys: undefined});
```
或者，為您的屬性命名，以便明確它們屬於您的建構。如此一來，它們不太可能與未來 AWS CDK 版本中的屬性碰撞。如果其中有許多，請使用單一適當命名的物件來保留它們。
### 缺少值
物件 （例如 props) 中的遺失值具有 TypeScript `undefined` 中的值。3.7 版的語言引進了可簡化使用這些值的運算子，當達到未定義的值時，更容易指定預設值和「短路」鏈結。如需這些功能的詳細資訊，請參閱 [TypeScript 3.7 版本備註](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)，特別是前兩個功能：選用鏈結和 Nullish Coalescing。
## 建置並執行 CDK 應用程式
一般而言，在建置和執行應用程式時，您應該位於專案的根目錄中。
Node.js 無法直接執行 TypeScript；反之，您的應用程式會使用 TypeScript 編譯器 轉換為 JavaScript`tsc`。接著會執行產生的 JavaScript 程式碼。
AWS CDK 會在需要執行應用程式時自動執行此操作。不過，手動編譯 以檢查錯誤和執行測試會很有用。若要手動編譯 TypeScript 應用程式，請發出 `npm run build`。您也可以發出 `npm run watch`進入監看模式，其中 TypeScript 編譯器會在您將變更儲存到來源檔案時自動重建您的應用程式。
# 在 JavaScript 中使用 AWS CDK
JavaScript 是完全支援的 AWS CDK 用戶端語言，且被視為穩定。在 JavaScript 中使用 AWS 雲端開發套件 (AWS CDK) 會使用熟悉的工具，包括 [Node.js ](https://nodejs.org/)和 Node Package Manager (`npm`)。如果您願意，也可以使用 [Yarn](https://yarnpkg.com/)，但本指南中的範例使用 NPM。構成 AWS 建構程式庫的模組會透過 NPM 儲存庫 https：//[npmjs.org](https://www.npmjs.com/) 進行分發。
您可以使用任何編輯器或 IDE。許多 AWS CDK 開發人員使用 [Visual Studio Code](https://code.visualstudio.com/) （或其開放原始碼同等 [VSCodium](https://vscodium.com/))，其對 JavaScript 有良好的支援。
## JavaScript 入門 JavaScript
若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱 [AWS CDK 入門](getting-started.md)。
JavaScript AWS CDK 應用程式不需要這些以外的其他先決條件。
**注意**
第三方語言棄用：只有在廠商或社群共用其 EOL （生命週期結束） 之前，才支援語言版本，且可能會有所變更，恕不另行通知。
## 建立專案
您可以透過`cdk init`在空目錄中叫用 來建立新的 AWS CDK 專案。使用 `--language`選項並指定 `javascript`：
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language javascript
```
建立專案也會安裝 [aws-cdk-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) 模組及其相依性。
`cdk init` 使用專案資料夾的名稱來命名專案的各種元素，包括類別、子資料夾和檔案。資料夾名稱中的連字號會轉換為底線。不過，名稱應該遵循 JavaScript 識別符的形式；例如，它不應以數字開頭或包含空格。
## 使用本機 `cdk`
在大部分情況下，本指南假設您全域安裝 CDK Toolkit (`npm install -g aws-cdk`)，而提供的命令範例 （例如 `cdk synth`) 遵循此假設。此方法可讓您輕鬆讓 CDK Toolkit 保持最新狀態，而且由於 CDK 採取嚴格的回溯相容性方法，因此一律使用最新版本的風險通常很少。
有些團隊偏好指定每個專案中的所有相依性，包括 CDK Toolkit 等工具。此實務可讓您將這類元件固定到特定版本，並確保團隊中的所有開發人員 （以及 CI/CD 環境） 完全使用這些版本。這消除了可能的變更來源，有助於使建置和部署更加一致且可重複。
CDK 包含 JavaScript 專案範本 中 CDK Toolkit 的相依性`package.json`，因此如果您想要使用此方法，則不需要對專案進行任何變更。您只需要使用稍微不同的命令來建置應用程式和發出`cdk`命令。
| 作業 | 使用全域工具 | 使用本機工具 |
| --- | --- | --- |
| **初始化專案** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` |
| **執行 CDK Toolkit 命令** | `cdk …` | `npm run cdk …` 或 `npx aws-cdk …` |
`npx aws-cdk` 會執行目前專案中本機安裝的 CDK Toolkit 版本，如果有的話，請返回全域安裝。如果沒有全域安裝， 會`npx`下載 CDK Toolkit 的臨時複本並執行該複本。您可以使用`@`語法指定 CDK Toolkit 的任意版本：`npx aws-cdk@1.120 --version`列印 `1.120.0`。
**提示**
設定別名，以便您可以搭配本機 CDK Toolkit 安裝使用 `cdk`命令。
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## 管理 AWS 建構程式庫模組
使用 Node Package Manager (`npm`) 來安裝和更新 AWS Construct Library 模組，以供您的應用程式以及您需要的其他套件使用。(`npm`您也可以使用 `yarn`而非 。) `npm`也會自動安裝這些模組的相依性。
大多數 AWS CDK 建構模組位於名為 的主 CDK 套件中`aws-cdk-lib`，這是 所建立新專案的預設相依性`cdk init`。"Experimental" AWS Construct Library 模組仍在開發中，名為 `aws-cdk-lib/-alpha`。服務名稱具有 *aws-* 字首。如果您不確定模組的名稱，[請在 NPM 上搜尋](https://www.npmjs.com/search?q=%40aws-cdk)。
**注意**
[CDK API 參考](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)也會顯示套件名稱。
例如，以下命令會安裝實驗模組 for AWS CodeStar。
```
npm install @aws-cdk/aws-codestar-alpha
```
有些服務的建構程式庫支援位於多個命名空間中。例如，除了 `aws-route53`之外，還有三個額外的 Amazon Route 53 命名空間：`aws-route53-targets`、 `aws-route53-patterns`和 `aws-route53resolver`。
專案的相依性會在 中維護`package.json`。您可以編輯此檔案，將部分或全部相依性鎖定至特定版本，或允許在特定條件下將其更新至較新的版本。若要根據您在 中指定的規則，將專案的 NPM 相依性更新為最新允許的版本`package.json`：
```
npm update
```
在 JavaScript 中，您可以使用使用 NPM 安裝模組的相同名稱，將模組匯入您的程式碼。我們建議您在應用程式中匯入 AWS CDK 類別和 AWS 建構程式庫模組時採用下列實務。遵循這些準則有助於讓您的程式碼與其他 AWS CDK 應用程式保持一致，並且更容易理解。
+ 使用 `require()`，而非 ES6-style的`import`指令。較舊版本的 Node.js 不支援 ES6 匯入，因此使用較舊的語法更廣泛相容。（如果您真的想要使用 ES6 匯入，請使用 [esm](https://www.npmjs.com/package/esm) 確保您的專案與 Node.js 的所有支援版本相容。)
+ 一般而言，從 匯入個別類別`aws-cdk-lib`。
```
const { App, Stack } = require('aws-cdk-lib');
```
+ 如果您需要來自 的許多類別`aws-cdk-lib`，您可以使用 命名空間別名，`cdk`而不是匯入個別類別。避免同時執行這兩個動作。
```
const cdk = require('aws-cdk-lib');
```
+ 一般而言，使用短命名空間別名匯入 AWS 建構程式庫。
```
const { s3 } = require('aws-cdk-lib/aws-s3');
```
## 在 JavaScript 中管理相依性
在 JavaScript 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`檔案。針對 JavaScript 產生的檔案類似，但沒有 TypeScript 相關項目。
```
{
"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 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。請勿使用 ^ 或 \$1，因為這些模組的較新版本可能會導致 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 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。使用 `peerDependencies`可確保樹狀目錄中只有一個 CDK `node_modules` 程式庫的副本。
在 中`devDependencies`，指定測試所需的工具和程式庫，選擇性使用 ^ 來表示可接受較新的相容版本。準確指定 （不含 ^ 或 \$1) 您公告程式庫的 `aws-cdk-lib`和其他 CDK 套件的最低版本相容。此實務可確保您的測試會針對這些版本執行。如此一來，如果您不小心使用只在較新版本中找到的功能，您的測試可能會截獲它。
**警告**
`peerDependencies` 僅由 NPM 7 和更新版本自動安裝。如果您使用 NPM 6 或更早版本，或者您使用 Yarn，則必須在 中包含相依性的相依性`devDependencies`。否則，不會安裝它們，而且您將收到有關未解決對等相依性的警告。
### 安裝和更新相依性
執行下列命令來安裝專案的相依性。
**Example**
```
# Install the latest version of everything that matches the ranges in 'package.json'
npm install
# Install the same exact dependency versions as recorded in 'package-lock.json'
npm ci
```
```
# Install the latest version of everything that matches the ranges in 'package.json'
yarn upgrade
# Install the same exact dependency versions as recorded in 'yarn.lock'
yarn install --frozen-lockfile
```
若要更新已安裝的模組，可以使用上述 `npm install`和 `yarn upgrade`命令。任一命令都會將 中的套件更新`node_modules`為符合 中規則的最新版本`package.json`。不過，它們不會更新`package.json`本身，您可能想要這樣做來設定新的最低版本。如果您在 GitHub 上託管套件，您可以設定 [Dependabot 版本更新](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates)以自動更新 `package.json`。或者，使用 [npm-check-updates](https://www.npmjs.com/package/npm-check-updates)。
**重要**
根據設計，當您安裝或更新相依性時，NPM 和 Yarn 會選擇符合 中指定需求的每個套件的最新版本`package.json`。這些版本一律會有損壞的風險 （意外或刻意）。在更新專案的相依性後徹底測試。
## AWS JavaScript 中的 CDK 慣用語
### 屬性
所有 AWS 建構程式庫類別都是使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*ID* 和 *props*，即建構函數用來設定其建立之 AWS 資源的金鑰/值對套件。其他類別和方法也會針對引數使用「屬性組合」模式。
使用具有良好 JavaScript 自動完成的 IDE 或編輯器有助於避免屬性名稱拼寫錯誤。如果建構模組預期有 `encryptionKeys` 屬性，而您在執行個體化建構模組時將其拼寫為 `encryptionkeys`，表示您尚未傳遞預期的值。如果需要 屬性，這可能會在合成時間導致錯誤，或者如果是選用，則會導致屬性無提示地忽略。在後一種情況下，您可能會收到要覆寫的預設行為。請在此特別注意。
子分類 AWS 建構程式庫類別 （或覆寫採用類似 props 引數的方法） 時，您可能想要接受其他屬性供自己使用。這些值會被父類別或覆寫方法忽略，因為它們永遠不會在該程式碼中存取，因此您通常可以傳遞您收到的所有道具。
未來的 AWS CDK 版本可能會同時新增具有您用於自有屬性名稱的新屬性。然後，傳遞您收到的繼承鏈值可能會導致意外行為。將 屬性移除或設定為 時收到的道具淺層副本傳遞更安全`undefined`。例如：
```
super(scope, name, {...props, encryptionKeys: undefined});
```
或者，為您的屬性命名，以便明確它們屬於您的建構。如此一來，它們不太可能與未來 AWS CDK 版本中的屬性碰撞。如果其中有許多，請使用單一適當命名的物件來保留它們。
### 缺少值
物件 （例如 `props`) 中的遺失值具有 JavaScript `undefined`中的 值。通常的技巧適用於處理這些技巧。例如，存取可能未定義之值屬性的常見慣用語如下所示：
```
// a may be undefined, but if it is not, it may have an attribute b
// c is undefined if a is undefined, OR if a doesn't have an attribute b
let c = a && a.b;
```
不過，如果 `a`可以具有 以外的一些其他「虛假」值`undefined`，最好讓測試更明確。在這裡，我們將利用 `null`和 `undefined` 等於一次測試兩者的事實：
```
let c = a == null ? a : a.b;
```
**提示**
Node.js 14.0 及更新版本支援可簡化未定義值處理的新運算子。如需詳細資訊，請參閱[選用的鏈結](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md)和 [nullish coalescing](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md) 提案。
## 搭配 JavaScript 使用 TypeScript 範例
[TypeScript](https://www.typescriptlang.org/) 是我們用來開發 AWS CDK 的語言，也是支援開發應用程式的第一個語言，因此許多可用的 AWS CDK 程式碼範例都以 TypeScript 撰寫。這些程式碼範例可能是 JavaScript 開發人員的好資源；您只需移除程式碼的 TypeScript 特定部分。
TypeScript 程式碼片段通常會使用較新的 ECMAScript `import`和`export`關鍵字，從其他模組匯入物件，並宣告要在目前模組外部提供物件。Node.js 剛開始在其最新版本中支援這些關鍵字。根據您正在使用的 Node.js 版本 （或想要支援），您可以重寫匯入和匯出以使用較舊的語法。
匯入可以取代為對 `require()`函數的呼叫。
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';
```
```
const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');
```
匯出可以指派給`module.exports`物件。
**Example**
```
export class Stack1 extends cdk.Stack {
// ...
}
export class Stack2 extends cdk.Stack {
// ...
}
```
```
class Stack1 extends cdk.Stack {
// ...
}
class Stack2 extends cdk.Stack {
// ...
}
module.exports = { Stack1, Stack2 }
```
**注意**
使用舊式匯入和匯出的替代方案是使用 [esm](https://www.npmjs.com/package/esm) 模組。
一旦匯入和匯出已排序，您就可以深入了解實際的程式碼。您可以執行這些常用的 TypeScript 功能：
+ 輸入註釋
+ 介面定義
+ 類型轉換/廣播
+ 存取修飾詞
可以為變數、類別成員、函數參數和函數傳回類型提供類型註釋。對於變數、參數和成員，類型是依照具有冒號和 類型的識別符來指定。函數傳回值遵循函數簽章，由冒號和 類型組成。
若要將類型註釋程式碼轉換為 JavaScript，請移除冒號 和 類型。類別成員在 JavaScript 中必須具有一些值；`undefined`如果在 TypeScript 中只有類型註釋，則將其設定為 。
**Example**
```
var encrypted: boolean = true;
class myStack extends cdk.Stack {
bucket: s3.Bucket;
// ...
}
function makeEnv(account: string, region: string) : object {
// ...
}
```
```
var encrypted = true;
class myStack extends cdk.Stack {
bucket = undefined;
// ...
}
function makeEnv(account, region) {
// ...
}
```
在 TypeScript 中，界面用於提供必要和選用屬性的套件及其類型名稱。然後，您可以使用界面名稱做為類型註釋。TypeScript 將確保您用作函數引數的物件具有正確類型的必要屬性。
```
interface myFuncProps {
code: lambda.Code,
handler?: string
}
```
JavaScript 沒有界面功能，因此一旦移除了類型註釋，請完全刪除界面宣告。
當函數或方法傳回一般用途類型 （例如 `object`)，但您想要將該值視為更具體的子類型，以存取不屬於較一般類型界面的屬性或方法時，TypeScript 可讓您使用 *轉換*值，`as`後面接著類型或界面名稱。JavaScript 不支援 （或需要），因此只要移除 `as`和下列識別符即可。較不常見的轉換語法是在括號 中使用類型名稱``；這些轉換也必須移除。
最後，TypeScript 支援類別`private`成員的存取修飾詞 `protected`、 `public`和 。JavaScript 中的所有類別成員都是公開的。只要在您看到這些修飾詞的地方將其移除即可。
了解如何識別和移除這些 TypeScript 功能，對於將簡短 TypeScript 程式碼片段適應 JavaScript 有很大的幫助。但是，以此方式轉換較長的 TypeScript 範例可能不切實際，因為它們更有可能使用其他 TypeScript 功能。在這些情況下，我們建議使用 [Sucrase](https://github.com/alangpierce/sucrase)。例如，如果程式碼使用未定義的變數，則 Sucrase 不會`tsc`投訴。如果語法有效，則 Sucrase 可以將其翻譯為 JavaScript。這使得轉換可能無法自行執行的程式碼片段特別有價值。
## 遷移至 TypeScript
許多 JavaScript 開發人員會隨著專案變得更大且更複雜，而移至 [TypeScript](https://www.typescriptlang.org/)。TypeScript 是 JavaScript 的超集，所有 JavaScript 程式碼都是有效的 TypeScript 程式碼，因此不需要變更程式碼，而且也是支援的 AWS CDK 語言。類型註釋和其他 TypeScript 功能是選用的，您可以在 AWS CDK 應用程式中找到值時將其新增至 CDK 應用程式。TypeScript 也可讓您提早存取新的 JavaScript 功能，例如選用的鏈結和 Nullish Coalescing，然後再完成，而且不需要升級 Node.js。
TypeScript 的「形狀型」界面，可定義 物件內必要和選用屬性 （及其類型） 的套件，允許在您撰寫程式碼時攔截常見錯誤，讓您的 IDE 更輕鬆地提供強大的自動完成和其他即時編碼建議。
TypeScript 中的編碼確實涉及一個額外的步驟：使用 TypeScript 編譯器 編譯您的應用程式`tsc`。對於典型 AWS 的 CDK 應用程式，編譯最多需要幾秒鐘的時間。
將現有 JavaScript AWS CDK 應用程式遷移至 TypeScript 的最簡單方法是使用 建立新的 TypeScript 專案`cdk init app --language typescript`，然後將您的來源檔案 （以及任何其他必要檔案，例如 AWS Lambda 函數原始程式碼等資產） 複製到新專案。重新命名 JavaScript 檔案以結束於 ，`.ts`並在 TypeScript 中開始開發。
# 在 Python 中使用 AWS CDK
Python 是完全支援的 AWS 雲端開發套件 (AWS CDK) 用戶端語言，並被視為穩定。在 Python 中使用 AWS CDK 會使用熟悉的工具，包括標準 Python 實作 (CPython)`virtualenv`、搭配 的虛擬環境，以及 Python 套件安裝程式 `pip`。包含 AWS Construct Library 的模組會透過 https：//[pypi.org](https://pypi.org/search/?q=aws-cdk) 進行分發。 AWS CDK 的 Python 版本甚至使用 Python 樣式識別符 （例如`snake_case`方法名稱）。
您可以使用任何編輯器或 IDE。許多 AWS CDK 開發人員使用 [Visual Studio Code](https://code.visualstudio.com/) （或其開放原始碼同等 [VSCodium](https://vscodium.com/))，可透過[官方擴充](https://marketplace.visualstudio.com/items?itemName=ms-python.python)功能對 Python 提供良好的支援。Python 隨附的 IDLE 編輯器足以開始使用。 AWS CDK 的 Python 模組確實有類型提示，對於支援類型驗證的 linting 工具或 IDE 很有用。
## Python 入門
若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱 [AWS CDK 入門](getting-started.md)。
Python AWS CDK 應用程式需要 Python 3.9 或更新版本。如果您尚未安裝，請在 https：//[python.org](https://www.python.org/) 下載作業系統的[相容版本](https://www.python.org/downloads/)。如果您執行 Linux，您的系統可能隨附相容的版本，或者您可以使用 distro 的套件管理員 (`yum`、 `apt`等） 安裝它。Mac 使用者可能對 [Homebrew](https://brew.sh/) 感興趣，後者是適用於 macOS 的 Linux 型套件管理員。
**注意**
第三方語言棄用：只有在廠商或社群共用其 EOL （生命週期結束） 之前，才支援語言版本，且可能會有所變更，恕不另行通知。
`virtualenv`也需要 Python 套件安裝程式 `pip`和虛擬環境管理員 。相容的 Python 版本的 Windows 安裝包含這些工具。在 Linux 上， `pip` 和 `virtualenv`可能會在您的套件管理員中以個別套件的形式提供。或者，您可以使用下列命令來安裝它們：
```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```
如果您遇到許可錯誤，請使用 `--user`旗標執行上述命令，以便將模組安裝在您的使用者目錄中，或使用 `sudo`取得整個系統安裝模組的許可。
**注意**
Linux 部屬通常會使用 Python 3.x `python3`的可執行檔名稱，並`python`參考 Python 2.x 安裝。有些 distros 有選用的套件，您可以安裝讓 `python`命令參考 Python 3。否則，您可以透過`cdk.json`在專案的主目錄中編輯 來調整用於執行應用程式的命令。
**注意**
在 Windows 上，您可能想要使用適用於 Windows `py` 的 Python [啟動器可執行檔來叫用 Python](https://docs.python.org/3/using/windows.html#launcher) （和 `pip`)。此外，啟動器可讓您輕鬆指定要使用的 Python 安裝版本。
如果在`python`命令列中輸入 會產生從 Windows 存放區安裝 Python 的訊息，即使安裝了 Windows 版本的 Python，也請開啟 Windows 的管理應用程式執行別名設定面板，並關閉 Python 的兩個應用程式安裝程式項目。
## 建立專案
您可以透過`cdk init`在空目錄中叫用 來建立新的 AWS CDK 專案。使用 `--language`選項並指定 `python`：
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init` 使用專案資料夾的名稱來命名專案的各種元素，包括類別、子資料夾和檔案。資料夾名稱中的連字號會轉換為底線。不過，名稱應該遵循 Python 識別符的形式；例如，它不應以數字開頭或包含空格。
若要使用新專案，請啟用其虛擬環境。這可讓專案的相依性在本機安裝在專案資料夾中，而不是全域安裝。
```
$ source .venv/bin/activate
```
**注意**
您可以將其識別為用來啟用虛擬環境的 Mac/Linux 命令。Python 範本包含一個批次檔案 `source.bat`，允許在 Windows 上使用相同的命令。傳統的 Windows 命令 也可`.\venv\Scripts\activate`運作。
如果您使用 AWS CDK Toolkit v1.70.0 或更早版本初始化 CDK 專案，您的虛擬環境位於 `.env`目錄中，而不是 `.venv`。
**重要**
開始處理專案時，請啟用專案的虛擬環境。否則，您將無法存取該處安裝的模組，而您安裝的模組將進入 Python 全域模組目錄 （或會導致許可錯誤）。
第一次啟用虛擬環境後，請安裝應用程式的標準相依性：
```
$ python -m pip install -r requirements.txt
```
## 管理 AWS 建構程式庫模組
使用 Python 套件安裝程式 `pip`來安裝和更新 AWS Construct Library 模組以供您的應用程式使用，以及您需要的其他套件。 `pip`也會自動安裝這些模組的相依性。如果您的系統無法辨識`pip`為獨立命令，請呼叫 `pip` 做為 Python 模組，如下所示：
```
$ python -m pip
```
大多數 AWS CDK 建構模組都在 中`aws-cdk-lib`。實驗模組位於名為 的個別模組中`aws-cdk..alpha`。服務名稱包含 *aws* 字首。如果您不確定模組的名稱，[請在 PyPI 中搜尋](https://pypi.org/search/?q=aws-cdk)。例如，以下命令會安裝 AWS CodeStar 程式庫。
```
$ python -m pip install aws-cdk.aws-codestar-alpha
```
有些服務的建構模組位於多個命名空間中。例如，除了 之外`aws-cdk.aws-route53`，還有三個額外的 Amazon Route 53 命名空間，名為 `aws-route53-targets`、 `aws-route53-patterns`和 `aws-route53resolver`。
**注意**
[CDK API 參考的 Python 版本](https://docs.aws.amazon.com/cdk/api/v2/python/index.html)也會顯示套件名稱。
用於將 AWS Construct Library 模組匯入 Python 程式碼的名稱如下所示。
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```
我們建議您在應用程式中匯入 AWS CDK 類別和 AWS 建構程式庫模組時採用下列實務。遵循這些準則有助於讓您的程式碼與其他 AWS CDK 應用程式保持一致，並且更容易理解。
+ 一般而言，從頂層 匯入個別類別`aws_cdk`。
```
from aws_cdk import App, Construct
```
+ 如果您需要來自 的許多類別`aws_cdk`，您可以使用 命名空間別名，`cdk`而不是匯入個別類別。避免同時執行這兩個動作。
```
import aws_cdk as cdk
```
+ 一般而言，使用短命名空間別名匯入 AWS 建構程式庫。
```
import aws_cdk.aws_s3 as s3
```
安裝模組後，請更新專案的 `requirements.txt` 檔案，其中列出專案的相依性。最好手動執行此操作，而不是使用 `pip freeze`。 會`pip freeze`擷取安裝在 Python 虛擬環境中所有模組的目前版本，這在綁定要在其他位置執行的專案時非常有用。
不過，通常，您的 `requirements.txt` 應該只列出頂層相依性 （應用程式直接依賴的模組），而不是這些程式庫的相依性。此策略可讓您更輕鬆地更新相依性。
您可以編輯 `requirements.txt` 以允許升級；只需將`==`前面的版本編號取代`~=`為 以允許升級到更高的相容版本，或完全移除版本需求以指定模組的最新可用版本。
在適當`requirements.txt`編輯以允許升級的情況下，發出此命令以隨時升級專案已安裝的模組：
```
$ pip install --upgrade -r requirements.txt
```
## 在 Python 中管理相依性
在 Python 中，您可以將應用程式或建構程式庫`requirements.txt`的相依性放入 `setup.py`，以指定相依性。然後，使用 PIP 工具管理相依性。以下列其中一種方式叫用 PIP：
```
pip
python -m pip
```
`python -m pip` 調用適用於大多數系統；`pip`要求 PIP 的可執行檔位於系統路徑上。如果 `pip`無法運作，請嘗試將其取代為 `python -m pip`。
`cdk init --language python` 命令會為您的新專案建立虛擬環境。這可讓每個專案都有自己的相依性版本，以及基本`requirements.txt`檔案。您必須`source .venv/bin/activate`在每次開始使用專案時執行 ，以啟用此虛擬環境。在 Windows 上執行 `.\venv\Scripts\activate`
### CDK 應用程式
以下是範例 `requirements.txt` 檔案。由於 PIP 沒有相依性鎖定功能，我們建議您使用 == 運算子來指定所有相依性的確切版本，如下所示。
```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```
使用 安裝模組`pip install`不會自動將其新增至 `requirements.txt`。您必須自行執行。如果您想要升級至較新版本的相依性，請在 中編輯其版本編號`requirements.txt`。
若要在建立或編輯 之後安裝或更新專案的相依性`requirements.txt`，請執行下列動作：
```
python -m pip install -r requirements.txt
```
**提示**
`pip freeze` 命令會以可寫入文字檔案的格式輸出所有已安裝相依性的版本。這可以用作 的要求檔案`pip install -r`。此檔案方便將所有相依性 （包括可轉移相依性） 鎖定到您測試的確切版本。若要避免稍後升級套件時發生問題，請為此使用不同的檔案，例如 `freeze.txt`（而非 `requirements.txt`)。然後，當您升級專案的相依性時，請將其重新產生。
### 第三方建構程式庫
在程式庫中，相依性是在 中指定`setup.py`，因此應用程式使用套件時會自動下載傳輸相依性。否則，每個想要使用套件的應用程式都需要將您的相依性複製到其 `requirements.txt`。此處`setup.py`顯示範例。
```
from setuptools import setup
setup(
name='my-package',
version='0.0.1',
install_requires=[
'aws-cdk-lib==2.14.0',
],
...
)
```
若要使用 套件進行開發，請建立或啟用虛擬環境，然後執行下列命令。
```
python -m pip install -e .
```
雖然 PIP 會自動安裝暫時性相依性，但任何一個套件只能有一個已安裝的副本。選取相依性樹狀目錄中指定的最高版本；應用程式一律在安裝的套件版本中具有最後一個單字。
## AWS Python 中的 CDK 慣用詞
### 語言衝突
在 Python 中， `lambda` 是語言關鍵字，因此您無法將其用作 AWS Lambda 建構程式庫模組或 Lambda 函數的名稱。這類衝突的 Python 慣例是在變數名稱中使用結尾底線`lambda_`，如 所示。
根據慣例， AWS CDK 建構的第二個引數名為 `id`。撰寫您自己的堆疊和建構時，呼叫參數`id`「陰影」Python 內建函數 `id()`，這會傳回物件的唯一識別符。此函數不常使用，但如果您應該在建構中需要它，請重新命名引數，例如 `construct_id`。
### 引數和屬性
所有 AWS 建構程式庫類別都會使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*ID* 和 *props*，即建構函數用來設定其建立之資源的金鑰/值對套件。其他類別和方法也會針對引數使用「屬性組合」模式。
*範圍*和 *ID* 應一律做為位置引數傳遞，而非關鍵字引數，因為如果建構接受名為*範圍*或 *ID* 的屬性，其名稱會變更。
在 Python 中，prop 會以關鍵字引數表示。如果引數包含巢狀資料結構，則會使用在執行個體化時採用自己關鍵字引數的類別來表示這些引數。相同的模式會套用至採用結構化引數的其他方法呼叫。
例如，在 Amazon S3 儲存貯體的 `add_lifecycle_rule`方法中， `transitions` 屬性是`Transition`執行個體的清單。
```
bucket.add_lifecycle_rule(
transitions=[
Transition(
storage_class=StorageClass.GLACIER,
transition_after=Duration.days(10)
)
]
)
```
延伸類別或覆寫方法時，您可能想要接受父類別無法理解的其他引數，以達成自己的目的。在此情況下，您應該接受您不在意使用 \$1\$1kwargs idiom 的引數，並使用僅限關鍵字的引數來接受您感興趣的引數。呼叫父系建構函數或覆寫方法時，僅傳遞預期的引數 （通常僅 \$1\$1kwargs)。傳遞父類別或方法預期不會導致錯誤的引數。
```
class MyConstruct(Construct):
def __init__(self, id, *, MyProperty=42, **kwargs):
super().__init__(self, id, **kwargs)
# ...
```
AWS CDK 的未來版本可能會同時新增具有您用於自有屬性名稱的新屬性。這不會對建構或方法的使用者造成任何技術問題 （因為您的屬性未傳遞「上鏈」，父類別或覆寫方法只會使用預設值），但可能會導致混淆。您可以透過命名屬性來避免此潛在問題，以便它們明確屬於您的建構。如果有許多新屬性，請將它們綁定到適當命名的類別中，並將其做為單一關鍵字引數傳遞。
### 缺少值
AWS CDK 使用 `None` 來表示遺失或未定義的值。使用 \$1\$1kwargs 時，如果未提供屬性，請使用字典的 `get()`方法提供預設值。避免使用 `kwargs[…]`，因為這會導致`KeyError`缺少值。
```
encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing
```
有些 AWS CDK 方法 （例如`tryGetContext()`取得執行時間內容值） 可能會傳回 `None`，您需要明確檢查。
### 使用界面
Python 不像其他某些語言那樣具有界面功能，但它確實具有[類似抽象的基礎類別](https://docs.python.org/3/library/abc.html)。（如果您不熟悉界面，維基百科會有[很好的介紹](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages)。) TypeScript 是實作 AWS CDK 的語言，提供界面，建構和其他 AWS CDK 物件通常需要遵循特定界面的物件，而不是繼承自特定類別。因此， AWS CDK 提供自己的界面功能，做為 [JSII](https://github.com/aws/jsii) layer 的一部分。
若要指出類別實作特定界面，您可以使用`@jsii.implements`裝飾項目：
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
### 類型陷阱
Python 使用動態類型，其中所有變數都可以參考任何類型的值。參數和傳回值可以使用 類型加上註釋，但這些是「提示」且不會強制執行。這表示在 Python 中，將不正確類型的值輕鬆傳遞至 AWS CDK 建構。當 JSII 層 （在 Python 和 AWS CDK 的 TypeScript 核心之間轉換） 無法處理非預期的類型時，您可能會改為收到執行階段錯誤，而不是在建置期間收到類型錯誤，就像從靜態類型語言一樣。
在我們的經驗中，Python 程式設計人員的類型錯誤往往屬於這些類別。
+ 傳遞單一值，其中建構需要容器 (Python 清單或字典），反之亦然。
+ 將與第 1 層 (`CfnXxxxxx`) 建構相關聯的類型值傳遞至 L2 或 L3 建構，反之亦然。
## 防止類型錯誤
AWS CDK Python 模組包含類型註釋，因此您可以使用支援它們的工具在部署之前擷取類型錯誤。
### IDE 整合 （建議）
Visual Studio Code with Pylance 在您編寫程式碼時提供即時類型檢查：
1. 安裝 [Pylance 延伸](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)模組
1. 在 中設定嚴格類型檢查`.vscode/settings.json`：
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. 類型錯誤現在會立即出現，並顯示紅色魷魚和詳細的錯誤訊息
[PyCharm](https://www.jetbrains.com/pycharm/) 也提供具有類似功能的內建類型檢查。
### 命令列類型檢查
針對 CI/CD 管道或預先遞交驗證，請使用下列其中一種類型檢查程式：
**MyPy (Python 型）：**
```
pip install mypy
mypy app.py
```
**Pyright （更快、JavaScript 型、與 Pylance 相同的引擎）：**
```
npm install -g pyright
pyright app.py
```
### 建議的工作流程
1. 在開發期間：使用 Pyright 或 Pylance 進行即時意見回饋
1. 遞交之前：執行 `mypy app.py`或 `pyright app.py`
1. 在 CI/CD 中：讓類型在部署之前檢查必要步驟
# 在 Java 中使用 AWS CDK
Java 是 AWS CDK 完全支援的用戶端語言，且被視為穩定。您可以使用熟悉的工具在 Java 中開發 AWS CDK 應用程式，包括 JDK (Oracle 的 或 OpenJDK 分佈，例如 Amazon Corretto) 和 Apache Maven。
AWS CDK 支援 Java 8 和更新版本。不過，我們建議您使用最新版本，因為較新版本的語言包含開發 AWS CDK 應用程式特別方便的改進。例如，Java 9 引入 `Map.of()`方法 （一種方便的方式，用於宣告會在 TypeScript 中寫入為物件常值的雜湊）。Java 10 使用 `var`關鍵字引入本機類型推論。
**注意**
本開發人員指南中的大多數程式碼範例都適用於 Java 8。一些範例使用 `Map.of()`；這些範例包含註解，指出他們需要 Java 9。
您可以使用任何文字編輯器或可讀取 Maven 專案的 Java IDE，來處理 AWS CDK 應用程式。我們在本指南中提供 [Eclipse](https://www.eclipse.org/downloads/) 提示，但 IntelliJ IDEA、NetBeans 和其他 IDEs 可以匯入 Maven 專案，並可用於在 Java 中開發 AWS CDK 應用程式。
可以使用 Java 以外的 JVM 託管語言 （例如 Kotlin、Groovy、Clojure 或 Scala) 撰寫 AWS CDK 應用程式，但體驗可能不特別特殊，我們無法為這些語言提供任何支援。
## Java 入門
若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱 [AWS CDK 入門](getting-started.md)。
Java AWS CDK 應用程式需要 Java 8 (v1.8) 或更新版本。我們建議使用 [Amazon Corretto](https://aws.amazon.com/corretto/)，但您可以使用任何 OpenJDK 分佈或 [Oracle 的 JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)。您也需要 [Apache Maven](https://maven.apache.org/download.cgi) 3.5 或更新版本。您也可以使用 Gradle 等工具，但 AWS CDK Toolkit 產生的應用程式骨架是 Maven 專案。
**注意**
第三方語言棄用：只有在廠商或社群共用其 EOL （生命週期結束） 之前，才支援語言版本，且可能會有所變更，恕不另行通知。
## 建立專案
您可以透過`cdk init`在空目錄中叫用 來建立新的 AWS CDK 專案。使用 `--language`選項並指定 `java`：
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language java
```
`cdk init` 使用專案資料夾的名稱來命名專案的各種元素，包括類別、子資料夾和檔案。資料夾名稱中的連字號會轉換為底線。不過，名稱應該遵循 Java 識別符的形式；例如，不應以數字開頭或包含空格。
產生的專案包含 `software.amazon.awscdk` Maven 套件的參考。Maven 會自動安裝它及其相依性。
如果您使用的是 IDE，您現在可以開啟或匯入專案。例如，在 Eclipse 中，選擇**檔案** > **匯入** > **Maven** > **現有 Maven 專案**。確定專案設定設定為使用 Java 8 (1.8)。
## 管理 AWS 建構程式庫模組
使用 Maven 安裝組 中的 AWS 建構程式庫套件`software.amazon.awscdk`。大多數建構在成品 中`aws-cdk-lib`，預設會新增至新的 Java 專案。目前仍在開發更高層級 CDK 支援之服務的模組，採用個別的「實驗性」套件，以其服務名稱的簡短版本 （無 AWS 或 Amazon 字首） 命名。[搜尋 Maven 中央儲存庫](https://search.maven.org/search?q=software.amazon.awscdk)，尋找所有 AWS CDK 和 AWS 建構模組程式庫的名稱。
**注意**
[CDK API 參考的 Java 版本](https://docs.aws.amazon.com/cdk/api/v2/java/index.html)也會顯示套件名稱。
有些服務「 AWS 建構程式庫支援位於多個命名空間中。例如，Amazon Route 53 的功能分為 `software.amazon.awscdk.route53`、`route53-patterns`、 `route53resolver`和 `route53-targets`。
主要 AWS CDK 套件會以 Java 程式碼匯入為 `software.amazon.awscdk`。 AWS Construct Library 中各種服務的模組位於 下`software.amazon.awscdk.services`，且名稱與其 Maven 套件名稱類似。例如，Amazon S3 模組的命名空間為 `software.amazon.awscdk.services.s3`。
我們建議您為每個 Java 來源檔案中使用的每個 AWS 建構程式庫類別撰寫單獨的 Java `import`陳述式，並避免萬用字元匯入。您可以隨時使用類型的完整名稱 （包括其命名空間），無需 `import`陳述式。
如果您的應用程式依賴實驗套件，請編輯專案的 ，`pom.xml`並在``容器中新增``元素。例如，下列``元素指定 CodeStar 實驗建構程式庫模組：
```
software.amazon.awscdk
codestar-alpha
2.0.0-alpha.10
```
**提示**
如果您使用 Java IDE，它可能具有管理 Maven 相依性的功能。不過，我們建議您`pom.xml`直接編輯 ，除非您確定 IDE 的功能符合您手動執行的操作。
## 在 Java 中管理相依性
在 Java 中，相依性是在 中指定，`pom.xml`並使用 Maven 安裝。`` 容器包含每個套件的 ``元素。以下是`pom.xml`典型 CDK Java 應用程式的 區段。
```
software.amazon.awscdk
aws-cdk-lib
2.14.0
software.amazon.awscdk
appsync-alpha
2.10.0-alpha.0
```
**提示**
許多 Java IDEs都有整合的 Maven 支援和視覺化`pom.xml`編輯器，您可能會發現這對於管理相依性非常方便。
Maven 不支援相依性鎖定。雖然您可以在 中指定版本範圍`pom.xml`，但我們建議您一律使用確切的版本來保持建置可重複。
Maven 會自動安裝傳輸相依性，但每個套件只能有一個已安裝的副本。已選取 POM 樹狀目錄中指定的最高版本；應用程式一律在安裝的套件版本中具有最後一個字。
Maven 會在您建置 (`mvn compile`) 或封裝 (`mvn package`) 專案時自動安裝或更新相依性。CDK Toolkit 會在每次執行時自動執行此操作，因此通常不需要手動叫用 Maven。
## AWS Java 中的 CDK 慣用語
### 屬性
所有 AWS 建構程式庫類別都會使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*id* 和 *props*，即建構函數用來設定其建立之資源的金鑰/值對套件。其他類別和方法也會針對引數使用「屬性組合」模式。
在 Java 中，props 是使用 [Builder 模式](https://en.wikipedia.org/wiki/Builder_pattern)來表示。每個建構類型都有對應的道具類型；例如，建構 `Bucket` （代表 Amazon S3 儲存貯體） 採用 做為其道具 執行個體`BucketProps`。
`BucketProps` 類別 （如同每個 AWS Construct Library props 類別） 具有稱為 的內部類別`Builder`。`BucketProps.Builder` 類型提供設定`BucketProps`執行個體各種屬性的方法。每個方法都會傳回`Builder`執行個體，因此方法呼叫可以鏈結以設定多個屬性。在鏈結結尾，您可以呼叫 `build()` 來實際產生`BucketProps`物件。
```
Bucket bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps.Builder()
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build());
```
建構和其他使用類似道具物件作為其最終引數的類別，提供捷徑。類別具有`Builder`自己的 ，可在一個步驟中執行個體化它及其道具物件。如此一來，您不需要明確執行個體化 （例如） `BucketProps`和 `Bucket`--，而且您不需要匯入 props 類型。
```
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build();
```
從現有的建構中衍生自己的建構時，您可能想要接受其他屬性。我們建議您遵循這些建置器模式。不過，這不如將建構類別子分類那麼簡單。您必須自行提供兩個新`Builder`類別的移動部分。您可能只想讓您的建構接受一或多個額外的引數。當 引數為選用時，您應該提供額外的建構函數。
### 一般結構
在某些 APIs中， AWS CDK 會使用 JavaScript 陣列或未輸入物件做為方法的輸入。（例如，請參閱 AWS CodeBuild 的 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue)方法。) 在 Java 中，這些物件會以 表示`java.util.Map`。如果這些值都是字串，您可以使用 `Map`。
Java 不提供撰寫這類容器常值的方法，就像其他語言一樣。在 Java 9 和更新版本中，您可以使用 [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-) 來輕鬆地定義最多十個項目的映射，這些項目與其中一個呼叫內嵌。
```
java.util.Map.of(
"base-directory", "dist",
"files", "LambdaStack.template.json"
)
```
若要建立超過十個項目的映射，請使用 [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-)。
如果您使用的是 Java 8，您可以提供自己的方法，類似於這些方法。
JavaScript 陣列在 Java `List`中以 `List