Guide de syntaxe des diagrammes en flux Mermaid.js

Qu’est-ce qu’un diagramme en flux ?

Un Diagramme en fluxest une carte comportementale fondamentale qui visualise un flux opérationnel étape par étape, une procédure algorithmique ou une logique métier séquentielle. En représentant les actions du système sous forme de formes géométriques distinctes et en traçant le flux de contrôle à l’aide de flèches directionnelles, un diagramme en flux permet aux ingénieurs logiciels et aux architectes système de suivre facilement les chemins d’exécution conditionnels, d’isoler les blocs à point de défaillance unique et d’analyser les boucles logiques du système avant d’écrire du code backend réel.

Avec Mermaid.js, vous n’avez pas à passer des heures à glisser des boîtes, à gérer minutieusement les lignes de grille ou à recalculer les variables de marge. Le moteur de mise en page calcule dynamiquement les coordonnées des nœuds à partir de vos scripts déclaratifs bruts, vous permettant de vous concentrer entièrement sur la logique sous-jacente de votre système.

Guide de syntaxe principale : éléments et constructions

Pour concevoir un diagramme en flux élégant et facile à lire dans Mermaid, vous devez maîtriser les indicateurs de direction du canevas, les enclosures géométriques des nœuds, les variables de câblage des liens et les sous-graphes structurels.

1. Définition des directions du canevas

L’orientation de votre diagramme en flux est déterminée directement à la première ligne par le couple de mots-clés appliqué au graph ou flowchartenveloppe. Vous pouvez contrôler la direction d’échelle visuelle de votre disposition en utilisant quatre clés d’orientation principales :

• flowchart TD (Haut vers le bas / orientation verticale)
• flowchart BU (Bas vers le haut)
• flowchart LR (Gauche vers la droite / orientation horizontale)
• flowchart RL (Droite vers la gauche)

2. Personnalisation de la géométrie des nœuds (formes)

Par défaut, une déclaration d’ID simple s’affiche sous forme de boîte rectangulaire nette. Pour rendre vos diagrammes plus faciles à lire, utilisez les crochets d’encadrement spécifiques de Mermaid pour injecter instantanément un contexte visuel dans les différentes étapes du flux de travail. Chaque bloc de définition doit être précédé d’un jeton de disposition directionnelle pour être correctement analysé :

• Bords arrondis : id(Texte) — Représente une étape générale du processus.
• Forme stade/capsule : id([Texte]) — Marqueur standard pour les jalons de début et de fin des limites.
• Sous-programme/Processus prédéfini : id[[Texte]] — Représente une routine système encapsulée ou un script de classe externe.
• Cylindre/Base de données : id[(Texte)] — Représente la persistance de base de données, les caches ou les entrepôts de données.
• Losange/Point de décision : id{Texte} — Représente des commutateurs conditionnels, des branches if/else ou des points d’évaluation.
• Parallélogramme : id[/Texte/] ou id[Texte] — Affiche des limites inclinées pour représenter des entrées/sorties de données explicites (E/S).

