Dies ist der AWS CDK v2-Entwicklerhandbuch. Die ältere CDK Version 1 wurde am 1. Juni 2022 in die Wartung aufgenommen und der Support wurde am 1. Juni 2023 eingestellt.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Arbeiten mit AWS CDK dem JavaScript

JavaScriptist eine vollständig unterstützte Client-Sprache für die AWS CDK und gilt als stabil. Bei der Arbeit mit dem AWS Cloud Development Kit (AWS CDK) In werden vertraute Tools JavaScript verwendet, darunter Node.js und der Node Package Manager (npm). Sie können auch Yarn verwenden, wenn Sie dies bevorzugen, obwohl die Beispiele in diesem Handbuch dies verwendenNPM. Die Module, aus denen die AWS Construct-Bibliothek besteht, werden über das NPM Repository npmjs.org vertrieben.

Sie können einen beliebigen Editor verwenden oder. IDE Viele AWS CDK Entwickler verwenden Visual Studio Code (oder sein Open-Source-Äquivalent VSCodium), das eine gute Unterstützung für JavaScript bietet.

Erste Schritte mit JavaScript

Um mit dem arbeiten zu können AWS CDK, müssen Sie über ein AWS Konto und Anmeldeinformationen verfügen und Node.js und das AWS CDK Toolkit installiert haben. Siehe Erste Schritte mit dem AWS CDK.

JavaScript AWS CDK Für Anwendungen sind darüber hinaus keine weiteren Voraussetzungen erforderlich.

Erstellen eines Projekts

Sie erstellen ein neues AWS CDK Projekt, indem Sie es cdk init in einem leeren Verzeichnis aufrufen. Verwenden Sie die --language Option und geben Sie anjavascript:

mkdir my-project
cd my-project
cdk init app --language javascript

Beim Erstellen eines Projekts werden auch das aws-cdk-libModul und seine Abhängigkeiten installiert.

cdk initverwendet den Namen des Projektordners, um verschiedene Elemente des Projekts zu benennen, einschließlich Klassen, Unterordnern und Dateien. Bindestriche im Ordnernamen werden in Unterstriche umgewandelt. Ansonsten sollte der Name jedoch die Form eines JavaScript Bezeichners haben; er sollte beispielsweise nicht mit einer Zahl beginnen oder Leerzeichen enthalten.

Lokal verwenden cdk

In diesem Handbuch wird größtenteils davon ausgegangen, dass Sie das CDK Toolkit global (npm install -g aws-cdk) installieren, und die bereitgestellten Befehlsbeispiele (wiecdk synth) folgen dieser Annahme. Dieser Ansatz macht es einfach, das CDK Toolkit auf dem neuesten Stand zu halten, und da es einen strikten Ansatz zur Abwärtskompatibilität CDK verfolgt, besteht im Allgemeinen nur ein geringes Risiko, immer die neueste Version zu verwenden.

Einige Teams ziehen es vor, alle Abhängigkeiten innerhalb jedes Projekts anzugeben, einschließlich Tools wie dem CDK Toolkit. Auf diese Weise können Sie solche Komponenten bestimmten Versionen zuordnen und sicherstellen, dass alle Entwickler in Ihrem Team (und Ihrer CI/CD-Umgebung) genau diese Versionen verwenden. Dadurch wird eine mögliche Änderungsquelle vermieden, was dazu beiträgt, Builds und Bereitstellungen konsistenter und wiederholbarer zu gestalten.

Das CDK beinhaltet eine Abhängigkeit für das CDK Toolkit in den JavaScript Projektvorlagen. Wenn Sie also diesen Ansatz verwenden möchten, müssen Sie keine Änderungen an Ihrem Projekt vornehmen. package.json Sie müssen lediglich leicht unterschiedliche Befehle zum Erstellen Ihrer App und zum Ausgeben von cdk Befehlen verwenden.

npx aws-cdkführt die lokal im aktuellen Projekt installierte Version des CDK Toolkits aus, falls vorhanden, und greift dabei auf die globale Installation zurück, falls vorhanden. Wenn keine globale Installation vorhanden ist, wird eine temporäre Kopie des CDK Toolkits npx heruntergeladen und ausgeführt. Sie können eine beliebige Version des CDK Toolkits mit der folgenden @ Syntax angeben: npx aws-cdk@1.120 --version prints. 1.120.0

AWS Construct Library-Module verwalten

