Guia de Sintaxe de Diagrama de Sequência do Mermaid.js

O que é um Diagrama de Sequência?

Um Diagrama de Sequência é um diagrama comportamental essencial diagrama UML projetado para visualizar o fluxo cronológico de mensagens, chamadas de funções e cargas úteis de dados entre entidades do sistema diferentes ao longo de uma linha do tempo linear. Reconhecido como um tipo central tipo de diagrama UML, ele mapeia as interações em tempo de execução empilhando os componentes do sistema ao longo do eixo X como linhas de vida verticais e rastreando as trocas de mensagens ao longo do eixo Y. Este modelo é inestimável para desenvolvedores depurando trocas de mão de API distribuídas, caminhos de orquestração de microsserviços ou fluxos de autenticação de usuário em tempo real.

Com Mermaid.js, você pode criar processos temporais complexos usando uma estrutura de texto intuitiva. O motor gerencia automaticamente o espaçamento vertical, controla os alinhamentos das setas de mensagem e desenha blocos de ativação em tempo de execução de forma limpa em toda a sua tela.

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

Para criar um diagrama de sequência UML preciso e altamente legível no Mermaid, você deve dominar as declarações de participantes, variantes de setas de mensagem, linhas de vida explícitas e estruturas de blocos condicionais.

1. Declarando Participantes e Atores

Você declara uma entidade padrão do sistema usando a participantepalavra-chave. Se a entidade representa um usuário final humano ou um operador externo, use a atorpalavra-chave para renderizar um ícone padrão de figura de palito na tela:

sequenceDiagram
    ator Cliente
    participante API como Gateway Router

Dica Profissional: Use a comopalavra-chave para mapear nomes longos de componentes para aliases internos compactos, mantendo seus scripts de mensagens concisos e legíveis.

2. Formatação de Setas de Mensagem

O tipo de linha e ponta de seta que você usa determina o estilo de comunicação entre seus participantes do sistema:

• ->> **Chamada Síncrona:** Uma linha contínua com uma seta cheia. Representa uma solicitação bloqueante que aguarda a conclusão da execução.
• --> **Linha de Resposta:** Uma linha tracejada com uma seta aberta. Usada para retornar cargas úteis de dados ou tokens de confirmação.
• -> **Chamada Assíncrona:** Uma linha contínua com uma seta aberta. Indica uma mensagem não bloqueante ou transmissão de evento.

sequenceDiagram
    App->>Server: Payload de Solicitação
    Server-->App: Resposta 200 OK

3. Gerenciando Barras de Ativação de Vida

Para mostrar exatamente quando um componente do sistema está executando ativamente uma tarefa ou ocupando memória de thread, use os comandosactivate e deactivate comandos. Alternativamente, você pode acrescentar um sinal de mais (+) ou um sinal de menos (-) diretamente em seus destinos de mensagem como um atalho visual rápido:

sequenceDiagram
    Client->>+Server: Processar Dados
    %% O servidor agora está visualmente ativo
    Server-->-Client: Retornar Resultados

4. Estruturando Condicionais e Alternativas (Alt, Opt, Loop)

Para lidar com lógica de tempo de execução ramificada, avaliações de tokens ou repetições de tentativas de solicitação, envolva seus scripts de mensagem dentro de fragmentos de bloco padrão:

• alt / else — Avalia caminhos condicionais (semelhante aos blocos de código if/else).
• opt — Define uma etapa opcional que só é executada sob critérios específicos.
• loop — Repete uma sequência de execução até que uma condição seja satisfeita.

sequenceDiagram
    loop A cada 30 segundos
        Cliente->>Servidor: Ping de Batimento
    end

Melhores Práticas para Linhas do Tempo de Sequência Limpas

