Avant de plonger dans des agencements architecturaux spécifiques comme les modèles C4 ou les chronologies de séquence, il est essentiel de comprendre les règles fondamentales qui régissent le Guide pratique PlantUML. PlantUML repose sur un système de notation textuelle clair et très intuitif. Une fois que vous comprenez comment le moteur ouvre les documents, nomme les composants structurels et route les lignes de connexion, la rédaction de tout agencement de système complexe devient totalement naturelle.
Ce bref aperçu couvre les mécaniques syntaxiques structurelles globales qui s’appliquent à presque tous les types de diagrammes PlantUML dans l’environnement VPasCode.
1. Les enveloppes obligatoires du document
Chaque bloc de code PlantUML doit commencer et se terminer par des balises de cadre explicites. Ces balises indiquent au parseur VPasCode de démarrer le moteur de rendu approprié dans votre canevas d’aperçu :
@startuml— Cette ligne exacte doit être placée en tout premier lieu de votre script. Rien d’autre ne doit la précéder.@enduml— Cette ligne exacte doit être placée en tout dernier lieu de votre script, marquant la fin de votre bloc de données du diagramme.
Tout code rédigé en dehors de ces deux repères sera ignoré en toute sécurité par le compilateur, ou pourrait déclencher un avertissement de validation syntaxique dans le panneau de diagnostic de votre espace de travail.
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, des acteurs ou des microservices. Dans PlantUML, vous pouvez déclarer un élément explicitement en définissant son type, un ID abrégé interne et un nom d’affichage convivial entouré de guillemets :
composant microservice_id comme "API de traitement des paiements"
database db_id comme "SQL des transactions utilisateur"Pourquoi c’est une bonne pratique : Utiliser un ID interne court et clair (comme microservice_id) rend le dessin 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 » à « Service de paiement global », vous n’aurez qu’à modifier cette ligne unique de code, plutôt que de mettre à jour des dizaines de lignes dans tout 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 (-) et de crochets fléchés (>). La longueur de vos tirets et l’inclusion de mots-clés directionnels vous donnent un contrôle implicite sur la manière dont le moteur de disposition automatisé échelonne votre diagramme :
- Connexions de base :
A --> Bdessine une flèche dirigée standard pointant de l’élément A directement vers l’élément B. - Lignes de dépendance pointillées : Remplacer les tirets par des points crée une ligne pointillée, qui est la norme de l’industrie pour indiquer des dépendances asynchrones ou des appels réseau :
A ..> B. - Forcer l’orientation du layout : Bien que le moteur de mise en page place les boîtes automatiquement, vous pouvez explicitement contrôler l’orientation en insérant un mot-clé de direction directement dans la chaîne de flèche :
A -up-> B(Force B à s’afficher au-dessus de A)A -down-> B(Force B à s’afficher en dessous de A)A -left-> B(Force B à s’afficher à gauche de A)A -right-> B(Force B à s’afficher à droite de A)
4. Ajout de contexte en ligne : étiquettes et commentaires de code
Une documentation claire repose fortement sur le fait de placer un 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 ajoutant deux points (“:) juste après votre mappage de relation :
client_id --> api_id : "POST HTTPS /v1/checkout"Ré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 la toile, utilisez un caractère d’apostrophe (“'). 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]Maintenant que vous êtes familier avec les enveloppes de syntaxe globales, les déclarations de composants et les paramètres de flèches directionnelles de PlantUML, vous êtes parfaitement équipé pour commencer à créer des formes système avancées. Passez à la page suivante pour débloquer notre collection de Diagrammes d’architecture et de conception de haut niveau!