Cómo escribir un diagrama de secuencia mermaid
Un diagrama de secuencia muestra quién habla con quién, y en qué orden. En mermaid se tarda casi lo mismo en escribirlo que en describirlo en voz alta, por eso es el tipo de diagrama que sobrevive más tiempo en una base de código. Todo lo de abajo está listo para copiar y pegar en el editor.
Lo mínimo
Declara el tipo de diagrama y luego escribe una línea por mensaje. Los participantes se crean en su primera mención, en el orden en que aparecen.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedDeclara los participantes explícitamente con participant User cuando quieras un orden de izquierda a derecha específico en lugar del orden de primera mención.
Tipos de flecha
| Sintaxis | Significado |
|---|---|
A->>B: text | Solicitud — línea sólida, punta de flecha rellena |
A-->>B: text | Respuesta — línea discontinua, punta de flecha rellena |
A->B: text | Línea sólida, punta de flecha abierta |
A-)B: text | Mensaje asíncrono — punta de flecha abierta, sin respuesta esperada |
A-xB: text | Mensaje que falla o se descarta |
La convención que vale la pena mantener: sólida para la llamada, discontinua para la respuesta. Así el lector puede distinguir una solicitud de una respuesta sin leer una sola etiqueta.
Participantes y alias
sequenceDiagram
participant U as Browser
participant A as API gateway
participant S as Order service
U->>A: GET /orders
A->>S: list(userId)
S-->>A: orders
A-->>U: 200 OKUsa actor U as Browser en lugar de participant para dibujar una figura de palo — vale la pena para la persona en el extremo izquierdo de un flujo de autenticación.
Barras de activación
Las barras de activación muestran cuánto tiempo está ocupado un participante. Márcalas explícitamente con activate/deactivate, o añade + y - a las flechas, que es más corto y más difícil de desbalancear.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptBucles, condicionales y trabajo en paralelo
sequenceDiagram
User->>API: POST /import
loop every row
API->>DB: upsert row
end
alt all rows valid
API-->>User: 200 OK
else some failed
API-->>User: 422 with errors
end
par notify
API->>Email: send summary
and audit
API->>Log: write entry
endloop <label>…end— repetición.alt <label>…else <label>…end— ramas mutuamente excluyentes.opt <label>…end— una rama que puede simplemente no ocurrir.par <label>…and <label>…end— cosas que ocurren al mismo tiempo.critical/break— una sección que no debe interrumpirse, y una salida anticipada.
Notas
sequenceDiagram
User->>API: POST /login
Note right of API: Rate limited<br>5 per minute
API-->>User: token
Note over User,API: Token is valid for 30 daysNote over A,B abarca dos participantes y es el lugar adecuado para una restricción que pertenece a la interacción en sí, más que a uno de los dos lados.
Un ejemplo completo
sequenceDiagram
actor U as User
participant A as App
participant P as Provider
U->>+A: Click "Sign in"
A-->>-U: Redirect to provider
U->>+P: Authorise
P-->>-U: Redirect back with code
U->>+A: GET /callback?code=…
A->>+P: Exchange code for token
P-->>-A: access token
Note right of A: Session cookie set here
A-->>-U: Signed inEdita este diagrama
Pégalo en la pestaña de código y cambia una línea — la vista previa se redibuja mientras escribes.
Preguntas frecuentes
¿Cómo numero los mensajes?
Pon autonumber en la línea justo después de sequenceDiagram. Cada mensaje recibe entonces un número secuencial, lo que hace que sea mucho más fácil hablar de un diagrama en los comentarios de revisión.
¿Puede un participante enviarse un mensaje a sí mismo?
Sí — escribe el mismo nombre en ambos lados: API->>API: retry. Mermaid dibuja el bucle de vuelta hacia la misma línea de vida.
¿Cómo muestro que un participante es destruido?
Usa destroy <name> antes del mensaje que lo termina, o create participant <name> para que aparezca a mitad del diagrama en lugar de al principio.
¿Puedo editar un diagrama de secuencia en el lienzo visual?
El lienzo visual edita flowcharts. Los diagramas de secuencia se escriben en la pestaña de código, donde se renderizan en vivo en la vista previa — lo cual suele ser más rápido de todos modos, ya que un diagrama de secuencia es esencialmente una lista de líneas.