Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 gewartet 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 der AWS CDK in JavaScript

JavaScript ist eine vollständig unterstützte Client-Sprache für das AWS CDK und gilt als stabil. Beim Arbeiten mit dem AWS Cloud Development Kit (AWS CDK) in werden vertraute Tools JavaScript verwendet, einschließlich Node.js und Node Package Manager (npm). Sie können Yarn auch verwenden, wenn Sie möchten, obwohl die Beispiele in diesem Handbuch NPM verwenden. Die Module, aus denen die AWS Construct Library besteht, werden über das NPM-Repository npmjs.org verteilt.

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

Erste Schritte mit JavaScript

Um mit der zu arbeiten 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 der AWS CDK.

JavaScript AWS CDK -Anwendungen erfordern keine weiteren Voraussetzungen.

Erstellen eines Projekts

Sie erstellen ein neues AWS CDK Projekt, indem Sie 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

Durch das Erstellen eines Projekts werden auch das aws-cdk-lib Modul und seine Abhängigkeiten installiert.

cdk init verwendet den Namen des Projektordners, um verschiedene Elemente des Projekts zu benennen, einschließlich Klassen, Unterordner und Dateien. Bindestriche im Ordnernamen werden in Unterstriche umgewandelt. Der Name sollte jedoch ansonsten der Form einer JavaScript Kennung folgen; er sollte beispielsweise nicht mit einer Zahl beginnen oder Leerzeichen enthalten.

Verwenden von Local cdk

In diesem Handbuch wird größtenteils davon ausgegangen, dass Sie das CDK Toolkit global installieren (npm install -g aws-cdk), und die bereitgestellten Befehlsbeispiele (z. B. cdk synth) folgen dieser Annahme. Dieser Ansatz macht es einfach, das CDK Toolkit auf dem neuesten Stand zu halten, und da das CDK einen strengen Ansatz für die Abwärtskompatibilität verfolgt, besteht in der Regel 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. Mit dieser Methode können Sie solche Komponenten an bestimmte Versionen anheften und sicherstellen, dass alle Entwickler in Ihrem Team (und Ihrer CI/CD-Umgebung) genau diese Versionen verwenden. Dadurch wird eine mögliche Änderungsquelle beseitigt und Builds und Bereitstellungen werden einheitlicher und wiederholbarer.

Das CDK enthält eine Abhängigkeit für das CDK Toolkit im der JavaScript Projektvorlagepackage.json. Wenn Sie diesen Ansatz verwenden möchten, müssen Sie keine Änderungen an Ihrem Projekt vornehmen. Sie müssen lediglich leicht unterschiedliche Befehle verwenden, um Ihre App zu erstellen und cdk Befehle auszugeben.

npx aws-cdk führt die lokal im aktuellen Projekt installierte Version des CDK Toolkits aus, falls vorhanden, die auf die globale Installation zurückgreift, falls vorhanden. Wenn keine globale Installation vorhanden ist, lädt eine temporäre Kopie des CDK Toolkits npx herunter und führt diese aus. Sie können eine beliebige Version des CDK Toolkits mit der @ Syntax angeben: npx aws-cdk@1.120 --version Druckt 1.120.0.

Verwalten von Modulen AWS der Construct Library

Verwenden Sie den Node Package Manager (npm), um AWS Construct Library-Module für die Verwendung durch Ihre Apps sowie andere benötigte Pakete zu installieren und zu aktualisieren. (Sie können yarn anstelle von verwendennpm, wenn Sie möchten.) installiert npm auch die Abhängigkeiten für diese Module automatisch.

Die meisten AWS CDK Konstrukte befinden sich im CDK-Hauptpaket namens , was eine Standardabhängigkeit bei neuen Projekten istaws-cdk-lib, die von erstellt wurdencdk init. „Experimentell“ AWS Module der Konstruktbibliothek, bei denen sich übergeordnete Konstrukte noch in der Entwicklung befinden, heißen aws-cdk-lib/SERVICE-NAME-alpha. Der Servicename hat das Präfix aws-. Wenn Sie sich über den Namen eines Moduls nicht sicher sind, suchen Sie nach diesem auf NPM .

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

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

Die Unterstützung der Konstruktbibliothek einiger Services befindet sich in mehr als einem Namespace. Neben gibt aws-route53es beispielsweise drei zusätzliche Amazon Route 53-Namespaces, aws-route53-targetsaws-route53-patterns, und aws-route53resolver.

Die Abhängigkeiten Ihres Projekts werden in verwaltetpackage.json. Sie können diese Datei bearbeiten, um einige oder alle Ihrer Abhängigkeiten auf eine bestimmte Version zu sperren oder deren Aktualisierung auf neuere Versionen unter bestimmten Kriterien zu ermöglichen. So aktualisieren Sie die NPM-Abhängigkeiten Ihres Projekts auf die neueste zulässige Version gemäß den Regeln, die Sie in angegeben habenpackage.json:

