Diagrama de arquitetura de microsserviços: um exemplo e sete regras para mantê-lo legível

Peça a um time para desenhar seus microsserviços e, muitas vezes, você recebe a mesma imagem: trinta caixas, todas ligadas a todas, setas sem rótulo. Ela está correta e não responde a nenhuma pergunta que alguém tenha. Engenheiros chamam isso de diagrama Estrela da Morte.

Um diagrama de arquitetura de microsserviços útil é um conjunto de decisões sobre o que mostrar. Este guia percorre um exemplo, uma loja virtual com cinco serviços, e as sete regras que o deixam legível. As mesmas regras valem tanto para cinco serviços quanto para cinquenta.

O que o diagrama precisa responder

Antes de desenhar, anote as perguntas. Um bom diagrama de microsserviços responde a cinco delas num relance:

1. Por onde as requisições entram? Clientes, o gateway de API, backends for frontends (BFF).
2. Qual serviço é dono de quais dados? Cada banco de dados deve ter exatamente um dono.
3. Quem chama quem de forma síncrona? Essas chamadas compartilham latência e falhas.
4. O que acontece de forma assíncrona? Eventos e filas desacoplam os serviços no tempo.
5. O que está fora do nosso controle? Provedores de pagamento, serviços de e-mail, APIs de parceiros.

Se uma caixa ou uma seta não ajuda a responder a nenhuma delas, provavelmente pertence a outro diagrama.

O exemplo: uma loja virtual com cinco serviços

A loja tem clientes web e mobile, um gateway de API e cinco serviços:

• Catalog serve os produtos a partir do próprio banco de dados PostgreSQL.
• Cart guarda os carrinhos no Redis.
• Orders cria os pedidos no próprio banco PostgreSQL e publica OrderPlaced no tópico orders do Kafka.
• Payments consome OrderPlaced, cobra o cartão via Stripe, armazena o resultado e publica PaymentSucceeded ou PaymentFailed no tópico payments.
• Notifications consome o tópico payments e, por meio de um provedor de e-mail, envia um recibo ou um aviso de que o pagamento falhou.

Orders também consome o tópico payments para marcar um pedido como pago. Ninguém chama Payments diretamente; o fluxo de checkout é uma cadeia de eventos. É exatamente essa decisão de design que o diagrama precisa tornar visível:

Leia da esquerda para a direita: o gateway é o único ponto de entrada, setas sólidas são chamadas síncronas, setas tracejadas são eventos que passam por tópicos nomeados, e cada banco de dados fica pendurado em exatamente um serviço.

Sete regras para um diagrama de microsserviços legível

1. Comece pelos pontos de entrada

Desenhe primeiro os clientes e o gateway de API, à esquerda. Eles ancoram a direção de leitura e mostram quais serviços estão de fato expostos. Um serviço sem nenhum caminho a partir do gateway é interno, e vale a pena enxergar isso.

2. Ligue cada banco de dados ao seu dono

Coloque cada armazenamento de dados ao lado do único serviço que é dono dele e conecte só esse serviço. Se hoje dois serviços compartilham um banco de dados, desenhe isso também. É um sinal de alerta conhecido, e um diagrama que o esconde torna a próxima migração mais difícil de planejar.

3. Separe chamadas síncronas de eventos

Use dois estilos de linha e explique isso em uma legenda: sólida para requisição e resposta (REST, gRPC), tracejada para mensagens que passam por um broker. Desenhe os tópicos ou as filas como nós. Uma única caixa de "barramento de eventos" com todos os serviços ligados a ela esconde quem produz e quem consome o quê.

4. Rotule cada conexão com o que passa por ela

GET /products, POST /orders, OrderPlaced, PaymentFailed. Um rótulo transforma uma seta em um contrato, e é isso que as pessoas procuram no diagrama durante um incidente.

5. Agrupe por domínio, não por tecnologia

Se precisar de frames, agrupe os serviços por domínio de negócio ou por time responsável: compras, checkout, comunicação com o cliente. Frames como "serviços Node.js" ou "serviços Java" respondem a uma pergunta que ninguém faz.

6. Mantenha a infraestrutura em uma visão própria

