Gerador de Sequence Diagram

Diagramas de sequência: a visão UML de quando as coisas acontecem

Um diagrama de sequência é um dos treze tipos de diagrama da UML e o que a maioria dos engenheiros realmente usa no dia a dia. Enquanto um diagrama de classes responde "o que existe no sistema" e um diagrama de estados responde "o que pode acontecer com um objeto", o diagrama de sequência responde "quem fala com quem, em que ordem e o que volta". A notação foi unificada entre 1994 e 1997 por Grady Booch, James Rumbaugh e Ivar Jacobson na Rational Software — os "Três Amigos" — e padronizada na UML 1.0 em 1997; a versão atual é a UML 2.5.1, ratificada pela OMG em 2017.

O diagrama é lido de cima para baixo (o tempo desce) e da esquerda para a direita (cada participante tem uma lifeline vertical). Toda interação — request, resposta, callback, retry — vira uma seta horizontal entre duas lifelines, ordenada temporalmente pela posição vertical.

Anatomia de um diagrama de sequência

• Participantes — caixas no topo representando sistemas, serviços ou papéis. Desenhados como bonecos quando o participante é um ator humano.
• Lifelines — linhas tracejadas verticais que descem de cada participante; representam a existência daquele objeto ao longo do tempo.
• Mensagens — setas horizontais entre lifelines. Linha sólida com ponta cheia é chamada síncrona; linha tracejada é retorno; ponta aberta é mensagem assíncrona.
• Activation bars — retângulos finos sobre a lifeline indicando o período em que o participante está processando ativamente.
• Notas — retângulos com canto dobrado usados para anotar uma região do diagrama.
• Combined fragments — caixas rotuladas loop, alt, opt, par, critical que envolvem várias mensagens e atribuem semântica de controle de fluxo.

Sintaxe Mermaid sequenceDiagram

O Mermaid modela diagramas de sequência com uma gramática enxuta, uma linha por construção:

sequenceDiagram
  actor Usuário
  participant Browser
  participant AuthServer
  participant API

  Usuário->>Browser: clica em Login
  Browser->>AuthServer: GET /authorize
  AuthServer-->>Browser: 302 formulário de login
  Usuário->>Browser: envia credenciais
  Browser->>AuthServer: POST /token
  AuthServer-->>Browser: access_token
  Browser->>API: GET /me  (Bearer …)
  API-->>Browser: 200 JSON do usuário
  Note over Browser,API: token em cache por 1h

Tipos de seta: ->> síncrona sólida, -->> retorno tracejado, -) assíncrona com ponta aberta, -x mensagem perdida. Os fragmentos abrem com loop / end, alt / else / end, opt / end, par / and / end.

Quando o diagrama se paga

• Documentar um protocolo — handshake do OAuth, 3-D Secure do pagamento, upgrade de websocket, ida e volta do SAML.
• Debugar condições de corrida — desenhar a ordem real dos eventos força você a descobrir a aresta happens-before que faltava.
• Onboarding de novo dev — um diagrama de "o que acontece quando o usuário clica em checkout" substitui uma hora de explicação verbal.
• Projetar fluxos assíncronos — visualizar produtores, consumidores e acks da fila antes de escrever código.

Alternativas e diagramas companheiros

PlantUML oferece sintaxe de fragments mais rica e é padrão de fato em muitas lojas Java. WebSequenceDiagrams popularizou o fluxo de texto-para-imagem antes do Mermaid existir. draw.io e Lucidchart atendem o público WYSIWYG. Dentro da UML, o diagrama de estados modela o que um objeto pode fazer, o diagrama de atividades modela um workflow e o diagrama de comunicação (colaboração) é uma visão alternativa da mesma interação, com layout espacial em vez de temporal.

FAQ

Posso mostrar o payload de uma mensagem? Sim — coloque em uma Note over A,B: { id: 42 } ao lado da seta, ou após dois pontos como A->>B: POST /users { name }. Para JSON longo, uma nota lateral é mais legível.

Um diagrama de sequência pode rodar horizontalmente? Não — diagramas de sequência UML são sempre verticais (o tempo desce). Se você precisa de uma visão horizontal, use um diagrama de comunicação.

Meu diagrama tem 25 participantes e está ilegível. O que faço? Quebre em vários diagramas por caso de uso (um por cenário) e linke nos docs. Um único diagrama de sequência deve caber em uma tela, com oito ou menos lifelines.

Como mostro chamadas paralelas? Envolva em um fragment par com ramos separados por and.

Diagramas de sequência substituem logs ou traces? Não — são artefatos de design. Em runtime, ferramentas de tracing distribuído (Jaeger, Honeycomb, OpenTelemetry) produzem visões estilo sequência a partir de spans reais.