• Mantenha as Linhas de Vida Desembaraçadas: Evite listar dezenas de microentidades ao longo do eixo X. Se um processo interage com classes auxiliares menores, abstraia-as atrás de uma fronteira de sistema de alto nível, como[Trabalhador de Autenticação] ou [Pool de Cache].
• Labelize os Códigos de Status Explicitamente: Ao escrever retornos de resposta (-->), não escreva apenas “Retornar Dados”. Rotule a trajetória com códigos HTTP explícitos ou tipos de evento (por exemplo, "201 Criado (Token JWT)") para fornecer aos engenheiros um contexto preciso.
• Implemente Notas para Cálculos Complexos: Use a instrução Note over, Note left of, ou Note right of para documentar operações não visuais, como etapas internas de criptografia ou hash de dados do banco de dados.

Exemplos Reais de Diagramas de Sequência Mermaid.js

Exemplo 1: Fluxo de Troca de Token Seguro OAuth2 (Blocos de Ativação e Alternativa)

Este modelo funcional representa uma sequência de login de usuário segura. Ele demonstra como combinar atores humanos, linhas de vida de sistema explícitas e caminhos de validação complexos usando um bloco alt/else.

sequenceDiagram
    ator Usuário como Usuário Final
    participante App como Cliente do Aplicativo Móvel
    participante Auth como Provedor de Identidade Auth0

    Usuário->>+App: Clique em "Entrar com OAuth"
    App->>+Auth: Redirecionar com client_id e escopo
    Auth-->>Usuário: Exibir Interface de Login
    Usuário->>Auth: Enviar Credenciais
    
    Auth->>Auth: Validar Hash da Senha
    
    alt Credenciais São Válidas
        Auth-->>App: Redirecionamento 302 com Código de Autenticação
        App->>Auth: Trocar Código por Token de Acesso
        Auth-->>-App: Retornar Token JWT (IdToken)
        App-->>Usuário: Exibir Página Inicial da Conta do Usuário
    senão Credenciais Inválidas
        Auth-->>App: Retornar Erro 401 Não Autorizado
        App-->>-Usuário: Exibir Alerta "Nome de Usuário/Senha Inválidos"
    fim

Análise de Sintaxe: Este cronograma rastreia um aperto de mão entre múltiplas partes. O alt / senão o contêiner mapeia claramente os caminhos de validação binária, garantindo que os estados de erro sejam totalmente documentados junto com o caminho principal.

Exemplo 2: Checkout de Estoque de Pedidos Distribuídos (Processos Paralelos e Notas)

Este projeto avançado de sistema mapeia uma pipeline de checkout de e-commerce corporativo. Ele utiliza blocos paralelos (par) para mostrar rotinas de envio simultâneo de API e gerencia notas de bloqueio de banco de dados em toda a topologia.

sequenceDiagram
    participante Web como Frontend Web
    participante Ord como Orquestrador de Pedidos
    participante Inv como Serviço de Estoque
    participante Pay como Gateway de Pagamento

    Web->>+Ord: Enviar Solicitação de Checkout
    Nota sobre Ord: Verificar Disponibilidade de Estoque do Item
    
    par Enviar Chamadas de API Concorrentes
        Ord->>+Inv: Bloquear Itens de Estoque
        Inv-->-Ord: Estoque Reservado (Estoque Bloqueado)
    e
        Ord->>+Pay: Autorizar Cobrança com Cartão de Crédito
        Pay-->-Ord: Captura Bem-Sucedida (Cobrança Concluída)
    fim
    
    opt O Processo de Alocação Falha
        Nota à direita de Ord: Executar saga de rollback se alguma chamada falhar
    fim
    
    Ord-->-Web: 200 Sucesso Confirmação de Checkout

Análise de Sintaxe: O par / e contêiner instrui o motor a agrupar execuções paralelas juntas, documentando operações de backend concorrentes. O Nota sobre e Nota à direita de tags injetam explicações técnicas de tempo de execução diretamente na grade da tela, ajudando as equipes a entenderem transações em segundo plano como bloqueio de dados e sagas de rollback sem poluir as setas principais da mensagem.