Diagrama de secuencia
Muestra cómo dialogan sistemas y personas
¿Qué es un Diagrama de secuencia?
Un diagrama de secuencia muestra los mensajes intercambiados entre participantes a lo largo del tiempo: llamadas a la API, flujos de autenticación, comunicación entre microservicios. Es el estándar para documentar interacciones en arquitectura de software.
Los diagramas de secuencia se ganan su sitio en las revisiones de diseño y en los informes de incidentes, donde la pregunta siempre es la misma: quién llamó a quién, en qué orden y qué respondió. Nada revela más rápido un error de ordenación o un timeout que falta. Lo que no muestran es el estado: una línea de vida dice que un participante está ocupado, nunca en cuál de sus estados internos se encuentra ni qué recuerda entre dos ejecuciones.
Ejemplo en directo
sequenceDiagram
autonumber
participant U as User
participant A as API
participant D as Database
U->>A: POST /login
A->>D: SELECT user
D-->>A: user row
A-->>U: 200 + JWT token
U->>A: GET /profile (Bearer)
A-->>U: 200 profileCuándo usarlo
Errores frecuentes
Activaciones que quedan abiertas
Cada + necesita su - correspondiente, y cada activate su deactivate. Un par descompensado dibuja una barra que llega hasta el final del diagrama o falla con «Trying to inactivate an inactive participant».
El orden lo fija la declaración
Mermaid coloca a los participantes según el orden en que los encuentra, así que uno citado solo en una rama de error acaba al extremo derecho. Declara cada participant al principio, en el orden en que los quieras ver.
Una flecha simple no es una llamada
A->B dibuja una línea continua sin punta, que se lee como si no hubiera pasado nada. Las llamadas síncronas son ->>, las respuestas -->> y los mensajes sin retorno -). Mira la punta, no solo los guiones.
Sintaxis básica
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Sync request
B-->>A: Async responsesequenceDiagram autonumberautonumber antepone un número a cada mensaje, de modo que en una revisión se puede hablar del «paso 4» en lugar de describir a qué flecha te refieres.
U->>+API: POST /orders API-->>-U: 201 CreatedUn + en una flecha abre una barra de activación en el receptor y un - la cierra, mostrando cuánto tiempo permanece ocupado cada participante atendiendo la llamada.
note over API,DB: single transactionLas notas recogen el detalle que las flechas no pueden: límites de transacción, política de reintentos, timeouts. Usa note left of o note right of para fijar una a un solo participante.
box Payment domain participant PSP endUn box dibuja un marco con título alrededor de los participantes de un mismo sistema o equipo. Pon un nombre de color antes del título para teñir el marco.
Preguntas sobre este diagrama
¿Qué significan los tipos de flecha en un diagrama de secuencia Mermaid?
Las flechas continuas (->>) son llamadas síncronas; las flechas discontinuas (-->>) son respuestas o mensajes asíncronos. Las activaciones muestran cuándo un participante está ocupado procesando.
¿Puedo representar bucles y condiciones?
Sí — Mermaid admite los bloques loop, alt (if/else), opt (opcional) y par (paralelo) para expresar la lógica de protocolos reales.
¿Puedo poner un diagrama de secuencia en la descripción de un pull request de GitHub?
Sí: pega el código en un bloque delimitado con la etiqueta mermaid y GitHub lo renderiza dentro de pull requests, issues y comentarios. A diferencia de una captura, el diagrama aparece luego como texto en el diff.
¿Puede un diagrama de secuencia Mermaid mostrar el tiempo transcurrido o la latencia?
No. El eje vertical solo indica orden — no hay escala temporal, así que dos flechas separadas por un milisegundo se ven igual que dos separadas por una hora. Pon la cifra en una nota, o usa un diagrama de Gantt cuando lo importante sea la duración.
¿Cómo represento un participante que solo existe durante parte del flujo?
Decláralo donde aparece con create participant Worker y termínalo con destroy Worker. La línea de vida arranca entonces en el mensaje que lo crea y acaba en una cruz, que es como se dibuja un job, una sesión o un proceso temporal.
¿Cómo resalto un grupo de mensajes?
Envuélvelos en rect rgb(240,240,255) … end para sombrear el fondo, algo útil para marcar un bloque de reintentos o una transacción. Los bloques rect se anidan, así que un reintento dentro de una transacción se sigue leyendo. Los bloques loop, alt y opt dibujan su propio marco con título.
¿Diagrama de secuencia u otro tipo de diagrama?
¿Diagrama de secuencia o diagrama de flujo?
Cuenta los sistemas. Un proceso que ocurre dentro de un solo componente es un diagrama de flujo; dos o más participantes intercambiando mensajes son un diagrama de secuencia. Si te sorprendes escribiendo «el servicio B recibe…» dentro de una caja, cambia: las líneas de vida hacen ese trabajo.
¿Diagrama de secuencia o diagrama de estados?
Ambos describen el comportamiento en el tiempo. El de secuencia sigue una ejecución concreta y muestra el tráfico entre participantes; el de estados cubre todas las ejecuciones de un participante y muestra qué recuerda. Depura con el primero, especifica con el segundo.
Crea tu Diagrama de secuencia ahora
Descríbelo en lenguaje natural — la IA escribe el código Mermaid por ti.
Abrir Mermaid Studio