Diagramas como código: Diagramas de secuencia UML con PlantUML y VPasCode

Un UML diagrama de secuencia muestra cómo interactúan los participantes a lo largo del tiempo. Es útil para documentar un caso de uso, flujo de API, proceso empresarial o escenario del sistema. El tiempo generalmente avanza de arriba hacia abajo; la colocación horizontal muestra quién participa, no una medida precisa del tiempo transcurrido.

PlantUML te permite describir el diagrama como texto. el editor VPasCode de Visual Paradigm combina un editor de código con una vista previa en tiempo real y asistencia de IA para generar, modificar y corregir código de diagramas. Un buen flujo de trabajo es utilizar la IA para obtener un primer borrador y luego inspeccionar y refinar el código PlantUML tú mismo.

1. La estructura básica

Un diagrama de secuencia PlantUML comienza con @startuml y termina con @enduml. Los participantes suelen listarse antes de los mensajes para que puedas controlar sus nombres y orden.

@startuml
actor Cliente
participant Navegador
participant "API de pedidos" como API
database "Base de datos de pedidos" como DB

Cliente -> Navegador: Realizar pedido
Navegador -> API: POST /pedidos
API -> DB: Guardar pedido
DB --> API: ID de pedido
API --> Navegador: 201 Creado
Navegador -> Cliente: Mostrar confirmación
@enduml

La etiqueta mostrada del participante puede estar entre comillas, con como que proporciona un alias más corto para usar en mensajes. Las palabras clave comunes de participantes incluyen actor, participante, límite, control, entidad, base de datos, y colecciones. Utilice la palabra clave que mejor comunique el rol del participante; no impone una arquitectura particular.

2. Lectura de mensajes y tiempo

Cada mensaje se escribe como un remitente, una flecha, un destinatario y una etiqueta. El orden de las líneas de mensajes determina su orden vertical en el diagrama.

• -> es una flecha de mensaje sólida, comúnmente utilizada para una solicitud o llamada.

• --> es una flecha discontinua, a menudo utilizada para una respuesta o retorno.

• ->> y -->> utilizan puntas de flecha abiertas en los estilos comunes de PlantUML.

• : texto añade la etiqueta del mensaje.

Elija una convención coherente para llamadas y respuestas. Los diagramas UML comunican una interacción; no garantizan automáticamente que la implementación siga el protocolo representado.

3. Activaciones y vidas de los participantes

Las activaciones pueden mostrar cuándo un participante está realizando trabajo. Use activate y desactivar, o la abreviatura ++ y -- en las flechas de mensaje.

@startuml
actor Usuario
participante "API de inicio de sesión" como API
database Usuarios

Usuario -> API: Enviar credenciales
activar API
API -> Usuarios: Buscar cuenta
activar Usuarios
Usuarios --> API: Registro de cuenta
desactivar Usuarios
API --> Usuario: Resultado de inicio de sesión
desactivar API
@enduml

Las activaciones son más útiles cuando aclaran llamadas anidadas o responsabilidades. Evite añadirlas mecánicamente a cada mensaje si hacen que el diagrama sea más difícil de leer.

4. Condiciones, alternativas y repetición

Use fragmentos combinados para mostrar el flujo de control. La palabra clave fragment inicia el bloque, else separa las alternativas cuando sea aplicable, y end lo cierra. Las condiciones de guardia van entre corchetes.

Rutas alternativas: alt y de lo contrario

@startuml
actor Usuario
participante "API de inicio de sesión" como API
database Usuarios

Usuario -> API: Enviar nombre de usuario y contraseña
API -> Usuarios: Verificar credenciales
Usuarios --> API: Resultado de coincidencia

alt [credenciales válidas]
  API --> Usuario: Devolver token de sesión
else [credenciales inválidas]
  API --> Usuario: Devolver error de autenticación
end
@enduml

alt es apropiado cuando las rutas son mutuamente excluyentes. Utilice etiquetas que hagan claras las condiciones.

Comportamiento opcional: opt

