Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Trabalhando com o AWS CDK em TypeScript
TypeScript é uma linguagem de cliente totalmente compatível com o AWS Cloud Development Kit (AWS CDK) e é considerada estável. Trabalhar com o AWS CDK TypeScript usa ferramentas familiares, incluindo o TypeScript compilador (tsc), o Node.jsnpm) da Microsoft. Você também pode usar o Yarn
Você pode usar qualquer editor ou IDE. Muitos desenvolvedores de AWS CDK usam o Visual Studio Code
Comece com TypeScript
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte Introdução ao AWS CDK.
Você também precisa de TypeScript si mesmo (versão 3.8 ou posterior). Se ainda não o tiver, você pode instalá-lo usandonpm.
$ npm install -g typescript
nota
Se você receber um erro de permissão e tiver acesso de administrador em seu sistema, tente sudo npm install -g typescript.
TypeScript Mantenha-se atualizado com um cliente regularnpm update -g typescript.
nota
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
Criação de um projeto
Você cria um novo projeto AWS CDK invocando cdk init em um diretório vazio. Use a opção --language e especifique typescript:
$ mkdir my-project $ cd my-project $ cdk init app --language typescript
A criação de um projeto também instala o módulo aws-cdk-lib e suas dependências.
cdk init usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, caso contrário, o nome deve seguir a forma de um TypeScript identificador; por exemplo, ele não deve começar com um número ou conter espaços.
Uso de tsc e cdk local
Na maioria das vezes, este guia pressupõe que você instale TypeScript o CDK Toolkit globalmente (npm install -g typescript aws-cdk), e os exemplos de comandos fornecidos (comocdk synth) seguem essa suposição. Essa abordagem facilita a atualização dos dois componentes e, como ambos adotam uma abordagem rígida de compatibilidade com versões anteriores, geralmente há pouco risco em sempre usar as versões mais recentes.
Algumas equipes preferem especificar todas as dependências em cada projeto, incluindo ferramentas como o TypeScript compilador e o CDK Toolkit. Essa prática permite que você fixe esses componentes em versões específicas e garanta que todos os desenvolvedores da sua equipe (e do seu ambiente de CI/CD) usem exatamente essas versões. Isso elimina uma possível fonte de mudança, ajudando a tornar as compilações e implantações mais consistentes e reproduzíveis.
O CDK inclui dependências para ambos TypeScript e o CDK Toolkit no modelo do TypeScript projeto. Portantopackage.json, se você quiser usar essa abordagem, não precisará fazer nenhuma alteração em seu projeto. Tudo o que você precisa fazer é usar comandos ligeiramente diferentes para compilar sua aplicação e emitir comandos cdk.
| Operação | Usar ferramentas globais | Usar ferramentas locais |
|---|---|---|
|
Inicializar projeto |
|
|
|
Compilar |
|
|
|
Execute o comando CDK Toolkit |
|
|
npx aws-cdk executa a versão do CDK Toolkit instalada localmente no projeto atual, se houver, retornando à instalação global, se houver. Se não existir uma instalação global, npx baixa uma cópia temporária do CDK Toolkit e a executa. Você pode especificar uma versão arbitrária do CDK Toolkit usando a sintaxe @: npx aws-cdk@2.0 --version imprime 2.0.0.
dica
Configure um alias para que você possa usar o comando cdk com uma instalação local do CDK Toolkit.
Gerenciando módulos da AWS Construct Libr
Use o Node Package Manager (npm) para instalar e atualizar os módulos da AWS Construct Library para uso por seus aplicativos, bem como por outros pacotes necessários. (Você pode usar yarn em vez de npm, se preferir.) npm também instala as dependências desses módulos automaticamente.
A maioria das construções de AWS CDK está no pacote CDK principal, chamadoaws-cdk-lib, que é uma dependência padrão em novos projetos criados por. cdk init Os módulos “experimentais” da AWS Construct Library, nos quais construções de nível superior ainda estão em desenvolvimento, são nomeados como. @aws-cdk/<SERVICE-NAME>-alpha O nome do serviço tem um prefixo aws-. Se você não tiver certeza do nome de um módulo, procure-o no NPM
nota
A Referência da API CDK também mostra os nomes dos pacotes.
Por exemplo, o comando abaixo instala o módulo experimental para AWS CodeStar.
$ npm install @aws-cdk/aws-codestar-alpha
O suporte da Biblioteca de Constructos de alguns serviços está em mais de um namespace. Por exemplo, além de aws-route53, há três namespaces adicionais do Amazon Route 53, aws-route53-targets, aws-route53-patterns e aws-route53resolver.
As dependências do seu projeto são mantidas empackage.json. Você pode editar esse arquivo para bloquear algumas ou todas as suas dependências em uma versão específica ou para permitir que elas sejam atualizadas para versões mais recentes sob determinados critérios. Para atualizar as dependências do NPM do seu projeto para a versão mais recente permitida de acordo com as regras que você especificou em: package.json
$ npm update
Em TypeScript, você importa módulos para o seu código com o mesmo nome usado para instalá-los usando o NPM. Recomendamos as seguintes práticas ao importar classes AWS CDK e módulos da AWS Construct Library em seus aplicativos. Seguir essas diretrizes ajudará a tornar seu código consistente com outros aplicativos AWS CDK, além de ser mais fácil de entender.
-
Use
importdiretivas ES6 -style, não.require() -
Geralmente, importe classes individuais de
aws-cdk-lib.import { App, Stack } from 'aws-cdk-lib'; -
Se precisar de muitas classes de
aws-cdk-lib, você pode usar um alias de namespace decdk, em vez de importar as classes individuais. Evite fazer as duas coisas.import * as cdk from 'aws-cdk-lib'; -
Geralmente, importe construções AWS de serviços usando aliases curtos de namespace.
import { aws_s3 as s3 } from 'aws-cdk-lib';
Gerenciando dependências em TypeScript
Em projetos TypeScript CDK, as dependências são especificadas no package.json arquivo no diretório principal do projeto. Os módulos AWS CDK principais estão em um único NPM pacote chamadoaws-cdk-lib.
Quando você instala um pacote usando npm install, o NPM grava o pacote em package.json para você.
Se preferir, você pode usar o Yarn no lugar do NPM. No entanto, o CDK não suporta o modo Yarn, que é o plug-and-play modo padrão no Yarn 2. Adicione o seguinte ao .yarnrc.yml arquivo do seu projeto para desativar esse recurso.
nodeLinker: node-modules
Aplicações do CDK
Veja a seguir um exemplo de arquivo package.json gerado pelo comando cdk init --language typescript:
{ "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" } }
Para aplicações CDK implantáveis, aws-cdk-lib deve ser especificado na seção dependencies de package.json. Você pode usar um especificador de número de versão com acento circunflexo (^) para indicar que aceitará versões posteriores à especificada, desde que estejam na mesma versão principal.
Para construções experimentais, especifique as versões exatas dos módulos da biblioteca de construções alfa, APIs que podem mudar. Não use ^ ou ~, pois versões posteriores desses módulos podem trazer alterações na API que podem prejudicar sua aplicação.
Especifique as versões das bibliotecas e ferramentas necessárias para testar sua aplicação (por exemplo, a estrutura de teste jest) na seção devDependencies de package.json. Opcionalmente, use ^ para especificar que versões compatíveis posteriores sejam aceitáveis.
Bibliotecas de constructos de terceiros
Se você estiver desenvolvendo uma biblioteca de construção, especifique suas dependências usando uma combinação das devDependencies seções peerDependencies e, conforme mostrado no package.json arquivo de exemplo a seguir.
{ "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" } }
Em peerDependencies, use um acento circunflexo (^) para especificar a versão mais baixa de aws-cdk-lib com a qual sua biblioteca trabalha. Isso maximiza a compatibilidade da sua biblioteca com uma variedade de versões do CDK. Especifique as versões exatas dos módulos da biblioteca de construção alfa, APIs que podem mudar. O uso de peerDependencies garante que haja apenas uma cópia de todas as bibliotecas CDK na árvore node_modules.
Em devDependencies, especifique as ferramentas e bibliotecas que você precisa para testar, opcionalmente com ^ para indicar que versões compatíveis posteriores são aceitáveis. Especifique exatamente (sem ^ ou ~) as versões mais baixas de aws-cdk-lib e outros pacotes de CDK com os quais você anuncia a compatibilidade da sua biblioteca. Essa prática garante que seus testes sejam executados nessas versões. Dessa forma, se você usar inadvertidamente um atributo encontrado apenas em versões mais recentes, seus testes poderão detectá-lo.
Atenção
peerDependencies são instalados automaticamente somente pelo NPM 7 e versões posteriores. Se você estiver usando o NPM 6 ou versão anterior, ou se estiver usando o Yarn, deverá incluir as dependências de suas dependências no devDependencies. Caso contrário, eles não serão instalados e você receberá um aviso sobre dependências de pares não resolvidas.
Instalação e atualização de dependências
Execute o comando a seguir para instalar as dependências do seu projeto.
Para atualizar os módulos instalados, os comandos npm install e yarn upgrade anteriores podem ser usados. Qualquer um dos comandos atualiza os pacotes em node_modules para as versões mais recentes que atendem às regras em package.json. No entanto, não atualizam package.json por conta própria, o que talvez você queira fazer para definir uma nova versão mínima. Se você hospedar seu pacote em GitHub, você pode configurar as atualizações de versão do Dependabot para serem atualizadaspackage.json Como alternativa, use npm-check-updates
Importante
Por padrão, quando você instala ou atualiza dependências, o NPM e o Yarn escolhem a versão mais recente de cada pacote que atenda aos requisitos especificados em package.json. Sempre existe o risco de que essas versões sejam quebradas (acidental ou intencionalmente). Teste minuciosamente depois de atualizar as dependências do seu projeto.
AWS Expressões idiomáticas do CDK em TypeScript
Props
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o escopo no qual a construção está sendo definida (seu pai na árvore de construção), um id e adereços. Argument props é um pacote de pares de chave/valor que a construção usa para configurar os AWS recursos que ela cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
Em TypeScript, a forma de props é definida usando uma interface que informa os argumentos obrigatórios e opcionais e seus tipos. Essa interface é definida para cada tipo de argumento props, geralmente específico para um único constructo ou método. Por exemplo, a Bucketconstrução (no aws-cdk-lib/aws-s3 módulo) especifica um props argumento em conformidade com a BucketPropsinterface.
Se uma propriedade for em si um objeto, por exemplo, a websiteRedirectpropriedade deBucketProps, esse objeto terá sua própria interface à qual sua forma deve se adequar, nesse caso RedirectTarget.
Se você estiver subclassificando uma classe da AWS Construct Library (ou substituindo um método que usa um argumento semelhante a adereços), você pode herdar da interface existente para criar uma nova que especifique quaisquer novos adereços que seu código exija. Ao chamar a classe principal ou o método base, você normalmente pode passar todo o argumento props recebido, pois quaisquer atributos fornecidos no objeto, mas não especificados na interface, serão ignorados.
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Passar o valor que você recebe para a cadeia de herança pode causar um comportamento inesperado. É mais seguro passar uma cópia rasa dos adereços que você recebeu com sua propriedade removida ou configurada para. undefined Por exemplo:
super(scope, name, {...props, encryptionKeys: undefined});
Como alternativa, nomeie suas propriedades para que fique claro que elas pertencem ao seu constructo. Dessa forma, é improvável que eles colidam com propriedades em futuras versões do AWS CDK. Se houver muitas delas, use um único objeto com nome apropriado para mantê-las.
Valores ausentes
Valores ausentes em um objeto (como adereços) têm o valor undefined em TypeScript. A versão 3.7 da linguagem introduziu operadores que simplificam o trabalho com esses valores, facilitando a especificação de padrões e o encadeamento em “curto-circuito” quando um valor indefinido é atingido. Para obter mais informações sobre esses recursos, consulte as Notas de versão TypeScript 3.7
Compilação e execução de aplicações do CDK
Geralmente, você deve estar no diretório raiz do projeto ao criar e executar seu aplicativo.
O Node.js não pode ser executado TypeScript diretamente; em vez disso, seu aplicativo é convertido para JavaScript usar o TypeScript compilador,tsc. O JavaScript código resultante é então executado.
O AWS CDK faz isso automaticamente sempre que precisa executar seu aplicativo. No entanto, pode ser útil compilar manualmente para verificar erros e executar testes. Para compilar seu TypeScript aplicativo manualmente, emitanpm run build. Você também pode optar por npm run watch entrar no modo de observação, no qual o TypeScript compilador recria automaticamente seu aplicativo sempre que você salva as alterações em um arquivo de origem.
