Capítulo 3: Diagramas de Secuencia, Participantes y Bloques de Control

En los capítulos anteriores abordamos los diagramas de flujo y su personalización. En esta tercera entrega nos enfocaremos en los diagramas de secuencia (sequenceDiagram), una herramienta fundamental para representar interacciones cronológicas entre sistemas, procesos o actores a lo largo del tiempo.

---

1. Definición de Participantes y Actores

Por defecto, Mermaid crea los participantes en el orden en que aparecen en las conexiones. Sin embargo, declararlos explícitamente al inicio permite ordenar la secuencia y personalizar su apariencia.

Tipos de elementos: participant vs actor

• participant: Se representa como un bloque rectangular estándar.
• actor: Se representa con el icono de una figura humana (ideal para usuarios o roles externos).

sequenceDiagram
    actor Usuario
    participant Front as Frontend (React)
    participant API as API Gateway
    participant DB as Base de Datos

    Usuario ->> Front: Hace clic en "Comprar"
    Front ->> API: POST /orders
    API ->> DB: INSERT INTO orders

sequenceDiagram
    actor Usuario
    participant Front as Frontend (React)
    participant API as API Gateway
    participant DB as Base de Datos

    Usuario ->> Front: Hace clic en "Comprar"
    Front ->> API: POST /orders
    API ->> DB: INSERT INTO orders

Alias de participantes: Puedes definir un nombre extenso y asignarle una etiqueta corta con la palabra clave as (por ejemplo: participant Front as Frontend (React)).

---

2. Tipos de Mensajes y Conectores

El tipo de flecha utilizado entre los participantes define la naturaleza de la comunicación (sincrónica, asincrónica, respuestas o señales).

Sintaxis	Estilo de línea	Tipo de cabezal	Significado habitual
->	Sólida	Sin flecha	Mensaje simple / Notificación
-->	Punteada	Sin flecha	Respuesta simple
->>	Sólida	Con flecha	Mensaje sincrónico (espera respuesta)
-->>	Punteada	Con flecha	Respuesta sincrónica
-x	Sólida	Con cruz al final	Mensaje asincrónico
--x	Punteada	Con cruz al final	Respuesta asincrónica
-)	Sólida	Abierta	Mensaje asincrónico sin bloqueo
--)	Punteada	Abierta	Respuesta asincrónica sin bloqueo

Activación y desactivación de participantes

Para indicar que un servicio está procesando información (mostrando una barra vertical sobre su línea de tiempo), utiliza activate y deactivate, o bien los sufijos + y - en los mensajes:

sequenceDiagram
    autonumber
    actor U as Usuario
    participant S as Servidor

    U ->>+ S: Petición de datos (HTTP GET)
    Note over S: Procesando consulta SQL
    S -->>- U: Respuesta 200 OK (JSON)

sequenceDiagram
    autonumber
    actor U as Usuario
    participant S as Servidor

    U ->>+ S: Petición de datos (HTTP GET)
    Note over S: Procesando consulta SQL
    S -->>- U: Respuesta 200 OK (JSON)

Numeración automática: Agregar la directiva autonumber al inicio del diagrama asigna un número secuencial a cada mensaje enviado.

---

3. Bloques de Control y Flujos Lógicos

Los diagramas de secuencia permiten modelar decisiones, bucles y ejecuciones paralelas mediante bloques delimitados por la palabra clave end.

Condiciones: alt / else y opt

• alt / else: Representa un flujo condicional con múltiples caminos (equivalente a if / else).
• opt: Representa un paso opcional que solo se ejecuta si se cumple una condición (equivalente a if simple).

sequenceDiagram
    actor Cliente
    participant API as API Pago

    Cliente ->> API: Enviar credenciales
    
    alt Credenciales Válidas
        API -->> Cliente: Token JWT generado
    else Credenciales Inválidas
        API -->> Cliente: Error 401 Unauthorized
    end

    opt Requiere Verificación de Dos Factores (2FA)
        API ->> Cliente: Enviar código SMS
    end

sequenceDiagram
    actor Cliente
    participant API as API Pago

    Cliente ->> API: Enviar credenciales
    
    alt Credenciales Válidas
        API -->> Cliente: Token JWT generado
    else Credenciales Inválidas
        API -->> Cliente: Error 401 Unauthorized
    end

    opt Requiere Verificación de Dos Factores (2FA)
        API ->> Cliente: Enviar código SMS
    end