Pods, sidecars, service meshes e dashboards importam, mas não na visão lógica. Desenhe a implantação em um diagrama separado, por exemplo um diagrama de arquitetura do Kubernetes, e ligue os dois.

7. Mostre um fluxo crítico

Escolha o fluxo que paga as contas, aqui o checkout, e deixe-o fácil de seguir: numere os passos nas conexões ou destaque o caminho dele. Um fluxo por diagrama; um segundo fluxo ganha a própria cópia da visão.

Quando o sistema é grande demais para um diagrama

Passou de umas vinte caixas, divida. Um padrão que se sustenta:

• Um diagrama de visão geral com os domínios como frames e só as conexões mais importantes entre eles.
• Um diagrama por domínio com seus serviços, armazenamentos de dados e tópicos, desenhado com as regras acima.
• Diagramas de fluxo para as poucas jornadas que importam, como checkout ou cadastro.

Isso se encaixa bem no modelo C4: a visão geral fica próxima de uma visão de contexto do sistema, e cada diagrama de domínio é uma visão de contêineres em que os serviços e seus bancos de dados são os contêineres.

Erros comuns

• Setas sem rótulo. Quem lê adivinha, e cada um adivinha de um jeito.
• O gateway ligado a bancos de dados. Se ele realmente lê um banco, isso é uma decisão de design a discutir, não um atalho a desenhar.
• Misturar visões. Pods, serviços da AWS e capacidades de negócio no mesmo canvas fazem com que ninguém consiga ler nenhum deles.
• Esconder o broker. Kafka não é um cano; tópicos têm nomes, donos e consumidores.
• Um retrato que nunca muda. Um diagrama da última rearquitetura é um documento histórico. Coloque uma data nele ou mantenha-o vivo.

Monte no Archboard

O Archboard tem packs de nós para cada parte deste diagrama, então serviços, armazenamentos e tópicos são nós tipados com portas, e não caixas que parecem todas iguais:

1. Entre com Google ou GitHub e crie um diagrama.
2. Adicione uma Caixa do pack Básico para os clientes e um Gateway de API do pack Nuvem.
3. Adicione os serviços como nós Contêiner do pack Modelo C4, com a linguagem ou o framework no campo Tecnologia.
4. Adicione Postgres e Redis do pack Dados ao lado dos seus donos, e nós Tópico para orders e payments.
5. Adicione nós Sistema externo do pack Modelo C4 para a Stripe e o provedor de e-mail.
6. Conecte as portas. Mantenha as chamadas síncronas com linha sólida e mude os eventos para linha tracejada; depois, rotule cada conexão.
7. Compartilhe o link ao vivo com o time ou, no Pro, incorpore o diagrama na sua documentação.

O exemplo acima tem 15 nós de diagrama, o que cabe no plano Free. Para exemplos relacionados, abra /examples/kubernetes-microservices para o lado da implantação e /examples/api-gateway-infographic para um infográfico do padrão de gateway de API.

Perguntas frequentes

Quantos serviços um diagrama deve mostrar? Quantos você conseguir ler sem dar zoom, normalmente até umas vinte caixas. Passou disso, divida por domínio e mantenha uma visão geral por cima.

Devo usar o modelo C4 para microsserviços? Funciona bem. Os serviços e seus bancos de dados viram contêineres em uma visão de contêineres. Alguns times modelam cada serviço com dono independente como um sistema de software próprio; escolha uma convenção e registre-a por escrito.

Como mostro o Kubernetes, o service mesh e o monitoramento? Em um diagrama de implantação separado. A visão lógica responde quem fala com quem; a visão de implantação responde onde tudo roda.

Os eventos devem apontar do consumidor para o tópico, já que os consumidores fazem pull? Desenhe a direção em que os dados fluem, do produtor para o tópico e do tópico para o consumidor, e anote que os consumidores fazem pull se isso importar para a discussão.

Como mantenho o diagrama atualizado? Dê um dono ao diagrama, atualize-o no mesmo pull request da mudança e coloque na sua documentação um link para o diagrama ao vivo em vez de colar capturas de tela.

Comece grátis — um assento, sem cartão de crédito.