Diagrammes de séquence : le dialogue dans le temps

À retenir — Un diagramme de séquence montre qui envoie quoi à qui, et dans quel ordre. Le temps s'écoule de haut en bas, chaque acteur a sa ligne de vie verticale, et chaque message est une flèche horizontale. C'est l'outil de référence pour documenter une API, un échange réseau ou une interaction entre composants.

Quand le flowchart ne suffit plus

Un flowchart répond à « quelles étapes ? ». Un diagramme de séquence répond à « qui parle à qui, et dans quel ordre ? ». Dès qu'il y a plusieurs acteurs qui s'échangent des messages dans le temps — un navigateur, un serveur, une base de données — c'est lui qu'il faut.

sequenceDiagram
    participant U as Utilisateur
    participant N as Navigateur
    participant S as Serveur
    U->>N: Clique sur « Se connecter »
    N->>S: POST /login
    S-->>N: 200 OK + cookie de session
    N-->>U: Affiche le tableau de bord

Lisez de haut en bas : c'est l'ordre chronologique. Chaque colonne est un acteur, chaque flèche un message. On comprend l'échange complet sans une ligne d'explication.

Déclarer les participants

La ligne de départ est sequenceDiagram. On déclare ensuite les acteurs avec participant, et l'alias as permet d'écrire court tout en affichant un nom lisible.

sequenceDiagram
    participant C as Client
    actor A as Admin
    participant API
    C->>API: Demande
    A->>API: Validation

• participant affiche un rectangle (un système, un service).
• actor affiche un bonhomme (un humain).
• Déclarer les participants dans l'ordre voulu fixe leur position de gauche à droite. Sans déclaration explicite, Mermaid les crée dans l'ordre d'apparition.

:::tip[Toujours déclarer l'ordre] Laisser Mermaid deviner l'ordre des participants donne souvent une mise en page avec des flèches qui se croisent. Déclarez vos participant en tête, dans l'ordre de lecture naturel, et le diagramme reste propre même en grandissant. :::

Les types de flèches : tout le vocabulaire

C'est ici que le diagramme de séquence est riche. La flèche encode la nature du message.

sequenceDiagram
    participant A
    participant B
    A->>B: Message synchrone (attend une réponse)
    B-->>A: Réponse
    A->>B: Message simple
    A-)B: Message asynchrone (n'attend pas)
    A--xB: Message perdu / échec

Le tableau de référence :

:::warning[La convention pleine/pointillée] Par convention, la flèche pleine (->>) part de celui qui demande, et la flèche pointillée (-->>) marque la réponse qui revient. Inverser les deux rend le diagramme techniquement valide mais trompeur à la lecture. Gardez : pleine à l'aller, pointillée au retour. :::

Activations : montrer « qui travaille »

Une activation est la barre verticale qui épaissit la ligne de vie pendant qu'un acteur traite une demande. Elle rend visible le temps de traitement.

sequenceDiagram
    participant N as Navigateur
    participant S as Serveur
    participant D as Base de données
    N->>S: GET /profil
    activate S
    S->>D: SELECT utilisateur
    activate D
    D-->>S: Données utilisateur
    deactivate D
    S-->>N: Page profil
    deactivate S

Le raccourci + / - fait la même chose plus brièvement, accolé à la flèche :

sequenceDiagram
    participant N as Navigateur
    participant S as Serveur
    N->>+S: GET /profil
    S-->>-N: Page profil

->>+ ouvre l'activation au moment du message, -->>- la ferme. Plus court, même résultat.

Notes : annoter sans casser le flux

Une note pose un commentaire à côté ou par-dessus la séquence.

sequenceDiagram
    participant C as Client
    participant S as Serveur
    Note over C,S: Connexion sécurisée TLS établie
    C->>S: Requête authentifiée
    Note right of S: Vérifie le jeton<br/>avant de répondre
    S-->>C: Réponse

Trois placements : Note left of X, Note right of X, et Note over X,Y (qui chevauche un ou plusieurs participants).

La vraie puissance : les blocs logiques

C'est ce qui distingue un diagramme de séquence d'un simple échange linéaire. On peut exprimer conditions, boucles et parallélisme.

Alternative (alt / else)

sequenceDiagram
    participant U as Utilisateur
    participant S as Serveur
    U->>S: POST /login
    alt Identifiants valides
        S-->>U: 200 + session
    else Identifiants invalides
        S-->>U: 401 Non autorisé
    end

Optionnel (opt)

sequenceDiagram
    participant U as Utilisateur
    participant S as Serveur
    U->>S: Commande validée
    opt Code promo fourni
        S->>S: Appliquer la réduction
    end
    S-->>U: Confirmation

Boucle (loop)

sequenceDiagram
    participant C as Client
    participant S as Serveur
    loop Toutes les 30 secondes
        C->>S: Ping
        S-->>C: Pong
    end

Parallèle (par)

sequenceDiagram
    participant S as Serveur
    participant Mail as Service Mail
    participant Log as Journal
    S->>S: Commande payée
    par Notifier le client
        S->>Mail: Envoyer la confirmation
    and Tracer l'événement
        S->>Log: Écrire dans le journal
    end

Ces blocs s'imbriquent : un alt peut contenir un loop, qui contient un opt. C'est ce qui permet de décrire des protocoles complets.

:::example[Cas concret : un paiement avec retry] Voici un échange réaliste qui combine activation, alternative et boucle — exactement le type de schéma qui clarifie une discussion technique d'équipe.

sequenceDiagram
    actor U as Client
    participant App as Application
    participant Pay as Passerelle de paiement
    U->>+App: Valider le panier
    App->>+Pay: Demander le paiement
    loop Jusqu'à 3 tentatives
        Pay->>Pay: Traiter la carte
    end
    alt Paiement accepté
        Pay-->>-App: Succès + reçu
        App-->>U: Commande confirmée
    else Paiement refusé
        Pay-->>App: Échec
        App-->>-U: Demander un autre moyen
    end

:::

Erreurs fréquentes

:::danger[Ce qui casse un diagramme de séquence]

• Oublier le end d'un bloc alt/loop/opt : le diagramme entier ne s'affiche pas.
• Deux-points manquants après une flèche : A->>B Message est invalide, il faut A->>B: Message.
• Activation jamais fermée : chaque activate (ou +) doit avoir son deactivate (ou -).
• Espaces dans un identifiant de participant non déclaré : utilisez un alias avec as. :::

En résumé

• Le diagramme de séquence montre qui envoie quoi à qui, et dans quel ordre — le temps va de haut en bas.
• participant pour un système, actor pour un humain ; déclarez-les dans l'ordre de lecture.
• Flèche pleine à l'aller (->>), pointillée au retour (-->>) ; -) pour l'asynchrone.
• Les activations (+/-) montrent le temps de traitement.
• alt, opt, loop, par expriment conditions, options, répétitions et parallélisme — et s'imbriquent.

Vous maîtrisez maintenant les deux diagrammes les plus utilisés. Le quiz du chapitre suivant fait le point sur les flowcharts et les diagrammes de séquence avant d'attaquer les diagrammes orientés structure.