Guía de sintaxis de diagramas de secuencia de Mermaid.js

¿Qué es un diagrama de secuencia?

Un diagrama de secuencia es un diagrama comportamental esencial diagrama UML diseñado para visualizar el flujo cronológico de mensajes, llamadas a funciones y cargas útiles de datos entre diferentes entidades del sistema a lo largo de una línea temporal lineal. Reconocido como un tipo fundamental de tipo de diagrama UML, representa las interacciones en tiempo de ejecución al apilar los componentes del sistema a lo largo del eje X como líneas de vida verticales y rastrear los intercambios de mensajes a lo largo del eje Y. Este plano es invaluable para los desarrolladores que depuran intercambios de API distribuidas, rutas de orquestación de microservicios o flujos de autenticación de usuarios en tiempo real.

Con Mermaid.js, puedes crear procesos temporales complejos utilizando una estructura de texto intuitiva. El motor maneja automáticamente el espaciado vertical, gestiona la alineación de las flechas de mensaje y dibuja bloques de activación en tiempo de ejecución de forma limpia en tu lienzo.

Guía de sintaxis principal: elementos y construcciones

Para diseñar un diagrama de secuencia UML preciso y altamente legible en Mermaid, debes dominar las declaraciones de participantes, las variantes de flechas de mensaje, las líneas de vida explícitas y las estructuras de bloques condicionales.

1. Declaración de participantes y actores

Declaras una entidad estándar del sistema utilizando la participantepalabra clave. Si la entidad representa un usuario final humano o un operador externo, utiliza la actorpalabra clave para representar un icono estándar de figura de palo en el lienzo:

diagramaSecuencia
    actor Cliente
    participante API como Router de Puerta de Enlace

Consejo profesional: Usa la comopalabra clave para asignar nombres largos de componentes a alias internos compactos, manteniendo tus scripts de mensajes concisos y legibles.

2. Formato de flechas de mensaje

El tipo de línea y punta de flecha que uses determina el estilo de comunicación entre los participantes de tu sistema:

• ->> **Llamada síncrona:** Una línea continua con una punta de flecha llena. Representa una solicitud bloqueante que espera la finalización de una ejecución.
• --> **Línea de respuesta:** Una línea punteada con una punta de flecha abierta. Se utiliza para devolver cargas útiles de datos o tokens de reconocimiento.
• -> **Llamada asíncrona:** Una línea continua con una punta de flecha abierta. Indica un mensaje no bloqueante o una transmisión de eventos.

sequenceDiagram
    App->>Server: Carga útil de solicitud
    Server-->App: Respuesta 200 OK

3. Gestión de las barras de activación de la línea de vida

Para mostrar exactamente cuándo un componente del sistema está ejecutando activamente una tarea o ocupando memoria de hilo, utiliza los comandosactivate y deactivate comandos. Alternativamente, puedes añadir un signo más (+) o un signo menos (-) directamente a tus destinos de mensaje como un atajo visual rápido:

sequenceDiagram
    Client->>+Server: Procesar datos
    %% El servidor ahora está visualmente activo
    Server-->-Client: Devolver resultados

4. Estructuración de condicionales y alternativas (Alt, Opt, Loop)

Para manejar lógica de tiempo de ejecución con ramificaciones, evaluaciones de tokens o reintentos repetidos de solicitudes, envuelve tus scripts de mensaje dentro de fragmentos de bloque estándar:

• alt / else — Evalúa caminos condicionales (similar a los bloques de código if/else).
• opt — Define un paso opcional que solo se ejecuta bajo criterios específicos.
• bucle — Repite una secuencia de ejecución hasta que se cumpla una condición.

diagramaSecuencia
    bucle Cada 30 segundos
        Cliente->>Servidor: Ping de latido
    fin

Mejores prácticas para líneas de tiempo de secuencia limpias

