Diagrammes d'états : le cycle de vie d'un objet

À retenir — Un diagramme d'états répond à une question précise : « dans quels états mon objet peut-il être, et quels événements le font passer de l'un à l'autre ? ». Une commande, un abonnement, une connexion réseau, une machine à café — tout ce qui a un cycle de vie se modélise ici.

La bonne question à se poser

Le diagramme de classes décrivait la forme du code. Le diagramme d'états décrit son comportement dans le temps : les états successifs d'un même objet et les transitions entre eux. Si vous vous surprenez à écrire dans la doc « quand X est en attente, il peut passer à validé ou annulé », vous décrivez déjà un diagramme d'états.

stateDiagram-v2
    [*] --> Brouillon
    Brouillon --> Publié : publier
    Publié --> Archivé : archiver
    Archivé --> [*]

Deux symboles fondateurs :

[*] est l'état initial (en haut) ou final (en bas), selon le sens de la flèche.
Etat --> Etat : événement est une transition déclenchée par un événement (le texte après les deux-points).

Notez le -v2 : utilisez toujours stateDiagram-v2, la version moderne, plus complète et mieux rendue.

Transitions et événements

Le texte après les deux-points est l'événement ou la condition qui provoque le changement d'état. C'est lui qui rend le diagramme lisible.

stateDiagram-v2
    [*] --> Déverrouillé
    Déverrouillé --> Verrouillé : verrouiller
    Verrouillé --> Déverrouillé : bon code PIN
    Verrouillé --> Bloqué : 3 échecs
    Bloqué --> Déverrouillé : réinitialisation admin

On lit chaque ligne comme une phrase : « depuis Verrouillé, l'événement bon code PIN mène à Déverrouillé ». Un même état peut avoir plusieurs sorties — c'est tout l'intérêt.

:::tip[Nommer la transition, pas juste relier] Une flèche sans étiquette ne dit pas pourquoi l'objet change d'état. Mettez toujours l'événement déclencheur après les deux-points (: paiement reçu, : délai dépassé). C'est cette étiquette qui transforme un dessin en documentation utile. :::

Décrire ce qui se passe dans un état

Un état peut porter une description de ce qu'il fait, avec :.

stateDiagram-v2
    [*] --> Chargement
    Chargement : Affiche un spinner
    Chargement : Récupère les données
    Chargement --> Succès : données reçues
    Chargement --> Erreur : échec réseau
    Succès --> [*]
    Erreur --> Chargement : réessayer

États composites : zoomer dans un état

C'est la fonctionnalité qui fait passer le diagramme d'états au niveau supérieur. Un état peut contenir ses propres sous-états, regroupés entre accolades.

stateDiagram-v2
    [*] --> Hors_ligne
    Hors_ligne --> En_ligne : connexion

    state En_ligne {
        [*] --> Inactif
        Inactif --> Actif : activité
        Actif --> Inactif : 5 min d'inactivité
    }

    En_ligne --> Hors_ligne : déconnexion

L'objet est globalement En_ligne, et à l'intérieur il oscille entre Inactif et Actif. Cette imbrication évite de dupliquer des transitions et garde le diagramme lisible quand la logique se complexifie.

Transitions parallèles avec le fork

Quand un état se scinde en plusieurs sous-machines qui tournent en même temps, on utilise -- pour séparer les régions parallèles à l'intérieur d'un état composite.

stateDiagram-v2
    [*] --> Commande_active

    state Commande_active {
        [*] --> Préparation
        Préparation --> Prête : colis fait
        --
        [*] --> Paiement_attente
        Paiement_attente --> Payé : encaissé
    }

Les deux régions (préparation et paiement) évoluent indépendamment au sein de la même commande active.

Choix conditionnel

Pour modéliser un aiguillage basé sur une condition, l'état <<choice>> agit comme un losange de décision.

stateDiagram-v2
    [*] --> Vérification
    Vérification --> choix
    state choix <<choice>>
    choix --> Approuvé : score >= 700
    choix --> Refusé : score < 700
    Approuvé --> [*]
    Refusé --> [*]

:::example[Cas concret : le cycle de vie d'une commande e-commerce] Le diagramme d'états par excellence — celui que toute équipe produit finit par dessiner pour aligner tout le monde sur les statuts possibles.

stateDiagram-v2
    [*] --> Panier
    Panier --> En_attente_paiement : validation
    En_attente_paiement --> Payée : paiement accepté
    En_attente_paiement --> Annulée : paiement refusé
    Payée --> En_préparation : stock confirmé
    En_préparation --> Expédiée : remise au transporteur
    Expédiée --> Livrée : réception client
    Livrée --> [*]
    Payée --> Remboursée : annulation client
    Remboursée --> [*]
    Annulée --> [*]

:::

Notes et directions

On peut annoter un état et changer le sens de lecture, comme dans un flowchart :

stateDiagram-v2
    direction LR
    [*] --> Actif
    Actif --> Suspendu : impayé
    Suspendu --> Actif : régularisation
    note right of Suspendu : Accès en lecture seule

direction LR bascule le diagramme à l'horizontale — utile pour les cycles de vie longs et linéaires.

Erreurs fréquentes

:::danger[Ce qui casse un diagramme d'états]

Utiliser stateDiagram sans -v2 : préférez toujours la v2, plus riche et mieux supportée.
Oublier de fermer un état composite par }.
Confondre [*] initial et final : c'est le sens de la flèche qui décide. [*] --> A = entrée ; A --> [*] = sortie.
Noms d'états avec espaces : utilisez des underscores (En_attente) ou un alias. :::

En résumé

Le diagramme d'états modélise le cycle de vie d'un objet : ses états et les événements qui le font transiter.
[*] marque l'état initial ou final selon le sens de la flèche ; Etat --> Etat : événement est une transition.
Nommez chaque transition par son déclencheur — c'est ce qui rend le diagramme utile.
Les états composites (state X { … }) imbriquent des sous-états ; -- crée des régions parallèles.
<<choice>> modélise un aiguillage conditionnel ; utilisez toujours stateDiagram-v2.

Au chapitre suivant, on quitte le code pour les données : le diagramme entité-relation (ERD), l'outil pour concevoir et documenter un schéma de base de données.