@startuml
actor Cliente
participante Checkout
participante "Servicio de correo electrónico" como Email

Cliente -> Checkout: Completar compra
Checkout --> Cliente: Confirmación de pedido

opt [cliente se ha suscrito al correo]
  Checkout -> Email: Enviar recibo
  Email --> Checkout: Aceptado
end
@enduml

Repetición: bucle

@startuml
participante "Trabajo por lotes" como Job
participante "API de pagos" como API

bucle [para cada pago pendiente]
  Job -> API: Enviar pago
  API --> Job: Resultado del pago
end
@enduml

Coloque la acción repetida dentro del fragmento y especifique claramente la condición o el alcance del bucle.

5. Interacciones paralelas y agrupadas

Use par cuando las interacciones ocurren de forma concurrente o su orden no es significativo. Use group para etiquetar un conjunto de mensajes sin implicar una estructura de flujo de control particular.

@startuml
participante "Servicio de Pedidos" como Pedidos
participante "Servicio de Inventario" como Inventario
participante "Servicio de Notificaciones" como Notificar

Pedidos -> Pedidos: Pedido aceptado

par Reservar stock
  Pedidos -> Inventario: Reservar artículos
  Inventario --> Pedidos: Resultado de la reserva
else Notificar al cliente
  Pedidos -> Notificar: Enviar actualización del pedido
  Notificar --> Pedidos: Aceptado
end
@enduml

Usar par solo cuando la concurrencia tenga sentido. Si una acción debe terminar antes de que comience otra, muestre los mensajes en secuencia en su lugar.

6. Notas, referencias y agrupación visual

Las notas pueden aclarar suposiciones, restricciones o decisiones. Un ref fragmento puede dirigir a los lectores a otro diagrama o a una interacción documentada por separado.

@startuml
actor Cliente
participante "Interfaz de Pago" como UI
participante "Servicio de Pago" como Pago
participante "Verificación de Fraude" como Fraude

Cliente -> UI: Pagar por el pedido
UI -> Pago: Autorizar pago
Pago -> Fraude: Evaluar transacción

nota derecha de Fraude
  Las reglas de riesgo se mantienen
  fuera de esta interacción.
end note

Fraude --> Pago: Resultado de riesgo
Pago -> UI: Resultado de autorización
UI -> Cliente: Mostrar resultado
@enduml

Las notas deben añadir contexto en lugar de repetir las etiquetas de los mensajes. Si el diagrama se vuelve abigarrado, divídelo en escenarios enfocados y utiliza referencias o enlaces de documentación para conectarlos.

7. Creación y refinamiento de diagramas en VPasCode

VPasCode admite la edición de PlantUML con renderizado en vivo, así como generación de diagramas asistida por IA, modificación de código y corrección de sintaxis. Su interfaz exacta y la disponibilidad de funciones pueden cambiar, pero el flujo de trabajo general es:

1. Abre VPasCode y elige o introduce PlantUML.

2. Describe la interacción o pega un borrador de PlantUML en el editor.

3. Revisa la vista previa renderizada mientras refinas el código fuente.

4. Pide a la IA que realice un cambio específico, como «añadir una ruta para credenciales inválidas usando alt.”

5. Revisa el código y el diagrama resultantes tanto por sintaxis como por corrección del sistema.

6. Exporta o comparte el diagrama final utilizando las opciones disponibles en el editor.

Un prompt útil proporciona a la IA el tipo de diagrama, los actores, los límites del sistema, la ruta principal de éxito, las rutas alternativas importantes y el nivel de detalle. Por ejemplo:

Crea un diagrama de secuencia PlantUML para un cliente que inicia sesión en una aplicación web. Incluye Navegador, API de Inicio de Sesión, Proveedor de Identidad y Base de Datos de Usuarios. Muestra la ruta de inicio de sesión exitoso y una alternativa para contraseña inválida. Usa etiquetas concisas y no inventes servicios más allá de estos.

Trata el código generado como un borrador. Verifica que los participantes, flechas, condiciones y rutas de error reflejen el sistema real, no solo un flujo que parezca plausible.