Verwenden Sie den Node Package Manager (npm), um AWS Construct Library-Module für Ihre Apps sowie andere Pakete, die Sie benötigen, zu installieren und zu aktualisieren. (Sie können yarn stattdessen verwenden, npm wenn Sie es vorziehen.) npminstalliert auch die Abhängigkeiten für diese Module automatisch.

Die meisten AWS CDK Konstrukte befinden sich im CDK Hauptpaket mit dem Namen. Dies ist eine Standardabhängigkeit in neuen Projektenaws-cdk-lib, die von cdk init erstellt wurden. Module der „experimentellen“ AWS Construct-Bibliothek, bei denen sich übergeordnete Konstrukte noch in der Entwicklung befinden, werden wie benannt. aws-cdk-lib/SERVICE-NAME-alpha Der Dienstname hat ein aws-Präfix. Wenn Sie sich nicht sicher sind, wie ein Modul heißt, suchen Sie auf NPM.

Mit dem folgenden Befehl wird beispielsweise das experimentelle Modul für installiert AWS CodeStar.

npm install @aws-cdk/aws-codestar-alpha

Die Construct Library-Unterstützung einiger Dienste erfolgt in mehr als einem Namespace. Außerdem gibt es aws-route53 beispielsweise drei zusätzliche Amazon Route 53-Namespaces,aws-route53-targets, aws-route53-patterns und. aws-route53resolver

Die Abhängigkeiten Ihres Projekts werden in verwaltet. package.json Sie können diese Datei bearbeiten, um einige oder alle Ihrer Abhängigkeiten für eine bestimmte Version zu sperren oder um zu ermöglichen, dass sie unter bestimmten Kriterien auf neuere Versionen aktualisiert werden. So aktualisieren Sie die NPM Abhängigkeiten Ihres Projekts gemäß den Regeln, die Sie in angegeben haben, auf die neueste zulässige Versionpackage.json:

npm update

JavaScriptIn importieren Sie Module in Ihren Code unter demselben Namen, mit dem Sie sie installiert habenNPM. Wir empfehlen die folgenden Methoden, wenn Sie AWS CDK Klassen und AWS Construct Library-Module in Ihre Anwendungen importieren. Das Befolgen dieser Richtlinien trägt dazu bei, dass Ihr Code mit anderen AWS CDK Anwendungen konsistent und verständlicher ist.

Verwaltung von Abhängigkeiten in JavaScript

In JavaScript CDK Projekten werden Abhängigkeiten in der package.json Datei im Hauptverzeichnis des Projekts angegeben. Die AWS CDK Kernmodule befinden sich in einem einzigen NPM Paket namensaws-cdk-lib.

Wenn Sie ein Paket mitnpm install, installieren, NPM zeichnet das Paket package.json für Sie auf.

Wenn Sie möchten, können Sie Yarn anstelle von verwendenNPM. Der plug-and-play Modus von Yarn, der in Yarn 2 der Standardmodus ist, wird jedoch CDK nicht unterstützt. Fügen Sie der .yarnrc.yml Datei Ihres Projekts Folgendes hinzu, um diese Funktion zu deaktivieren.

nodeLinker: node-modules

CDKAnwendungen

Im Folgenden finden Sie eine package.json Beispieldatei, die mit dem cdk init --language typescript Befehl generiert wurde. Die generierte Datei für JavaScript ist ähnlich, nur ohne die TypeScript zugehörigen Einträge.

{
  "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"
  }
}

Für bereitstellbare CDK Apps aws-cdk-lib muss dies im dependencies Abschnitt von package.json angegeben werden. Sie können die Versionsnummer mit einem Caret-Zeichen (^) angeben, dass Sie neuere Versionen als die angegebene akzeptieren, sofern sie sich in derselben Hauptversion befinden.

Geben Sie für experimentelle Konstrukte die exakten Versionen der Alpha-Konstruktbibliotheksmodule an, bei denen sich APIs das ändern kann. Verwenden Sie nicht ^ oder ~, da spätere Versionen dieser Module API Änderungen mit sich bringen können, die Ihre App beschädigen können.

Geben Sie im devDependencies Abschnitt von die Versionen der Bibliotheken und Tools an, die Sie zum jest Testen Ihrer App benötigen (z. B. das Test-Framework)package.json. Verwenden Sie optional ^, um anzugeben, dass spätere kompatible Versionen zulässig sind.

Konstruktbibliotheken von Drittanbietern

