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 dem AWS CDK in TypeScript TypeScript ist eine vollständig unterstützte Client-Sprache für das AWS Cloud Development Kit (AWS CDK) und gilt als stabil. Bei der Arbeit mit dem AWS CDK werden vertraute Tools TypeScript verwendet, darunter der TypeScript Compiler (`tsc`) von Microsoft, [Node.js](https://nodejs.org/) und der Node Package Manager (`npm`). Sie können auch [Yarn](https://yarnpkg.com/) verwenden, wenn Sie möchten, obwohl die Beispiele in diesem Handbuch NPM verwenden. [Die Module, aus denen die AWS Construct-Bibliothek besteht, werden über das NPM-Repository npmjs.org vertrieben.](https://www.npmjs.com/) Sie können jeden Editor oder jede IDE verwenden. Viele AWS CDK-Entwickler verwenden [Visual Studio Code](https://code.visualstudio.com/) (oder sein Open-Source-Äquivalent [VSCodium](https://vscodium.com/)), das hervorragende Unterstützung für bietet. TypeScript ## Fangen Sie an mit TypeScript Um mit dem AWS CDK arbeiten zu können, 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 CDK](getting-started.md). AWS Sie benötigen auch es TypeScript selbst (Version 3.8 oder höher). Wenn Sie es noch nicht haben, können Sie es mit installieren`npm`. ``` $ npm install -g typescript ``` **Anmerkung** Wenn Sie einen Berechtigungsfehler erhalten und Administratorzugriff auf Ihr System haben, versuchen Sie es`sudo npm install -g typescript`. TypeScript Bleiben Sie regelmäßig auf dem Laufenden`npm update -g typescript`. **Anmerkung** Veraltete Sprachversion von Drittanbietern: Die Sprachversion wird nur bis zu ihrem vom Anbieter oder der Community mitgeteilten EOL (End Of Life) unterstützt und kann sich nach vorheriger Ankündigung ändern. ## Erstellen eines Projekts Sie erstellen ein neues AWS CDK-Projekt, indem Sie es in einem leeren Verzeichnis aufrufen`cdk init`. Verwenden Sie die `--language` Option und geben Sie an: `typescript` ``` $ mkdir my-project $ cd my-project $ cdk init app --language typescript ``` Beim Erstellen eines Projekts werden auch das [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)Modul und seine Abhängigkeiten installiert. `cdk init`verwendet 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. ## Lokal `tsc` und verwenden `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 (wie`cdk 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 enthält 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 Befehlen verwenden. `cdk` | Operation | Verwenden Sie globale Tools | Verwenden Sie lokale Tools | | --- | --- | --- | | **Projekt initialisieren** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **Entwicklung** | `tsc` | `npm run build` | | **Führen Sie den Befehl CDK Toolkit aus** | `cdk …​` | `npm run cdk …​` oder `npx aws-cdk …​` | `npx aws-cdk`fü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. Falls 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: prints. `@` `npx aws-cdk@2.0 --version` `2.0.0` **Tipp** Richten Sie einen Alias ein, damit Sie den `cdk` Befehl mit einer lokalen CDK Toolkit-Installation verwenden können. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## 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.) `npm`installiert 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 Projekten`aws-cdk-lib`, die von erstellt wurden. `cdk init` Module der „experimentellen“ AWS Construct Library, bei denen sich übergeordnete Konstrukte noch in der Entwicklung befinden, werden wie benannt. `@aws-cdk/-alpha` Der Dienstname hat ein aws-Präfix*.* Wenn Sie sich des Namens eines Moduls nicht sicher sind, [suchen Sie auf NPM danach](https://www.npmjs.com/search?q=%40aws-cdk). **Anmerkung** Die [CDK-API-Referenz](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) zeigt auch die Paketnamen. Mit dem folgenden Befehl wird beispielsweise das experimentelle Modul für AWS CodeStar installiert. ``` $ 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. Um die NPM-Abhängigkeiten Ihres Projekts gemäß den Regeln, die Sie angegeben haben, auf die neueste zulässige Version zu aktualisieren: `package.json` ``` $ npm update ``` In TypeScript importieren Sie Module in Ihren Code unter demselben Namen, den Sie für die Installation mit NPM verwenden. 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. + Verwenden Sie `import` Direktiven ES6 im Stil von -style, nicht. `require()` + Importiere generell einzelne Klassen von`aws-cdk-lib`. ``` import { App, Stack } from 'aws-cdk-lib'; ``` + Wenn Sie viele Klassen von benötigen`aws-cdk-lib`, können Sie einen Namespace-Alias von verwenden, `cdk` anstatt die einzelnen Klassen zu importieren. Vermeiden Sie es, beides zu tun. ``` import * as cdk from 'aws-cdk-lib'; ``` + Im Allgemeinen importieren Sie AWS Dienstkonstrukte mit kurzen Namespace-Aliasnamen. ``` import { aws_s3 as s3 } from 'aws-cdk-lib'; ``` ## 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 namens. `aws-cdk-lib` Wenn Sie ein Paket mit installieren`npm install`, zeichnet NPM das Paket `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 plug-and-play Modus von Yarn, der in Yarn 2 der Standardmodus ist. Fügen Sie der `.yarnrc.yml` Datei 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: ``` { "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 angegeben werden. `package.json` 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 \$1, 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 anzugeben`aws-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. `peerDependencies`Durch die Verwendung wird sichergestellt, dass nur eine Kopie aller CDK-Bibliotheken im `node_modules` Baum vorhanden ist. Geben Sie `devDependencies` unter die Tools und Bibliotheken an, die Sie zum Testen benötigen, optional mit ^, um anzugeben, dass spätere kompatible Versionen zulässig sind. Geben Sie genau (ohne ^ oder \$1) 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. **Warnung** `peerDependencies`werden nur von NPM 7 und höher automatisch installiert. Wenn Sie NPM 6 oder früher verwenden oder wenn Sie Yarn verwenden, müssen Sie die Abhängigkeiten Ihrer Abhängigkeiten in einbeziehen. `devDependencies` Andernfalls werden sie nicht installiert und Sie erhalten eine Warnung vor ungelösten Peer-Abhängigkeiten. ### Abhängigkeiten installieren und aktualisieren Führen Sie den folgenden Befehl aus, um die Abhängigkeiten Ihres Projekts zu installieren. **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 ``` 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 entsprechen`package.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](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) so konfigurieren, dass sie automatisch aktualisiert werden. `package.json` Als alternative Vorgehensweise verwenden Sie [npm-check-updates](https://www.npmjs.com/package/npm-check-updates). **Wichtig** Standardmäßig wählen NPM und Yarn bei der Installation oder Aktualisierung von Abhängigkeiten die neueste Version jedes Pakets aus, das die in angegebenen Anforderungen erfüllt. `package.json` Es besteht immer das Risiko, dass diese Versionen beschädigt werden (entweder versehentlich oder absichtlich). Testen Sie gründlich, nachdem Sie die Abhängigkeiten Ihres Projekts aktualisiert haben. ## AWS CDK-Idiome 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 [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)Konstrukt (im `aws-cdk-lib/aws-s3` Modul) ein `props` Argument, das der [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)Schnittstelle entspricht. Wenn eine Eigenschaft selbst ein Objekt ist, zum Beispiel die [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)Eigenschaft von`BucketProps`, hat dieses Objekt in diesem Fall seine eigene Schnittstelle, der seine Form entsprechen muss. [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) 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. Eine future Version des AWS CDK könnte zufällig eine neue Immobilie mit einem Namen hinzufügen, den Sie für Ihre eigene Immobilie verwendet haben. Wenn Sie den Wert, den Sie erhalten, in der Vererbungskette weiterreichen, 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. Zum Beispiel: ``` 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. 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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), insbesondere in den ersten beiden Funktionen, Optionales Verketten und Nullish Coalescing. ## CDK-Apps erstellen und ausführen 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. Das AWS CDK tut dies automatisch, wann immer es 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 ein`npm 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.