Antes de mergulhar em layouts arquitetônicos específicos, como modelos C4 ou cronogramas de sequência, é essencial compreender as regras fundamentais que regem o Guia Prático do PlantUML. O PlantUML depende de um sistema de notação de texto limpo e altamente intuitivo. Uma vez que você entenda como o motor abre documentos, nomeia componentes estruturais e roteia linhas de conexão, escrever qualquer layout de sistema complexo torna-se completamente natural.
Este breve guia aborda as mecânicas sintáticas estruturais globais que se aplicam a quase todos os tipos de diagramas PlantUML dentro do ambiente VPasCode.
1. Os Envoltórios Obrigatórios do Documento
Cada bloco individual de código PlantUML deve começar e terminar com tags explícitas de estrutura. Essas tags informam ao analisador VPasCode para iniciar o motor de renderização correto na sua área de visualização:
@startuml— Esta linha exata deve ser colocada na parte superior absoluta do seu script. Nada mais deve precedê-la.@enduml— Esta linha exata deve ser colocada na parte inferior absoluta do seu script, marcando o fim do bloco de dados do seu diagrama.
Qualquer código escrito fora desses dois marcadores será ignorado com segurança pelo compilador, ou pode acionar um aviso de validação de sintaxe no painel de diagnóstico do seu workspace.
2. Declarando Elementos: IDs vs. Rótulos de Exibição
Ao modelar um sistema de software, você criará diversos elementos estruturais, como componentes, bancos de dados, atores ou microsserviços. No PlantUML, você pode declarar um elemento explicitamente definindo seu tipo, uma ID curta interna e um nome de exibição amigável, cercado por aspas:
componente microservice_id como "API de Processamento de Pagamentos"
database db_id como "SQL de Transações do Usuário"Por que esta é uma melhor prática: Usar uma ID interna curta e limpa (como microservice_id) torna muito mais rápido desenhar linhas de relacionamento posteriormente. Se você precisar alguma vez mudar o rótulo visível para o cliente de “API de Processamento de Pagamentos” para “Serviço de Checkout Global”, você precisará editar apenas uma única linha de código, em vez de atualizar dezenas de linhas em todo o seu script.
3. Dominando Setas de Relacionamento e Roteamento Direcional
As conexões entre nós do sistema são desenhadas usando combinações de traços (-) e colchetes de seta (>). O comprimento dos seus traços e a inclusão de palavras-chave direcionais lhe dão controle implícito sobre como o motor de layout automático escala o seu diagrama:
- Conexões Básicas:
A --> Bdesenha uma seta direcional padrão apontando do elemento A diretamente para o elemento B. - Linhas de Dependência Pontilhadas: Substituir traços por pontos cria uma linha pontilhada, que é o padrão da indústria para indicar dependências assíncronas ou chamadas de rede:
A ..> B. - Forçando a Orientação do Layout: Embora o motor de layout espaçe as caixas automaticamente, você pode orientar explicitamente a direção inserindo uma palavra-chave de direção diretamente na string da seta:
A -up-> B(Força B a ser renderizado acima de A)A -down-> B(Força B a ser renderizado abaixo de A)A -left-> B(Força B a ser renderizado à esquerda de A)A -right-> B(Força B a ser renderizado à direita de A)
4. Adicionando Contexto Inline: Rótulos e Comentários de Código
Documentação clara depende muito de colocar o contexto apropriado ao redor das suas linhas visuais e scripts de texto:
Rotulando Linhas de Conexão
Você pode adicionar texto explicativo diretamente em qualquer linha de conexão acrescentando dois pontos (“:) logo após o seu mapeamento de relacionamento:
client_id --> api_id : "POST HTTPS /v1/checkout"Escrevendo Comentários de Código
Se você quiser deixar uma nota administrativa, crédito de design ou explicação arquitetônica dentro do seu arquivo de script sem renderizar uma caixa visual na tela, use um caractere de apóstrofo (“'). Isso informa ao motor para ignorar completamente a análise dessa linha:
' TODO: Precisamos atualizar esta caixa de limite assim que a migração DevOps for concluída
[Monólito Legado] --> [Novo Microserviço]Agora que você está familiarizado com os envoltórios de sintaxe global, declarações de componentes e parâmetros de setas direcionais do PlantUML, você está perfeitamente preparado para começar a criar formas avançadas de sistema. Prossiga para a próxima página para desbloquear nossa coleção de Diagramas de Arquitetura e de Projeto de Alto Nível!