Esta es la guía para AWS CDK desarrolladores de la versión 2. La versión anterior del CDK v1 entró en mantenimiento el 1 de junio de 2022 y dejó de ofrecer soporte el 1 de junio de 2023.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Trabajando con la AWS CDK tinta JavaScript

JavaScriptes un lenguaje de cliente totalmente compatible AWS CDK y se considera estable. Para trabajar con AWS Cloud Development Kit (AWS CDK) él se JavaScript utilizan herramientas conocidas, como Node.js y Node Package Manager (npm). También puedes usar Yarn si lo prefieres, aunque en los ejemplos de esta guía se usa NPM. Los módulos que componen la biblioteca AWS Construct se distribuyen a través del repositorio de NPM, npmjs.org.

Puede utilizar cualquier editor o IDE. Muchos AWS CDK desarrolladores utilizan Visual Studio Code (o su equivalente de código abierto, VSCodium), que cuenta con un buen soporte. JavaScript

Introducción a JavaScript

Para trabajar con él AWS CDK, debe tener una AWS cuenta y credenciales y tener instalados Node.js y el kit de herramientas. AWS CDK Consulte Cómo empezar con el AWS CDK.

JavaScript AWS CDK las aplicaciones no requieren requisitos previos adicionales más allá de estos.

Creación de un proyecto

Para crear un AWS CDK proyecto nuevo, se invoca cdk init en un directorio vacío. Utilice la --language opción y especifiquejavascript:

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

Al crear un proyecto, también se instala el aws-cdk-libmódulo y sus dependencias.

cdk initusa el nombre de la carpeta del proyecto para nombrar varios elementos del proyecto, incluidas las clases, las subcarpetas y los archivos. Los guiones del nombre de la carpeta se convierten en guiones bajos. Sin embargo, de lo contrario, el nombre debe tener la forma de un JavaScript identificador; por ejemplo, no debe empezar por un número ni contener espacios.

Uso de local cdk

En su mayor parte, en esta guía se supone que se instala el kit de herramientas CDK de forma global (npm install -g aws-cdk), y los ejemplos de comandos proporcionados (comocdk synth) siguen esta suposición. Este enfoque facilita mantener actualizado el kit de herramientas del CDK y, dado que el CDK adopta un enfoque estricto en cuanto a la compatibilidad con versiones anteriores, por lo general, se corre poco riesgo al utilizar siempre la última versión.

Algunos equipos prefieren especificar todas las dependencias de cada proyecto, incluidas herramientas como el kit de herramientas del CDK. Esta práctica le permite fijar dichos componentes a versiones específicas y garantizar que todos los desarrolladores de su equipo (y de su entorno de CI/CD) utilicen exactamente esas versiones. Esto elimina una posible fuente de cambio, lo que ayuda a que las compilaciones y las implementaciones sean más consistentes y repetibles.

El CDK incluye una dependencia para el kit de herramientas del CDK en las plantillas del JavaScript proyectopackage.json, por lo que si quieres utilizar este enfoque, no necesitas realizar ningún cambio en el proyecto. Todo lo que necesitas hacer es usar comandos ligeramente diferentes para crear tu aplicación y para emitir comandos. cdk

npx aws-cdkejecuta la versión del kit de herramientas CDK instalada localmente en el proyecto actual, si existe, y recurre a la instalación global, si la hubiera. Si no existe una instalación global, npx descarga una copia temporal del kit de herramientas del CDK y la ejecuta. Puede especificar una versión arbitraria del kit de herramientas del CDK mediante la @ sintaxis: prints. npx aws-cdk@1.120 --version 1.120.0

Administrar los módulos de AWS Construct Library

Use el Node Package Manager (npm) para instalar y actualizar los módulos de AWS Construct Library para que los usen sus aplicaciones, así como otros paquetes que necesite. (Puede usarlo yarn en lugar de npm si lo prefiere). npmtambién instala las dependencias de esos módulos automáticamente.

La mayoría de AWS CDK las construcciones se encuentran en el paquete CDK principal, llamadoaws-cdk-lib, que es una dependencia predeterminada en los nuevos proyectos creados por. cdk init Los módulos de la biblioteca de AWS construcciones «experimentales», en los que aún se están desarrollando construcciones de nivel superior, reciben el mismo nombre. aws-cdk-lib/SERVICE-NAME-alpha El nombre del servicio tiene el prefijo aws-. Si no está seguro del nombre de un módulo, búsquelo en NPM.

