Guia de Sintaxe de Fluxograma do Mermaid.js

O que é um Fluxograma?

Um Fluxogramaé um mapa comportamental fundamental que visualiza um fluxo operacional passo a passo, um procedimento algorítmico ou uma lógica de negócios sequencial. Representando as ações do sistema como formas geométricas distintas e traçando o fluxo de controle com setas direcionais, um fluxograma torna fácil para engenheiros de software e arquitetos de sistemas rastrear caminhos de execução condicional, isolar blocos de falha única e analisar loops lógicos do sistema antes de escrever o código backend real.

Com Mermaid.js, você não precisa perder horas arrastando caixas, gerenciando minuciosamente linhas de grade ou recalcular variáveis de preenchimento. O motor de layout calcula dinamicamente as coordenadas dos nós a partir de seus scripts declarativos brutos, permitindo que você se concentre inteiramente na lógica subjacente do seu sistema.

Guia de Sintaxe Básica: Elementos e Construções

Para projetar um fluxograma elegante e altamente legível no Mermaid, você deve dominar indicadores de direção da tela, envoltórios geométricos de nós, variáveis de conexão de links e subgrafos estruturais.

1. Definindo Direções da Tela

A orientação do seu fluxograma é determinada diretamente na primeira linha pelo par de palavras-chave aplicado ao graph ou fluxogramaenvoltório. Você pode controlar a direção de escala visual do seu layout usando quatro chaves principais de orientação:

• fluxograma TD (De Cima para Baixo / Orientação Vertical)
• fluxograma BU (De Baixo para Cima)
• fluxograma LR (Da Esquerda para a Direita / Orientação Horizontal)
• fluxograma RL (Da Direita para a Esquerda)

2. Personalizando a Geometria do Nó (Formas)

Por padrão, uma declaração de ID simples é renderizada como uma caixa retangular nítida. Para tornar seus diagramas mais fáceis de ler, use os colchetes especiais do Mermaid para injetar contexto visual imediato em diferentes etapas do fluxo de trabalho. Cada bloco de definição deve ser precedido por um token de layout direcional para ser analisado corretamente:

• Bordas Arredondadas: id(Texto) — Representa uma etapa geral do processo.
• Forma de Estádio/Cápsula: id([Texto]) — Marcador padrão para marcos de limite de início e parada.
• Subrotina/Processo Pré-definido: id[[Texto]] — Representa uma rotina de sistema encapsulada ou script de classe externo.
• Cilindro/Banco de Dados: id[(Texto)] — Representa persistência de banco de dados, caches ou data warehouses.
• Losango/Ponta de Decisão: id{Texto} — Representa comutadores condicionais, ramificações if/else ou pontos de avaliação.
• Paralelogramo: id[/Texto/] ou id[Texto] — Representa limites inclinados para representar entrada/saída de dados explícita (E/S).

fluxograma TD
    start_node([Iniciar Execução])
    query_db[(Instância PostgreSQL)]
    validate_check{Autorizado?}

3. Regras de Ligação de Fios e Rótulos Inseridos

Você pode ajustar suas linhas de conexão para representar diferentes relações estruturais e estilos de comunicação. Para manter seus diagramas limpos, insira rótulos descritivos diretamente em seus caminhos de ligação:

fluxograma TD
    %% Setinha de conexão padrão com rótulo de texto
    A --> |"Payload JSON"| B

    %% Linha pontilhada/assíncrona com rótulo de texto
    B -.-> |"Evento Assíncrono"| C

    %% Linha grossa em negrito com rótulo de texto
    C ==> |"Escrita Crítica"| D

4. Isolamento Modular por Subgrafos

Para estabelecer perimeters de rede limpos, agrupar microsserviços ou isolar responsabilidades de equipes, agrupe seus elementos dentro de estruturas subgrafo envoltórios. Você define um subgrafo atribuindo-lhe um ID interno, um título opcional de exibição e fechando-o com um fim etiqueta:

fluxograma TD
    subgrafo auth_sub["Fronteira de Segurança"]
        gateway[API Gateway] --> auth_worker(Validador de Token)
    fim