• Mantén las líneas de vida despejadas:Evita listar decenas de microentidades a lo largo del eje X. Si un proceso interactúa con clases auxiliares menores, abstractas detrás de un límite de sistema de alto nivel como[Trabajador de autenticación] o [Grupo de caché].
• Etiqueta los códigos de estado explícitamente: Al escribir devoluciones de respuesta (-->), no escribas simplemente “Devolver datos”. Etiqueta la ruta con códigos HTTP explícitos o tipos de eventos (por ejemplo, "201 Creado (Token JWT)") para dar a los ingenieros un contexto preciso.
• Implementa notas para cálculos complejos: Usa la instrucción Nota sobre, Nota a la izquierda de, o Nota a la derecha de para documentar operaciones no visuales, como pasos internos de cifrado o hashing de datos de base de datos.

Ejemplos reales de diagramas de secuencia de Mermaid.js

Ejemplo 1: Flujo de intercambio de token seguro OAuth2 (bloques de activación y alternativos)

Este plano funcional modela una secuencia de inicio de sesión de usuario segura. Muestra cómo combinar actores humanos, líneas de vida de sistema explícitas y rutas de validación complejas utilizando un bloque alt/else.

sequenceDiagram
    actor Usuario como Usuario Final
    participante App como Cliente de Aplicación Móvil
    participante Auth como Proveedor de Identidad Auth0

    Usuario->>+App: Haga clic en "Iniciar sesión con OAuth"
    App->>+Auth: Redirigir con client_id y scope
    Auth-->>Usuario: Mostrar Interfaz de Inicio de Sesión
    Usuario->>Auth: Enviar Credenciales
    
    Auth->>Auth: Validar Hash de Contraseña
    
    alt Las Credenciales Son Válidas
        Auth-->>App: Redirección 302 con Código de Autenticación
        App->>Auth: Intercambiar Código por Token de Acceso
        Auth-->>-App: Devolver Token JWT (IdToken)
        App-->>Usuario: Mostrar Inicio de Cuenta de Usuario
    else Credenciales Inválidas
        Auth-->>App: Devolver Error 401 No Autorizado
        App-->>-Usuario: Mostrar Alerta "Nombre de usuario/contraseña inválidos"
    end

Desglose de Sintaxis: Esta cronología traza un intercambio entre múltiples partes. El alt / sino el contenedor muestra claramente las rutas de validación binarias, asegurando que los estados de error se documenten completamente junto con la ruta exitosa.

Ejemplo 2: Compra de inventario de pedido distribuido (Procesos paralelos y notas)

Este plano avanzado del sistema traza una canalización de compra empresarial de comercio electrónico. Utiliza bloques paralelos (par) para mostrar rutas de envío de API concurrentes y maneja notas de bloqueo de base de datos a través de la topología.

sequenceDiagram
    participante Web como Interfaz Web
    participante Ord como Orquestador de Pedidos
    participante Inv como Servicio de Inventario
    participante Pay como Pasarela de Pago

    Web->>+Ord: Enviar Solicitud de Compra
    Nota sobre Ord: Verificar Disponibilidad de Stock de Artículo
    
    par Enviar Llamadas de API Concurrentes
        Ord->>+Inv: Bloquear Artículos de Inventario
        Inv-->-Ord: Inventario Reservado (Stock Bloqueado)
    y
        Ord->>+Pay: Autorizar Cargo con Tarjeta de Crédito
        Pay-->-Ord: Captura Exitosa (Cargo Confirmado)
    fin
    
    opt El Proceso de Asignación Falla
        Nota a la derecha de Ord: Ejecutar saga de reversión si alguna llamada falla
    fin
    
    Ord-->-Web: Confirmación de Compra Exitosa 200

Desglose de Sintaxis: El par / y el contenedor instruye a la máquina a agrupar las ejecuciones paralelas juntas, documentando operaciones de fondo concurrentes. El Nota sobre y Nota a la derecha de las etiquetas inyectan explicaciones técnicas de tiempo de ejecución directamente en la cuadrícula de la pantalla, ayudando a los equipos a comprender transacciones en segundo plano como el bloqueo de datos y las sagas de reversión sin ensuciar las flechas principales del mensaje.