Por ejemplo, el siguiente comando instala el módulo experimental para. AWS CodeStar

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

El soporte de Construct Library de algunos servicios está en más de un espacio de nombres. Por ejemplo, ademásaws-route53, hay tres espacios de nombres adicionales de Amazon Route 53, aws-route53-targetsaws-route53-patterns, y. aws-route53resolver

Las dependencias de su proyecto se mantienen en. package.json Puedes editar este archivo para bloquear algunas o todas tus dependencias en una versión específica o para permitir que se actualicen a versiones más recientes según ciertos criterios. Para actualizar las dependencias de NPM de tu proyecto a la última versión permitida de acuerdo con las reglas que especificaste en: package.json

npm update

En JavaScript, importas módulos a tu código con el mismo nombre que utilizaste para instalarlos mediante NPM. Recomendamos las siguientes prácticas al importar AWS CDK clases y módulos de AWS Construct Library a sus aplicaciones. Seguir estas pautas ayudará a que su código sea coherente con el de otras AWS CDK aplicaciones y a que sea más fácil de entender.

Administrar las dependencias en JavaScript

En los proyectos de JavaScript CDK, las dependencias se especifican en el package.json archivo del directorio principal del proyecto. Los AWS CDK módulos principales se encuentran en un único NPM paquete llamado. aws-cdk-lib

Cuando instala un paquete utilizandonpm install, NPM graba el paquete package.json por usted.

Si lo prefieres, puedes usar Yarn en lugar de NPM. Sin embargo, el CDK no admite el plug-and-play modo de Yarn, que es el modo predeterminado en Yarn 2. Agrega lo siguiente al .yarnrc.yml archivo de tu proyecto para desactivar esta función.

nodeLinker: node-modules

Aplicaciones CDK

El siguiente es un ejemplo de package.json archivo generado por el cdk init --language typescript comando. El archivo generado para JavaScript es similar, solo que sin las entradas TypeScript relacionadas.

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

En el caso de las aplicaciones de CDK desplegables, aws-cdk-lib debe especificarse en la dependencies sección de. package.json Puede usar un especificador de número de versión con un signo de intercalación (^) para indicar que aceptará versiones posteriores a la especificada, siempre y cuando estén dentro de la misma versión principal.

En el caso de las construcciones experimentales, especifique las versiones exactas de los módulos de la biblioteca de construcciones alfa, que tienen API que pueden cambiar. No utilices ^ ni ~, ya que las versiones posteriores de estos módulos pueden incluir cambios en la API que pueden dañar tu aplicación.

Especifica las versiones de las bibliotecas y herramientas necesarias para probar tu aplicación (por ejemplo, el marco de jest pruebas) en la devDependencies sección depackage.json. Si lo desea, utilice ^ para especificar si se aceptan versiones posteriores compatibles.

Bibliotecas de construcción de terceros

Si está desarrollando una biblioteca de construcción, especifique sus dependencias mediante una combinación de las devDependencies secciones peerDependencies y, como se muestra en el siguiente package.json archivo de ejemplo.

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

EnpeerDependencies, utilice un signo de intercalación (^) para especificar la versión más baja con la aws-cdk-lib que funciona la biblioteca. Esto maximiza la compatibilidad de la biblioteca con una variedad de versiones de CDK. Especifique las versiones exactas de los módulos de la biblioteca Alpha Construct, que tienen API que pueden cambiar. El uso peerDependencies garantiza que solo haya una copia de todas las bibliotecas de CDK en el node_modules árbol.

EndevDependencies, especifique las herramientas y bibliotecas que necesita para realizar las pruebas, si lo desea, con ^ para indicar que se aceptan versiones posteriores compatibles. Especifique exactamente (sin ^ ni ~) las versiones más bajas aws-cdk-lib y otros paquetes de CDK con los que anuncia que su biblioteca es compatible. Esta práctica garantiza que las pruebas se ejecuten con esas versiones. De esta forma, si utilizas inadvertidamente una función que solo se encuentra en las versiones más recientes, tus pruebas pueden detectarla.

Instalación y actualización de las dependencias

Ejecuta el siguiente comando para instalar las dependencias de tu proyecto.

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

Para actualizar los módulos instalados, se pueden usar yarn upgrade los comandos anteriores npm install y. Cualquiera de los dos comandos actualiza los paquetes node_modules a las versiones más recientes que cumplen las reglas depackage.json. Sin embargo, no package.json se actualizan solos, por lo que puede que desee establecer una nueva versión mínima. Si alojas tu paquete GitHub, puedes configurar las actualizaciones de las versiones del Dependabot para que se actualicen automáticamente. package.json Para otras opciones, consulte npm-check-updates.

