VPasCode: Diagramas de Atividade UML com PlantUML – Um Tutorial Prático

Um diagrama de atividade UML modela como o trabalho flui através de um processo: as ações realizadas, as decisões tomadas, o trabalho paralelo e os caminhos para a conclusão. O PlantUML permite descrever esse modelo como texto e, em seguida, renderizá-lo como um diagrama — uma abordagem útil quando se deseja diagramas fáceis de revisar, analisar e manter junto à documentação do projeto. A sintaxe atual de atividades do PlantUML usa palavras-chave legíveis como início, se, repetir, e ramificação; sua sintaxe antiga de atividades ainda é suportada, mas a sintaxe mais recente é recomendada para novos diagramas.

1. O que modelar

Use um diagrama de atividade para explicar um processo ou algoritmo, por exemplo:

• Um fluxo de trabalho de checkout de cliente

• Um processo de aprovação

• Um pipeline de importação de dados

• As etapas em um caso de uso

• Trabalho dividido entre pessoas, equipes ou componentes do sistema

Uma atividade é uma unidade de trabalho, como “Validar pedido”. Um fluxo de controleconecta atividades e indica sua ordem. Um decisãoescolhe entre caminhos alternativos; fluxos paralelosmostram trabalho que pode prosseguir simultaneamente. O diagrama deve esclarecer o comportamento, não tentar documentar cada detalhe de implementação.

Uma regra prática útil: se a pergunta principal é “O que acontece a seguir e sob quais condições?”, um diagrama de atividade é uma boa escolha.

2. Noções básicas do PlantUML

Um diagrama PlantUML começa com @startuml e termina com @enduml. Na sintaxe atual de atividade:

• start marca o nó inicial.

• :Action; define uma ação.

• if (...) then (...) ramifica com base em uma condição.

• endif fecha a condicional.

• stop encerra um fluxo.

• repeat e repeat while modela a repetição.

• fork, fork again, e end fork modela trabalho paralelo.

As ações são escritas em ordem e estão implicitamente conectadas. Você pode adicionar rótulos às ramificações e usar partition para agrupar o trabalho por responsabilidade ou função.

Aqui está um exemplo mínimo:

@startuml
start
:Receber solicitação;
:Validar solicitação;
stop
@enduml

3. Decisões e caminhos alternativos

Use se quando o processo faz uma escolha. Os rótulos dos ramos devem comunicar os resultados da condição, não apenas repetir a condição.

@startuml
start
:Receber pedido;
:Verificar estoque;

se (Todos os itens disponíveis?) então (Sim)
  :Reservar itens;
  :Solicitar pagamento;
else (Não)
  :Notificar cliente;
  stop
endif

:Confirmar pedido;
stop
@enduml

Aqui, se introduz uma decisão e endif a encerra. Os Sim e Não rótulos tornam as alternativas visíveis. Quando os caminhos continuam para uma ação compartilhada após endif, eles se juntam novamente ao fluxo.

Dica de modelagem: Seja explícito sobre o que acontece em cada resultado significativo. Se um caminho de erro, timeout ou rejeição for relevante para as partes interessadas, mostre-o em vez de deixá-lo implícito.

4. Loops e retentativas

Use um loop quando uma ação ou grupo de ações puder se repetir. Este exemplo continua solicitando entrada até que ela passe pela validação:

@startuml
start
:Ler dados submetidos;

repeat
  :Validar dados;
  if (Válido?) then (Sim)
    :Salvar dados;
    break
  else (Não)
    :Mostrar erros de validação;
    :Pedir ao usuário que corrija os dados;
  endif
repeat while (Usuário continua?) é (Sim) não (Não)

stop
@enduml

Laços podem ser difíceis de ler se sua condição de saída for vaga. Declare o que causa outra tentativa e o que encerra a repetição — especialmente quando as tentativas são limitadas ou podem ser canceladas.

5. Trabalho paralelo e sincronização

Use fork quando ações independentes podem ocorrer simultaneamente, e end fork quando os caminhos devem ser sincronizados antes que o processo continue.

@startuml
start
:Pedido confirmado;

fork
  :Enviar e-mail de confirmação;
fork again
  :Preparar lista de separação do armazém;
fork again
  :Atualizar painel de vendas;
end fork

:Marcar pedido como em processamento;
stop
@enduml

Um fork não significa necessariamente pessoas separadas; pode representar comportamento concorrente do sistema. Use-o apenas quando as ações realmente puderem ocorrer em paralelo. Se uma tarefa deve terminar antes que outra comece, modele-as sequencialmente em vez disso.

