UML : diagrammes de séquence

Le diagramme de séquence montre l’ordre des échanges de messages entre des participants (objets, services, acteurs) pour un scénario précis. Le temps s’écoule de haut en bas.

Les éléments

Élément	Rôle
Participant	Acteur, objet, service (boîte en haut)
Ligne de vie	Ligne verticale pointillée sous le participant
Message synchrone	Flèche pleine : l’appelant attend la réponse
Message asynchrone	Flèche ouverte : l’appelant n’attend pas
Retour	Flèche pointillée
Barre d’activation	Rectangle étroit : le participant est en train de traiter
Fragment	Cadre (`alt`, `opt`, `loop`, `par`) pour les conditions et boucles

Un scénario : passer une commande

 Client           Site web         API            Base de données      Banque
   │                 │              │                   │                 │
   │ valider panier  │              │                   │                 │
   ├────────────────>│              │                   │                 │
   │                 │ POST /commandes                  │                 │
   │                 ├─────────────>│                   │                 │
   │                 │              │ INSERT commande   │                 │
   │                 │              ├──────────────────>│                 │
   │                 │              │<─ ─ ─ ─ ─ ─ ─ ─ ─ ┤ numéro          │
   │                 │              │ payer(montant)    │                 │
   │                 │              ├────────────────────────────────────>│
   │                 │              │<─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤ accepté
   │                 │              │ UPDATE statut     │                 │
   │                 │              ├──────────────────>│                 │
   │                 │<─ ─ ─ ─ ─ ─ ─┤ 201 Créée         │                 │
   │<─ ─ ─ ─ ─ ─ ─ ─ ┤ confirmation │                   │                 │

Chaque flèche est un appel (nom de l’opération ou de la route et ses paramètres) ; chaque flèche pointillée est une réponse.

Sources PlantUML

@startuml
actor Client
participant "Site web" as Web
participant API
database "Base de données" as BD
participant Banque

Client -> Web : valider le panier
Web -> API : POST /commandes
API -> BD : INSERT commande
BD --> API : numéro de commande
API -> Banque : payer(montant)
Banque --> API : paiement accepté
API -> BD : UPDATE statut = 'payee'
API --> Web : 201 Créée
Web --> Client : confirmation
@enduml

Syntaxe PlantUML	Sens
`A -> B : texte`	Message synchrone
`A ->> B`	Message asynchrone
`A --> B`	Retour (pointillé)
`activate B` / `deactivate B`	Barre d’activation
`autonumber`	Numérote les messages
`A -> A : texte`	Auto-appel

Voir Outils et PlantUML pour produire l’image.

Fragments : alternatives, options, boucles

@startuml
actor Client
participant API
participant Banque
database BD

Client -> API : payer la commande
alt paiement accepté
  API -> Banque : débiter(montant)
  Banque --> API : accepté
  API -> BD : statut = payee
  API --> Client : confirmation
else paiement refusé
  Banque --> API : refusé
  API -> BD : statut = nouvelle
  API --> Client : échec, proposer un autre moyen
end

opt code promo saisi
  API -> BD : vérifier le code
end

loop pour chaque article
  API -> BD : décrémenter le stock
end
@enduml

Fragment	Sens
`alt` / `else`	Alternative (si… sinon)
`opt`	Option (exécuté si la condition est vraie)
`loop`	Boucle
`par`	Exécution parallèle
`break`	Sortie du scénario
`ref`	Renvoie à un autre diagramme

Quand en faire un

Bon usage	Mauvais usage
Expliquer un scénario précis (connexion, paiement)	Décrire tout le système
Clarifier les responsabilités entre composants	Remplacer le code
Documenter un échange entre services ou une API	Montrer chaque appel interne
Préparer l’écriture de tests d’intégration	Modéliser des algorithmes (préférer l’activité)

Un diagramme de séquence couvre un scénario : en prévoir un pour le cas nominal et un pour chaque variante importante (erreurs comprises).

De la séquence au code

Le scénario ci-dessus donne le squelette d’un service :

class ServiceCommande {
  constructor(
    private readonly depot: DepotCommandes,
    private readonly banque: PasserelleBancaire,
  ) {}

  async passer(commande: Commande): Promise<Commande> {
    const numero = await this.depot.inserer(commande); // API -> BD
    const paiement = await this.banque.payer(commande.total()); // API -> Banque
    if (!paiement.accepte) {
      await this.depot.changerStatut(numero, 'nouvelle');
      throw new Error('paiement refusé');
    }
    await this.depot.changerStatut(numero, 'payee'); // API -> BD
    return { ...commande, numero, statut: 'payee' } as Commande;
  }
}

Chaque participant devient une classe ou un service (voir POO : polymorphisme et interfaces) ; chaque message, une méthode. Les retours deviennent des valeurs de retour ou des exceptions.

Cohérence avec les autres diagrammes

Diagramme	Lien avec la séquence
Classes	Les participants sont des classes ou des instances ; les messages sont leurs méthodes
Cas d’utilisation	Chaque cas se décline en une ou plusieurs séquences
États	Les messages provoquent des changements d’état d’un objet (statut de la commande)

Bonnes pratiques

Un scénario par diagramme ; 4 à 7 participants au plus.
Nommer les messages comme des opérations ou des routes d’API réelles.
Montrer les retours importants (erreurs, valeurs) et laisser de côté l’anecdotique.
Ordre chronologique strict, de haut en bas.
Garder le diagramme en texte (PlantUML) dans le dépôt, à côté du code concerné.

Dépannage

Symptôme	Piste
Diagramme trop large	Trop de participants : regrouper (par exemple « Back-office ») ou scinder
Diagramme trop long	Scinder avec `ref` vers des sous-diagrammes
Messages sans nom précis	Nommer comme une opération ou route réelle
Impossible d’exprimer une boucle complexe	Passer par un diagramme d’activité
Le diagramme PlantUML ne se génère pas	Erreur de syntaxe ligne indiquée ; voir Outils et PlantUML
Diagramme dépassé	Le mettre à jour dans le même commit que la modification du comportement

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune.