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.

Mit dem AWS CDK in arbeiten TypeScript

TypeScript ist eine vollständig unterstützte Client-Sprache für die AWS Cloud Development Kit (AWS CDK) und gilt als stabil. Bei der Arbeit mit dem AWS CDK In werden vertraute Tools TypeScript verwendet, darunter der TypeScript Compiler (tsc) von Microsoft, 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 hervorragende Unterstützung für TypeScript bietet.

Fangen Sie an mit TypeScript

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

Sie benötigen auch es TypeScript selbst (Version 3.8 oder höher). Wenn Sie es noch nicht haben, können Sie es mit installierennpm.

npm install -g typescript

TypeScript Bleiben Sie regelmäßig auf dem Laufendennpm update -g typescript.

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 antypescript:

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

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 TypeScript Bezeichners haben; er sollte beispielsweise nicht mit einer Zahl beginnen oder Leerzeichen enthalten.

Verwenden Sie lokal tsc und cdk

In den meisten Fällen wird in diesem Handbuch davon ausgegangen, dass Sie das CDK Toolkit global (npm install -g typescript aws-cdk) installieren TypeScript , und die bereitgestellten Befehlsbeispiele (wiecdk synth) folgen dieser Annahme. Dieser Ansatz macht es einfach, beide Komponenten auf dem neuesten Stand zu halten, und da beide einen strikten Ansatz zur Abwärtskompatibilität verfolgen, besteht im Allgemeinen nur ein geringes Risiko, immer die neuesten Versionen zu verwenden.

Einige Teams ziehen es vor, alle Abhängigkeiten innerhalb jedes Projekts anzugeben, einschließlich Tools wie dem TypeScript Compiler und dem CDK Toolkit. Auf diese Weise können Sie diese 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 Abhängigkeiten TypeScript sowohl für beide als auch für das CDK Toolkit in den TypeScript 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@2.0 --version prints. 2.0.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/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

TypeScriptIn 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 TypeScript

In TypeScript 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:

{
  "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. Beide Befehle aktualisieren die Pakete node_modules auf die neuesten Versionen, 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 TypeScript

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 Requisiten. Argument props ist ein Bündel von Schlüssel/Wert-Paaren, das 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.

TypeScriptIn props wird die Form von mithilfe einer Schnittstelle definiert, die Ihnen die erforderlichen und optionalen Argumente und deren Typen mitteilt. Eine solche Schnittstelle wird für jede Art von props Argument definiert, normalerweise spezifisch für ein einzelnes Konstrukt oder eine einzelne Methode. Zum Beispiel spezifiziert das Bucket-Konstrukt (in deraws-cdk-lib/aws-s3 module) ein props Argument, das der BucketPropsSchnittstelle entspricht.

Wenn eine Eigenschaft selbst ein Objekt ist, zum Beispiel die websiteRedirectEigenschaft vonBucketProps, hat dieses Objekt in diesem Fall seine eigene Schnittstelle, der seine Form entsprechen muss. RedirectTarget

Wenn Sie einer AWS Construct-Library-Klasse eine Unterklasse zuordnen (oder eine Methode überschreiben, die ein Argument wie Requisiten verwendet), können Sie von der vorhandenen Schnittstelle erben, um eine neue zu erstellen, die alle neuen Requisiten angibt, die Ihr Code benötigt. Wenn Sie die übergeordnete Klasse oder Basismethode aufrufen, können Sie im Allgemeinen das gesamte Argument props übergeben, das Sie erhalten haben, da alle im Objekt angegebenen, aber nicht in der Schnittstelle angegebenen Attribute ignoriert werden.

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. Requisiten) haben den Wert in. undefined TypeScript In Version 3.7 der Sprache wurden Operatoren eingeführt, die die Arbeit mit diesen Werten vereinfachen. Sie erleichtern die Angabe von Standardwerten und die Verkettung von Kurzschlüssen, wenn ein undefinierter Wert erreicht wird. Weitere Informationen zu diesen Funktionen finden Sie in den Versionshinweisen zu TypeScript 3.7, insbesondere in den ersten beiden Funktionen, Optionales Verketten und Nullish Coalescing.

Apps erstellen und ausführen CDK

Im Allgemeinen sollten Sie sich beim Erstellen und Ausführen Ihrer Anwendung im Stammverzeichnis des Projekts befinden.

Node.js kann nicht TypeScript direkt ausgeführt werden. Stattdessen wird Ihre Anwendung so konvertiert, tsc dass sie den TypeScript Compiler JavaScript verwendet. Der resultierende JavaScript Code wird dann ausgeführt.

Der tut dies AWS CDK automatisch, wann immer er Ihre App ausführen muss. Es kann jedoch nützlich sein, manuell zu kompilieren, um nach Fehlern zu suchen und Tests durchzuführen. Um Ihre TypeScript App manuell zu kompilieren, geben Sie das Problem einnpm run build. Sie können auch npm run watch den Überwachungsmodus aufrufen, in dem der TypeScript Compiler Ihre App automatisch neu erstellt, wenn Sie Änderungen an einer Quelldatei speichern.