Guide de syntaxe des diagrammes de séquence Mermaid.js

Qu’est-ce qu’un diagramme de séquence ?

Un diagramme de séquence est un diagramme comportemental essentiel diagramme UML conçu pour visualiser le flux chronologique des messages, des appels de fonctions et des charges utiles de données entre différentes entités système au fil d’un timeline linéaire. Reconnu comme un type fondamental type de diagramme UML, il modélise les interactions en temps réel en empilant les composants système selon l’axe X sous forme de lignes de vie verticales et en suivant les échanges de messages selon l’axe Y. Ce schéma est inestimable pour les développeurs déboguant des échanges d’API distribuées, des chemins d’orchestration de microservices ou des flux d’authentification utilisateur en temps réel.

Avec Mermaid.js, vous pouvez scripter des processus temporels complexes à l’aide d’une structure de texte intuitive. Le moteur gère automatiquement l’espacement vertical, ajuste les alignements des flèches de message et dessine proprement les blocs d’activation en temps réel sur votre canevas.

Guide de syntaxe fondamentale : éléments et constructions

Pour concevoir un diagramme de séquence UML précis et facilement lisible dans Mermaid, vous devez maîtriser les déclarations de participants, les variantes des flèches de message, les lignes de vie explicites et les structures de blocs conditionnels.

1. Déclarer les participants et les acteurs

Vous déclarez une entité système standard en utilisant le mot-clé participant mot-clé. Si l’entité représente un utilisateur final humain ou un opérateur externe, utilisez le mot-clé acteur mot-clé pour afficher une icône standard de figure en bâton sur le canevas :

sequenceDiagram
    acteur Client
    participant API comme Routeur de passerelle

Astuce pro : Utilisez le mot-clé comme pour mapper des noms de composants longs à des alias internes compacts, en gardant vos scripts de messages concis et lisibles.

2. Formater les flèches de message

Le type de ligne et de tête de flèche que vous utilisez détermine le style de communication entre vos participants système :

• ->> **Appel synchrone :** Une ligne pleine avec une flèche remplie. Représente une demande bloquante qui attend la fin de l’exécution.
• --> **Ligne de réponse :** Une ligne pointillée avec une flèche ouverte. Utilisée pour renvoyer des charges utiles de données ou des jetons de confirmation.
• -> **Appel asynchrone :** Une ligne pleine avec une flèche ouverte. Indique un message non bloquant ou une diffusion d’événement.

sequenceDiagram
    App->>Serveur : Charge utile de requête
    Serveur-->App : Réponse 200 OK

3. Gestion des barres d’activation de la ligne de vie

Pour montrer précisément quand un composant système exécute activement une tâche ou utilise la mémoire du thread, utilisez les commandesactiver et désactiver . En alternative, vous pouvez ajouter un signe plus (+) ou un signe moins (-) directement à vos cibles de message comme raccourci visuel rapide :

sequenceDiagram
    Client->>+Serveur : Traiter les données
    %% Le serveur est maintenant visuellement actif
    Serveur-->-Client : Retourner les résultats

4. Structuration des conditions et alternatives (Alt, Opt, Boucle)

Pour gérer la logique d’exécution conditionnelle, les évaluations de jetons ou les réessais répétés de requêtes, enveloppez vos scripts de message dans des fragments de bloc standards :

• alt / sinon — Évalue des chemins conditionnels (similaire aux blocs de code if/else).
• opt — Définit une étape facultative qui s’exécute uniquement sous des critères spécifiques.
• boucle — Répète une séquence d’exécution jusqu’à ce qu’une condition soit satisfaite.

sequenceDiagram
    boucle Toutes les 30 secondes
        Client->>Serveur : Ping de battement de cœur
    fin

Meilleures pratiques pour des chronologies de séquence propres