6. Faixas de nado com partições

Partições agrupam ações por função, equipe ou sistema responsável. Isso pode tornar as transferências claras sem alterar o processo em si. O PlantUML suporta o agrupamento de atividades com partition.

@startuml
start

partition Cliente {
  :Enviar pedido;
}

partition "Serviço de Pedidos" {
  :Validar pedido;
  if (Pedido válido?) then (Sim)
    :Criar registro de pedido;
  else (Não)
    :Retornar erros de validação;
    stop
  endif
}

partition Armazém {
  :Preparar remessa;
}

partition "Serviço de Pedidos" {
  :Enviar confirmação;
}

stop
@enduml

Escolha rótulos de faixas que correspondam à divisão real de responsabilidades. Evite criar uma nova partição para cada pequeno componente; muitas faixas podem tornar o diagrama mais difícil de analisar.

7. Objetos de dados e notas

Alguns fluxos de trabalho se beneficiam ao mostrar entradas ou saídas importantes. Os diagramas de atividade do PlantUML suportam estereótipos de nó de objeto; notas também podem adicionar contexto sem transformar cada rótulo de ação em um parágrafo.

@startuml
start
:Receber solicitação de pagamento;

:Autorizar pagamento;
nota à direita
  Usa a resposta de autorização
  do provedor de pagamento.
end note

:Registrar resultado do pagamento;
stop
@enduml

Mantenha os rótulos das atividades principais curtos. Coloque regras de negócio, suposições ou esclarecimentos em notas quando os leitores precisarem deles, mas eles não forem etapas em si do fluxo.

8. Exemplo completo: checkout online

Este exemplo maior combina partições, uma decisão, um caminho alternativo e trabalho paralelo.

@startuml
title Checkout Online

start

partition Cliente {
  :Revisar carrinho;
  :Enviar checkout;
}

partition "Serviço de Pedidos" {
  :Validar carrinho e endereço;

  if (Carrinho e endereço válidos?) then (Sim)
    :Calcular total;
  else (Não)
    :Mostrar erros de validação;
    stop
  endif
}

partition "Serviço de Pagamento" {
  :Autorizar pagamento;

  if (Pagamento aprovado?) then (Aprovado)
    :Capturar pagamento;
  else (Recusado)
    :Retornar falha no pagamento;
    stop
  endif
}

partition "Serviço de Pedidos" {
  :Criar pedido;
}

fork
  partition "Serviço de Notificação" {
    :Enviar confirmação do pedido;
  }
fork again
  partition Armazém {
    :Fila do pedido para separação;
  }
end fork

partition "Serviço de Pedidos" {
  :Mostrar confirmação do pedido;
}

stop
@enduml

Leia de cima para baixo: o cliente envia o checkout, o serviço de pedidos o valida, o pagamento é autorizado e o pedido é criado. Em seguida, a confirmação e a preparação do armazém ocorrem em paralelo. Se a validação ou o pagamento falhar, o fluxo termina pelo caminho de falha correspondente.

9. Fluxo de trabalho de diagrama como código

Um fluxo de trabalho prático é:

Fluxo de trabalho de diagrama como código

Um fluxo de trabalho prático é:

1. Descreva o processo em linguagem simples.Identifique seu início, fim, ações principais, decisões, exceções, tarefas paralelas e papéis responsáveis.

2. Escreva um primeiro rascunho em PlantUML.Foque na lógica antes da estilização.

3. Renderize e inspecione-o.Verifique se o resultado é natural de ler e se os ramos e loops são compreensíveis.

4. Revise a lógica com as partes interessadas.A renderização verifica a sintaxe, não se o processo está correto.

5. Revise a fonte e salve-a junto ao projeto.Diagramas baseados em texto são simples de comparar e revisar junto com outra documentação.

Para renderização local, a ferramenta de linha de comando do PlantUML pode gerar arquivos de diagrama; editores baseados em navegador são convenientes para rascunhos rápidos e visualizações. O PlantUML também oferece um editor no navegador, enquanto o VPasCode fornece um editor baseado em navegador com visualização ao vivo e suporte a diagramas de atividade PlantUML.

1. Descreva o processo em linguagem simples.Identifique seu início, fim, ações principais, decisões, exceções, tarefas paralelas e papéis responsáveis.

2. Escreva um primeiro rascunho em PlantUML.Foque na lógica antes da estilização.

3. Renderize e inspecione-o.Verifique se o resultado é natural de ler e se os ramos e loops são compreensíveis.