Melhores Práticas para Fluxogramas Limpos

• Desacople os Layouts Horizontalmente: Para pipelines de engenharia longas e de múltiplos passos, escolha um fluxograma LR direção. Isso escala muito mais limpo em monitores padrão de tela larga em paisagem do que um layout vertical longo.
• Isole Loops Complexos: Se um fluxo de trabalho contém um loop de repetição pesado, rotule claramente o conector reverso (por exemplo, tentar novamente --> |"Tentativa de Reinicialização"| início) para evitar que os leitores confundam o loop com um caminho padrão para frente.
• Evite Misturar Tipos de Gráficos: Mantenha-se no moderno fluxograma palavra-chave em vez da legada grafo sinalizador ao renderizar mapas complexos. O fluxogramamotor usa um algoritmo de layout atualizado que suporta combinações avançadas de setas e roteamento de caminhos mais limpo.

Exemplos Reais de Fluxogramas Mermaid.js

Exemplo 1: Malha de Ingestão Orientada a Eventos de Microserviço (Arquitetura da Esquerda para a Direita)

Este projeto funcional modela um serviço de ingestão de telemetria web. Ele demonstra como combinar entradas de dados, losangos de decisão e formas de banco de dados em nuvem em uma tela horizontal nítida.

fluxograma LR
    %% Defina nós de elementos com formas geométricas explícitas
    init([Webhook Acionado]) --> input_io[/Capturar Solicitação HTTP/]
    input_io --> auth_check{Validar Token}
    
    auth_check --> |"Token Inválido"| err_stop([Retornar 401 Não Autorizado])
    auth_check --> |"JWT Válido"| write_queue[[Publicar na Fila Kafka]]
    
    write_queue --> worker_proc(Daemon Consumidor)
    worker_proc --> db_store[(Cluster TimescaleDB)]
    db_store --> term([Fluxo Finalizado])

    %% Sobrescritas de estilo personalizadas rápidas
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Análise de Sintaxe: Este diagrama flui suavemente da esquerda para a direita. A etapa de validação usa uma forma de losango de decisão amarelo (auth_check{Validar Token}), que divide claramente o caminho de execução em dois resultados distintos. Os armazenamentos de dados são imediatamente reconhecíveis graças aos seus cilindros personalizados de banco de dados ([(Cluster TimescaleDB)]) e entradas em paralelogramo.

Exemplo 2: Motor de Registro de Usuário Multi-Nível Empresarial (Vertical com Subgrafos Aninhados)

Este avançado plano empresarial mapeia uma pipeline de registro de aplicativo. Organiza os passos verticalmente em três subgrafos estruturais separados para representar camadas arquitetônicas distintas.

flowchart TD
    subgraph Client_Tier["Camada de Interface de Apresentação"]
        app[Interface do Aplicativo Móvel]
        web[Frontend SPA Web]
    end

    subgraph Service_Tier["Roteador Principal de Gateway"]
        proxy[[Proxy Reverso Nginx Ingress]]
        auth_svc(Trabalhador do Serviço de Autenticação)
    end

    subgraph Persistence_Tier["Centro de Dados Seguro"]
        main_db[(Banco de Dados Principal de Contas de Usuário)]
        cache_node[(Cache de Sessão Redis)]
    end

    %% Define pipelines de comunicação entre camadas de subsistemas
    app -- "Requisição HTTPS" --> proxy
    web -- "Requisição HTTPS" --> proxy
    
    proxy --> |"Roteamento /v1/auth"| auth_svc
    
    auth_svc --> |"Verificar Sessão"| cache_node
    auth_svc --> |"Confirmar Conta"| main_db

Análise de Sintaxe: O indicador de orientação de cima para baixo (flowchart TD), que força o motor de layout a empilhar os componentes de forma limpa de cima para baixo. Blocos delimitadores agrupam componentes relacionados em camadas distintas (Cliente, Serviço e Persistência), dando à arquitetura geral uma sensação intuitiva e altamente estruturada.