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.

Trabalho com o AWS CDK em Go

O Go 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. Trabalhar com o AWS CDK no Go envolve o uso de ferramentas familiares. A versão Go do AWS CDK usa até mesmo identificadores no estilo Go.

Ao contrário das outras linguagens com suporte no CDK, o Go não é uma linguagem de programação tradicional orientada a objetos. O 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 no Go. Veja a postagem do blog de anúncios para ver um passo a passo de um projeto Go simples para o AWS CDK.

Conceitos básicos do Go

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.

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

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 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 principal do Go Go do AWS CDK, github.com/aws/aws-cdk-go/awscdk/v2, em go.mod. Emita go get para instalar este e outros módulos necessários.

Gerenciamento de módulos da Biblioteca de Constructos da AWS

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

O suporte da Biblioteca de Constructos da AWS de alguns serviços está em mais de um módulo da Biblioteca de Constructos (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 pacote principal do AWS CDK, que você precisará na maioria das aplicações do AWS CDK, é importado em código de Go como github.com/aws/aws-cdk-go/awscdk/v2. Os pacotes para os vários serviços da Biblioteca de Constructos da AWS estão em github.com/aws/aws-cdk-go/awscdk/v2. Por exemplo, o namespace do módulo do 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 de Go) para os serviços que deseja usar em sua aplicação, você acessa os constructos desse módulo usando, por exemplo, awss3.Bucket.

Gerenciamento de 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 da versão necessária anexado. O sistema de módulo do Go não oferece suporte a 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.

Expressões idiomáticas do AWS CDK em Go

Nomes de campos e métodos

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

Liberar

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 objetos do AWS CDK, como pacotes de propriedades, são representados por nil. O 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 seu id do constructo como uma string em vez de um ponteiro para uma string.

Ao lidar com valores opcionais do AWS CDK, incluindo valores primitivos e tipos complexos, é necessário testar explicitamente os ponteiros para garantir que não sejam nil antes de fazer algo 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

Os constructos que representam um ou mais recursos da AWS e seus atributos associados são representados 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 do 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 matrizes de JavaScript ou objetos não tipados como entrada para um método. (Veja, por exemplo, o método BuildSpec.fromObject() do 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")

Trabalho com quaisquer fatias

Certos constructos esperam propriedades que sejam uma lista de vários tipos (tipos de união no TypeScript). Em Go, eles são como uma fatia de qualquer (*[]any). O any CDK garante que o compilador permita a atribuição de diferentes tipos lá. Consulte a documentação do AWS CDK Go package para descobrir quais são os tipos permitidos.

Para trabalhar com essas propriedades, use as funções auxiliares fornecidas pelo jsii para criar fatias de qualquer tipo diferente:

Por exemplo:

func Arns() *[]*string {
a := "arn:aws:s3:::bucket1"
b := "arn:aws:s3:::bucket2"
return &[]*string{&a, &b}
}

awsiam.NewCfnUser(stack, jsii.String("User"), &awsiam.CfnUserProps{
	ManagedPolicyArns: jsii.AnySlice(Arns())
  // or
	ManagedPolicyArns: jsii.AnyStrings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2")
  // or
  ManagedPolicyArns: &[]interface{}{
    jsii.String("arn:aws:s3:::bucket1"),
    jsii.String("arn:aws:s3:::bucket2"),
  }
})

Essa abordagem garante que suas fatias sejam interpretadas corretamente pelo CDK, evitando erros de desserialização ao implantar ou sintetizar suas pilhas.

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 do CDK, por exemplo, é possível 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 um 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.

Compilação, sintetização e implantação

O AWS CDK compila automaticamente sua aplicação antes de executá-la. No entanto, pode ser útil criar sua aplicação manualmente para verificar erros e executar testes. É possível 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.

Solução de problemas

Se você encontrar um erro de compilador como o a seguir, isso significa que as fatias de string foram passadas diretamente para uma propriedade que espera uma fatia de qualquer.

Cannot use 'jsii.Strings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2")' (type *[]*string) as the type *[]interface{}

Para resolver esse erro, substitua jsii.Strings() por jsii.AnyStrings(). Veja este CDK GitHub issue para obter mais contexto e soluções adicionais.