8. Un ejemplo más completo: pago con fallo de pago

Este ejemplo combina alias de participantes, activaciones y una ruta alternativa.

@startuml
título: Verificación de compra y autorización de pago

actor Cliente
boundary "Interfaz de verificación de compra" como UI
control "Servicio de pedidos" como Pedidos
participant "Pasarela de pago" como Pago
database "Base de datos de pedidos" como DB

Cliente -> UI: Enviar verificación de compra
UI -> Pedidos: Crear pedido pendiente
activate Pedidos

Pedidos -> DB: Guardar pedido pendiente
DB --> Pedidos: ID de pedido

Pedidos -> Pago: Autorizar pago
activate Pago

alt [pago aprobado]
  Pago --> Pedidos: Código de autorización
  deactivate Pago

  Pedidos -> DB: Marcar pedido confirmado
  DB --> Pedidos: Actualizado
  Pedidos --> UI: Pedido confirmado
  UI --> Cliente: Mostrar confirmación
else [pago rechazado]
  Pago --> Pedidos: Motivo del rechazo
  deactivate Pago

  Pedidos -> DB: Marcar pedido fallido
  DB --> Pedidos: Actualizado
  Pedidos --> UI: Pago rechazado
  UI --> Cliente: Mostrar opción de reintento
end

deactivate Pedidos
@enduml

Verifique que el orden del diagrama coincida con el comportamiento real. Por ejemplo, si el sistema persiste el pedido solo después de que la autorización tenga éxito, mueva los mensajes de la base de datos para que coincidan con ese diseño.

9. Directrices prácticas de modelado

• Mantenga el diagrama enfocado.Muestre un escenario o un conjunto de caminos estrechamente relacionados. Separe los detalles profundos que distraigan de la interacción principal.

• Nombre a los participantes según su responsabilidad. Prefiera etiquetas como “Servicio de pedidos” o “Pasarela de pago” en lugar de etiquetas vagas como “Sistema.

• “Muestre límites significativos.Distinga entre el usuario, el cliente, los servicios internos, las bases de datos y los sistemas externos cuando esto ayude a los lectores a comprender la responsabilidad.

• Use etiquetas de mensajes claras. Incluya una operación, evento o resultado importante; evite etiquetas que simplemente digan “proceso”.

• Modele las rutas de fallo que importan. Incluya tiempos de espera relevantes, rechazos, reintentos o fallos de validación cuando afecten al escenario.

• Use fragmentos con precisión. alt significa rutas alternativas, opt significa comportamiento opcional, loop significa repetición, y par significa comportamiento paralelo.

• Evite el ruido de implementación. No diagramue cada getter, método interno o detalle de bajo nivel a menos que la audiencia lo necesite.

• Mantenga el código fuente mantenible. Use alias para nombres largos, nomenclatura consistente y comentarios o notas breves para suposiciones importantes.

10. Errores comunes y lista de verificación de revisión

Si el diagrama no se renderiza, verifique que @startuml y @enduml están presentes, los bloques de fragmento tienen coincidencias de fin declaraciones, los alias se utilizan de manera consistente y todos los puntos de destino de los mensajes se refieren a participantes definidos. También verifique si hay sintaxis de otro lenguaje de diagramación pegada accidentalmente en el código fuente de PlantUML.

Antes de compartir, revise dos cosas:

• Sintaxis: ¿Se renderiza correctamente? ¿Están cerrados los fragmentos? ¿Son consistentes los participantes y los alias?

• Significado: ¿Son correctos los participantes y las direcciones de los mensajes? ¿Se incluyen las rutas de error importantes? ¿Están representados con precisión los sistemas externos y los almacenes de datos?

El flujo de trabajo más sólido de diagramación como código combina código fuente legible, retroalimentación visual rápida y revisión del dominio. PlantUML proporciona control explícito sobre la notación de interacción, mientras que VPasCode puede acelerar el borrador y la iteración; la autoridad final sobre la precisión del diagrama sigue siendo el comportamiento del sistema que se pretende describir.