Diagramas como Código: Diagramas de Sequência UML com PlantUML e VPasCode

Um UML diagrama de sequênciamostra como os participantes interagem ao longo do tempo. É útil para documentar um caso de uso, fluxo de API, processo de negócios ou cenário de sistema. O tempo geralmente avança de cima para baixo; a posição horizontal mostra quem participa, não uma medida precisa do tempo decorrido.

PlantUMLpermite descrever o diagrama como texto. VPasCode Edito do Visual Paradigmr combina um editor de código com uma visualização ao vivo e assistência de IA para gerar, modificar e corrigir código de diagrama. Um bom fluxo de trabalho é usar a IA para obter um rascunho inicial e, em seguida, inspecionar e refinar o PlantUML você mesmo.

1. A estrutura básica

Um diagrama de sequência PlantUMLcomeça com @startuml e termina com @enduml. Os participantes geralmente são listados antes das mensagens para que você possa controlar seus nomes e ordem.

@startuml
ator Cliente
participante Navegador
participante "API de Pedidos" como API
database "Banco de Dados de Pedidos" como DB

Cliente -> Navegador: Fazer pedido
Navegador -> API: POST /pedidos
API -> DB: Salvar pedido
DB --> API: ID do Pedido
API --> Navegador: 201 Criado
Navegador -> Cliente: Exibir confirmação
@enduml

O rótulo exibido do participante pode ser aspas, com como fornecendo um alias mais curto para uso em mensagens. Palavras-chave comuns de participante incluem ator, participante, fronteira, controle, entidade, banco de dados, e coleções. Use a palavra-chave que melhor comunique o papel do participante; ela não impõe uma arquitetura específica.

2. Leitura de mensagens e tempo

Cada mensagem é escrita como um remetente, uma seta, um destinatário e um rótulo. A ordem das linhas de mensagem determina sua ordem vertical no diagrama.

• -> é uma seta de mensagem sólida, comumente usada para uma solicitação ou chamada.

• --> é uma seta tracejada, frequentemente usada para uma resposta ou retorno.

• ->> e -->> usam pontas de seta abertas nos estilos comuns do PlantUML.

• : texto adiciona o rótulo da mensagem.

Escolha uma convenção consistente para chamadas e respostas. Diagramas UML comunicam uma interação; eles não garantem automaticamente que a implementação siga o protocolo representado.

3. Ativações e tempos de vida dos participantes

As ativações podem mostrar quando um participante está realizando trabalho. Use activate e desativar, ou a abreviatura ++ e -- nas setas de mensagem.

@startuml
ator User
participante "Login API" como API
banco de dados Users

User -> API: Enviar credenciais
ativar API
API -> Users: Encontrar conta
ativar Users
Users --> API: Registro de conta
desativar Users
API --> User: Resultado de login
desativar API
@enduml

As ativações são mais úteis quando esclarecem chamadas aninhadas ou responsabilidades. Evite adicioná-las mecanicamente a cada mensagem se isso tornar o diagrama mais difícil de ler.

4. Condições, alternativas e repetição

Use fragmentos combinados para mostrar o fluxo de controle. A palavra-chave fragment inicia o bloco, else separa as alternativas quando aplicável, e end o fecha. Condições de guarda vão entre colchetes.

Caminhos alternativos: alt e senão

@startuml
ator User
participante "API de Login" como API
banco de dados Users

User -> API: Enviar nome de usuário e senha
API -> Users: Verificar credenciais
Users --> API: Resultado da correspondência

alt [credenciais válidas]
  API --> User: Retornar token de sessão
senão [credenciais inválidas]
  API --> User: Retornar erro de autenticação
end
@enduml

alt é apropriado quando os caminhos são mutuamente exclusivos. Use rótulos que tornem as condições claras.

Comportamento opcional: opt

@startuml
ator Customer
participante Checkout
participante "Serviço de E-mail" como Email