AWS CDK modismos en JavaScript

Accesorios

Todas las clases de AWS Construct Library se instancian mediante tres argumentos: el ámbito en el que se define la construcción (su elemento principal en el árbol de construcciones), un identificador y props, un conjunto de pares clave/valor que la construcción utiliza para configurar los recursos que crea. AWS Otras clases y métodos también utilizan el patrón de «conjunto de atributos» como argumento.

El uso de un IDE o un editor que tenga una buena JavaScript función de autocompletar ayudará a evitar errores ortográficos en los nombres de las propiedades. Si un componente fijo está esperando una encryptionKeys propiedad y la escribes al crear una instancia del componente fijo, no le has dado el valor deseado. encryptionkeys Esto puede provocar un error en el momento de la síntesis si la propiedad es necesaria o hacer que la propiedad se ignore silenciosamente si es opcional. En este último caso, es posible que obtenga un comportamiento predeterminado que pretendía anular. Tenga especial cuidado aquí.

Cuando subclasifique una clase de AWS Construct Library (o sustituya un método que utilice un argumento similar a un objeto), puede que desee aceptar propiedades adicionales para su propio uso. La clase principal o el método anulado ignorarán estos valores, ya que en ese código nunca se accede a ellos, por lo que, en general, puedes transferir todos los accesorios que hayas recibido.

Una futura versión del AWS CDK podría añadir casualmente una nueva propiedad con el nombre que utilizó para su propia propiedad. Pasar el valor que reciba a la cadena de herencia puede provocar un comportamiento inesperado. Es más seguro entregar una copia superficial de los accesorios que recibiste con tus bienes retirados o puestos a undefined punto. Por ejemplo:

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

Como alternativa, ponle un nombre a tus propiedades para que quede claro que pertenecen a tu construcción. De esta forma, es poco probable que choquen con propiedades en futuras AWS CDK versiones. Si hay muchos de ellos, utilice un único objeto con el nombre apropiado para sostenerlos.

Valores faltantes

Los valores que faltan en un objeto (por ejemploprops) tienen el valor en. undefined JavaScript Para tratarlos se utilizan las técnicas habituales. Por ejemplo, un modismo común para acceder a una propiedad de un valor que puede no estar definido es el siguiente:

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

Sin embargo, si además a pudiera tener algún otro valor «falso»undefined, es mejor hacer la prueba más explícita. Aquí, aprovecharemos el hecho de que null undefined somos iguales para probar ambos a la vez:

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

Sintetizar y desplegar

Las pilas definidas en tu AWS CDK aplicación se pueden sintetizar e implementar de forma individual o conjunta mediante los siguientes comandos. Por lo general, debes estar en el directorio principal de tu proyecto cuando los emitas.

Puedes especificar los nombres de varias pilas que se van a sintetizar o implementar en un solo comando. Si tu aplicación define solo una pila, no es necesario que la especifiques.

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

También puedes usar los comodines * (cualquier número de caracteres) y? (cualquier carácter individual) para identificar las pilas por patrón. Cuando utilice caracteres comodín, escriba el patrón entre comillas. De lo contrario, es posible que el shell intente ampliarlo hasta incluir los nombres de los archivos del directorio actual antes de pasarlos al AWS CDK kit de herramientas.

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

Para obtener la documentación completa del cdk comando, consulte. AWS CDK Kit de herramientas (cdkcomando)

Uso de TypeScript ejemplos con JavaScript

TypeScriptes el lenguaje que utilizamos para desarrollar y fue el AWS CDK primer lenguaje compatible para el desarrollo de aplicaciones, por lo que están escritos muchos ejemplos de AWS CDK código disponibles TypeScript. Estos ejemplos de código pueden ser un buen recurso para JavaScript los desarrolladores; basta con eliminar las partes TypeScript específicas del código.

TypeScript Los fragmentos suelen utilizar el ECMAScript más reciente import y export palabras clave para importar objetos de otros módulos y declarar que los objetos estarán disponibles fuera del módulo actual. Node.js acaba de empezar a admitir estas palabras clave en sus últimas versiones. En función de la versión de Node.js que utilice (o que desee admitir), puede reescribir las importaciones y exportaciones para utilizar la sintaxis anterior.

