Visão geral dos registros de decisão de arquitetura

Last reviewed 2023-04-11 UTC

Para ajudar a explicar por que suas equipes de infraestrutura ou aplicativo fazem determinadas escolhas de design, use registros de decisão de arquitetura (ADRs, na sigla em inglês). Este documento explica quando e como usar ADRs conforme você cria e executa aplicativos no Google Cloud.

Um ADR captura as principais opções disponíveis, os principais requisitos que determinam uma decisão e as próprias decisões de design. Muitas vezes, você armazena os ADRs em um arquivo Markdown próximo à base de código relevante para essa decisão. Se alguém precisar entender o histórico de uma decisão de arquitetura específica, por exemplo, por que você usa um cluster regional do Google Kubernetes Engine (GKE), poderá revisar o ADR e, em seguida, o código associado.

Os ADRs também ajudam a executar aplicativos e serviços mais confiáveis. O ADR ajuda a entender o estado atual e resolver problemas quando há um problema. Os ADRs também criam um conjunto de decisões de engenharia para ajudar nas futuras escolhas e implantações.

Quando usar ADRs

Os ADRs são usados para rastrear as principais áreas que você considera importantes para a implantação. As categorias a seguir podem estar nos seus ADRs:

  • Escolhas específicas do produto, como a escolha entre Pub/Sub e Pub/Sub Lite.
  • Opções e configurações de produtos específicos, como o uso de clusters regionais do GKE com a entrada de vários clusters para aplicativos altamente disponíveis.
  • Orientação geral sobre arquitetura, como as práticas recomendadas para manifestos do Dockerfile.

Alguns exemplos específicos que podem solicitar que você crie um ADR são as seguintes opções:

  • Como e por que você configura a alta disponibilidade (HA, na sigla em inglês) para suas instâncias do Cloud SQL?
  • Como você aborda o tempo de atividade dos clusters do GKE? Você usa clusters regionais? Você usa versões canário? Por quê?

À medida que você avalia os produtos a serem usados, o ADR ajuda a explicar cada uma das suas decisões. É possível revisitar o ADR conforme a equipe evolui e aprende mais sobre a pilha e conforme novas decisões são tomadas ou ajustadas. Se você fizer ajustes, inclua a decisão anterior e o motivo da alteração. Esse histórico mantém um registro de como a arquitetura mudou conforme as necessidades de negócios evoluíram ou onde há novos requisitos técnicos ou soluções disponíveis.

Os prompts a seguir ajudam você a saber quando criar ADRs:

  • Quando você tiver um desafio ou uma questão técnica e não houver uma base para uma decisão, como uma solução recomendada, um procedimento de operação padrão, um blueprint ou uma base de código.
  • Quando você ou sua equipe oferece uma solução que não está documentada em algum lugar acessível à equipe.
  • Quando há duas ou mais opções de engenharia e você quer documentar suas ideias e motivos por trás da seleção.

Ao escrever um ADR, é útil lembrar de possíveis leitores. Os leitores principais são membros da equipe que trabalham na tecnologia coberta pelo ADR. Grupos mais amplos de leitores em potencial do ADR podem incluir equipes adjacentes que querem entender suas decisões, como equipes de arquitetura e segurança.

Considere também que o aplicativo pode alterar os proprietários ou incluir novos membros da equipe. Um ADR ajuda os novos colaboradores a entender o contexto das escolhas de engenharia feitas. Um ADR também facilita o planejamento de alterações futuras.

Formato de um ADR

Um ADR típico inclui um conjunto de capítulos. Os ADRs devem ajudar a capturar o que você considera importante para o aplicativo e sua organização. Alguns ADRs podem ter uma página, enquanto outros exigem uma explicação mais longa.

O exemplo de resumo ADR a seguir mostra como é possível formatar um ADR para incluir as informações importantes para seu ambiente:

  • Autores e a equipe
  • Contexto e problema que você quer resolver
  • Requisitos funcionais e não funcionais que você quer resolver
  • Possível jornada ideal do usuário (CUJ) que a decisão afeta
  • Visão geral das principais opções
  • Sua decisão e os motivos por trás da escolha aceita

Para ajudar a manter um registro das decisões, inclua um carimbo de data/hora para cada decisão a ser exibida quando a escolha foi feita.

Como os ADRs funcionam

Os ADRs funcionam melhor quando engenheiros, desenvolvedores ou proprietários de aplicativos podem acessar facilmente as informações que contêm. Quando eles têm uma pergunta sobre o motivo pelo qual algo é feito de alguma forma, podem recorrer ao ADR para encontrar a resposta.

Para tornar o ADR acessível, algumas equipes o hospedam em um wiki central que também pode ser acessado por proprietários de empresas, e não no repositório de controle de origem. Quando alguém tem uma pergunta sobre uma decisão específica de engenharia, o ADR está lá para fornecer respostas.

Os ADRs funcionam bem nos seguintes cenários:

  • Integração: novos membros da equipe podem aprender sobre o projeto e podem analisar o ADR quando tiverem dúvidas ao analisar o código do aplicativo ou outras implementações.
  • Transferência de propriedade: se houver uma transferência de pilha de tecnologia entre as equipes, os novos proprietários poderão analisar as decisões anteriores para entender o estado atual. O ADR também pode ajudar a evitar a repetição dos mesmos pontos de discussão ou a revisitar tópicos no futuro com conhecimento do contexto histórico.
  • Alinhamento: as equipes podem se alinhar às práticas recomendadas em toda a organização quando os ADRs detalham por que algumas decisões foram tomadas e alternativas foram decididas.

Um ADR geralmente é escrito em Markdown para mantê-lo leve e baseado em texto. Os arquivos Markdown podem ser incluídos no repositório de controle da origem com o código do aplicativo.

Armazene os ADRs perto do código do seu aplicativo, de preferência no mesmo sistema de controle de versões. Ao fazer alterações no ADR, é possível revisar versões anteriores do controle de origem conforme necessário.

Também é possível usar outra mídia, como um arquivo compartilhado do Documentos Google ou um wiki interno. Esses locais alternativos podem ser mais acessíveis para usuários que não fazem parte da equipe do ADR. Outra opção é criar o ADR em um repositório de controle de origem, mas espelhar as principais decisões em uma wiki mais acessível.

A seguir