Avant de plonger dans des agencements architecturaux spécifiques comme des diagrammes de flux complexes ou des chronologies de séquence, il est essentiel de comprendre les règles fondamentales qui régissent le Guide Mermaid. Mermaid repose sur un système de notation textuelle propre et très intuitive. Une fois que vous comprenez comment le moteur initialise un type de canevas, nomme les composants structurels et oriente les flèches directionnelles, la rédaction de tout agencement de système complexe devient totalement naturelle.
Ce bref aperçu couvre les mécaniques de syntaxe structurelle globales qui s’appliquent à presque tous les types de diagrammes Mermaid dans l’environnement VPasCode.
1. Les enveloppes obligatoires du type de diagramme
Chaque bloc de code Mermaid doit commencer par une déclaration explicite de son archétype de diagramme sur la toute première ligne. Cela indique au parseur VPasCode exactement quel moteur structurel doit être lancé dans votre canevas d’aperçu :
graph TD— Spécifie un agencement de diagramme de flux organisé du haut vers le bas.sequenceDiagram— Spécifie un diagramme de chronologie de temps d’exécution.classDiagram— Spécifie un plan directeur logiciel structuré orienté objet.
Contrairement à d’autres moteurs de conversion texte-diagramme, Mermaid n’exige pas d’étiquettes de fin. Le parseur lit simplement la déclaration structurelle de la première ligne et compile tout ce qui est imbriqué directement en dessous dans votre conteneur de bloc de code.
2. Déclaration des éléments : ID vs. étiquettes d’affichage
Lors de la modélisation d’un système logiciel, vous créerez divers éléments structurels tels que des composants, des bases de données ou des microservices. Dans Mermaid, vous déclarez un élément en définissant un court ID alphanumérique interne, suivi immédiatement d’un style entre crochets qui contrôle sa forme visuelle, et d’un nom d’affichage convivial :
microservice_id[API de traitement des paiements]
db_id[(SQL des transactions utilisateur)]Pourquoi c’est une bonne pratique : Utiliser un ID interne court et propre (comme microservice_id) rend le tracé des lignes de relation beaucoup plus rapide par la suite. Si vous devez un jour modifier l’étiquette visible par le client de « API de traitement des paiements » en « Service de paiement global », vous n’aurez qu’à la modifier dans la seule ligne où elle est déclarée, plutôt que de mettre à jour des dizaines de lignes dans votre script.
3. Maîtriser les flèches de relation et le routage directionnel
Les connexions entre les nœuds du système sont dessinées à l’aide de combinaisons de tirets (-), signes égaux (=), et des crochets fléchés (>). Le style de vos lignes vous donne un contrôle implicite sur la manière dont le moteur de mise en page automatique échelonne votre diagramme :
A --> Bdessine une flèche dirigée standard pointant de l’élément A à l’élément B.A --- Bdessine une ligne de liaison plate et non orientée sans tête de flèche, idéale pour des associations simples.A -.-> Bcrée une ligne de dépendance pointillée, qui est la norme de l’industrie pour indiquer des dépendances asynchrones ou des webhooks réseau.A ==> Bcrée une ligne de connexion épaisse et en gras, parfaite pour mettre en évidence les voies principales de traitement des données ou les liens essentiels de l’infrastructure.
4. Ajout de contexte en ligne : étiquettes et commentaires de code
Une documentation claire repose fortement sur l’ajout de contexte approprié autour de vos lignes visuelles et de vos scripts texte :
Étiquetage des lignes de connexion
Vous pouvez ajouter du texte explicatif directement sur n’importe quelle ligne de connexion en insérant la chaîne de texte entre deux paires de traits d’union, ou en ajoutant un caractère barre verticale (|Texte|) juste après votre carte de relation :
client_id -- "POST HTTPS /v1/checkout" --> api_id
client_id --> |POST HTTPS /v1/checkout| api_idRédaction de commentaires de code
Si vous souhaitez laisser une note administrative, un crédit de conception ou une explication architecturale dans votre fichier de script sans afficher de boîte visuelle sur le canevas, utilisez deux signes de pourcentage (%%). Cela indique au moteur de sauter complètement l’analyse de cette ligne :
%% TODO : Nous devons mettre à jour cette boîte de limite une fois la migration DevOps terminée
[Monolithe hérité] --> [Nouveau microservice]