Diagramas de Casos de Uso UML como Código com PlantUML e VPasCode

Um diagrama de casos de uso UML mostra o que um sistema oferece e quem — ou o quê — interage com ele. Com um fluxo de trabalho de diagrama como código, a fonte do diagrama é texto simples: edite o texto, renderize o diagrama e mantenha a fonte junto com a documentação do projeto.

O PlantUML suporta diagramas de casos de uso. O editor VPasCode da Visual Paradigm oferece um editor e visualização do PlantUML, juntamente com recursos de geração e edição de diagramas assistidos por IA.

1. O que um diagrama de casos de uso comunica

Diagramas de casos de uso focam em escopo do sistema e objetivos do usuário, não as mecânicas passo a passo de um fluxo de trabalho. Um diagrama tipicamente contém:

• Fronteira do sistema: Um retângulo que nomeia o sistema que está sendo modelado.

• Ator: Um papel fora do sistema que interage com ele. Os atores podem ser pessoas, organizações, dispositivos ou sistemas externos.

• Caso de uso: Uma capacidade ou objetivo fornecido pelo sistema, geralmente mostrado como uma elipse e nomeado com uma frase verbal, como “Fazer pedido.”

• Associação: Uma linha que mostra que um ator participa de um caso de uso.

• Relacionamentos de casos de uso: Incluir, estender e generalização.

Atores representam papéis, não indivíduos específicos. Um serviço de pagamento externo pode ser um ator se interagir com o sistema que está sendo modelado.

Diagramas de casos de uso são úteis para esclarecer o escopo do sistema, discutir requisitos com partes interessadas, identificar dependências externas e fornecer uma visão compartilhada para desenvolvimento e testes. Combine-os com descrições escritas de casos de uso quando precisar de detalhes como pré-condições, etapas principais, fluxos alternativos e resultados.

2. Relacionamentos em uma olhada

• Associação ator–caso de uso: Uma linha simples indicando interação.

• <<incluir>>: O caso de uso que inclui sempre utiliza o comportamento incluído. A seta tracejada aponta do caso de uso que inclui para o caso de uso incluído. Por exemplo, fazer um pedido pode sempre incluir a autorização de pagamento.

• <<estender>>: Um caso de uso que estende adiciona comportamento a um caso de uso base sob uma condição. A seta tracejada aponta do caso de uso de extensão para o caso de uso base. Por exemplo, aplicar uma promoção pode estender o ato de fazer um pedido.

• Generalização: Um ator especializado ou caso de uso herda de um mais geral. A linha sólida com um triângulo vazio aponta para o elemento geral.

Uma distinção útil: include significa comportamento obrigatório; extend significa comportamento condicional adicionado.

3. Essenciais do PlantUML

Um diagrama PlantUML começa com @startuml e termina com @enduml. Declare atores com actor, casos de uso com usecase e limites de sistema com rectangle. Aliass facilitam a referência de elementos em relacionamentos.

@startuml
direção da esquerda para a direita

actor Cliente

rectangle "Loja Online" {
  usecase "Navegar produtos" as Navegar
  usecase "Fazer pedido" as FazerPedido
}

Cliente --> Navegar
Cliente --> FazerPedido
@enduml

direção da esquerda para a direita solicita ao PlantUML que organize o diagrama horizontalmente. O PlantUML pode ajustar o layout preciso conforme o diagrama muda.

4. Exemplo: loja online básica

@startuml
direção da esquerda para a direita

ator Cliente
ator Administrador como Admin

retângulo "Loja Online" {
  caso de uso "Navegar pelos produtos" como Navegar
  caso de uso "Fazer pedido" como Fazer
  caso de uso "Rastrear remessa" como Rastrear
  caso de uso "Gerenciar catálogo" como Gerenciar
}

Cliente --> Navegar
Cliente --> Fazer
Cliente --> Rastrear
Admin --> Gerenciar
@enduml

Os clientes navegam, fazem pedidos e rastreiam remessas. O administrador gerencia o catálogo. O diagrama deliberadamente omite as etapas internas do processamento do pedido.

5. Exemplo: include e extend

Suponha que fazer um pedido sempre requer autorização de pagamento, enquanto aplicar uma promoção é opcional e condicional.

@startuml
direção da esquerda para a direita

ator Cliente

retângulo "Loja Online" {
  caso de uso "Fazer pedido" como Fazer
  caso de uso "Autorizar pagamento" como Pagamento
  caso de uso "Aplicar promoção" como Promoção
}

Cliente --> Fazer

Fazer ..> Pagamento : <<include>>
Promoção ..> Fazer : <<extend>>
@enduml

A Fazer ..> Pagamento seta significa que “Fazer pedido” inclui o comportamento de pagamento obrigatório. A Promoção ..> Fazer seta significa que “Aplicar promoção” estende “Fazer pedido” quando sua condição é atendida.