4. Revise a lógica com as partes interessadas.A renderização verifica a sintaxe, não se o processo está correto.

5. Revise a fonte e salve-a junto ao projeto.Diagramas baseados em texto são simples de comparar e revisar junto com outra documentação.

Para renderização local, a ferramenta de linha de comando do PlantUML pode gerar arquivos de diagrama; editores baseados em navegador são convenientes para rascunhos rápidos e visualizações. O PlantUML também oferece um editor no navegador, enquanto o VPasCode fornece um editor baseado em navegador com visualização ao vivo e suporte a diagramas de atividade PlantUML.

10. Usando o Visual Paradigm VPasCode e assistência de IA

O VPasCode é o editor de texto para diagrama baseado em navegador da Visual Paradigm. Seu suporte ao PlantUML inclui diagramas de atividade, e seu editor oferece renderização ao vivo. A Visual Paradigm também descreve a geração de diagramas por linguagem natural integrada e a assistência de IA para modificar ou corrigir o código do diagrama.

Um fluxo de trabalho útil com assistência de IA:

1. Solicite o comportamento, não apenas o tipo de diagrama.Por exemplo:
   “Crie um diagrama de atividade PlantUML para checkout online. Inclua validação do carrinho, validação de endereço, autorização de pagamento, caminhos de falha, criação de pedido, e e-mail de confirmação e preparação do armazém em paralelo. Use partições para Cliente, Serviço de Pedido, Serviço de Pagamento, Serviço de Notificação e Armazém. Use a sintaxe atual de atividade do PlantUML.”

2. Inspecione a fonte gerada.Verifique se ela usa @startuml/@enduml, de que cada ramo representa uma condição real e de que caminhos falhos ou alternativos são tratados.

3. Renderize-o no VPasCode. Use a pré-visualização para identificar erros de sintaxe, rótulos confusos ou layouts excessivamente complexos.

4. Refine o PlantUML por si mesmo ou com edições direcionadas de IA. Peça uma alteração específica, como “Adicionar um caminho de tempo limite de pagamento” ou “Tornar a preparação do armazém sequencial após a criação do pedido.”

5. Valide o processo com alguém que o conheça. A IA pode rascunhar um diagrama plausível, mas não pode estabelecer que o processo real da sua organização está correto.

Os controles exatos e a disponibilidade de funcionalidades do VPasCode podem variar conforme a edição do produto; confirme as opções atuais no editor que está a utilizar.

11. Fluxo de trabalho de modelação do Visual Paradigm

Utilize o VPasCode quando quiser trabalhar diretamente com a fonte do diagrama e a pré-visualização. Utilize o ambiente de modelação do Visual Paradigm quando a tarefa exigir edição gráfica ou trabalho de modelação mais amplo. A orientação do Visual Paradigm descreve um fluxo de trabalho de gerar ou importar um diagrama e, em seguida, refiná-lo no editor visual; os caminhos de importação exatos podem depender do produto e da versão.

Uma transição sensata é:

1. Rascunhe e itere no PlantUML.

2. Partilhe o diagrama renderizado e a fonte para revisão.

3. Abra ou importe-o no editor relevante do Visual Paradigm se precisar de edição visual ou outras capacidades de modelação.

4. Mantenha a fonte do PlantUML como a versão mantida se for a fonte da verdade escolhida pela equipa; evite fazer edições conflitantes silenciosamente em dois locais.

12. Erros comuns e lista de verificação de qualidade

Antes de partilhar um diagrama, verifique:

• Tem um início claro e um fim significativo?

• Cada ação descreve uma parte de trabalho reconhecível?

• Os resultados das decisões estão claramente rotulados?

• Os caminhos de rejeição, erro, tempo limite ou cancelamento estão incluídos onde são relevantes?

• As condições de loop tornam claros o comportamento de repetição e saída?

• As ações paralelas são genuinamente independentes e a sincronização é mostrada onde necessário?

• As partições representam limites de propriedade úteis?

• Um leitor consegue compreender o fluxo sem ler rótulos de ação longos?

• O diagrama renderizado corresponde ao processo real?

Um bom diagrama de atividade não é o mais longo ou o mais detalhado. É o diagrama mais pequeno que torna claros o fluxo de trabalho, as decisões, as responsabilidades e as exceções importantes.

Referência rápida de sintaxe

Os exemplos utilizam a sintaxe atual de diagramas de atividade do PlantUML. Para construções incomuns ou comportamento de renderização específico de versão, consulte a referência de diagramas de atividade do PlantUML.

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