Wenn Sie eine Konstruktbibliothek entwickeln, geben Sie deren Abhängigkeiten mithilfe einer Kombination aus den devDependencies Abschnitten peerDependencies und an, wie in der folgenden package.json Beispieldatei gezeigt.

{
  "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"
  }
}

Verwenden Sie in peerDependencies ein Caret-Zeichen (^), um die niedrigste Version anzugebenaws-cdk-lib, mit der Ihre Bibliothek arbeitet. Dadurch wird die Kompatibilität Ihrer Bibliothek mit einer Reihe von CDK Versionen maximiert. Geben Sie genaue Versionen für Alpha-Construct-Bibliotheksmodule an, bei denen sich APIs das ändern kann. peerDependenciesDurch die Verwendung wird sichergestellt, dass nur eine Kopie aller CDK Bibliotheken im node_modules Baum vorhanden ist.

Geben Sie in die Tools und Bibliotheken andevDependencies, die Sie zum Testen benötigen, optional mit ^, um anzugeben, dass spätere kompatible Versionen zulässig sind. Geben Sie genau (ohne ^ oder ~) die niedrigsten Versionen aws-cdk-lib und andere CDK Pakete an, mit denen Sie angeben, dass Ihre Bibliothek kompatibel ist. Diese Vorgehensweise stellt sicher, dass Ihre Tests mit diesen Versionen ausgeführt werden. Wenn Sie also versehentlich eine Funktion verwenden, die nur in neueren Versionen zu finden ist, können Ihre Tests sie catch.

Abhängigkeiten installieren und aktualisieren

Führen Sie den folgenden Befehl aus, um die Abhängigkeiten Ihres Projekts zu installieren.

NPM

# 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

Yarn

# 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

Um die installierten Module zu aktualisieren, können die vorherigen yarn upgrade Befehle npm install und verwendet werden. Mit beiden Befehlen werden die Pakete node_modules auf die neuesten Versionen aktualisiert, die den Regeln von entsprechenpackage.json. Sie aktualisieren package.json sich jedoch nicht von selbst, was Sie möglicherweise tun sollten, um eine neue Mindestversion festzulegen. Wenn Sie Ihr Paket auf hosten GitHub, können Sie Dependabot-Versionsupdates so konfigurieren, dass sie automatisch aktualisiert werden. package.json Als alternative Vorgehensweise verwenden Sie npm-check-updates.

AWS CDK Redewendungen in JavaScript

Requisiten

Alle AWS Construct-Library-Klassen werden mit drei Argumenten instanziiert: dem Bereich, in dem das Konstrukt definiert wird (sein übergeordnetes Objekt im Konstruktbaum), einer ID und props, einem Bündel von Schlüssel/Wert-Paaren, die das Konstrukt verwendet, um die von ihm erstellten Ressourcen zu konfigurieren. AWS Andere Klassen und Methoden verwenden ebenfalls das Muster „Bündel von Attributen“ für Argumente.

Wenn Sie einen IDE OR-Editor mit guter JavaScript Autovervollständigung verwenden, können Sie vermeiden, dass Eigenschaftsnamen falsch geschrieben werden. Wenn ein Konstrukt eine encryptionKeys Eigenschaft erwartet und Sie sie buchstabierenencryptionkeys, haben Sie bei der Instanziierung des Konstrukts nicht den gewünschten Wert übergeben. Dies kann bei der Synthese zu einem Fehler führen, wenn die Eigenschaft erforderlich ist, oder dazu führen, dass die Eigenschaft stillschweigend ignoriert wird, wenn sie optional ist. In letzterem Fall erhalten Sie möglicherweise ein Standardverhalten, das Sie überschreiben wollten. Seien Sie hier besonders vorsichtig.

Wenn Sie einer AWS Construct Library-Klasse eine Unterklasse zuordnen (oder eine Methode überschreiben, die ein Argument wie Requisiten verwendet), möchten Sie möglicherweise zusätzliche Eigenschaften für Ihren eigenen Gebrauch akzeptieren. Diese Werte werden von der übergeordneten Klasse oder überschriebenen Methode ignoriert, da in diesem Code nie auf sie zugegriffen wird. Sie können also generell alle Requisiten weitergeben, die Sie erhalten haben.

