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

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

# 在 TypeScript 中使用 AWS CDK
<a name="work-with-cdk-typescript"></a>

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 入門
<a name="typescript-prerequisites"></a>

若要使用 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 （生命週期結束） 之前，才支援語言版本，且可能會有所變更，恕不另行通知。

## 建立專案
<a name="typescript-newproject"></a>

您可以透過`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`
<a name="typescript-local"></a>

在大部分情況下，本指南假設您全域安裝 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 建構程式庫模組
<a name="typescript-managemodules"></a>

使用 Node Package Manager (`npm`) 來安裝和更新 AWS Construct Library 模組，以供您的應用程式以及您需要的其他套件使用。（您可以`yarn`改為使用 。`npm`) `npm`也會自動安裝這些模組的相依性。

大多數 AWS CDK 建構模組位於名為 的主 CDK 套件中`aws-cdk-lib`，這是 所建立新專案的預設相依性`cdk init`。"Experimental" AWS Construct Library 模組，其中更高層級的建構仍在開發中，命名為 `@aws-cdk/<SERVICE-NAME>-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 中管理相依性
<a name="work-with-cdk-typescript-dependencies"></a>

在 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 應用程式
<a name="work-with-cdk-typescript-dependencies-apps"></a>

以下是 `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`。或者，使用 ^ 指定可接受較新的相容版本。

### 第三方建構程式庫
<a name="work-with-cdk-typescript-dependencies-libraries"></a>

如果您正在開發建構程式庫，請使用 `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`。否則，不會安裝它們，而且您將收到有關未解決對等相依性的警告。

### 安裝和更新相依性
<a name="work-with-cdk-typescript-dependencies-install"></a>

執行下列命令來安裝專案的相依性。

**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 慣用詞
<a name="typescript-cdk-idioms"></a>

### Props
<a name="typescript-props"></a>

所有 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 版本中的屬性碰撞。如果其中有許多，請使用單一適當命名的物件來保留它們。

### 缺少值
<a name="typescript-missing-values"></a>

物件 （例如 props) 中的遺失值具有 TypeScript `undefined` 中的值。3.7 版的語言引進了可簡化使用這些值的運算子，當達到未定義的值時，更容易指定預設值和「短路」鏈結。如需這些功能的詳細資訊，請參閱 [TypeScript 3.7 版本備註](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)，特別是前兩個功能：選用鏈結和 Nullish Coalescing。

## 建置並執行 CDK 應用程式
<a name="typescript-running"></a>

一般而言，在建置和執行應用程式時，您應該位於專案的根目錄中。

Node.js 無法直接執行 TypeScript；反之，您的應用程式會使用 TypeScript 編譯器 轉換為 JavaScript`tsc`。接著會執行產生的 JavaScript 程式碼。

 AWS CDK 會在需要執行應用程式時自動執行此操作。不過，手動編譯 以檢查錯誤和執行測試會很有用。若要手動編譯 TypeScript 應用程式，請發出 `npm run build`。您也可以發出 `npm run watch`進入監看模式，其中 TypeScript 編譯器會在您將變更儲存到來源檔案時自動重建您的應用程式。