Antes de adentrarnos en diseños arquitectónicos específicos como modelos C4 o cronologías de secuencia, es esencial comprender las reglas fundamentales que rigen elManual de PlantUML. PlantUML se basa en un sistema de notación de texto limpio y altamente intuitivo. Una vez que entiendas cómo el motor abre documentos, nombra los componentes estructurales y enruta las líneas de conexión, escribir cualquier diseño de sistema complejo se vuelve completamente natural.
Esta breve introducción cubre las mecánicas sintácticas estructurales globales que se aplican en casi todos los tipos de diagramas de PlantUML dentro del entorno de trabajo VPasCode.
1. Los envoltorios obligatorios de documento
Cada bloque individual de código de PlantUML debe comenzar y terminar con etiquetas de marco explícitas. Estas etiquetas indican al analizador de VPasCode que active el motor de renderizado correcto en tu lienzo de vista previa:
@startuml— Esta línea exacta debe colocarse en la parte superior absoluta de tu script. Nada más debe precederla.@enduml— Esta línea exacta debe colocarse en la parte inferior absoluta de tu script, marcando el final de tu bloque de datos del diagrama.
Cualquier código escrito fuera de estos dos marcadores será ignorado de forma segura por el compilador, o podría desencadenar una advertencia de validación de sintaxis en el panel de diagnóstico de tu entorno de trabajo.
2. Declaración de elementos: IDs frente a etiquetas de visualización
Al modelar un sistema de software, crearás diversos elementos estructurales como componentes, bases de datos, actores o microservicios. En PlantUML, puedes declarar un elemento explícitamente definiendo su tipo, una ID abreviada interna y un nombre de visualización amigable entre comillas:
componente microservice_id como "API de procesamiento de pagos"
database db_id como "SQL de transacciones de usuario"Por qué esta es una buena práctica: Usar una ID interna corta y limpia (comomicroservice_id) hace que dibujar líneas de relación sea mucho más rápido más adelante. Si en algún momento necesitas cambiar la etiqueta visible para el cliente de “API de procesamiento de pagos” a “Servicio de caja global”, solo tendrás que editarla en una sola línea de código, en lugar de actualizar decenas de líneas en todo tu script.
3. Dominar las flechas de relación y la ruta direccional
Las conexiones entre nodos del sistema se dibujan utilizando combinaciones de guiones (-) y corchetes de flecha (>). La longitud de tus guiones y la inclusión de palabras clave direccionales te dan un control implícito sobre cómo el motor de diseño automático escala tu diagrama:
- Conexiones básicas:
A --> Bdibuja una flecha dirigida estándar que apunta desde el elemento A directamente hacia el elemento B. - Líneas de dependencia punteadas:Sustituir los guiones por puntos crea una línea punteada, que es el estándar de la industria para indicar dependencias asíncronas o llamadas de red:
A ..> B. - Forzando la orientación del diseño: Aunque el motor de diseño espacia los cuadros automáticamente, puedes dirigir explícitamente la orientación insertando una palabra clave de dirección directamente dentro de la cadena de flecha:
A -up-> B(Fuerza a B a renderizarse encima de A)A -down-> B(Fuerza a B a renderizarse debajo de A)A -left-> B(Fuerza a B a renderizarse a la izquierda de A)A -right-> B(Fuerza a B a renderizarse a la derecha de A)
4. Añadiendo contexto en línea: Etiquetas y comentarios de código
La documentación clara depende en gran medida de colocar el contexto adecuado alrededor de tus líneas visuales y scripts de texto:
Etiquetado de líneas de conexión
Puedes agregar texto explicativo directamente a cualquier línea de conexión añadiendo dos puntos (“:) justo después de tu mapeo de relación:
client_id --> api_id : "POST HTTPS /v1/checkout"Escribiendo comentarios de código
Si deseas dejar una nota administrativa, crédito de diseño o explicación arquitectónica dentro de tu archivo de script sin renderizar una caja visual en la cuadrícula, utiliza un carácter de comilla simple (“'). Esto indica al motor que omita completamente el análisis de esa línea:
' TODO: Debemos actualizar esta caja de límite una vez finalice la migración de DevOps
[Monolito heredado] --> [Nuevo Microservicio]Ahora que estás familiarizado con los envolventes de sintaxis globales, las declaraciones de componentes y los parámetros de flecha direccionales de PlantUML, estás perfectamente preparado para comenzar a crear formas de sistema avanzadas. Procede a la siguiente página para desbloquear nuestra colección de Diagramas de Arquitectura y Diseño de Alto Nivel!