Antes de mergulhar em layouts arquitetônicos específicos, como fluxogramas complexos ou cronogramas de sequência, é essencial entender as regras fundamentais que regem o Guia do Mermaid. O Mermaid depende de um sistema de notação de texto limpo e altamente intuitivo. Uma vez que você entenda como o motor inicializa um tipo de canvas, nomeia componentes estruturais e roteia setas direcionais, escrever qualquer layout de sistema complexo torna-se completamente natural.
Este breve guia aborda as mecânicas sintáticas estruturais globais que se aplicam a quase todos os tipos de diagramas do Mermaid dentro do ambiente VPasCode.
1. Os Envoltórios Obrigatórios do Tipo de Diagrama
Cada bloco individual de código Mermaid deve começar declarando explicitamente seu arquétipo de diagrama na primeira linha. Isso informa ao parser do VPasCode exatamente qual motor estrutural deve ser iniciado na sua área de visualização:
graph TD— Especifica um layout de Fluxograma organizado de Cima para Baixo.sequenceDiagram— Especifica um gráfico de Linha do Tempo cronológica de tempo de execução.classDiagram— Especifica um projeto estrutural de software Orientado a Objetos.
Diferentemente de outras engines de texto para diagrama, o Mermaid não exige tags de fechamento. O parser simplesmente lê a declaração estrutural na primeira linha e compila tudo que está aninhado diretamente abaixo dentro do contêiner do seu bloco de código.
2. Declarando Elementos: IDs vs. Rótulos de Exibição
Ao modelar um sistema de software, você criará diversos elementos estruturais, como componentes, bancos de dados ou microserviços. No Mermaid, você declara um elemento definindo um ID alfanumérico curto e interno, seguido imediatamente por um estilo de colchetes que controla sua forma visual, e um nome amigável para exibição:
microservice_id[API de Processamento de Pagamentos]
db_id[(SQL de Transação do Usuário)]Por que esta é uma melhor prática: Usar um ID interno curto e limpo (como microservice_id) torna o desenho de linhas de relacionamento muito mais rápido posteriormente. Se você precisar alguma vez mudar o rótulo visível para o cliente de “API de Processamento de Pagamentos” para “Serviço de Checkout Global”, você precisará apenas editá-lo na única linha onde foi declarado, em vez de atualizar dezenas de linhas em todo o seu script.
3. Dominando Setas de Relacionamento e Roteamento Direcional
Conexões entre nós do sistema são desenhadas usando combinações de traços (-), sinais de igualdade (=), e colchetes de seta (>). O estilo das suas linhas fornece um controle implícito sobre como o motor de layout automático escala o seu diagrama:
A --> Bdesenha uma seta direcional padrão apontando do elemento A diretamente para o elemento B.A --- Bdesenha uma linha de ligação plana e não direcional, sem ponta de seta, ideal para associações simples.A -.-> Bcria uma linha de dependência pontilhada, que é o padrão da indústria para indicar dependências assíncronas ou webhooks de rede.A ==> Bcria uma linha de conexão grossa e em negrito, perfeita para destacar rotas principais de processamento de dados ou links de infraestrutura crítica.
4. Adicionando contexto inline: rótulos e comentários de código
Documentação clara depende muito de colocar o contexto apropriado ao redor das suas linhas visuais e scripts de texto:
Rotulando linhas de conexão
Você pode adicionar texto explicativo diretamente em qualquer linha de conexão inserindo a string de texto entre dois pares de traços, ou acrescentando um caractere de pipe (|Texto|) logo após o seu mapeamento de relacionamento:
client_id -- "POST HTTPS /v1/checkout" --> api_id
client_id --> |POST HTTPS /v1/checkout| api_idEscrevendo comentários de código
Se você quiser deixar uma nota administrativa, crédito de design ou explicação arquitetônica dentro do seu arquivo de script sem renderizar uma caixa visual na tela, use dois sinais de porcentagem (%%). Isso informa ao motor para ignorar completamente a análise dessa linha:
%% TODO: Precisamos atualizar esta caixa de limite assim que a migração DevOps for concluída
[Monolito Legado] --> [Novo Microserviço]