Ceci est le guide du AWS CDK développeur de la version 2. L'ancienne CDK version 1 est entrée en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Travailler avec le AWS CDK in JavaScript

JavaScriptest une langue client entièrement prise en charge pour le AWS CDK et est considérée comme stable. L'utilisation du AWS Cloud Development Kit (AWS CDK) in JavaScript utilise des outils familiers, notamment Node.js et le Node Package Manager (npm). Vous pouvez également utiliser Yarn si vous préférez, comme le montrent les exemples de ce guideNPM. Les modules composant la bibliothèque AWS Construct sont distribués via le NPM référentiel npmjs.org.

Vous pouvez utiliser n'importe quel éditeur ouIDE. De nombreux AWS CDK développeurs utilisent Visual Studio Code (ou son équivalent open source VSCodium), qui bénéficie d'un bon support pour JavaScript.

Premiers pas avec JavaScript

Pour utiliser le AWS CDK, vous devez disposer d'un AWS compte et d'informations d'identification et avoir installé Node.js et le AWS CDK Toolkit. Consultez Commencer à utiliser le AWS CDK.

JavaScript AWS CDK les applications ne nécessitent aucun prérequis supplémentaire.

Création d’un projet

Vous créez un nouveau AWS CDK projet en l'appelant cdk init dans un répertoire vide. Utilisez l'--languageoption et spécifiez javascript :

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

La création d'un projet installe également le aws-cdk-libmodule et ses dépendances.

cdk initutilise le nom du dossier du projet pour nommer les différents éléments du projet, notamment les classes, les sous-dossiers et les fichiers. Les traits d'union figurant dans le nom du dossier sont convertis en traits de soulignement. Toutefois, le nom doit sinon prendre la forme d'un JavaScript identifiant ; par exemple, il ne doit pas commencer par un chiffre ni contenir d'espaces.

Utilisation du local cdk

Dans l'ensemble, ce guide suppose que vous installez le CDK Toolkit globalement (npm install -g aws-cdk), et les exemples de commandes fournis (tels quecdk synth) suivent cette hypothèse. Cette approche facilite la mise à jour du CDK kit d'outils, et comme il CDK adopte une approche stricte en matière de rétrocompatibilité, il y a généralement peu de risques à toujours utiliser la dernière version.

Certaines équipes préfèrent spécifier toutes les dépendances au sein de chaque projet, y compris des outils tels que le CDK Toolkit. Cette pratique vous permet d'associer ces composants à des versions spécifiques et de vous assurer que tous les développeurs de votre équipe (et de votre environnement CI/CD) utilisent exactement ces versions. Cela élimine toute source potentielle de changement, ce qui contribue à rendre les builds et les déploiements plus cohérents et reproductibles.

CDKCela inclut une dépendance pour le CDK kit d'outils dans le modèle de JavaScript projetpackage.json, donc si vous souhaitez utiliser cette approche, vous n'avez pas besoin d'apporter de modifications à votre projet. Il vous suffit d'utiliser des commandes légèrement différentes pour créer votre application et pour émettre des cdk commandes.

npx aws-cdkexécute la version du CDK Toolkit installée localement dans le projet en cours, s'il en existe une, en revenant à l'installation globale, le cas échéant. S'il n'existe aucune installation globale, npx télécharge une copie temporaire du CDK Toolkit et l'exécute. Vous pouvez spécifier une version arbitraire du CDK Toolkit en utilisant la @ syntaxe : npx aws-cdk@1.120 --version prints1.120.0.

Gestion des modules AWS de la bibliothèque Construct

Utilisez le Node Package Manager (npm) pour installer et mettre à jour les modules AWS Construct Library destinés à être utilisés par vos applications, ainsi que par les autres packages dont vous avez besoin. (Vous pouvez utiliser à la yarn place de npm si vous préférez.) npminstalle également automatiquement les dépendances de ces modules.

La plupart AWS CDK des constructions se trouvent dans le CDK package principal, nomméaws-cdk-lib, qui est une dépendance par défaut dans les nouveaux projets créés parcdk init. Les modules de la bibliothèque de AWS construction « expérimentaux », dans lesquels des constructions de niveau supérieur sont encore en cours de développement, sont nommés ainsi. aws-cdk-lib/SERVICE-NAME-alpha Le nom du service comporte un préfixe aws-. Si vous n'êtes pas sûr du nom d'un module, recherchez-le sur NPM.

Par exemple, la commande ci-dessous installe le module expérimental pour AWS CodeStar.

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