In einer future Version von AWS CDK könnte zufällig eine neue Immobilie mit einem Namen hinzugefügt werden, den Sie für Ihre eigene Immobilie verwendet haben. Wenn Sie den erhaltenen Wert in der Vererbungskette weiterleiten, kann dies zu unerwartetem Verhalten führen. Es ist sicherer, eine oberflächliche Kopie der Requisiten weiterzugeben, die Sie erhalten haben, wenn Ihr Eigentum entfernt oder auf undefined Null gesetzt wurde. Beispielsweise:

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

Sie können Ihre Eigenschaften auch so benennen, dass klar ist, dass sie zu Ihrem Konstrukt gehören. Auf diese Weise ist es unwahrscheinlich, dass sie in future AWS CDK Versionen mit Eigenschaften kollidieren werden. Wenn es viele von ihnen gibt, verwenden Sie ein einzelnes Objekt mit dem entsprechenden Namen, um sie zu speichern.

Fehlende Werte

Fehlende Werte in einem Objekt (z. B.props) haben den Wert in. undefined JavaScript Für den Umgang mit diesen gelten die üblichen Techniken. Ein gängiges Idiom für den Zugriff auf eine Eigenschaft mit einem möglicherweise undefinierten Wert lautet beispielsweise wie folgt:

// 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;

Wenn es aber a auch noch einen anderen „falschen“ Wert geben könnte, ist es besserundefined, den Test expliziter zu machen. Hier machen wir uns die Tatsache zunutze, dass null und gleich undefined sind, um beide gleichzeitig zu testen:

let c = a == null ? a : a.b;

Verwenden von Beispielen mit TypeScript JavaScript

TypeScriptist die Sprache, die wir für die Entwicklung von verwenden AWS CDK, und es war die erste Sprache, die für die Entwicklung von Anwendungen unterstützt wurde. Daher sind viele verfügbare AWS CDK Codebeispiele in dieser Sprache geschrieben TypeScript. Diese Codebeispiele können eine gute Quelle für JavaScript Entwickler sein. Sie müssen nur die TypeScript -spezifischen Teile des Codes entfernen.

TypeScript In Codefragmenten werden häufig die export Schlüsselwörter new ECMAScript import und verwendet, um Objekte aus anderen Modulen zu importieren und die Objekte so zu deklarieren, dass sie außerhalb des aktuellen Moduls verfügbar gemacht werden. Node.js hat gerade damit begonnen, diese Schlüsselwörter in seinen neuesten Versionen zu unterstützen. Abhängig von der Version von Node.js, die Sie verwenden (oder unterstützen möchten), können Sie Importe und Exporte so umschreiben, dass sie die ältere Syntax verwenden.

Importe können durch Aufrufe der require() Funktion ersetzt werden.

TypeScript

import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';

JavaScript

const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');

Exporte können dem module.exports Objekt zugewiesen werden.

TypeScript

export class Stack1 extends cdk.Stack {
  // ...
}

export class Stack2 extends cdk.Stack {
  // ...
}

JavaScript

class Stack1 extends cdk.Stack {
  // ...
}

class Stack2 extends cdk.Stack {
  // ...
}

module.exports = { Stack1, Stack2 }

Sobald Sie die Importe und Exporte sortiert haben, können Sie sich mit dem eigentlichen Code befassen. Möglicherweise stoßen Sie auf diese häufig verwendeten Funktionen TypeScript :

Typanmerkungen können für Variablen, Klassenmitglieder, Funktionsparameter und Funktionsrückgabetypen bereitgestellt werden. Bei Variablen, Parametern und Elementen werden Typen angegeben, indem hinter dem Bezeichner ein Doppelpunkt und der Typ stehen. Funktionsrückgabewerte folgen der Funktionssignatur und bestehen aus einem Doppelpunkt und dem Typ.

Um Code mit Typanmerkungen in umzuwandeln JavaScript, entfernen Sie den Doppelpunkt und den Typ. Klassenmitglieder müssen einen bestimmten Wert in JavaScript haben. Setzen Sie sie auf, undefined wenn sie nur eine Typanmerkung enthalten. TypeScript

TypeScript

var encrypted: boolean = true;

class myStack extends cdk.Stack {
    bucket: s3.Bucket;
    // ...
}

function makeEnv(account: string, region: string) : object {
    // ...
}

JavaScript

var encrypted = true;

class myStack extends cdk.Stack {
    bucket = undefined;
    // ...
}

function makeEnv(account, region) {
    // ...
}

