Un diagramme C4 est une méthode standardisée de visualisation architecturale conçue pour modéliser les systèmes logiciels à plusieurs niveaux d’abstraction structurelle. Intégré nativement dans Mermaid.js, le c4 moteur suit les quatre niveaux fondamentaux du modèle C4 : Contexte (l’écosystème macro), Conteneurs (applications, services et bases de données), Composants (modules structurels internes), et Interactions dynamiques. Cet outil élimine les complications liées au style CSS personnalisé en appliquant des blocs architecturaux cohérents et prêts à être présentés, basés sur vos déclarations textuelles.
Comprendre les abstractions et les mots-clés des diagrammes C4
Mermaid prend en charge quatre en-têtes d’initialisation de diagrammes spécialisés, selon le niveau de détail requis par votre disposition système :
C4Contexte: Se concentre sur la vue d’ensemble, affichant les utilisateurs, les écosystèmes logiciels principaux et les dépendances externes de haut niveau.C4Conteneur: Zoom sur un niveau pour décomposer les applications autonomes, les interfaces frontend, les microservices, les systèmes de stockage de bases de données et les files d’attente.C4Composant: Pénètre en profondeur dans un conteneur pour mettre en évidence les modules au niveau du code interne, tels que les Contrôleurs, Services et Référentiels.C4Dynamique: Se concentre sur le suivi des interactions de données en temps réel ou la séquence étape par étape des transactions entre les blocs d’infrastructure.
Structure de syntaxe de base
Chaque diagramme C4 commence par son en-tête de niveau spécifique, suivi d’une déclaration de titre facultative et de composants macro séparés par des virgules. Les parenthèses contiennent les paramètres, les chaînes étant délimitées par des guillemets doubles.
C4Contexte
titre "Maquette de contexte du système pour le cœur d'Internet"
Personne(client, "Client bancaire", "Un client de la banque possédant des comptes personnels.")
Système(systeme_bancaire, "Système de banque en ligne", "Permet aux clients d'afficher les informations de leur compte.")
Rel(client, systeme_bancaire, "Utilise", "HTTPS")
La taxonomie complète des macros d’éléments C4
La bibliothèque C4 de Mermaid fournit un ensemble étendu de macros spécialisées pour distinguer clairement les composants internes, les systèmes externes et les couches de base de données à travers tous les niveaux d’abstraction.
1. Macros Personne et Utilisateur
Personne(alias, libellé, [descr], [sprite], [tags]): Modélise un utilisateur humain interne ou un acteur clé.Personne_Ext(alias, libellé, [descr], [sprite], [tags]): Modélise un utilisateur externe (par exemple, un fournisseur tiers ou un vérificateur) situé en dehors de votre périmètre organisationnel principal.
2. Macros Système et Écosystème Logiciel
Système(alias, libellé, [descr], [sprite], [tags]): Représente un cluster de systèmes logiciels internes, inclus dans la portée de votre gestion directe.Système_Ext(alias, libellé, [descr], [sprite], [tags]): Modélise un système logiciel externe essentiel géré par un tiers (par exemple, des fournisseurs d’identité, des registres bancaires centraux).SystèmeBd(alias, libellé, [descr], [sprite], [tags]): Affiche une boîte de répository de données au niveau du système, de forme cylindrique.SystèmeBd_Ext(alias, libellé, [descr], [sprite], [tags]): Affiche un niveau de base de données externe géré par un tiers.
3. Macros Couche Conteneur (niveau C4Container)
Conteneur(alias, libellé, technologie, [descr], [sprite], [tags]): Modélise une application exécutable séparée, un serveur API ou une interface front-end.ConteneurBd(alias, libellé, technologie, [descr], [sprite], [tags]): Affiche une enveloppe de moteur de base de données relationnelle ou non relationnelle au niveau du conteneur.Conteneur_Ext(alias, libellé, technologie, [descr], [sprite], [tags]): Représente un conteneur cloud externe ou un service d’application.ConteneurBd_Ext(alias, libellé, technologie, [descr], [sprite], [tags]): Représente un niveau de stockage de base de données cloud externe et géré.
4. Macros Couche Composant (niveau C4Component)
Composant(alias, libellé, technologie, [descr], [sprite], [tags]): Cartographie un module, une couche ou un contrôleur de classe au niveau du code interne.ComposantBd(alias, libellé, technologie, [descr], [sprite], [tags]): Modélise un système de stockage de micro-composants internes ou un système de mise en cache de fichiers de bas niveau.
Conteneurs de limite et enveloppement structurel
Pour indiquer des périmètres de sécurité, des pare-feu d’entreprise ou des limites logiques d’application, Mermaid fournit trois enveloppes de conteneurs spécifiques encadrées par des crochets. Les éléments imbriqués sont visuellement regroupés.
Enterprise_Boundary(alias, libellé) { ... }: Enveloppe les systèmes de haut niveau dans une large frontière visuelle représentant le périmètre global de l’infrastructure d’entreprise ou de l’organisation.System_Boundary(alias, libellé) { ... }: Regroupe des conteneurs d’applications ou des microservices étroitement liés à l’intérieur d’une boîte d’écosystème logiciel unifié.Container_Boundary(alias, libellé) { ... }: Isole les composants au niveau du code à l’intérieur d’une couche contextuelle unique d’un module d’application.
Opérateurs directionnels avancés de relations
La connexion des blocs dans les diagrammes C4 repose sur la macro Rel macro ou ses variantes explicitement directionnelles. Plutôt que de transmettre des lignes de diagramme de flux brutes, vous suivez les connexions de manière sémantique en déclarant directement des vecteurs technologiques à l’intérieur des blocs logiques.
| Jetons de syntaxe de relation | Direction visuelle de la flèche | Contexte d’alignement d’utilisation |
|---|---|---|
Rel(de, à, libellé, [tech]) |
Dynamique / Automatisé | Relation par défaut. Laissez l’algorithme de disposition déterminer le meilleur tracé de ligne. |
BiRel(de, à, libellé, [tech]) |
Bidirectionnel (<–>) | Indique des échanges interactifs bidirectionnels, des protocoles duplex ou des processus de synchronisation. |
Rel_Arriere(de, à, libellé, [tech]) |
Flèche inversée en haut (<–) | Trace la relation dans le sens logique du code, mais inverse la flèche visuelle vers l’arrière. |
Rel_Voisin(de, à, libellé, [tech]) |
Préférence de disposition horizontale | Force le nœud cible à rester directement à côté du nœud source sur la même ligne horizontale. |
Rel_VersLeBas(de, à, libellé, [tech]) / Rel_VB(...) |
Droite vers le bas (v) | Force les flux de données verticaux vers le bas vers les couches de base de données ou les processus ultérieurs en arrière-plan. |
Rel_Up(from, to, label, [tech]) / Rel_U(...) |
Vers le haut en ligne droite (^) | Force les trajectoires de relation à aller en ligne droite vers les composants de l’interface utilisateur client. |
Rel_Gauche(from, to, label, [tech]) / Rel_G(...) |
Vers la gauche en ligne droite (<-) | Redirige les chemins horizontalement vers le côté gauche de l’élément canevas. |
Rel_Droite(from, to, label, [tech]) / Rel_D(...) |
Vers la droite en ligne droite (->) | Redirige les chemins horizontalement vers le côté droit de l’élément canevas. |
Mise en forme dynamique personnalisée et balisage (remplacements de formes C4)
Pour signaler les applications héritées, mettre en évidence les systèmes premium ou mettre en évidence les flux de données sécurisés, vous pouvez créer des styles personnalisés en utilisant le moteur de balisage des éléments. Vous définissez une matrice de propriétés de balise en haut de votre document, puis vous ajoutez cette étiquette de balise à vos définitions d’éléments.
Mots-clés de modification de mise en forme :
MettreAJourStyleElement(nomElement, couleurFond, couleurPolice, [couleurBordure], [ombrage]): Remplacement direct de la palette de fond par défaut d’une boîte d’élément explicite.MettreAJourStyleRel(from, to, couleurLigne, couleurTexte): Cible explicitement une route de connexion pour recolorer les chemins de ligne ou les descriptions de connexion.
C4Context
titre "Carte d'architecture mondiale codée par couleur personnalisée"
Systeme(api_legacy, "Noyau de facturation hérité", "Traite les renouvellements d'abonnement.")
Systeme(portail_moderne, "Portail tableau de bord client", "Moteur moderne de visualisation web utilisateur.")
%% Personnalisation directe des couleurs
MettreAJourStyleElement(api_legacy, "#d9534f", "#ffffff", "#c9302c")
MettreAJourStyleElement(portail_moderne, "#5cb85c", "#ffffff", "#4cae4c")
Maquette du monde réel : Carte du conteneur de limite du système d’e-commerce d’entreprise
Cette maquette complète et à plusieurs niveaux suit un écosystème e-commerce en ligne. Elle isole les serveurs centraux internes à l’aide d’unConteneur_Systeme conteneur de bloc, implémente des relais de notification externes dans le cloud viaSystem_Ext, cartographie les stockages de bases de données relationnelles internes ainsi que les microservices de suivi externes, et fixe les pipelines de communication à l’aide de paramètres explicites de la pile technologique.
C4Container
titre "Schéma de conteneurs pour la plateforme d'e-commerce d'entreprise"
Personne(client, "Acheteur en ligne", "Parcourt les articles du catalogue et ajoute des produits à son panier numérique.")
System_Ext(passerelle_paiement, "Service API Stripe", "Coffre-fort et moteur de traitement de cartes de crédit tiers.")
System_Boundary(eco_scope, "Périmètre central de l'e-commerce") {
Conteneur(application_front, "Application Web du point de vente", "Next.js, React", "Fournit les ressources statiques et gère les sessions de panier utilisateur.")
Conteneur(service_commande, "Microservice de commande", "Node.js, Express", "Traite les flux de travail du panier et calcule les taxes.")
ConteneurDb(base_commandes, "Base de données du registre des commandes", "PostgreSQL", "Stocke les lignes de transactions historiques et les enregistrements de registre sécurisés.")
}
%% Chemins d'interaction architecturale
Rel(client, application_front, "Consulte les produits et passe des commandes en utilisant", "HTTPS/Navigateur")
Rel_Down(application_front, service_commande, "Envoie les transactions de panier via", "JSON/API REST")
Rel_Droite(service_commande, base_commandes, "Persiste les états transactionnels à l'intérieur de", "SQL/Connexion JDBC")
Rel_Gauche(service_commande, passerelle_paiement, "Autorise les appels de charge tokenisés avec", "API TLS/HTTPS sécurisée")
Péchés courants de syntaxe et contraintes du système
Lors de la compilation de cartes C4 propres pour les cadres logiciels, faites attention à ces paramètres d’exécution afin d’éviter la rupture du diagramme :
- Formatage des séparateurs par virgule : Contrairement à presque tous les autres schémas Mermaid, les macros C4 exigent des virgules strictes entre les paramètres :
Personne(id, "Étiquette", "Desc"). Oublier une virgule séparatrice fera complètement planter le générateur de mise en page. - Guillemets réservés aux étiquettes : Les champs d’affichage, les balises techniques et les blocs de description à l’intérieur des macros *doivent* être entourés de guillemets doubles clairs. Insérer du texte brut dans les champs sans enveloppe de guillemets provoque des erreurs de parsing qui cassent le diagramme.
- Ordre d’empilement des limites : Lors de l’enveloppement des éléments à l’intérieur d’un
System_BoundaryouEnterprise_Boundarybloc, vous devez explicitement vider le contenu de son espace de travail en utilisant des accolades standards{ }. Laisser une accolade de limite ouverte ou les appariements incorrects cassent les mises en page de rendu. - Instantiation d’alias dynamique : Vous ne pouvez pas tracer de relations (
Rel) vers un identifiant d’alias qui n’a pas été explicitement initialisé par un bloc de macro d’élément au-dessus. Gardez votre flux de déclaration en progression du haut vers le bas.