La prise en charge de la bibliothèque Construct par certains services se trouve dans plusieurs espaces de noms. Par exempleaws-route53, il existe en outre trois espaces de noms Amazon Route 53 supplémentaires, aws-route53-targetsaws-route53-patterns, etaws-route53resolver.

Les dépendances de votre projet sont conservées danspackage.json. Vous pouvez modifier ce fichier pour verrouiller certaines ou toutes vos dépendances dans une version spécifique ou pour permettre leur mise à jour vers des versions plus récentes selon certains critères. Pour mettre à jour NPM les dépendances de votre projet vers la dernière version autorisée conformément aux règles que vous avez spécifiées dans package.json :

npm update

Dans JavaScript, vous importez des modules dans votre code sous le même nom que celui que vous utilisez pour les installerNPM. Nous recommandons les pratiques suivantes lors de l'importation de AWS CDK classes et de modules AWS Construct Library dans vos applications. Le respect de ces directives vous aidera à rendre votre code cohérent avec AWS CDK les autres applications et à le rendre plus facile à comprendre.

Gestion des dépendances dans JavaScript

Dans les JavaScript CDK projets, les dépendances sont spécifiées dans le package.json fichier du répertoire principal du projet. Les AWS CDK modules principaux se trouvent dans un seul NPM package appeléaws-cdk-lib.

Lorsque vous installez un package à l'aide denpm install, NPM enregistre le package package.json pour vous.

Si vous préférez, vous pouvez utiliser Yarn à la place deNPM. Cependant, il CDK ne prend pas en charge le plug-and-play mode Yarn, qui est le mode par défaut dans Yarn 2. Ajoutez ce qui suit au .yarnrc.yml fichier de votre projet pour désactiver cette fonctionnalité.

nodeLinker: node-modules

CDKapplications

Voici un exemple de package.json fichier généré par la cdk init --language typescript commande. Le fichier généré pour JavaScript est similaire, mais sans les TypeScript entrées associées.

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

Pour les CDK applications déployables, aws-cdk-lib cela doit être spécifié dans la dependencies section depackage.json. Vous pouvez utiliser un spécificateur de numéro de version caret (^) pour indiquer que vous accepterez des versions ultérieures à celle spécifiée, à condition qu'elles soient dans la même version majeure.

Pour les constructions expérimentales, spécifiez les versions exactes des modules de la bibliothèque de constructions alpha, APIs qui peuvent changer. N'utilisez pas ^ ou ~ car les versions ultérieures de ces modules peuvent apporter API des modifications susceptibles de casser votre application.

Spécifiez les versions des bibliothèques et des outils nécessaires pour tester votre application (par exemple, le framework de jest test) dans la devDependencies section depackage.json. Utilisez éventuellement ^ pour indiquer que les versions compatibles ultérieures sont acceptables.

Bibliothèques de construction tierces

Si vous développez une bibliothèque de constructions, spécifiez ses dépendances à l'aide d'une combinaison des devDependencies sections peerDependencies et, comme indiqué dans l'exemple de package.json fichier suivant.

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

DanspeerDependencies, utilisez un curseur (^) pour spécifier la version la plus basse de aws-cdk-lib celle avec laquelle votre bibliothèque fonctionne. Cela permet d'optimiser la compatibilité de votre bibliothèque avec une gamme de CDK versions. Spécifiez les versions exactes des modules de la bibliothèque de construction alpha, APIs qui peuvent changer. L'utilisation peerDependencies garantit qu'il n'y a qu'une seule copie de toutes les CDK bibliothèques dans l'node_modulesarborescence.

DansdevDependencies, spécifiez les outils et les bibliothèques dont vous avez besoin pour les tests, éventuellement avec ^ pour indiquer que les versions compatibles ultérieures sont acceptables. Spécifiez exactement (sans ^ ou ~) les versions les plus basses aws-cdk-lib et les autres CDK packages avec lesquels vous annoncez que votre bibliothèque doit être compatible. Cette pratique garantit que vos tests s'exécutent par rapport à ces versions. Ainsi, si vous utilisez par inadvertance une fonctionnalité présente uniquement dans les nouvelles versions, vos tests peuvent la détecter.

Installation et mise à jour des dépendances

Exécutez la commande suivante pour installer les dépendances de votre projet.

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

