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

¿Qué es un diagrama de flujo?

Un Diagrama de flujoes un mapa de comportamiento fundamental que visualiza un flujo de trabajo operativo paso a paso, un procedimiento algorítmico o una lógica empresarial secuencial. Al representar las acciones del sistema como formas geométricas distintas y trazar el flujo de control con flechas direccionales, un diagrama de flujo facilita a los ingenieros de software y arquitectos de sistemas rastrear caminos de ejecución condicional, aislar bloques de punto único de falla y analizar bucles lógicos del sistema antes de escribir código de backend real.

Con Mermaid.js, no tienes que pasar horas arrastrando cuadros, gestionando minuciosamente líneas de cuadrícula o recalculando variables de relleno. El motor de diseño calcula dinámicamente las coordenadas de los nodos a partir de tus scripts declarativos sin procesar, permitiéndote centrarte completamente en la lógica subyacente de tu sistema.

Guía de sintaxis principal: Elementos y construcciones

Para diseñar un diagrama de flujo elegante y altamente legible en Mermaid, debes dominar los indicadores de dirección de la cuadrícula, los contenedores geométricos de nodos, las variables de conexión de enlaces y los subgrafos estructurales.

1. Establecer direcciones de la cuadrícula

La orientación de tu diagrama de flujo se determina directamente en la primera línea mediante el par de palabras clave aplicado al graph o flowchartenvolvente. Puedes controlar la dirección de escalado visual de tu diseño utilizando cuatro claves principales de orientación:

• flowchart TD (De arriba hacia abajo / orientación vertical)
• flowchart BU (De abajo hacia arriba)
• flowchart LR (De izquierda a derecha / orientación horizontal)
• flowchart RL (De derecha a izquierda)

2. Personalizar la geometría del nodo (formas)

Por defecto, una declaración de ID simple se representa como un cuadro rectangular afilado. Para que tus diagramas sean más fáciles de escanear, utiliza los corchetes especiales de Mermaid para inyectar contexto visual inmediato en diferentes pasos del flujo de trabajo. Cada bloque de definición debe ir precedido por un token de diseño direccional para que se analice correctamente:

• Bordes redondeados: id(Texto) — Representa un paso general del proceso.
• Forma de estadio/cápsula: id([Texto]) — Marcador estándar para los hitos de límite de inicio y finalización.
• Subrutina/Proceso predefinido: id[[Texto]] — Representa una rutina de sistema encapsulada o un script de clase externo.
• Cilindro/Bases de datos: id[(Texto)] — Representa la persistencia de bases de datos, cachés o almacenes de datos.
• Rombo/Piedra de decisión: id{Texto} — Representa conmutadores condicionales, bifurcaciones if/else o puntos de evaluación.
• Paralelogramo: id[/Texto/] o id[Texto] — Representa límites inclinados para representar entradas/salidas de datos explícitas (E/S).

diagrama de flujo TD
    start_node([Iniciar ejecución])
    query_db[(Instancia de PostgreSQL)]
    validate_check{¿Está autorizado?}

3. Reglas de conexión y etiquetas incrustadas

Puedes ajustar tus líneas de conexión para representar diferentes relaciones estructurales y estilos de comunicación. Para mantener tus diagramas limpios, inserta etiquetas descriptivas directamente en tus rutas de enlace:

diagrama de flujo TD
    %% Flecha de conector estándar con etiqueta de texto
    A --> |"Carga útil JSON"| B

    %% Línea punteada/asincrónica con etiqueta de texto
    B -.-> |"Evento asíncrono"| C

    %% Línea gruesa y en negrita con etiqueta de texto
    C ==> |"Escritura crítica"| D

4. Aislamiento modular mediante subgrafos

Para establecer perímetros de red limpios, agrupar microservicios o aislar responsabilidades del equipo, agrupa tus elementos dentro de estructurassubgrafo envolventes. Definir un subgrafo consiste en asignarle un ID interno, un título opcional de visualización y cerrarlo con unfin etiqueta:

diagrama de flujo TD
    subgrafo auth_sub["Límite de seguridad"]
        gateway[Portal de API] --> auth_worker(Validador de token)
    fin