• Gardez les lignes de vie dégagées : Évitez de lister des dizaines de micro-entités sur l’axe X. Si un processus interagit avec des classes auxiliaires mineures, abstrayez-les derrière une frontière système de haut niveau comme [Worker d'authentification] ou [Pool de cache].
• Libellez les codes d’état explicitement : Lorsque vous écrivez les retours de réponse (-->), ne rédigez pas simplement « Retourner des données ». Marquez le chemin avec des codes HTTP explicites ou des types d’événements (par exemple, "201 Créé (jeton JWT)") pour donner aux ingénieurs un contexte précis.
• Implémentez des notes pour les calculs complexes : Utilisez les directives Note au-dessus, Note à gauche de, ou Note à droite de pour documenter les opérations non visuelles, comme les étapes internes de chiffrement ou le hachage des données de base de données.

Exemples réels de diagrammes de séquence Mermaid.js

Exemple 1 : Flux d’échange de jeton OAuth2 sécurisé (blocs d’activation et alternatifs)

Ce schéma fonctionnel modélise une séquence de connexion utilisateur sécurisée. Il montre comment combiner des acteurs humains, des lignes de vie système explicites et des chemins de validation complexes en utilisant un bloc alt/else.

sequenceDiagram
    acteur Utilisateur comme Utilisateur final
    participant App comme Client Application Mobile
    participant Auth comme Fournisseur d'identité Auth0

    Utilisateur->>+App: Cliquez sur "Se connecter avec OAuth"
    App->>+Auth: Redirection avec client_id et scope
    Auth-->>Utilisateur: Afficher l'interface de connexion
    Utilisateur->>Auth: Soumettre les identifiants
    
    Auth->>Auth: Valider le hachage du mot de passe
    
    alt Les identifiants sont valides
        Auth-->>App: Redirection 302 avec code d'autorisation
        App->>Auth: Échanger le code contre un jeton d'accès
        Auth-->>-App: Retourner le jeton JWT (IdToken)
        App-->>Utilisateur: Afficher la page d'accueil du compte utilisateur
    sinon Identifiants invalides
        Auth-->>App: Retourner une erreur 401 Non autorisé
        App-->>-Utilisateur: Afficher l'alerte "Nom d'utilisateur ou mot de passe incorrect"
    fin

Analyse syntaxique : Ce chronogramme suit une poignée de main à plusieurs parties. Le alt / sinon conteneur met clairement en évidence les chemins de validation binaires, garantissant que les états d’erreur sont entièrement documentés aux côtés du parcours normal.

Exemple 2 : Validation de commande avec inventaire distribué (processus parallèles et notes)

Ce schéma système avancé décrit un pipeline de validation de commande pour une e-commerce d’entreprise. Il utilise des blocs parallèles (par) pour montrer les routines d’envoi d’API concurrentes et gérer les notes de verrouillage de base de données à travers la topologie.

sequenceDiagram
    participant Web comme Interface Web
    participant Ord comme Orchestrateur de commandes
    participant Inv comme Service d'inventaire
    participant Pay comme Passerelle de paiement

    Web->>+Ord: Soumettre la demande de validation
    Note au-dessus de Ord: Vérifier la disponibilité du stock des articles
    
    par Envoyer des appels API concurrents
        Ord->>+Inv: Verrouiller les articles en inventaire
        Inv-->-Ord: Inventaire réservé (stock verrouillé)
    et
        Ord->>+Pay: Autoriser le prélèvement de la carte bancaire
        Pay-->-Ord: Capture réussie (charge réglée)
    fin
    
    opt Le traitement de l'allocation échoue
        Note à droite de Ord: Exécuter la saga d'annulation si un appel échoue
    fin
    
    Ord-->-Web: 200 Succès Validation confirmée

Analyse syntaxique : Le par / et conteneur indique au moteur de regrouper les exécutions parallèles, en documentant les opérations backend concurrentes. Le Note au-dessus de et Note à droite de balises injectent des explications techniques d’exécution directement dans la grille du canevas, aidant les équipes à comprendre les transactions en arrière-plan comme le verrouillage des données et les sagas d’annulation, sans encombrer les flèches principales des messages.