npm update

In importieren Sie Module in Ihren Code unter demselben Namen JavaScript, den Sie für deren Installation mit NPM verwenden. Wir empfehlen die folgenden Methoden beim Importieren von AWS CDK Klassen und Modulen AWS der Konstruktbibliothek in Ihre Anwendungen. Die Einhaltung dieser Richtlinien trägt dazu bei, dass Ihr Code mit anderen AWS CDK Anwendungen konsistent und leichter verständlich ist.

Verwalten von Abhängigkeiten in JavaScript

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

Wenn Sie ein Paket mit installierennpm install, zeichnet NPM das Paket in package.json für Sie auf.

Wenn Sie möchten, können Sie Yarn anstelle von NPM verwenden. Das CDK unterstützt jedoch nicht den Yarn- plug-and-playModus, der der Standardmodus in Yarn 2 ist. Fügen Sie der -.yarnrc.ymlDatei Ihres Projekts Folgendes hinzu, um diese Funktion zu deaktivieren.

nodeLinker: node-modules

CDK-Anwendungen

Im Folgenden finden Sie eine package.json Beispieldatei, die mit dem cdk init --language typescript Befehl generiert wurde. Die für generierte Datei JavaScript ist ähnlich, nur ohne die TypeScript-bezogenen 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 im dependencies Abschnitt von angegeben werdenpackage.json. Sie können einen caret (^) Versionsnummernbezeichner verwenden, um anzugeben, dass Sie neuere Versionen als die angegebene akzeptieren werden, solange sie sich innerhalb derselben Hauptversion befinden.

Geben Sie für experimentelle Konstrukte exakte Versionen für die Alpha-Konstrukt-Bibliotheksmodule an, deren APIs sich ändern können. Verwenden Sie nicht ^ oder ~, da spätere Versionen dieser Module API-Änderungen mit sich bringen können, die Ihre App beeinträchtigen können.

Geben Sie im devDependencies Abschnitt von Versionen von Bibliotheken und Tools an, die zum Testen Ihrer App erforderlich sind (z. Bpackage.json. das jest Test-Framework). Verwenden Sie optional ^, um anzugeben, dass spätere kompatible Versionen akzeptabel sind.

Bibliotheken für Konstrukte von Drittanbietern

Wenn Sie eine Konstruktbibliothek entwickeln, geben Sie ihre Abhängigkeiten mithilfe einer Kombination der devDependencies Abschnitte 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 peerDependenciesin ein caret (^), um die niedrigste Version von 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-Konstrukt-Bibliotheksmodule an, deren APIs sich ändern können. Die Verwendung von peerDependencies stellt sicher, dass sich nur eine Kopie aller CDK-Bibliotheken im node_modules Baum befindet.

Geben Sie in die Tools und Bibliotheken andevDependencies, die Sie zum Testen benötigen, optional mit ^, um anzuzeigen, dass spätere kompatible Versionen akzeptabel sind. Geben Sie genau (ohne ^ oder ~) die niedrigsten Versionen von aws-cdk-lib an und andere CDK-Pakete, mit denen Sie Ihre Bibliothek ankündigen, sind kompatibel. Diese Vorgehensweise stellt sicher, dass Ihre Tests mit diesen Versionen ausgeführt werden. Wenn Sie also versehentlich ein Feature verwenden, das nur in neueren Versionen gefunden wurde, können Ihre Tests es abfangen.

Installieren und Aktualisieren von Abhängigkeiten

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 vorhergehenden yarn upgrade Befehle npm install und verwendet werden. Beide Befehle aktualisieren die Pakete in node_modules auf die neuesten Versionen, die die Regeln in erfüllenpackage.json. Sie aktualisieren sich jedoch nicht package.json selbst, was Sie möglicherweise tun möchten, um eine neue Mindestversion festzulegen. Wenn Sie Ihr Paket auf hosten GitHub, können Sie Dependabot-Versionsaktualisierungen konfigurieren, um automatisch zu aktualisierenpackage.json. Als alternative Vorgehensweise verwenden Sie npm-check-updates.

AWS CDK idioms in JavaScript

Eigenschaften

Alle AWS Klassen der Konstruktbibliothek werden mit drei Argumenten instanziiert: dem Umfang, in dem das Konstrukt definiert wird (der übergeordnete Wert in der Konstruktstruktur), einer ID und props, einem Paket von Schlüssel-Wert-Paaren, die das Konstrukt zur Konfiguration der erstellten AWS Ressourcen verwendet. Andere Klassen und Methoden verwenden auch das Muster „Paket von Attributen“ für Argumente.

