Trabalhando com o AWS CDK in Go

Este é o Guia do Desenvolvedor 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á.

Este é o Guia do Desenvolvedor 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á.

Go é uma linguagem de cliente totalmente compatível com o AWS Cloud Development Kit (AWS CDK) e é considerada estável. Trabalhar com o AWS CDK in Go usa ferramentas familiares. A versão Go do AWS CDK evento usa identificadores no estilo Go.

Ao contrário das outras linguagens suportadas pelo CDK, Go não é uma linguagem de programação tradicional orientada a objetos. Go utiliza composição onde outras linguagens frequentemente recorrem à herança. Tentamos empregar abordagens idiomáticas de Go ao máximo, mas há lugares em que o CDK pode ser diferente.

Este tópico fornece orientação ao trabalhar com o AWS CDK in Go. Veja a postagem do blog do anúncio para ver um passo a passo de um projeto Go simples para AWS CDK.

Comece com Go

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 Começando com o AWS CDK.

As vinculações Go para o AWS CDK usam o conjunto de ferramentas Go padrão, v1.18 ou posterior. Você pode usar o editor de sua preferência.

Criação de um projeto

Você cria um novo AWS CDK projeto invocando cdk init em um diretório vazio. Use a opção --language e especifique go:

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

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 Go; por exemplo, não deve começar com um número nem conter espaços.

O projeto resultante inclui uma referência ao módulo AWS CDK Go principal,github.com/aws/aws-cdk-go/awscdk/v2, emgo.mod. Emita go get para instalar este e outros módulos necessários.

Gerenciando módulos da AWS Construct Libr

Na maioria das AWS CDK documentações e exemplos, a palavra “módulo” é frequentemente usada para se referir aos módulos da AWS Construct Library, um ou mais por AWS serviço, o que difere do uso idiomático do termo em Go. A CDK Biblioteca de Constructos é fornecida em um módulo Go com os módulos individuais da Biblioteca de Constructos, que suportam os vários serviços AWS , fornecidos como pacotes Go dentro desse módulo.

O suporte da AWS Construct Library de alguns serviços está em mais de um módulo da Construct Library (pacote Go). Por exemplo, o Amazon Route 53 tem três módulos da Biblioteca de Constructos, além do pacote awsroute53 principal, denominados awsroute53patterns, awsroute53resolver e awsroute53targets.

O AWS CDK pacote principal, que você precisará na maioria dos AWS CDK aplicativos, é importado no código Go comogithub.com/aws/aws-cdk-go/awscdk/v2. Os pacotes para os vários serviços da AWS Construct Library estão abaixogithub.com/aws/aws-cdk-go/awscdk/v2. Por exemplo, o namespace do módulo Amazon S3 é github.com/aws/aws-cdk-go/awscdk/v2/awss3.

import (
        "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
        // ...
)

Depois de importar os módulos da Biblioteca de Constructos (pacotes Go) para os serviços que deseja usar em sua aplicação, você acessa os constructos desse módulo usando, por exemplo, awss3.Bucket.

Gerenciando dependências em Go

Em Go, as versões das dependências são definidas em go.mod. go.mod padrão é semelhante ao mostrado aqui.

module my-package

go 1.16

require (
  github.com/aws/aws-cdk-go/awscdk/v2 v2.16.0
  github.com/aws/constructs-go/constructs/v10 v10.0.5
  github.com/aws/jsii-runtime-go v1.29.0
)

Os nomes dos pacotes (módulos, no jargão do Go) são especificados por URL com o número de versão necessário anexado. O sistema de módulos do Go não suporta intervalos de versões.

Emita o comando go get para instalar todos os módulos necessários e atualizar go.mod. Para ver uma lista de atualizações disponíveis para suas dependências, emita go list -m -u all.

AWS CDK expressões idiomáticas em Go

Nomes de campos e métodos

Os nomes de campos e métodos usam camel casing (likeThis) in TypeScript, o idioma de origem do CDK. Em Go, eles seguem as convenções da linguagem, sendo, portanto, em Pascal case (LikeThis).

Limpeza

Em seu método main, use defer jsii.Close() para garantir que sua aplicação CDK se limpe sozinho.

Valores ausentes e conversão de ponteiro

