Um diagrama de arquitetura fornece um plano estruturado usado por arquitetos de sistemas e equipes DevOps para visualizar configurações de infraestrutura, microserviços em nuvem e configurações de layout estrutural. Construído sobre o arquitetura-betamotor, esta ferramenta baseada em texto substitui utilitários de arrastar manual por agrupamentos automáticos de grupos de serviços estruturais, clusters de banco de dados, gateways e caminhos de borda em layouts de sistema limpos e previsíveis.
Estrutura Básica de Sintaxe
Todo diagrama começa com o arquitetura-betacabeçalho de declaração. Você preenche a tela definindo elementos individuais de nó usando a serviçopalavra-chave, e mapeia trilhas de conexão especificando portas de coordenadas direcionais exatas (Top, Bottom, Left, Right) separadas por dois pontos e traços duplos.
arquitetura-beta
serviço gateway(internet)[Rótulo do Gateway]
serviço servidor(servidor)[Servidor de Aplicação]
gateway:B -- T:server
Referência de Sintaxe
A tabela abaixo detalha os principais componentes de dados, palavras-chave de formatação e atributos de conectores usados para construir um mapa de espaço de trabalho de arquitetura no Mermaid.js.
| Componente de Sintaxe | Requisito de Tipo | Descrição e Regras de Uso |
|---|---|---|
| Declaração | Identificador de Palavra-Chave | Inicializa a tela do espaço de trabalho de mapeamento de infraestrutura. Deve usar exatamente o arquitetura-beta bloco. |
| Nó de Serviço | Palavra-chave + Bloco de Identidade | Declara uma entidade arquitetônica. Usa a sintaxe: serviço id(ícone)[Rótulo de Exibição]. |
| Envoltório de Grupo | Palavra-chave de Container | Agrupa serviços relacionados dentro de um container visual. Usa a sintaxe: grupo id(ícone)[Rótulo do Grupo]. |
| Palavra-chave Em | Modificador de Atribuição | Atribui explicitamente um nó de serviço para residir dentro de um envoltório de grupo declarado especificamente: serviço id(ícone)[Rótulo] em groupId. |
| Nó de Junção | Identificador de Palavra-chave | Estabelece um ponto central de alinhamento estrutural usado para rotear com precisão caminhos de ligação complexos e multidirecionais: junção id. |
| Arestas de Conexão | Operadores de Direção de Porta | Configura caminhos de rastreamento direcional prendendo a ligação a lados específicos do nó (T, B, L, R): fonte:lado -- lado:alvo. Suporta pontas de seta direcionais (-->). |
Agrupamento Avançado e Roteamento de Arestas de Porta
Para controlar exatamente como os links viajam entre os elementos sem parecer bagunçado, o motor de arquitetura exige vinculações de portas explícitas. Nós relacionados podem ser organizados dentro de grupos estruturais para esclarecer os limites do sistema.
1. Regras Exatas de Vinculação de Portas
Você define onde uma linha de conexão sai e entra em um componente acrescentando dois pontos e uma bandeira de direção de aresta (“T, B, L, R) aos identificadores de nó respectivos:
db:R -- L:server: A linha sai pela **Direita** do banco de dados e entra pela **Esquerda** do servidor como uma linha horizontal reta.db:T -- L:server: A linha sai pela **Parte Superior** do banco de dados e entra pela **Esquerda** do servidor, dobrando automaticamente em um ângulo de cotovelo limpo de 90°.src:B --> T:proc: A linha sai pela **Parte Inferior** do nó de origem e segue para baixo até a **Parte Superior** do processador com uma ponta de seta direcional.
2. Estruturando Sistemas com Grupos
Para declarar um grupo visual (como uma nuvem privada virtual ou cluster de banco de dados), use a palavra-chave group palavra-chave e atribua nós a ele por meio do modificador in modificador:
architecture-beta
group cloudNetwork(cloud)[Nuvem Privada]
service auth(server)[Nó de Autenticação] in cloudNetwork
service api(server)[Pontos Finais da API] in cloudNetwork
Alinhando Elementos Irmãos (v11.16.0+)
Quando múltiplos serviços distintos compartilham caminhos idênticos de roteamento de arestas (por exemplo, três fontes de dados desconectadas transmitindo para um único trabalhador de mensagens), o algoritmo de layout às vezes pode agrupá-los. O align row e alinhar colunadiretivas forçam o motor a distribuir esses elementos irmãos de forma uniforme ao longo de uma linha de eixo específica.
arquitetura-beta
serviço src1(server)[Fonte 1]
serviço src2(server)[Fonte 2]
serviço proc(server)[Hub de Processamento]
src1:B --> T:proc
src2:B --> T:proc
alinhar linha src1 src2
Plano Prático do Mundo Real: Plano do Cluster de Microserviços
Este plano demonstra uma arquitetura de nuvem altamente resiliente e de nível corporativo. Ao centralizar o motor principal da API e ramificar autenticação e tarefas assíncronas horizontalmente para os lados, o layout utiliza princípios de design simétrico para evitar linhas sobrepostas. Todo o fluxo de dados move-se de forma previsível da porta de entrada pública até uma camada de armazenamento de dados bem alinhada, utilizando dual alinhar linhadiretivas para fixar componentes em trilhas horizontais nítidas e previsíveis.
arquitetura-beta
título "Arquitetura de Microserviços de Alta Disponibilidade"
%% Nível de Entrada Externa
serviço cloudflare(internet)[Cloudflare WAF]
serviço alb(server)[Balanceador de Carga de Aplicação AWS]
%% Cluster Principal de Aplicação
grupo appCluster(cloud)[Microserviços Gerenciados EKS]
serviço authService(server)[Serviço de Autenticação] no appCluster
serviço apiService(server)[Motor Principal da API] no appCluster
serviço workerNode(server)[Trabalhador de Tarefas Assíncronas] no appCluster
%% Nível de Armazenamento Protegido
grupo dataCluster(database)[Camada de Dados Protegida]
serviço redis(disk)[Cluster de Cache Redis] no dataCluster
serviço postgres(database)[Principal PostgreSQL] no dataCluster
%% 1. Fluxo Vertical: Entrada de tráfego da porta pública até o núcleo computacional
cloudflare:B --> T:alb
alb:B --> T:apiService
%% 2. Fluxo Horizontal: API principal ramificando-se simetricamente para a esquerda e direita
apiService:L --> R:authService
apiService:R --> L:workerNode
%% 3. Fluxo Base: Trabalhadores da aplicação descendo diretamente para os respectivos slots de dados
authService:B --> T:redis
workerNode:B --> T:postgres
%% Alinhamentos de Eixos de Layout para uma Grade Perfeita
alinhar linha authService apiService workerNode
alinhar linha redis postgres
Armadilhas Comuns de Sintaxe e Restrições do Sistema
Ao escrever código de infraestrutura, tenha em mente estas regras específicas de validação de configuração para evitar falhas na análise:
- Sequência de Colchetes de Rótulo:As strings de texto exibido devem usar colchetes retos
[Texto do Rótulo]e seguir os parênteses do ícone diretamente, sem espaços:serviço id(server)[Texto]está correto. Usar aspas dentro dos parênteses quebrará o analisador. - Sensibilidade de Caixa das Portas:Os pontos de ancoragem das arestas de conexão devem ser escritos em letras maiúsculas (
T,B,L,R). Letras minúsculas (t,b,l,r) não são reconhecidos e causarão falhas na geração de layout. - Regra de Declaração Anterior: Todo identificador de nó ou junção usado em uma instrução de caminho de aresta deve ser declarado explicitamente em uma linha separada acima dele. Conectar-se a um nome de nó implícito falhará ao compilar.
- Limites de Membros de Alinhamento: Quando usar o
alinhamento de linhaoualinhamento de colunadiretivas de posicionamento, você deve fornecer pelo menos dois ou mais identificadores de serviço ou junção válidos e previamente declarados na linha de comando.