Die Verwendung einer IDE oder eines Editors mit guter JavaScript automatischer Vervollständigung trägt dazu bei, dass Eigenschaftsnamen nicht falsch geschrieben werden. Wenn ein Konstrukt eine -encryptionKeysEigenschaft erwartet und Sie sie buchstabierenencryptionkeys, haben Sie beim Instanziieren des Konstrukts den gewünschten Wert nicht übergeben. Dies kann bei Bedarf zu einem Fehler zur Generierungszeit führen oder dazu führen, dass die Eigenschaft stillschweigend ignoriert wird, wenn sie optional ist. Im letzteren Fall erhalten Sie möglicherweise ein Standardverhalten, das Sie überschreiben möchten. Seien Sie hier besonders vorsichtig.

Wenn Sie eine AWS Construct Library-Klasse unterteilen (oder eine Methode überschreiben, die ein eigenschaftsähnliches Argument verwendet), sollten Sie zusätzliche Eigenschaften für Ihre eigene Verwendung akzeptieren. Diese Werte werden von der übergeordneten Klasse oder der überschriebenen Methode ignoriert, da in diesem Code nie auf sie zugegriffen wird, sodass Sie im Allgemeinen alle Eigenschaften übergeben können, die Sie erhalten haben.

Eine zukünftige Version von AWS CDK könnte zufällig eine neue Eigenschaft mit einem Namen hinzufügen, den Sie für Ihre eigene Eigenschaft verwendet haben. Das Übergeben des Werts, den Sie für die Vererbungskette erhalten, kann dann zu unerwartetem Verhalten führen. Es ist sicherer, eine gültige Kopie der Eigenschaften, die Sie erhalten haben, mit entfernter oder auf eingestellter Eigenschaft zu übergebenundefined. Beispielsweise:

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

Alternativ können Sie Ihre Eigenschaften benennen, damit klar ist, dass sie zu Ihrem Konstrukt gehören. Auf diese Weise ist es unwahrscheinlich, dass sie in zukünftigen AWS CDK Versionen mit Eigenschaften kollidieren werden. Wenn viele davon vorhanden sind, verwenden Sie ein einziges entsprechend benanntes Objekt, um sie zu speichern.

Fehlende Werte

Fehlende Werte in einem Objekt (z. B. props) haben den Wert undefined in JavaScript. Für den Umgang mit diesen gelten die üblichen Techniken. Ein häufiger Ausdruck für den Zugriff auf eine Eigenschaft eines Werts, der möglicherweise nicht definiert ist, ist 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 jedoch einen anderen „false“-Wert als haben a könnteundefined, ist es besser, den Test expliziter zu gestalten. Hier nutzen wir die Tatsache, dass null und gleich undefined sind, für beide auf einmal zu testen:

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

Synthetisieren und Bereitstellen

Die in Ihrer AWS CDK App definierten Stacks können mit den folgenden Befehlen einzeln oder zusammen synthetisiert und bereitgestellt werden. Im Allgemeinen sollten Sie sich im Hauptverzeichnis Ihres Projekts befinden, wenn Sie sie ausgeben.

Sie können die Namen mehrerer Stacks angeben, die in einem einzigen Befehl synthetisiert oder bereitgestellt werden sollen. Wenn Ihre App nur einen Stack definiert, müssen Sie ihn nicht angeben.

cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

Sie können auch die Platzhalter * (beliebige Anzahl von Zeichen) und ? (beliebiges einzelnes Zeichen) verwenden, um Stacks nach Mustern zu identifizieren. Wenn Sie Platzhalter verwenden, schließen Sie das Muster in Anführungszeichen ein. Andernfalls versucht die Shell möglicherweise, sie auf die Namen der Dateien im aktuellen Verzeichnis zu erweitern, bevor sie an das AWS CDK Toolkit übergeben werden.

cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

Eine vollständige Dokumentation des cdk Befehls finden Sie unter AWS CDK Toolkit (cdkBefehl).

Verwenden von TypeScript Beispielen mit JavaScript

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

TypeScript Ausschnitte verwenden häufig das neuere ECMAScript import und export Schlüsselwörter, um Objekte aus anderen Modulen zu importieren und die Objekte zu deklarieren, die außerhalb des aktuellen Moduls verfügbar gemacht werden sollen. 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 umschreiben, um die ältere Syntax zu 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 in den tatsächlichen Code eintauchen. Möglicherweise stoßen Sie auf diese häufig verwendeten TypeScript Funktionen:

Typanmerkungen können für Variablen, Klassenmitglieder, Funktionsparameter und Funktionsrückgabetypen bereitgestellt werden. Für Variablen, Parameter und Mitglieder werden Typen angegeben, indem der Kennung ein Doppelpunkt und der Typ folgen. Funktionsrückgabewerte folgen der Funktionssignatur und bestehen aus einem Doppelpunkt und dem Typ.

Um Code vom Typ mit Anmerkungen in zu konvertieren JavaScript, entfernen Sie den Doppelpunkt und den Typ . Klassenmitglieder müssen einen bestimmten Wert in haben JavaScript; setzen Sie sie auf undefined, wenn sie nur eine Typanmerkung in haben 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 Pakete mit erforderlichen und optionalen Eigenschaften und ihren Typen einen Namen zu geben. Sie können dann den Schnittstellennamen als Typanmerkung verwenden. TypeScript stellt sicher, dass das Objekt, das Sie als verwenden, z. B. ein Argument für eine Funktion die erforderlichen Eigenschaften der richtigen Typen hat.

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

JavaScript verfügt über kein Schnittstellenfeature. Sobald Sie die Typanmerkungen entfernt haben, löschen Sie die Schnittstellendeklarationen vollständig.

Wenn eine Funktion oder Methode einen Allzwecktyp zurückgibt (z. B. object), Sie diesen Wert jedoch als einen spezifischeren JavaScript untergeordneten Typ behandeln möchten, um auf Eigenschaften oder Methoden zuzugreifen, die nicht Teil der Schnittstelle des allgemeineren Typs sind, TypeScript lässt Sie den Wert mit umwandeln, as gefolgt von einem Typ oder Schnittstellennamen. unterstützt dies nicht (oder benötigt), entfernen Sie also einfach as und die folgende Kennung. Eine weniger häufige Umwandlungssyntax besteht darin, einen Typnamen in Klammern zu verwenden<LikeThis>. Diese Umwandlungen müssen ebenfalls entfernt werden.

Schließlich TypeScript unterstützt die Zugriffsmodifikatoren public, protectedund private für Mitglieder von Klassen. Alle Klassenmitglieder in JavaScript sind öffentlich. Entfernen Sie diese Modifikatoren einfach überall, wo Sie sie sehen.

Wenn Sie wissen, wie Sie diese TypeScript Funktionen identifizieren und entfernen können, ist dies ein großer Weg, um kurze TypeScript Ausschnitte an anzupassen JavaScript. Es kann jedoch unpraktisch sein, längere TypeScript Beispiele auf diese Weise zu konvertieren, da es wahrscheinlicher ist, dass sie andere TypeScript Funktionen verwenden. Für diese Situationen empfehlen wir Sucrase . Sucrase beschwert sich beispielsweise nicht, wenn Code eine undefinierte Variable verwendet, wie es der Fall tsc wäre. Wenn es syntaktisch gültig ist, kann Sucrase es mit wenigen Ausnahmen in übersetzen JavaScript. Dies macht es besonders nützlich, um Ausschnitte zu konvertieren, die möglicherweise nicht allein ausgeführt werden können.

Migrieren zu TypeScript

Viele JavaScript Entwickler wechseln zu , 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 AWS CDK Sprache. Typanmerkungen und andere TypeScript Funktionen sind optional und können Ihrer AWS CDK App hinzugefügt werden, sobald Sie Wert darin finden. TypeScript bietet Ihnen auch frühzeitigen Zugriff auf neue JavaScript Funktionen wie optionale Verkettung und nullische Zusammenführung, bevor sie abgeschlossen sind – und ohne dass Sie Node.js aktualisieren müssen.

TypeScriptDie „formbasierten“ Schnittstellen von , die Pakete mit erforderlichen und optionalen Eigenschaften (und ihren Typen) innerhalb eines Objekts definieren, zulassen, dass häufige Fehler beim Schreiben des Codes erkannt werden, und erleichtern es Ihrer IDE, robuste Empfehlungen zur automatischen Vervollständigung und anderen Echtzeitcodierung bereitzustellen.

Die Codierung in TypeScript beinhaltet einen zusätzlichen Schritt: Kompilieren Ihrer App mit dem TypeScript Compiler tsc. Bei typischen AWS CDK Apps dauert die Kompilierung maximal einige Sekunden.

Am einfachsten können Sie eine vorhandene JavaScript AWS CDK App zu migrieren, TypeScript indem Sie ein neues TypeScript Projekt mit erstellen cdk init app --language typescriptund dann Ihre Quelldateien (und alle anderen erforderlichen Dateien, z. B. Komponenten wie AWS Lambda Funktionsquellcode) in das neue Projekt kopieren. Benennen Sie Ihre JavaScript Dateien um, damit sie in enden .ts und mit der Entwicklung in beginnen TypeScript.