Customer -> Checkout: Concluir compra
Checkout --> Customer: Confirmação do pedido

opt [cliente optou por receber e-mail]
  Checkout -> Email: Enviar recibo
  Email --> Checkout: Aceito
end
@enduml

Repetição: loop

@startuml
participante "Trabalho em Lote" como Job
participante "API de Pagamento" como API

loop [para cada pagamento pendente]
  Job -> API: Submeter pagamento
  API --> Job: Resultado do pagamento
end
@enduml

Coloque a ação repetida dentro do fragmento e declare claramente a condição ou o escopo do loop.

5. Interações paralelas e agrupadas

Use par quando as interações ocorrem simultaneamente ou sua ordem não é significativa. Use group para rotular um conjunto de mensagens sem implicar uma estrutura específica de fluxo de controle.

@startuml
participant "Serviço de Pedidos" as Pedidos
participant "Serviço de Inventário" as Inventário
participant "Serviço de Notificação" as Notificar

Pedidos -> Pedidos: Pedido aceito

par Reservar estoque
  Pedidos -> Inventário: Reservar itens
  Inventário --> Pedidos: Resultado da reserva
else Notificar cliente
  Pedidos -> Notificar: Enviar atualização do pedido
  Notificar --> Pedidos: Aceito
end
@enduml

Use par apenas quando a concorrência for significativa. Se uma ação deve terminar antes que outra comece, mostre as mensagens em sequência em vez disso.

6. Notas, referências e agrupamento visual

Notas podem esclarecer pressupostos, restrições ou decisões. Um ref fragmento pode direcionar os leitores para outro diagrama ou uma interação documentada separadamente.

@startuml
ator Cliente
participant "Interface de Checkout" as UI
participant "Serviço de Pagamento" as Pagamento
participant "Verificação de Fraude" as Fraude

Cliente -> UI: Pagar pelo pedido
UI -> Pagamento: Autorizar pagamento
Pagamento -> Fraude: Avaliar transação

nota à direita de Fraude
  Regras de risco são mantidas
  fora desta interação.
end note

Fraude --> Pagamento: Resultado de risco
Pagamento -> UI: Resultado de autorização
UI -> Cliente: Mostrar resultado
@enduml

As notas devem adicionar contexto em vez de repetir rótulos de mensagens. Se o diagrama ficar muito lotado, divida-o em cenários focados e use referências ou links de documentação para conectá-los.

7. Criando e refinando diagramas no VPasCode

VPasCodesuporta a edição de PlantUML com renderização em tempo real, bem como geração de diagramas assistida por IA, modificação de código e correção de sintaxe. Sua interface exata e a disponibilidade de recursos podem mudar, mas o fluxo de trabalho geral é:

1. Abra o VPasCode e escolha ou insira PlantUML.

2. Descreva a interação ou cole um rascunho de PlantUML no editor.

3. Verifique a prévia renderizada enquanto refina a fonte.

4. Peça à IA para fazer uma alteração específica, como “adicionar um caminho de credenciais inválidas usando “alt.”

5. Revise o código e o diagrama resultantes quanto à sintaxe e à correção do sistema.

6. Exporte ou compartilhe o diagrama final usando as opções disponíveis no editor.

Um prompt útil fornece à IA o tipo de diagrama, atores, limites do sistema, caminho principal de sucesso, caminhos alternativos importantes e nível de detalhe. Por exemplo:

Crie um diagrama de sequência PlantUML para um cliente fazendo login em um aplicativo web. Inclua Navegador, API de Login, Provedor de Identidade e Banco de Dados de Usuários. Mostre o caminho de login bem-sucedido e uma alternativa de senha inválida. Use rótulos concisos e não invente serviços além desses.

Trate o código gerado como um rascunho. Verifique se os participantes, setas, condições e caminhos de erro refletem o sistema real — não apenas um fluxo que parece plausível.

8. Um exemplo mais completo: checkout com falha de pagamento