Documente a condição — por exemplo, “cliente insere um código promocional válido” — na descrição do caso de uso ou em uma nota.

6. Exemplo: generalização de ator e sistemas externos

Um ator especializado herda interações de um ator mais geral. Serviços externos também podem ser atores quando interagem com o sistema.

@startuml
direção da esquerda para a direita

ator "Usuário" como User
ator "Cliente cadastrado" como Customer
ator "Gateway de pagamento" como Gateway

Customer --|> User

retângulo "Loja Online" {
  caso de uso "Navegar pelos produtos" como Navegar
  caso de uso "Fazer pedido" como Fazer
  caso de uso "Processar pagamento" como Pay
}

User --> Navegar
Customer --> Fazer
Fazer ..> Pay : <<include>>
Gateway --> Pay
@enduml

“Cliente cadastrado” especializa “Usuário” e herda a interação geral do usuário. A gateway de pagamento está fora do limite da Loja Online, mas participa do caso de uso de pagamento.

7. Exemplo: generalização de caso de uso

A generalização pode representar versões especializadas de um caso de uso mais amplo. O triângulo vazio aponta para o caso de uso geral.

@startuml
left to right direction

actor Cliente

rectangle "Sistema de Pagamento" {
  usecase "Realizar pagamento" as Pagamento
  usecase "Pagar com cartão" as Cartao
  usecase "Pagar por transferência bancária" as Transferencia
}

Cliente --> Cartao
Cliente --> Transferencia

Cartao --|> Pagamento
Transferencia --|> Pagamento
@enduml

Use isso quando os casos de uso especializados compartilham um objetivo geral, mas têm diferenças significativas. Se as variações forem apenas etapas condicionais, um <<extend>> relação ou uma descrição escrita do caso de uso pode ser mais clara.

8. Trabalhando no VPasCode

Um fluxo de trabalho prático:

1. Defina o escopo.Identifique o limite do sistema, os papéis dos atores e os objetivos que cada papel deseja alcançar.

2. Crie um rascunho.Escreva o PlantUML diretamente ou peça ao assistente de IA para gerar um diagrama de casos de uso.

3. Revise o código e visualize a prévia.Confirme que os atores estão fora do limite do sistema, os casos de uso estão dentro dele e as setas apontam na direção correta.

4. Refine o modelo.Substitua nomes vagos, remova detalhes de implementação e adicione relacionamentos apenas quando refletirem requisitos reais.

5. Solicite edições direcionadas da IA.Por exemplo: “Adicione um ator de gateway de pagamento externo e mostre a interação de pagamento necessária usando um relacionamento include. Mantenha o resto inalterado.”

6. Valide com as partes interessadas.Verifique se o diagrama reflete o escopo real do sistema e os objetivos dos usuários.

7. Salve a fonte. Mantenha o .puml texto junto com a documentação do projeto ou no controle de versão. Exporte uma imagem quando necessário para documentos ou apresentações.

Exemplo de prompt para assistência de IA

Crie um diagrama de casos de uso UML em PlantUML para uma loja online. Inclua um limite de sistema, atores Cliente e Administrador, e os objetivos Navegar em produtos, Fazer pedido, Rastrear remessa e Gerenciar catálogo. Mostre a autorização de pagamento como comportamento obrigatório incluído por Fazer pedido. Mostre a aplicação de uma promoção como uma extensão condicional de Fazer pedido. Retorne apenas código-fonte PlantUML válido.

Trate o código gerado por IA como um rascunho inicial. Revise os atores, limites, relacionamentos e premissas de negócio antes de utilizá-lo.

9. Armadilhas comuns

• Modelar componentes internos como atores: Os atores devem ser papéis externos ou sistemas que interagem com o assunto.

• Nomear casos de uso como tarefas de implementação: Prefira “Rastrear remessa” em vez de “Chamar API de rastreamento.”

• Usar <<include>> para comportamento opcional: Include representa o comportamento que o caso de uso base exige.

• Inverter as setas de relacionamento: Include aponta para o caso de uso incluído; extend aponta para o caso de uso base.

• Sobrecarregar um único diagrama com detalhes: Use um diagrama de alto nível para o escopo e, em seguida, diagramas separados ou texto para cenários detalhados.

• Assumir que um render bem-sucedido significa que o modelo está correto: O PlantUML pode renderizar um diagrama que ainda representa incorretamente os requisitos.

10. Lista de verificação de revisão

Antes de compartilhar o diagrama, confirme que:

• O limite do sistema está claro.

• Cada ator é externo e representa um papel.

• Os nomes dos casos de uso descrevem objetivos significativos.

• As associações dos atores refletem interações reais.

• Os relacionamentos include são obrigatórios; os relacionamentos extend são condicionais ou de outra forma justificados.

• As setas de generalização apontam para o ator ou caso de uso geral.

• O diagrama permanece legível no tamanho pretendido.

• As suposições geradas por IA foram revisadas com pessoas familiarizadas com os requisitos.

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