In werden Schnittstellen verwendet TypeScript, um Bündeln von erforderlichen und optionalen Eigenschaften und ihren Typen einen Namen zu geben. Anschließend können Sie den Schnittstellennamen als Typanmerkung verwenden. TypeScript stellt sicher, dass das Objekt, das Sie beispielsweise als Argument für eine Funktion verwenden, die erforderlichen Eigenschaften der richtigen Typen hat.

interface myFuncProps {
    code: lambda.Code,
    handler?: string
}

JavaScript hat keine Schnittstellenfunktion. Wenn Sie also die Typanmerkungen entfernt haben, löschen Sie die Schnittstellendeklarationen vollständig.

Wenn eine Funktion oder Methode einen Allzwecktyp (z. B.object) zurückgibt, Sie diesen Wert aber als spezifischeren untergeordneten Typ behandeln möchten, um auf Eigenschaften oder Methoden zuzugreifen, die nicht Teil der Schnittstelle des allgemeineren Typs sind, TypeScript können Sie den Wert mit einem Typ- oder as Schnittstellennamen umwandeln. JavaScript unterstützt (oder benötigt) dies nicht, also entfernen Sie einfach den folgenden as Bezeichner. Eine weniger gebräuchliche Umwandlungssyntax besteht darin<LikeThis>, einen Typnamen in Klammern zu verwenden. Auch diese Umwandlungen müssen entfernt werden.

Schließlich werden die Zugriffsmodifizierer publicprotected, und private für Mitglieder von Klassen TypeScript unterstützt. Alle Klassenmitglieder JavaScript sind öffentlich. Entfernen Sie diese Modifikatoren einfach, wo immer Sie sie sehen.

Zu wissen, wie man diese TypeScript Merkmale identifiziert und entfernt, trägt wesentlich dazu bei, kurze TypeScript Ausschnitte an sie anzupassen. JavaScript Es kann jedoch unpraktisch sein, längere TypeScript Beispiele auf diese Weise zu konvertieren, da sie mit größerer Wahrscheinlichkeit andere Funktionen verwenden. TypeScript Für diese Situationen empfehlen wir Sucrase. Sucrase wird sich nicht beschweren, wenn Code beispielsweise eine undefinierte Variable verwendet, wie es der Fall wäre. tsc Wenn es syntaktisch gültig ist, kann Sucrase es mit wenigen Ausnahmen in übersetzen. JavaScript Dies macht es besonders nützlich für die Konvertierung von Snippets, die möglicherweise nicht eigenständig ausgeführt werden können.

Migration zu TypeScript

Viele JavaScript Entwickler wechseln dazu TypeScript, wenn ihre Projekte größer und komplexer werden. TypeScript ist eine Obermenge von JavaScript — der gesamte JavaScript Code ist gültiger TypeScript Code, sodass keine Änderungen an Ihrem Code erforderlich sind — und es ist auch eine unterstützte Sprache. AWS CDK Typanmerkungen und andere TypeScript Funktionen sind optional und können zu Ihrer AWS CDK App hinzugefügt werden, wenn Sie einen Mehrwert darin finden. TypeScript bietet Ihnen außerdem frühzeitig Zugriff auf neue JavaScript Funktionen wie optionales Chaining und Nullish-Coalescing, bevor diese fertiggestellt sind — und das, ohne dass Sie Node.js aktualisieren müssen.

TypeScriptDie „formbasierten“ Schnittstellen, die Bündel erforderlicher und optionaler Eigenschaften (und ihrer Typen) innerhalb eines Objekts definieren, ermöglichen es, häufig auftretende Fehler beim Schreiben des Codes aufzudecken und erleichtern es Ihnen, aussagekräftige Autocomplete-Funktionen und andere Codierungshinweise in Echtzeit bereitzustellen. IDE

Das Eincodieren TypeScript erfordert einen zusätzlichen Schritt: das Kompilieren Ihrer App mit dem Compiler,. TypeScript tsc Bei typischen AWS CDK Apps dauert die Kompilierung höchstens einige Sekunden.

Der einfachste Weg, eine bestehende JavaScript AWS CDK App zu migrieren, TypeScript besteht darin, ein neues TypeScript Projekt zu erstellencdk init app --language typescript, indem Sie Ihre Quelldateien (und alle anderen erforderlichen Dateien, z. B. Ressourcen wie AWS Lambda Funktionsquellcode) verwenden und dann in das neue Projekt kopieren. Benennen Sie Ihre JavaScript Dateien so um, dass sie in enden .ts und mit der Entwicklung beginnen TypeScript.