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á. # Trabalho com o AWS CDK em TypeScript O TypeScript consiste em uma linguagem de cliente com suporte total para o kit de desenvolvimento em nuvem da AWS (CDK da AWS), e considerada estável. O trabalho com o AWS CDK em TypeScript usa ferramentas familiares, incluindo o compilador TypeScript (`tsc`) da Microsoft, o [Node.js](https://nodejs.org/) e o Node Package Manager (`npm`). Você também pode usar o [Yarn](https://yarnpkg.com/) se preferir, embora os exemplos neste Guia usem o NPM. Os módulos que compõem a Biblioteca de Constructos da AWS são distribuídos por meio do repositório NPM, [npmjs.org](https://www.npmjs.com/). É possível usar qualquer editor ou IDE. Muitos desenvolvedores do AWS CDK usam o [Visual Studio Code](https://code.visualstudio.com/) (ou seu equivalente de código aberto [VSCodium](https://vscodium.com/)), que tem excelente suporte para TypeScript. ## Conceitos básicos de TypeScript Para trabalhar com o AWS CDK, é necessário ter uma conta e credenciais da AWS e ter instalado o Node.js e o Kit de Ferramentas CDK da AWS. Consulte [Conceitos básicos do AWS CDK](getting-started.md). Você também precisa do próprio TypeScript (versão 3.8 ou posterior). Se ainda não tiver, poderá instalá-lo usando `npm`. ``` $ 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`. Mantenha o TypeScript atualizado com `npm update -g typescript` normal. **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 do 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 [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) 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, o nome deve seguir a forma de um identificador do TypeScript; por exemplo, não deve começar com um número nem conter espaços. ## Uso de `tsc` e `cdk` local Na maioria das vezes, este guia pressupõe que você instale o TypeScript e o Kit de Ferramentas CDK globalmente (`npm install -g typescript aws-cdk`), e os exemplos de comandos fornecidos (como `cdk 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 compilador TypeScript e o Kit de Ferramentas CDK. 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 tanto para o TypeScript quanto para o Kit de Ferramentas CDK no `package.json` do modelo de projeto do TypeScript. Portanto, 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** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **Compilar** | `tsc` | `npm run build` | | **Execute o comando do Kit de Ferramentas CDK** | `cdk …​` | `npm run cdk …​` ou `npx aws-cdk …​` | `npx aws-cdk` executa a versão do Kit de Ferramentas CDK 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 Kit de Ferramentas CDK e a executa. É possível especificar uma versão arbitrária do Kit de Ferramentas CDK 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 Kit de Ferramentas CDK. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Gerenciamento de módulos da Biblioteca de Constructos da AWS Use o Node Package Manager (`npm`) para instalar e atualizar os módulos da Biblioteca de Constructos da AWS para uso por suas aplicações, bem como por outros pacotes necessários. (É possível usar `yarn` em vez de `npm`, se preferir.) `npm` também instala as dependências desses módulos automaticamente. A maioria dos constructos da AWS está no pacote principal do CDK, chamado `aws-cdk-lib`, que é uma dependência padrão em novos projetos criados por `cdk init`. Os módulos “experimentais” da Biblioteca de Constructos da AWS, nos quais constructos de nível superior ainda estão em desenvolvimento, são nomeados como `@aws-cdk/-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](https://www.npmjs.com/search?q=%40aws-cdk). **nota** A [Referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) 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 em `package.json`. É possível 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 ``` No TypeScript, você importa módulos para o seu código com o mesmo nome usado para instalá-los usando o NPM. Recomendamos as práticas a seguir ao importar classes do AWS CDK e módulos da Biblioteca de Constructos da AWS em suas aplicações. Seguir essas diretrizes ajudará a tornar seu código consistente com outras aplicações do AWS CDK, além de ser mais fácil de entender. + Use diretivas `import` no estilo ES6, 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 de `cdk`, em vez de importar as classes individuais. Evite fazer as duas coisas. ``` import * as cdk from 'aws-cdk-lib'; ``` + Geralmente, importe constructos de serviços AWS usando aliases curtos de namespace. ``` import { aws_s3 as s3 } from 'aws-cdk-lib'; ``` ## Gerenciamento de dependências em TypeScript Em projetos do CDK em TypeScript, as dependências são especificadas no arquivo `package.json`, no diretório principal do projeto. Os módulos principais do AWS CDK estão em um único pacote `NPM` chamado `aws-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 oferece suporte ao modo plug-and-play do Yarn, que é o modo padrão no Yarn 2. Adicione o seguinte ao arquivo `.yarnrc.yml` do seu projeto para desativar esse atributo. ``` 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`. É possível 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 constructos experimentais, especifique as versões exatas dos módulos da Biblioteca de Constructos alfa, que têm APIs que podem mudar. Não use ^ ou \$1, 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 constructos, especifique suas dependências usando uma combinação das seções `peerDependencies` e `devDependencies`, conforme mostrado no arquivo `package.json` 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 de Biblioteca de Constructos alfa, que têm 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 \$1) as versões mais baixas de `aws-cdk-lib` e outros pacotes do 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, elas não serão instaladas e você receberá um aviso sobre dependências de pares não resolvidas. ### Instalação e atualização de dependências Use o comando a seguir para instalar as dependências do seu projeto. **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 ``` 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 no GitHub, poderá configurar as [atualizações de versão do Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) para atualizar `package.json` automaticamente. Como alternativa, use [npm-check-updates](https://www.npmjs.com/package/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. ## Expressões idiomáticas do AWS em TypeScript ### Props *Todas as classes da Biblioteca de Constructos da AWS são instanciadas usando três argumentos: o *escopo* no qual o constructo está sendo definido (seu pai na árvore de constructos), um *id* e adereços.* O argumento *props* consiste em um pacote de pares de chave/valor que o constructo usa para configurar os recursos AWS que ele cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos. No 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, o constructo [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) (no módulo `aws-cdk-lib/aws-s3`) especifica um argumento `props` em conformidade com a interface [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). Se uma propriedade for em si um objeto, por exemplo, a propriedade [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) de `BucketProps`, esse objeto terá sua própria interface à qual sua forma deverá estar em conformidade, nesse caso, [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). Se estiver subclassificando uma classe da Biblioteca de Constructos da AWS (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 colidam com propriedades em versões futuras 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 props) 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 atributos, consulte as [Notas de versão do TypeScript 3.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), especificamente os dois primeiros recursos, encadeamento opcional e coalescência nula. ## Compilação e execução de aplicações do CDK Normalmente, é necessário estar no diretório raiz do projeto ao criar e executar sua aplicação. O Node.js não pode executar o TypeScript diretamente; em vez disso, sua aplicação é convertido em JavaScript usando o compilador TypeScript, `tsc`. Em seguida, o código JavaScript resultante é executado. O AWS CDK faz isso automaticamente sempre que precisa executar sua aplicação. No entanto, pode ser útil compilar manualmente para verificar erros e executar testes. Para compilar sua aplicação TypeScript manualmente, emita `npm run build`. Você também pode emitir `npm run watch` para entrar no modo de observação, no qual o compilador TypeScript reconstrói automaticamente sua aplicação sempre que você salva as alterações em um arquivo de origem.