Mejores prácticas para diagramas de flujo limpios

• Desacoplar los diseños horizontalmente: Para tuberías de ingeniería largas y de múltiples pasos, elija una diagrama de flujo LR dirección. Esto escala mucho más limpiamente en monitores estándar de pantalla ancha en modo retrato que un diseño vertical largo.
• Aislar bucles complejos: Si un flujo de trabajo contiene un bucle de repetición intensa, etiquete claramente el conector inverso (por ejemplo, reintentar --> |"Intentar reinicio"| inicio) para evitar que los lectores confundan el bucle con una ruta estándar hacia adelante.
• Evitar mezclar tipos de gráficos: Adhiera al uso del diagrama de flujo palabra clave en lugar del antiguo grafo indicador al renderizar mapas complejos. El diagrama de flujo motor utiliza un algoritmo de diseño actualizado que admite combinaciones avanzadas de flechas y una ruta de trayecto más limpia.

Ejemplos reales de diagramas de flujo de Mermaid.js

Ejemplo 1: Malla de ingesta impulsada por eventos de microservicio (arquitectura de izquierda a derecha)

Este plano funcional modela un servicio de ingesta de telemetría web. Muestra cómo combinar entradas de datos, diamantes de decisión y formas de base de datos en la nube sobre una superficie horizontal clara.

diagrama de flujo LR
    %% Definir nodos de elementos con formas geométricas explícitas
    init([Disparado Webhook]) --> input_io[/Capturar solicitud HTTP/]
    input_io --> auth_check{Validar token}
    
    auth_check --> |"Token inválido"| err_stop([Devolver 401 No autorizado])
    auth_check --> |"JWT válido"| write_queue[[Publicar en cola Kafka]]
    
    write_queue --> worker_proc(Daemon consumidor)
    worker_proc --> db_store[(Cluster TimescaleDB)]
    db_store --> term([Flujo finalizado])

    %% Sobrescrituras de estilo personalizadas rápidas
    estilo auth_check relleno:#fff3cd, borde:#ffc107, ancho-borde:2px
    estilo err_stop relleno:#f8d7da, borde:#dc3545, ancho-borde:1px

Desglose sintáctico: Este diagrama fluye suavemente de izquierda a derecha. La etapa de validación utiliza una forma de diamante de decisión amarillo (auth_check{Validar Token}), lo que divide claramente la ruta de ejecución en dos resultados distintos. Los almacenes de datos son inmediatamente reconocibles gracias a sus cilindros de base de datos personalizados ([(Cluster de TimescaleDB)]) y entradas en forma de paralelogramo.

Ejemplo 2: Motor de registro de usuarios multi-nivel empresarial (vertical con subgráficos anidados)

Este avanzado plano empresarial describe una canalización de registro de aplicaciones. Organiza los pasos verticalmente a través de tres subgráficos estructurales separados para representar capas arquitectónicas distintas.

flowchart TD
    subgraph Client_Tier["Capa de interfaz de presentación"]
        app[Interfaz de usuario de aplicación móvil]
        web[Frontend SPA web]
    end

    subgraph Service_Tier["Router principal de puerta de enlace"]
        proxy[[Proxy inverso Nginx de entrada]]
        auth_svc(Trabajador del servicio de autenticación)
    end

    subgraph Persistence_Tier["Centro de datos seguro"]
        main_db[(Base de datos principal de cuentas de usuario)]
        cache_node[(Caché de sesión Redis)]
    end

    %% Define los flujos de comunicación entre las capas de subsistemas
    app -- "Solicitud HTTPS" --> proxy
    web -- "Solicitud HTTPS" --> proxy
    
    proxy --> |"Ruta /v1/auth"| auth_svc
    
    auth_svc --> |"Verificar sesión"| cache_node
    auth_svc --> |"Confirmar cuenta"| main_db

Desglose sintáctico: El indicador de orientación de arriba hacia abajo (flowchart TD) obliga al motor de diseño a apilar los componentes limpiamente de arriba hacia abajo. Los bloques delimitadores agrupan componentes relacionados en capas distintas (cliente, servicio y persistencia), otorgando a la arquitectura general una sensación intuitiva y altamente estructurada.