Pour mettre à jour les modules installés, les yarn upgrade commandes npm install et précédentes peuvent être utilisées. L'une ou l'autre des commandes met node_modules à jour les packages vers les dernières versions conformes aux règles depackage.json. Cependant, ils ne package.json se mettent pas à jour d'eux-mêmes, ce que vous pouvez faire pour définir une nouvelle version minimale. Si vous hébergez votre package sur GitHub, vous pouvez configurer les mises à jour de version de Dependabot pour qu'elles soient mises à jour package.json automatiquement. Sinon, utilisez npm-check-updates.

AWS CDK expressions idiomatiques dans JavaScript

accessoires

Toutes les classes de la bibliothèque de AWS construction sont instanciées à l'aide de trois arguments : la portée dans laquelle la construction est définie (son parent dans l'arbre de construction), un identifiant, et props, un ensemble de paires clé/valeur que la construction utilise pour configurer les ressources qu'elle crée. AWS D'autres classes et méthodes utilisent également le modèle « bundle of attributes » pour les arguments.

L'utilisation d'un éditeur doté IDE d'une bonne JavaScript saisie semi-automatique permet d'éviter les fautes d'orthographe dans les noms de propriété. Si une construction attend une encryptionKeys propriété, et que vous l'épelezencryptionkeys, lors de l'instanciation de la construction, vous n'avez pas transmis la valeur que vous vouliez. Cela peut provoquer une erreur au moment de la synthèse si la propriété est obligatoire, ou entraîner son ignorance silencieuse si elle est facultative. Dans ce dernier cas, il se peut que vous obteniez un comportement par défaut que vous vouliez remplacer. Faites particulièrement attention ici.

Lorsque vous sous-classez une classe AWS Construct Library (ou que vous remplacez une méthode qui prend un argument semblable à un accessoire), vous souhaiterez peut-être accepter des propriétés supplémentaires pour votre propre usage. Ces valeurs seront ignorées par la classe parent ou par la méthode remplacée, car elles ne sont jamais accessibles dans ce code. Vous pouvez donc généralement transmettre tous les accessoires que vous avez reçus.

Une future version du AWS CDK pourrait par hasard ajouter une nouvelle propriété avec un nom que vous avez utilisé pour votre propre propriété. Le transfert de la valeur que vous recevez vers le haut de la chaîne d'héritage peut alors provoquer un comportement inattendu. Il est plus sûr de transmettre une copie sommaire des accessoires que vous avez reçus lorsque vos biens ont été retirés ou transférésundefined. Par exemple :

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

Vous pouvez également nommer vos propriétés de manière à ce qu'il soit clair qu'elles appartiennent à votre construction. De cette façon, il est peu probable qu'ils entrent en collision avec des propriétés dans les futures AWS CDK versions. S'ils sont nombreux, utilisez un seul objet portant le nom approprié pour les conserver.

Valeurs manquantes

Les valeurs manquantes dans un objet (par exempleprops) ont pour valeur undefined in JavaScript. Les techniques habituelles s'appliquent pour y faire face. Par exemple, un idiome courant pour accéder à une propriété dont la valeur n'est peut-être pas définie est le suivant :

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

Cependant, s'il a peut avoir une autre valeur « fausse »undefined, il est préférable de rendre le test plus explicite. Ici, nous allons profiter du fait que null et undefined sommes égaux pour les tester tous les deux en même temps :

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

À l'aide TypeScript d'exemples avec JavaScript

TypeScriptest le langage que nous utilisons pour le AWS CDK développer. C'est le premier langage pris en charge pour le développement d'applications. De nombreux exemples de AWS CDK code disponibles y sont donc écrits TypeScript. Ces exemples de code peuvent être une bonne ressource pour JavaScript les développeurs ; il suffit de supprimer les parties TypeScript spécifiques du code.

TypeScript les extraits de code utilisent souvent les export mots clés les plus récents ECMAScript import et pour importer des objets depuis d'autres modules et pour déclarer les objets à mettre à disposition en dehors du module actuel. Node.js vient de commencer à prendre en charge ces mots clés dans ses dernières versions. Selon la version de Node.js que vous utilisez (ou que vous souhaitez prendre en charge), vous pouvez réécrire les importations et les exportations pour utiliser l'ancienne syntaxe.

Les importations peuvent être remplacées par des appels à la require() fonction.

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');

Les exportations peuvent être attribuées à l'module.exportsobjet.

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 }

Une fois que vous avez trié les importations et les exportations, vous pouvez accéder au code lui-même. Vous pouvez rencontrer ces fonctionnalités couramment utilisées TypeScript  :