Este exemplo combina aliases de participantes, ativações e um caminho alternativo.

@startuml
title Checkout e Autorização de Pagamento

ator Cliente
fronteira "Interface de Checkout" como UI
controle "Serviço de Pedidos" como Pedidos
participante "Gateway de Pagamento" como Pag
banco de dados "Banco de Dados de Pedidos" como DB

Cliente -> UI: Enviar checkout
UI -> Pedidos: Criar pedido pendente
ativar Pedidos

Pedidos -> DB: Salvar pedido pendente
DB --> Pedidos: ID do Pedido

Pedidos -> Pag: Autorizar pagamento
ativar Pag

alt [pagamento aprovado]
  Pag --> Pedidos: Código de autorização
desativar Pag

  Pedidos -> DB: Marcar pedido confirmado
  DB --> Pedidos: Atualizado
  Pedidos --> UI: Pedido confirmado
  UI -> Cliente: Exibir confirmação
else [pagamento recusado]
  Pag --> Pedidos: Motivo da recusa
desativar Pag

  Pedidos -> DB: Marcar pedido falho
  DB --> Pedidos: Atualizado
  Pedidos --> UI: Pagamento recusado
  UI -> Cliente: Exibir opção de tentar novamente
end

desativar Pedidos
@enduml

Verifique se a ordem do diagrama corresponde ao comportamento real. Por exemplo, se o sistema persistir o pedido apenas após o sucesso da autorização, mova as mensagens do banco de dados para corresponder a esse design.

9. Diretrizes práticas de modelagem

• Mantenha o diagrama focado.Mostre um cenário ou um conjunto de caminhos estreitamente relacionados. Separe detalhes profundos que distraiam da interação principal.

• Nomeie os participantes por responsabilidade. Prefira rótulos como “Serviço de Pedidos" ou “Gateway de Pagamento" a rótulos vagos como “Sistema".

• Mostre fronteiras significativas.Distinga o usuário, cliente, serviços internos, bancos de dados e sistemas externos quando isso ajudar os leitores a entender a responsabilidade.

• Use rótulos de mensagem claros. Inclua uma operação, evento ou resultado importante; evite rótulos que digam apenas “processo.”

• Modele caminhos de falha que importam. Inclua timeouts, rejeições, retentativas ou falhas de validação relevantes quando afetarem o cenário.

• Use fragmentos com precisão. alt significa caminhos alternativos, opt significa comportamento opcional, loop significa repetição, e par significa comportamento paralelo.

• Evite ruído de implementação. Não diagramue cada getter, método interno ou detalhe de baixo nível, a menos que o público precise.

• Mantenha a fonte mantível. Use aliases para nomes longos, nomenclatura consistente e comentários ou notas curtos para suposições importantes.

10. Erros comuns e lista de verificação de revisão

Se o diagrama não for renderizado, verifique se @startuml e @enduml estão presentes, os blocos de fragmento têm correspondências de fim declarações, os apelidos são usados de forma consistente e todos os pontos de extremidade de mensagem referem-se a participantes definidos. Verifique também se há sintaxe de outra linguagem de diagrama colada acidentalmente na fonte do PlantUML.

Antes de compartilhar, revise duas coisas:

• Sintaxe: Ele é renderizado? Os fragmentos estão fechados? Os participantes e apelidos são consistentes?

• Significado: Os participantes e as direções das mensagens estão corretos? Os caminhos de erro importantes estão incluídos? Os sistemas externos e repositórios de dados são representados com precisão?

O fluxo de trabalho mais forte de diagrama como código combina fonte legível, feedback visual rápido e revisão de domínio. O PlantUML fornece controle explícito sobre a notação de interação, enquanto VPasCode pode acelerar o rascunho e a iteração; a autoridade final sobre a precisão do diagrama continua sendo o comportamento do sistema que ele deve descrever.

This post is also available in Deutsch, English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Polski, Ру́сский, Việt Nam, 简体中文 and 繁體中文.