Como escrever um diagrama de sequência mermaid

O mínimo

Declare o tipo de diagrama e depois escreva uma linha por mensagem. Os participantes são criados na primeira menção, pela ordem em que aparecem.

sequenceDiagram
  User->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: order id
  API-->>User: 201 Created

💡Declare os participantes explicitamente com participant User quando quiser uma ordem específica da esquerda para a direita, em vez da ordem da primeira menção.

Tipos de seta

A convenção que vale a pena manter: sólida para a chamada, tracejada para o retorno. Um leitor consegue então distinguir um pedido de uma resposta sem ler um único texto.

Participantes e apelidos

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 OK

Use actor U as Browser em vez de participant para desenhar um boneco — vale a pena para a pessoa na extremidade esquerda de um fluxo de autenticação.

Barras de ativação

As barras de ativação mostram durante quanto tempo um participante está ocupado. Marque-as explicitamente com activate/deactivate, ou acrescente + e - às setas, o que é mais curto e mais difícil de desequilibrar.

sequenceDiagram
  User->>+API: POST /pay
  API->>+Bank: charge
  Bank-->>-API: authorised
  API-->>-User: receipt

Loops, condicionais e trabalho em 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
  end

• loop <label> … end — repetição.
• alt <label> … else <label> … end — ramos mutuamente exclusivos.
• opt <label> … end — um ramo que pode simplesmente não acontecer.
• par <label> … and <label> … end — coisas a acontecer ao mesmo tempo.
• critical / break — uma secção que não pode ser interrompida, e uma saída antecipada.

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 days

Note over A,B abrange dois participantes e é o lugar certo para uma restrição que pertence à interação, e não a um dos lados dela.

Um exemplo 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 in