Bucles: loop

Permite definir iteraciones que se repiten mientras se cumpla una condición:

sequenceDiagram
    participant Worker as Proceso Worker
    participant Queue as Cola de Mensajes

    loop Cada 5 segundos
        Worker ->> Queue: Consultar nuevos trabajos
        Queue -->> Worker: Retornar lista de tareas
    end

sequenceDiagram
    participant Worker as Proceso Worker
    participant Queue as Cola de Mensajes

    loop Cada 5 segundos
        Worker ->> Queue: Consultar nuevos trabajos
        Queue -->> Worker: Retornar lista de tareas
    end

Ejecución Paralela: par / and

Representa acciones que ocurren de manera concurrente:

sequenceDiagram
    participant API as API Principal
    participant Log as Servicio Logs
    participant Mail as Servicio Email

    API ->> Log: Guardar registro de auditoría
    par Notificaciones simultáneas
        API ->> Mail: Enviar correo de confirmación
    and
        API ->> Log: Actualizar métricas
    end

sequenceDiagram
    participant API as API Principal
    participant Log as Servicio Logs
    participant Mail as Servicio Email

    API ->> Log: Guardar registro de auditoría
    par Notificaciones simultáneas
        API ->> Mail: Enviar correo de confirmación
    and
        API ->> Log: Actualizar métricas
    end

---

4. Ejemplo Complejo: Flujo de Autenticación OAuth2

A continuación, integramos todos los conceptos en un diagrama de secuencia avanzado:

sequenceDiagram
    autonumber
    actor Usuario
    participant App as Cliente Web
    participant Auth as Servidor OAuth
    participant API as API de Recursos

    Usuario ->> App: Clic en "Iniciar sesión con Google"
    App ->> Auth: Redirección a /authorize
    
    activate Auth
    Auth -->> Usuario: Muestra formulario de login
    Usuario ->> Auth: Ingresa usuario y contraseña
    
    alt Autenticación Exitosa
        Auth -->> App: Redirección con Authorization Code
        deactivate Auth
        
        App ->>+ Auth: POST /token (Code + Client Secret)
        Auth -->>- App: Retorna Access Token & Refresh Token
        
        par Obtención de datos e historial
            App ->>+ API: GET /user/profile (Bearer Token)
            API -->>- App: Datos del perfil
        and
            App ->>+ API: GET /user/activity (Bearer Token)
            API -->>- App: Registro de actividad
        end
        
    else Autenticación Fallida
        Auth -->> Usuario: Muestra mensaje de error
    end

sequenceDiagram
    autonumber
    actor Usuario
    participant App as Cliente Web
    participant Auth as Servidor OAuth
    participant API as API de Recursos

    Usuario ->> App: Clic en "Iniciar sesión con Google"
    App ->> Auth: Redirección a /authorize
    
    activate Auth
    Auth -->> Usuario: Muestra formulario de login
    Usuario ->> Auth: Ingresa usuario y contraseña
    
    alt Autenticación Exitosa
        Auth -->> App: Redirección con Authorization Code
        deactivate Auth
        
        App ->>+ Auth: POST /token (Code + Client Secret)
        Auth -->>- App: Retorna Access Token & Refresh Token
        
        par Obtención de datos e historial
            App ->>+ API: GET /user/profile (Bearer Token)
            API -->>- App: Datos del perfil
        and
            App ->>+ API: GET /user/activity (Bearer Token)
            API -->>- App: Registro de actividad
        end
        
    else Autenticación Fallida
        Auth -->> Usuario: Muestra mensaje de error
    end

Compilación desde Debian

Para compilar este diagrama a un formato de alta resolución desde la terminal:

mmdc -i secuencia_oauth.mmd -o secuencia_oauth.png -w 1200 -s 2

La opción -w 1200 establece el ancho en píxeles y -s 2 aplica un factor de escala (scale) para mejorar la nitidez del texto.

---

Resumen del Capítulo

1. Participantes: Organiza la estructura utilizando actor y participant, asignando alias cortos con as.
2. Conectores: Utiliza ->> para peticiones sincrónicas, -->> para respuestas y +/- para gestionar la barra de activación.
3. Estructuras complejas: Modela la lógica del sistema mediante bloques alt/else, opt, loop y par.

Etiquetas

• Manuales