System Design
Diagramas de secuencia
Explica cómo modelar el orden temporal de mensajes, responsabilidades, contratos, alternativas y fallos entre participantes mediante diagramas de secuencia.
- Última actualización
- Actualizada
- Nivel
- Aplicación
System Design
Explica cómo modelar el orden temporal de mensajes, responsabilidades, contratos, alternativas y fallos entre participantes mediante diagramas de secuencia.
Un diagrama de secuencia muestra cómo participantes concretos colaboran mediante mensajes ordenados para ejecutar un escenario. Su propósito es exponer responsabilidades, dependencias temporales y fallos; no copiar el código línea por línea.
Sequence Diagram responde:
¿quién participa?
¿quién llama a quién?
¿en qué orden?
¿qué espera una respuesta?
¿qué ocurre en alternativas, loops o paralelismo?El eje vertical representa tiempo aproximado de arriba hacia abajo. Las lifelines representan participantes, no necesariamente clases.
Una arquitectura con Frontend → API → DB → Broker parece simple hasta que se pregunta:
El diagrama hace visibles esas decisiones.
Actor representa alguien externo que inicia o participa. Participant puede ser sistema, componente, servicio, base o dependencia.
Muestra existencia del participante durante el escenario.
El emisor espera respuesta; forma parte de la ruta crítica.
El emisor entrega intención o hecho y continúa. No implica que el procesamiento sea instantáneo ni garantizado.
Aclara resultado cuando aporta; no hace falta dibujar cada retorno trivial.
Indica periodo conceptual de ejecución o control.
alt: alternativas mutuamente exclusivas.opt: comportamiento condicional.loop: repetición.par: ramas concurrentes.break: interrupción del escenario.critical: región que requiere exclusión, según notación/herramienta.sequenceDiagram
autonumber
actor Customer as Cliente
participant Web as Frontend
participant API as Order API
participant DB as PostgreSQL
participant Publisher as Outbox Publisher
participant Broker as Broker
Customer->>Web: Confirmar pedido
Web->>API: POST /orders + idempotency key
activate API
API->>DB: BEGIN
API->>DB: Reservar stock y crear pedido
API->>DB: Insertar evento en outbox
API->>DB: COMMIT
DB-->>API: Confirmado
API-->>Web: 201 Created
deactivate API
Publisher->>DB: Leer eventos pendientes
Publisher-)Broker: Publicar OrderCreated
Publisher->>DB: Marcar publicado
Web-->>Customer: Pedido confirmadoEl diagrama no demuestra por sí solo todas las garantías; la explicación completa la semántica.
sequenceDiagram
actor User as Cliente
participant API
participant Payment
User->>API: Confirmar pedido
API->>Payment: Cobrar(idempotencyKey)
alt Pago aprobado
Payment-->>API: approved + paymentId
API-->>User: Pedido confirmado
else Pago rechazado
Payment-->>API: rejected
API-->>User: Elegir otro medio
else Timeout / resultado incierto
Payment--xAPI: sin respuesta
API-->>User: Pago en verificación
endLa tercera rama es distinta de rechazo. Un timeout no prueba que no hubo cobro.
Participantes por responsabilidad: Pedidos, Inventario, Pagos.
Instancias o componentes: Next.js, Order API, PostgreSQL, provider.
No mezcles Cliente, OrderAggregate, Kubernetes Pod y PostgreSQL sin una audiencia clara. Puedes crear dos vistas enlazadas.
Nombra mensajes con intención:
ReserveInventory(product, quantity, orderId)
InventoryReserved(reservationId, expiresAt)Un mensaje debe revelar contrato relevante sin listar todos los campos. Los detalles completos pertenecen al diseño de API o evento.
Una flecha síncrona añade latencia y fallo de la dependencia al flujo. Una asíncrona requiere:
El diagrama debe mostrar quién conserva el estado entre ambos momentos.
Utiliza alt cuando solo una condición puede suceder. Usa opt para un bloque adicional que no reemplaza el camino. En loop, indica guard y límite:
loop [error transitorio y attempts < 3]Un loop sin política de salida oculta retry infinito.
par comunica ramas que pueden ejecutarse simultáneamente. Pregunta:
No uses par solo para reducir altura del dibujo.
Representa timeout cuando cambia el estado o la recuperación. Una llamada cancelada por el cliente puede seguir ejecutándose en servidor; el diagrama debe diferenciar cancelación de espera y cancelación real de operación.
Una activation larga no equivale a transacción de base. Si la consistencia importa, muestra BEGIN/COMMIT o una nota de unidad atómica.
No dibujes una transacción distribuida implícita entre servicios si no existe.
Incluye:
Un webhook es otra solicitud, no continuación mágica de la conexión original.
Valida estado y versión antes de aplicar.
Consumidor deduplica o hace efecto idempotente.
Outbox o reconciliación evita perder evento.
Define qué se devuelve y qué queda pendiente.
El estado necesario debe persistir fuera de memoria.
Backoff, jitter y límites evitan amplificar incidente.
Muchos consumidores no deberían entrar todos en un diagrama de flujo principal; separa vistas.
Envejece rápido y no comunica decisiones.
Hace parecer atómica una interacción distribuida.
Distorsiona asincronía.
Confunde ownership y despliegue.
procesar() no explica intención.
Divide por escenario o responsabilidad.
Una línea entre servicios no explica timeout, datos ni garantía.
alt para resultados relevantes.Es valioso para integraciones, transacciones, APIs, eventos y concurrencia. No hace falta para cada método o CRUD sencillo.
alt y opt?Estados y ciclos de vida define qué situaciones persisten y qué transiciones son válidas antes de dibujar su máquina de estados.