Em Go, os valores ausentes em AWS CDK objetos, como pacotes de propriedades, são representados pornil. Go não tem tipos anuláveis; o único tipo que pode conter nil é um ponteiro. Para permitir que os valores sejam opcionais, então, todas as propriedades, argumentos e valores de retorno do CDK são ponteiros, mesmo para tipos primitivos. Isso se aplica tanto aos valores obrigatórios quanto aos opcionais, portanto, se um valor obrigatório se tornar opcional posteriormente, nenhuma alteração significativa no tipo será necessária.

Ao passar valores ou expressões literais, use as seguintes funções auxiliares para criar ponteiros para os valores.

Para fins de consistência, recomendamos que você use ponteiros de forma semelhante ao definir seus próprios constructos, mesmo que pareça mais conveniente, por exemplo, receber id do constructo como uma string em vez de um ponteiro para uma string.

Ao lidar com AWS CDK valores opcionais, incluindo valores primitivos e tipos complexos, você deve testar explicitamente os ponteiros para garantir que não estejam nil antes de fazer nada com eles. Go não dispõe de “açúcar sintático” para lidar com valores vazios ou ausentes, como algumas outras linguagens fazem. No entanto, é garantido que os valores necessários em pacotes de propriedades e estruturas similares existam (caso contrário, a construção falhará), portanto, esses valores não precisam ser verificados por nil.

Constructos e props

As construções, que representam um ou mais AWS recursos e seus atributos associados, são representadas em Go como interfaces. Por exemplo, awss3.Bucket é uma interface. Cada constructo tem uma função de fábrica, como awss3.NewBucket, para retornar uma estrutura que implementa a interface correspondente.

Todas as funções de fábrica usam três argumentos: o scope no qual o constructo está sendo definido (seu pai na árvore de constructos), id e props, um pacote de pares de chave/valor que o constructo usa para configurar os recursos que cria. O padrão “pacote de atributos” também é usado em outras partes de AWS CDK.

Em Go, os props são representados por um tipo de estrutura específico para cada constructo. Por exemplo, awss3.Bucket usa um argumento props do tipo awss3.BucketProps. Use uma estrutura literal para escrever argumentos de props.

var bucket = awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
    Versioned: jsii.Bool(true),
})

Estruturas genéricas

Em alguns lugares, o AWS CDK usa JavaScript matrizes ou objetos não digitados como entrada para um método. (Veja, por exemplo, o método BuildSpec.fromObject() de AWS CodeBuild.) Em Go, esses objetos são representados como fatias e uma interface vazia, respectivamente.

O CDK fornece funções auxiliares variáveis, como jsii.Strings para criar fatias contendo tipos primitivos.

jsii.Strings("One", "Two", "Three")

Desenvolvimento de constructos personalizados

Em Go, geralmente é mais simples escrever um novo constructo do que estender um existente. Primeiro, defina um novo tipo de estrutura, incorporando anonimamente um ou mais tipos existentes se uma semântica semelhante à extensão for desejada. Escreva métodos para qualquer nova funcionalidade que você esteja adicionando e os campos necessários para armazenar os dados necessários. Defina uma interface de props se o seu constructo precisar de uma. Por fim, escreva uma função de fábrica NewMyConstruct() para retornar uma instância do seu constructo.

Se você está simplesmente alterando alguns valores padrão em um constructo existente ou adicionando um comportamento simples na instanciação, você não precisa de todo esse encanamento. Em vez disso, escreva uma função de fábrica que chame a função de fábrica do constructo que você está “estendendo”. Em outras linguagens de CDK, por exemplo, você pode criar um constructo TypedBucket que imponha o tipo de objeto em um bucket do Amazon S3 substituindo o tipo s3.Bucket e, no inicializador do seu novo tipo, adicionando uma política de bucket que permite que somente extensões de nome de arquivo especificadas sejam adicionadas ao bucket. Em Go, é mais fácil simplesmente escrever NewTypedBucket que retorne s3.Bucket (instanciado com o uso de s3.NewBucket) ao qual você adicionou uma política de bucket apropriada. Nenhum novo tipo de constructo é necessário porque a funcionalidade já está disponível no constructo padrão do bucket; o novo “constructo” fornece apenas uma maneira mais simples de configurá-lo.

Construção, sintetização e implantação

Ele compila AWS CDK automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar sua aplicação manualmente para verificar erros e executar testes. Você pode fazer isso emitindo go build em um prompt de comando enquanto estiver no diretório raiz do seu projeto.

Execute todos os testes que você escreveu executando go test em um prompt de comando.