Ao projetar sistemas complexos, frequentemente surge a necessidade de criar diagramas de sequência e outras representações visuais. Ferramentas gráficas tradicionais, embora intuitivas, podem se tornar limitadas quando o diagrama exige muitos detalhes ou precisa ser versionado junto ao código-fonte. ### 1.1 Conceito e Funcionalidades
O PlantUML é uma ferramenta de código aberto que permite gerar diagramas a partir de descrições textuais simples. Ele suporta diversos tipos de diagramas, incluindo diagramas de sequência, de classes, de casos de uso, de componentes, de implantação, de estados e diagramas de atividades.
Além dos diagramas UML tradicionais, o PlantUML também trabalha com represantações de dados em JSON, YAML, diagramas EBNF e diagramas arquiteturais. Como toda a definição é feita em texto puro, os diagramas podem ser facilmente versionados com controle de versão e integrados diretamente na documentação do projeto.
Documentação oficial: https://plantuml.com/zh/
1.2 Plugins para Editores de Código
Diversos editores populares oferecem integração com o PlantUML por meio de plugins, tornando a experiência de criação de diagramas muito mais produtiva. Os plugins oferecem recursos como visualização em tempo real, destaque de sintaxe e exportação de imagens.
IntelliJ IDEA
No IntelliJ IDEA, o plugin PlantUML integration permite editar e visualizar diagramas diretamente no ambiente de desenvolvimento.
Visual Studio Code
No VS Code, o plugin disponível em jebbs.plantuml oferece funcionalidades semelhantes.
Primeiro Exemplo
Veja como criar um diagrama simples utilizando setas ->, --> e o caractere : para definir mensagens entre participantes sem declará-los explicitamente:
@startuml
Maria -> Carlos : Olá, tudo bem?
Carlos --> Maria : Oi, tudo ótimo!
Maria -> Carlos : Vamos marcar uma reunião?
Carlos <-- Maria : Combinado
@enduml
- Sintaxe de Diagramas de Sequência
2.1 Declarando Participantes
A palavra-chave participant permite declarar participantes com controle adicional. A ordem de declaração define a ordem de exibição. Existem variantes para representar diferentes tipos de elementos:
actor(ator)boundary(fronteira)control(controle)entity(entidade)database(banco de dados)collections(coleções)queue(fila)
O operador as permite renomear participantes para facilitar a leitura:
@startuml
participant Gerente as G
actor Cliente as Cli
boundary Portal as P
control Motor as M
entity Registro as R
database Armazen as DB
collections Cache as C
queue FilaMsg as F
@enduml
Também é possível definir cores personalizadas utilizando o caractere # seguido do código da cor:
@startuml
actor Administrador #DodgerBlue
participant "Servidor de\nAplicações" as Srv #LightGreen
participant Analista #Gold
Administrador->Srv: Solicitar relatório
Srv->Analista: Gerar dados
Analista-->Srv: Relatório pronto
Srv-->Administrador: Exibir relatório
@enduml
2.2 Tipos de Mensagens
Mensagem Síncrona
A -> B: texto da mensagem síncrona — o remetente aguarda o processamento.
Mensagem Assíncrona
A ->> B: texto da mensagem assíncrona — o remetente não aguarda resposta imediata.
Mensagem de Retorno
A <-- B: texto da resposta — geralmente vai do receptor de volta ao remetente.
Auto-chamada
A -> A: texto da chamada interna — o participante invoca a si mesmo.
2.3 Linhas de Vida e Barrras de Ativação
A linha de vida representa o período de existência de um objeto, exibida como uma linha tracejada vertical. A barra de ativação indica que o objeto está processando uma atividdae, mostrada como um retângulo sobre a linha de vida.
Ativação e Desativação Manual
Utilize activate, deactivate e destroy para controlar o ciclo de vida visualmente:
@startuml
participant Sistema
Sistema -> Processador: Iniciar processamento
activate Processador
Processador -> Repositorio: Consultar dados
activate Repositorio
Repositorio -> Banco: Executar query
activate Banco
Banco --> Repositorio: Resultados
destroy Banco
Repositorio --> Processador: Dados obtidos
deactivate Repositorio
Processador -> Sistema: Processamento concluído
deactivate Processador
@enduml
Ativação Automática
Utilize ++ após o destino para ativação automática e -- para desativação:
A->B++: Enviar solicitação (ativa B)
A<--B--: Responder solicitação (desativa B)
Ativações Aninhadas com Cores
Barras de ativação podem ser aninhadas para representar chamadas internas e receber cores personalizadas:
@startuml
participant Executor
Executor -> Motor: Executar tarefa
activate Motor #LightBlue
Motor -> Motor: Validação interna
activate Motor #MediumPurple
Motor -> Armazen: Persistir resultado
activate Armazen
Armazen --> Motor: Confirmado
deactivate Armazen
deactivate Motor
Motor -> Executor: Tarefa finalizada
deactivate Motor
@enduml
2.4 Agrupamento e Fluxos Condicionais
Agrupamentos organizam interações logicamente relacionadas:
group NomeDoGrupo
Remetente -> Destinatario: Mensagem
...
end group
Fluxos condicionais com alt/else representam caminhos alternativos:
alt Condição verdadeira
Servidor -> Cliente: Resposta de sucesso
else Condição alternativa
Servidor -> Cliente: Resposta de fallback
end
2.5 Anotações
Utilize note left of, note right of ou note over para adicionar comentários visuais ao diagrama:
@startuml
participant Desenvolvedor
participant Revisor
note left of Desenvolvedor #LightYellow
Responsável por implementar
a funcionalidade.
end note
note right of Revisor: Analisa e aprova o código.
note over Desenvolvedor, Revisor #Lavender
Fluxo de revisão de código
do projeto.
end note
@enduml
2.6 Personalização de Cores
O PlantUML permite customizar cores de praticamente todos os elementos visuais, como participantes, barras de ativação, bordas e fontes.
Definição Direta
Especifique cores diretamente ao declarar elementos, usando códigos hexadecimais ou nomes predefinidos:
@startuml
actor Operador #Coral
participant Motor #MediumAquamarine
Operador-[#DarkViolet]>Motor:Comando de execução
activate Motor #SteelBlue
@enduml
Configuração Global com skinparam
A diretiva skinparam permite definir cores padrão para todo o diagrama:
@startuml
skinparam ActorBorderColor #Sienna
skinparam ParticipantBackgroundColor #PaleTurquoise
actor Operador
participant Motor
@enduml
Entre as propriedades disponíveis estão BorderColor, BackgroundColor, FontColor e SequenceGroupBodyBackgroundColor.
- Exemplo Completo: Autenticação com OAuth de Terceiros
O exemplo a seguir demonstra um cenário realista onde o fluxo de login tradicional é estendido para incluir autenticação via provedor OAuth externo (GitHub, neste caso):
@startuml
skinparam ParticipantBackgroundColor #LightSteelBlue
actor Usuario as U #CornflowerBlue
participant "Aplicacao Cliente" as App
participant "Gateway" as GW
participant "Servico Auth" as Auth
database "Armazen" as Store #CornflowerBlue
participant "GitHub OAuth" as GH #Salmon
activate U #CornflowerBlue
activate App #CornflowerBlue
U->App: Solicitar login
group#Salmon #Salmon Fluxo GitHub (Cliente)
App -> GH : Redirecionar para OAuth
activate GH #CornflowerBlue
GH-->App: URL de autorizacao
App->GH: Usuario autentica
GH -> GH : Processar credenciais
GH --> App : Access Token
deactivate GH
end
|||
App -> GW : Requisicao de login
note right#Salmon: Novo metodo via OAuth externo
activate GW #CornflowerBlue
GW ->Auth: Encaminhar requisicao
activate Auth #CornflowerBlue
alt#CornflowerBlue Login Convencional
Auth -> Store : Buscar credenciais
activate Store #CornflowerBlue
Store -> Auth : Dados do usuario
deactivate Store
Auth->Auth:Validar senha
|||
else Login via GitHub
group#Salmon #Salmon Fluxo GitHub (Servidor)
Auth->GH:Verificar token
activate GH #CornflowerBlue
GH-->Auth:Perfil do usuario
deactivate GH
Auth->Auth:Registrar ou atualizar conta
end group
end
Auth-->GW:Resultado da autenticacao
deactivate Auth
GW -> App : Resposta ao cliente
deactivate GW
alt#CornflowerBlue Sucesso
App -> U : Login realizado
else Falha
App -> U : Falha na autenticacao
end
deactivate App
|||
@enduml