flowchart TD
    start_node([Démarrer l'exécution])
    query_db[(Instance PostgreSQL)]
    validate_check{Autorisé ?}

3. Règles de câblage des liens et étiquettes intégrées

Vous pouvez ajuster vos lignes de connexion pour représenter différentes relations structurelles et styles de communication. Pour garder vos diagrammes propres, insérez des étiquettes descriptives directement sur vos chemins de lien :

flowchart TD
    %% Flèche de connexion standard avec étiquette de texte
    A --> |"Charge utile JSON"| B

    %% Ligne pointillée/asynchrone avec étiquette de texte
    B -.-> |"Événement asynchrone"| C

    %% Ligne épaisse en gras avec étiquette de texte
    C ==> |"Écriture critique"| D

4. Isolation modulaire via des sous-graphes

Pour établir des périmètres de réseau clairs, regrouper des microservices ou isoler les responsabilités des équipes, regroupez vos éléments à l’intérieur de structures sous-graphe enveloppes. Vous définissez un sous-graphe en lui attribuant un ID interne, un titre d’affichage facultatif, et en le fermant avec un fin balise :

flowchart TD
    sousgraphique auth_sub["Frontière de sécurité"]
        gateway[Passerelle API] --> auth_worker(Validateur de jeton)
    fin

Meilleures pratiques pour des diagrammes de flux propres

• Déconnecter les mises en page horizontalement : Pour les pipelines d’ingénierie longs et à plusieurs étapes, choisissez une flowchart LR direction. Cela s’ajuste beaucoup mieux sur les écrans standards en paysage que sur une mise en page verticale longue.
• Isoler les boucles complexes : Si un flux de travail contient une boucle de répétition importante, étiquetez clairement le connecteur inverse (par exemple, retry --> |"Tentative de réinitialisation"| start) afin d’éviter que les lecteurs ne confondent la boucle avec un chemin standard vers l’avant.
• Éviter de mélanger les types de graphiques : Restez sur le mot-clé moderne flowchart plutôt que l’ancien graph drapeau lors du rendu de cartes complexes. Le moteur flowchart utilise un algorithme de mise en page mis à jour qui prend en charge des combinaisons avancées de flèches et un routage de chemin plus propre.

Exemples réels de diagrammes de flux Mermaid.js

Exemple 1 : Maillage d’ingestion déclenché par événement pour microservices (architecture Gauche-Droite)

Ce plan fonctionnel modélise un service d’ingestion de télémétrie web. Il montre comment combiner des entrées de données, des diamants de décision et des formes de base de données cloud sur une toile horizontale claire.

flowchart LR
    %% Définir les nœuds d'éléments avec des formes géométriques explicites
    init([Webhook déclenché]) --> input_io[/Capturer la requête HTTP/]
    input_io --> auth_check{Valider le jeton}
    
    auth_check --> |"Jeton non valide"| err_stop([Retourner 401 Non autorisé])
    auth_check --> |"JWT valide"| write_queue[[Publier dans la file Kafka]]
    
    write_queue --> worker_proc(Démon consommateur)
    worker_proc --> db_store[(Cluster TimescaleDB)]
    db_store --> term([Flot terminé])

    %% Remplacements rapides de style personnalisés
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Analyse syntaxique : Ce diagramme s’écoule de manière fluide de gauche à droite. L’étape de validation utilise une forme de losange jaune pour les décisions (auth_check{Valider le jeton}), ce qui sépare clairement le chemin d’exécution en deux résultats distincts. Les magasins de données sont immédiatement identifiables grâce à leurs cylindres de base de données personnalisés ([(Cluster TimescaleDB)]) et leurs entrées en parallélogramme.

Exemple 2 : Moteur d’inscription d’utilisateurs multi-niveaux d’entreprise (vertical avec sous-graphes imbriqués)

Ce schéma avancé d’entreprise décrit un pipeline d’inscription d’application. Il organise les étapes verticalement sur trois sous-graphes structurels distincts pour représenter des couches architecturales différentes.

flowchart TD
    sousgraph Client_Tier["Couche Interface Présentation"]
        app[Interface Mobile App]
        web[Frontend Web SPA]
    fin

    sousgraph Service_Tier["Routeur Principal de Passerelle"]
        proxy[[Proxy Inverse Nginx d'Ingress]]
        auth_svc(Service de validation des utilisateurs)
    fin

    sousgraph Persistence_Tier["Centre de données sécurisé"]
        main_db[(Base de données Principale des Comptes Utilisateurs)]
        cache_node[(Cache de Session Redis)]
    fin

    %% Définir les pipelines de communication entre les couches du sous-système
    app -- "Demande HTTPS" --> proxy
    web -- "Demande HTTPS" --> proxy
    
    proxy --> |"Route /v1/auth"| auth_svc
    
    auth_svc --> |"Vérifier la Session"| cache_node
    auth_svc --> |"Valider le Compte"| main_db

Analyse syntaxique : L’indicateur d’orientation du haut vers le bas (flowchart TD), ce qui force le moteur de mise en page à empiler les composants de manière propre du haut vers le bas. Les blocs limites regroupent les composants liés en couches distinctes (Client, Service et Persistence), donnant à l’architecture globale un aspect intuitif et fortement structuré.