Porque a vida é muito curta para redesenhar diagramas Recentemente, entrei em uma nova empresa como . Como sempre acontece, tive que começar do zero. Coisas como: Onde está o código de um aplicativo ativo? Como ele é implantado? De onde vêm as configurações? Felizmente, meus colegas fizeram um trabalho fantástico ao transformar tudo em “infraestrutura como código”. Então me peguei pensando: engenheiro de software se tudo está no código, por que não existe uma ferramenta para ligar todos os pontos? Essa ferramenta revisaria a base de código e construiria um diagrama de arquitetura de aplicativo, destacando os principais aspectos. Um novo engenheiro poderia olhar para o diagrama e dizer: “Ah, ok, é assim que funciona”. Primeiras coisas primeiro Não importa o quanto eu procurei, não consegui encontrar nada parecido. As correspondências mais próximas que encontrei foram serviços que desenham um diagrama de infraestrutura. Coloquei alguns deles para que você possa dar uma olhada mais de perto. Eventualmente, desisti de pesquisar no Google e decidi tentar desenvolver algumas coisas novas e legais. nesta análise Primeiro, criei um aplicativo de amostra com Gradle, e Terraform. O pipeline de ações do GitHub implanta o aplicativo no Amazon Elastic Container Service. Este repositório será uma fonte para a ferramenta que irei construir (o código está ). Java Docker aqui Em segundo lugar, desenhei um diagrama de alto nível do que queria ver como resultado: Decidi que haveria dois tipos de recursos: Relíquia Achei o termo muito sobrecarregado, então escolhi . Então, o que é uma relíquia? É 90% de tudo o que você deseja ver. Incluindo mas não limitado a: artefato Relic Artefatos (caixas azuis no esquema, ou seja, Jars, imagens Docker), Configurações de recursos do Terraform (caixas rosa no esquema, ou seja, instâncias EC2, ECS, filas SQS), Recursos do Kubernetes, e muitos, muitos mais Cada Relíquia tem um nome (por exemplo, my-shiny-app), tipo opcional (por exemplo, Jar) e um conjunto de pares chave → valor (por exemplo, caminho → /build/libs/my-shiny-app.jar) que descreve completamente a Relíquia. Eles são chamados de . Quanto mais definições o Relic tiver, melhor. Definições Fonte O segundo tipo é um . As fontes definem, constroem ou provisionam Relíquias (por exemplo, caixas amarelas acima). Uma Fonte descreve uma Relíquia em algum lugar e dá uma ideia de onde ela vem. Embora as Fontes sejam os componentes dos quais obtemos mais informações, elas geralmente têm significados secundários no diagrama. Você provavelmente não precisa de muitas flechas indo do Terraform ou Gradle para todas as outras relíquias. Source Relíquia e Fonte têm um relacionamento muitos para muitos. Dividir e conquistar Cobrir cada pedaço de código é impossível. Os aplicativos modernos podem ter muitas estruturas, ferramentas ou componentes de nuvem. Só a AWS tem cerca de 950 recursos e fontes de dados para Terraform! A ferramenta deve ser facilmente extensível e dissociada por design para que outras pessoas ou empresas possam contribuir. Embora eu seja um grande fã da arquitetura de provedores Terraform incrivelmente conectáveis, decidi construir a mesma, embora simplificada: O tem uma responsabilidade clara: construir Relíquias com base nos arquivos fonte solicitados. Por exemplo, lê arquivos *.gradle e retorna , ou Relics. Cada provedor constrói relíquias dos tipos que conhece. Os provedores não se importam com as interações entre as relíquias. Eles constroem Relíquias de forma declarativa, totalmente isoladas umas das outras. Provedor GradleProvider Jar War Gz Com essa abordagem, é fácil ir tão fundo quanto você quiser. Um bom exemplo são as ações do GitHub. Um arquivo YAML de fluxo de trabalho típico consiste em dezenas de etapas usando componentes e serviços fracamente acoplados. Um fluxo de trabalho poderia construir um JAR, depois uma imagem Docker e implantá-la no ambiente. Cada etapa do fluxo de trabalho pode ser coberta pelo seu fornecedor. Portanto, os desenvolvedores de, digamos, criam um Provedor relacionado apenas às etapas de seu interesse. Docker Actions Essa abordagem permite que qualquer número de pessoas trabalhe em paralelo, agregando mais lógica à ferramenta. Os usuários finais também podem implementar rapidamente seus provedores (no caso de alguma tecnologia proprietária). Veja mais em Personalização abaixo. Mesclar ou não mesclar Vejamos a próxima armadilha antes de passar para a parte mais interessante. Dois Provedores, cada um criando uma Relíquia. Isso é bom. Mas e se duas destas Relíquias forem apenas representações do mesmo componente definido em dois lugares? Aqui está um exemplo. analisa JSON de definição de tarefa e produz uma Relíquia com o tipo . O fluxo de trabalho de ação do GitHub também tem uma etapa relacionada ao ECS, portanto, outro provedor cria uma relíquia . Agora, temos duplicatas porque os dois provedores não sabem nada um do outro. Além disso, é incorreto que qualquer um deles presuma que outro já criou uma Relíquia. Então o que? AmazonECSProvider AmazonECSTask AmazonECSTaskDeployment Não podemos eliminar nenhuma das duplicatas por causa das definições (atributos) que cada uma delas possui. A única maneira é mesclá-los. Por padrão, a próxima lógica define a decisão de mesclagem: relic1.name() == relic2.name() && relic1.source() != relic2.source() Mesclamos duas relíquias se seus nomes forem iguais, mas elas são definidas em fontes diferentes (como em nosso exemplo, JSON no repositório e a referência de definição de tarefa está em ações do GithHub). Quando nos fundimos, nós: Escolha um único nome Mesclar todas as definições (chave → pares de valores) Crie uma fonte composta referindo-se a ambas as fontes originais Desenhe uma linha Omiti intencionalmente um aspecto crucial de uma Relíquia. Pode ter um – e é melhor tê-lo! O Matcher é uma função booleana que pega um argumento e o testa. Matchers são peças cruciais de um processo de vinculação. Se uma Relíquia corresponder a qualquer definição da Relíquia de outra pessoa, elas serão vinculadas. Matcher Lembra quando eu disse que os Provedores não têm ideia sobre as Relíquias criadas por outros Provedores? Isso ainda é verdade. Entretanto, um Provedor define um Matcher para uma Relíquia. Em outras palavras, representa um lado de uma seta entre duas caixas no diagrama resultante. Exemplo. Dockerfile possui uma instrução ENTRYPOINT. ENTRYPOINT java -jar /app/arch-diagram-sample.jar Com alguma certeza, podemos dizer que o Docker tudo o que é especificado no . Portanto, o Relic tem uma função Matcher simples: . Muito provavelmente, algumas Relics com nas Definições irão corresponder a ele. Se sim, uma seta entre e Relics aparece. conteineriza ENTRYPOINT Dockerfile entrypointInstruction.contains(anotherRelicsDefinition) Jar arch-diagram-sample.jar Dockerfile Jar Com o Matcher definido, o processo de vinculação parece bastante simples. O serviço de vinculação itera sobre todas as Relíquias e chama as funções de seu Matcher. A Relíquia A corresponde a alguma das definições da Relíquia B? Sim? Adicione uma borda entre essas relíquias no gráfico resultante. A borda também pode ser nomeada. Visualização A última etapa é visualizar nosso gráfico final da etapa anterior. Além do PNG óbvio, a ferramenta suporta formatos adicionais, como , e . Esses formatos de texto podem parecer menos atraentes, mas a grande vantagem é que você pode incorporar esses textos em praticamente qualquer página wiki ( , e muitos mais). Mermaid Plant UML DOT GitHub , Confluência Esta é a aparência do diagrama final do repositório de amostra: Costumização A capacidade de conectar componentes personalizados ou ajustar a lógica existente é essencial, especialmente quando uma ferramenta está em fase inicial. Relíquias e fontes são flexíveis o suficiente por padrão; você pode colocar o que quiser neles. Todos os outros componentes são personalizáveis. Os provedores existentes não cobrem os recursos que você precisa? Implemente o seu próprio com facilidade. Não está satisfeito com a lógica de fusão ou ligação descrita acima? Sem problemas; adicione seu próprio ou . Empacote tudo em um arquivo JAR e adicione-o na inicialização. Leia mais . LinkStrategy MergeStrategy aqui Outro A geração de um diagrama com base no código-fonte provavelmente ganhará força. E a ferramenta em particular (sim, esse é o nome da ferramenta da qual eu estava falando). ! NoReDraw Contribuintes são bem-vindos O benefício mais notável (que vem do nome) é que não há necessidade de redesenhar um diagrama quando os componentes mudam. A falta de atenção da engenharia é o motivo pelo qual a documentação em geral (e os diagramas em particular) fica desatualizada. Com ferramentas como , isso não deve mais ser um problema, pois é facilmente conectável a qualquer pipeline de PR/CI. Lembre-se, 😉 NoReDraw a vida é muito curta para redesenhar diagramas