Las importaciones se pueden sustituir por llamadas a la require() función.

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

Las exportaciones se pueden asignar al module.exports objeto.

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 }

Una vez que hayas ordenado las importaciones y exportaciones, puedes profundizar en el código real. Es posible que te encuentres con estas funciones de uso común TypeScript :

Se pueden proporcionar anotaciones de tipo para las variables, los miembros de la clase, los parámetros de las funciones y los tipos de retorno de las funciones. En el caso de las variables, los parámetros y los miembros, los tipos se especifican siguiendo el identificador con dos puntos y el tipo. Los valores devueltos por las funciones siguen la firma de la función y se componen de dos puntos y el tipo.

Para convertir el código anotado en texto JavaScript, elimine los dos puntos y el tipo. Los miembros de la clase deben tener algún valor JavaScript; configúrelo en undefined si solo tienen una anotación de texto. 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) {
    // ...
}

En TypeScript, las interfaces se utilizan para asignar un nombre a los paquetes de propiedades obligatorias y opcionales y a sus tipos. A continuación, puede utilizar el nombre de la interfaz como anotación de tipo. TypeScript se asegurará de que el objeto que utilice como argumento para una función, por ejemplo, tenga las propiedades requeridas de los tipos correctos.

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

JavaScript no tiene una función de interfaz, por lo que una vez que haya eliminado las anotaciones de tipo, elimine por completo las declaraciones de la interfaz.

Cuando una función o un método devuelve un tipo de uso general (por ejemploobject), pero desea tratar ese valor como un tipo secundario más específico para acceder a propiedades o métodos que no forman parte de la interfaz del tipo más general, TypeScript le permite convertir el valor as seguido de un nombre de tipo o interfaz. JavaScript no lo admite (o no lo necesita), así que basta con quitar as y el siguiente identificador. Una sintaxis de conversión menos común es usar el nombre de un tipo entre paréntesis<LikeThis>; estas conversiones también deben eliminarse.

Por último, TypeScript es compatible con los modificadores public de acceso y private para los miembros de las clases. protected Todos los miembros de la clase JavaScript son públicos. Simplemente elimine estos modificadores dondequiera que los vea.

Saber cómo identificar y eliminar estas TypeScript funciones contribuye en gran medida a adaptar los TypeScript fragmentos cortos a ellas. JavaScript Sin embargo, puede resultar poco práctico convertir TypeScript ejemplos más largos de esta manera, ya que es más probable que utilicen otras funciones. TypeScript Para estas situaciones, recomendamos Sucrase. Sucrase no se quejará si el código usa una variable indefinida, por ejemplo, como lo haría. tsc Si es sintácticamente válido, con pocas excepciones, Sucrase puede traducirlo a. JavaScript Esto lo hace particularmente valioso para convertir fragmentos que tal vez no se puedan ejecutar por sí solos.

¿Migrar a TypeScript

Muchos JavaScript desarrolladores se mudan a ella a TypeScriptmedida que sus proyectos se hacen más grandes y complejos. TypeScript es un superconjunto de JavaScript (todo el JavaScript código es TypeScript código válido, por lo que no es necesario realizar cambios en el código) y también es un lenguaje compatible. AWS CDK Las anotaciones de texto y otras TypeScript funciones son opcionales y puedes añadirlas a tu AWS CDK aplicación a medida que encuentres valor en ellas. TypeScript también te da acceso anticipado a nuevas JavaScript funciones, como el encadenamiento opcional y la fusión de valores nulos, antes de que estén listas y sin necesidad de actualizar Node.js.

TypeScriptSus interfaces «basadas en formas», que definen paquetes de propiedades obligatorias y opcionales (y sus tipos) dentro de un objeto, permiten detectar los errores más comunes al escribir el código y facilitan que el IDE pueda proporcionar consejos sólidos de autocompletado y otros consejos de codificación en tiempo real.

La codificación TypeScript implica un paso adicional: compilar la aplicación con el compilador,. TypeScript tsc Para AWS CDK las aplicaciones típicas, la compilación requiere unos segundos como máximo.

La forma más sencilla de migrar una JavaScript AWS CDK aplicación existente TypeScript es crear un nuevo TypeScript proyecto utilizando cdk init app --language typescript los archivos fuente (y cualquier otro archivo necesario, como recursos como el código fuente de una AWS Lambda función) y copiarlos al nuevo proyecto. Cambia el nombre de tus JavaScript archivos para que terminen en .ts y comiencen a desarrollar en TypeScript.