TypeScript 入門建立專案使用本機 tsc 和 cdk 管理 AWS 建構程式庫模組在中管理相依性 TypeScript AWS CDK TypeScript 中的慣用語建置並執行 CDK 應用程式

在 TypeScript AWS CDK 中使用

TypeScript 是完全支援的用戶端語言， AWS Cloud Development Kit (AWS CDK) 且被視為穩定。在 TypeScript AWS CDK 中使用會使用熟悉的工具，包括 Microsoft 的 TypeScript 編譯器 (tsc)、Node.js 和 Node Package Manager (npm)。如果您願意，也可以使用 Yarn，但本指南中的範例使用 NPM。包含 AWS Construct Library 的模組會透過 NPM 儲存庫 npmjs.org 進行分發。

您可以使用任何編輯器或 IDE。許多 AWS CDK 開發人員使用 Visual Studio Code （或其開放原始碼對等 VSCodium)，其對 TypeScript 有絕佳的支援。

TypeScript 入門

若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱入門 AWS CDK。

您也需要 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

建立專案也會安裝aws-cdk-lib模組及其相依性。

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 ...` or `npx aws-cdk ...`

npx aws-cdk 會執行目前專案中本機安裝的 CDK Toolkit 版本，如果有的話，請返回全域安裝。如果沒有全域安裝，會npx下載 CDK Toolkit 的臨時複本並執行該複本。您可以使用語法：npx aws-cdk@2.0 --version列印 @ 來指定 CDK Toolkit 的任意版本2.0.0。

提示

設定別名，以便您可以搭配本機 CDK Toolkit 安裝使用 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/SERVICE-NAME-alpha。服務名稱具有 aws- 字首。如果您不確定模組的名稱，請在 NPM 上搜尋。

注意

CDK API 參考也會顯示套件名稱。

例如，以下命令會安裝實驗模組 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。您可以使用 caret (^) 版本編號規範符，指出只要版本位於相同的主要版本，您接受的版本會比指定的版本更高。

對於實驗建構，請指定 alpha 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。請不要使用 ^ 或 ~，因為這些模組的較新版本可能會帶來 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，使用 caret (^) 指定aws-cdk-lib程式庫使用的最低版本。這可最大限度地提高程式庫與各種 CDK 版本的相容性。指定 alpha 建構程式庫模組的確切版本，這些模組具有可能會變更APIs。使用 peerDependencies可確保樹狀目錄中只有一個 CDK node_modules 程式庫的副本。

在中devDependencies，指定測試所需的工具和程式庫，選擇性地使用 ^ 來表示可接受較新的相容版本。準確指定（不含 ^ 或 ~) 您公告程式庫的 aws-cdk-lib和其他 CDK 套件的最低版本相容。此實務可確保您的測試會針對這些版本執行。如此一來，如果您不小心使用只在較新版本中找到的功能，您的測試可能會攔截到它。

警告

peerDependencies 僅由 NPM 7 和更新版本自動安裝。如果您使用的是 NPM 6 或更早版本，或者您使用 Yarn，則必須在中包含相依性的相依性devDependencies。否則，系統不會安裝它們，而且您將收到有關未解析對等相依性的警告。

安裝和更新相依性

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

若要更新已安裝的模組，可以使用上述 npm install和 yarn upgrade命令。任一命令都會將中的套件更新node_modules為符合中規則的最新版本package.json。不過，它們不會更新package.json本身，您可能想要這樣做來設定新的最低版本。如果您在 GitHub 上託管套件，您可以設定 Dependabot 版本更新以自動更新 package.json。或者，使用 npm-check-updates。

重要

根據設計，當您安裝或更新相依性時，NPM 和 Yarn 會選擇符合中指定需求的每個套件的最新版本package.json。這些版本一律有損壞的風險（意外或刻意）。更新專案的相依性後，請徹底測試。

AWS CDK TypeScript 中的慣用語

道具

所有 AWS 建構程式庫類別都是使用三個引數來執行個體化：定義建構的範圍 （其在建構樹中的父系）、id 和 prop。引數道具是一組鍵/值對，建構用來設定其建立 AWS 的資源。其他類別和方法也會使用「屬性組合」模式做為引數。

在 TypeScript 中，的形狀props是使用界面來定義，該界面會告訴您必要和選用的引數及其類型。這類界面是針對每種props引數來定義，通常是針對單一建構或方法。例如，儲存貯體建構（在中aws-cdk-lib/aws-s3 module) 會指定符合 BucketProps 介面的props引數。

如果屬性本身是物件，例如的 websiteRedirect 屬性BucketProps，則該物件會有其形狀必須符合的自有界面，在此情況下為 RedirectTarget。

如果您要將 AWS Construct Library 類別子類別（或覆寫採用類似 props 引數的方法），您可以從現有界面繼承，以建立新的界面，指定程式碼所需的任何新 props。呼叫父類別或基礎方法時，通常您可以傳遞您收到的整個 props 引數，因為在物件中提供但未在界面中指定的任何屬性都會遭到忽略。

未來的版本 AWS CDK 可能會意外地新增具有您用於自己屬性名稱的新屬性。然後，傳遞您收到的繼承鏈值可能會導致意外行為。將屬性移除或設定為時收到的道具淺版傳遞給會更安全undefined。例如：


super(scope, name, {...props, encryptionKeys: undefined});

或者，為您的屬性命名，以便清楚它們屬於您的建構。如此一來，它們不太可能在未來 AWS CDK 版本中與屬性碰撞。如果其中有許多，請使用單一適當命名的物件來保留它們。

缺少值

物件（例如 props) 中缺少的值，其值位於 TypeScript undefined中。3.7 版的語言引進了運算子，可簡化使用這些值的操作，當達到未定義的值時，更容易指定預設值和「短路」鏈結。如需這些功能的詳細資訊，請參閱 TypeScript 3.7 版本備註，特別是前兩個功能：選用鏈結和 Nullish Coalescing。

建置並執行 CDK 應用程式

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

Node.js 無法直接執行 TypeScript；而是您的應用程式會使用 TypeScript 編譯器轉換為 JavaScripttsc。然後執行產生的 JavaScript 程式碼。

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 CDK 程式庫

在 JavaScript 中