Des annotations de type peuvent être fournies pour les variables, les membres de classe, les paramètres de fonction et les types de retour de fonction. Pour les variables, les paramètres et les membres, les types sont spécifiés en suivant l'identifiant par deux points et le type. Les valeurs renvoyées par la fonction suivent la signature de la fonction et se composent de deux points et du type.

Pour convertir le code annoté en caractères typographiques JavaScript, supprimez les deux points et le type. Les membres de la classe doivent avoir une certaine valeur dans JavaScript ; définissez-leur sur undefined s'ils n'ont qu'une annotation de type dedans 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) {
    // ...
}

Dans TypeScript, les interfaces sont utilisées pour donner un nom à des ensembles de propriétés obligatoires et facultatives, ainsi qu'à leurs types. Vous pouvez ensuite utiliser le nom de l'interface comme annotation de type. TypeScript permettra de s'assurer que l'objet que vous utilisez, par exemple, comme argument d'une fonction possède les propriétés requises du bon type.

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

JavaScript ne possède pas de fonctionnalité d'interface, donc une fois que vous avez supprimé les annotations de type, supprimez complètement les déclarations d'interface.

Lorsqu'une fonction ou une méthode renvoie un type à usage général (tel queobject), mais que vous souhaitez traiter cette valeur comme un type enfant plus spécifique pour accéder à des propriétés ou à des méthodes qui ne font pas partie de l'interface du type plus général, vous TypeScript permet de convertir la valeur en utilisant le nom as du type ou de l'interface. JavaScript ne le supporte pas (ou n'en a pas besoin), il suffit donc as de supprimer l'identifiant suivant. Une syntaxe de conversion moins courante consiste à utiliser un nom de type entre crochets <LikeThis> ; ces conversions doivent également être supprimées.

Enfin, TypeScript prend en charge les modificateurs d'accès publicprotected, et private pour les membres des classes. Tous les membres de la classe JavaScript sont publics. Supprimez simplement ces modificateurs partout où vous les voyez.

Savoir comment identifier et supprimer ces TypeScript fonctionnalités contribue grandement à l'adaptation des TypeScript extraits courts à. JavaScript Mais il peut s'avérer peu pratique de convertir TypeScript des exemples plus longs de cette manière, car ils sont plus susceptibles d'utiliser d'autres TypeScript fonctionnalités. Dans ces situations, nous recommandons la sucrase. Sucrase ne se plaindra pas si le code utilise une variable non définie, par exemple, comme le tsc ferait. S'il est syntaxiquement valide, Sucrase peut le traduire en. JavaScript Cela le rend particulièrement utile pour convertir des extraits de code qui ne peuvent pas être exécutés seuls.

Migration vers TypeScript

De nombreux JavaScript développeurs optent pour cette TypeScriptsolution au fur et à mesure que leurs projets deviennent plus importants et plus complexes. TypeScript est un surensemble de JavaScript (tout le JavaScript code est un code valide, aucune modification de votre TypeScript code n'est donc requise) et il s'agit également d'une langue prise en charge. AWS CDK Les annotations de type et les autres TypeScript fonctionnalités sont facultatives et peuvent être ajoutées à votre AWS CDK application au fur et à mesure que vous y trouvez de la valeur. TypeScript vous donne également un accès anticipé aux nouvelles JavaScript fonctionnalités, telles que le chaînage facultatif et la fusion nulle, avant leur finalisation, sans avoir à mettre à jour Node.js.

TypeScriptles interfaces « basées sur les formes », qui définissent des ensembles de propriétés obligatoires et facultatives (et leurs types) au sein d'un objet, permettent de détecter les erreurs courantes lors de l'écriture du code et vous permettent de fournir plus facilement des conseils de saisie semi-automatique robustes et d'autres conseils de codage en temps réel. IDE

Le codage TypeScript implique une étape supplémentaire : compiler votre application avec le TypeScript compilateur,tsc. Pour les AWS CDK applications classiques, la compilation ne prend que quelques secondes au maximum.

Le moyen le plus simple de migrer une JavaScript AWS CDK application existante TypeScript est de créer un nouveau TypeScript projet en utilisantcdk init app --language typescript, puis de copier vos fichiers source (et tous les autres fichiers nécessaires, tels que les actifs tels que le code source des AWS Lambda fonctions) dans le nouveau projet. Renommez vos JavaScript fichiers pour qu'ils se terminent par .ts et que vous commenciez à les développer en TypeScript.