Les niveaux 3 et 4 du modèle C4 (composants et code) servent à montrer l'intérieur d'un conteneur à des architectes et des développeurs, mais ils ne sont pas à produire par défaut. Cette leçon facultative, pour qui a lu les trois premières du module, ouvre le conteneur API de la boutique, lit son diagramme de composants puis son diagramme de code, et surtout apprend à décider quand ne pas les dessiner, parce qu'un dessin périmé trompe plus qu'une absence.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »- Définir un composant au sens du modèle C4 et le distinguer d'un conteneur.
- Interpréter la vue composants de l'API de la boutique, relation par relation.
- Découper un conteneur par responsabilité, sans suivre les dossiers du dépôt.
- Reconnaître un diagramme de code et sa place dans l'outillage.
- Décider s'il faut descendre d'un niveau ou s'arrêter.
- Repérer les erreurs fréquentes d'un diagramme de composants.
Qu'est-ce qu'un composant au sens du modèle C4 ?
Section intitulée « Qu'est-ce qu'un composant au sens du modèle C4 ? »Un composant est un regroupement cohérent de code à l'intérieur d'un conteneur, avec une responsabilité claire et une technologie identifiable. Le niveau 3 prend pour périmètre un seul conteneur, et son public est celui des architectes et des développeurs. La leçon sur le modèle C4 pose le vocabulaire commun ; ici, seul ce niveau compte.
Un composant n'est ni un fichier ni une classe : c'est une brique que l'équipe sait nommer et expliquer en une phrase. Ce peut être un module Node.js (un fichier ou un dossier de code que d'autres parties importent), une bibliothèque ou un composant de framework (un cadre de développement qui impose une structure, comme Express pour recevoir des requêtes web).
Il diffère d'un conteneur sur un point précis : en pratique, il ne se déploie pas seul, l'unité qu'on déploie étant le conteneur. Le conteneur API se lance comme un processus Node.js ; ses cinq composants s'exécutent tous dedans. Les conteneurs sont détaillés dans la leçon sur le diagramme de conteneurs.
Le site c4model.com ne recommande pas ce niveau par défaut : sa FAQ répond « No, only create component diagrams if you feel they add value » (« Non, ne créez des diagrammes de composants que si vous estimez qu'ils apportent de la valeur »). Il conseille aussi d'automatiser leur production pour obtenir une documentation durable.
Que montre la vue composants de l'API de la boutique ?
Section intitulée « Que montre la vue composants de l'API de la boutique ? »La vue composants de la boutique ouvre un seul conteneur, l'API, et montre ses cinq composants avec les relations qu'ils entretiennent. Sur le schéma ci-dessous, regardez d'abord le composant mis en avant (Service Commandes), puis suivez les flèches de gauche à droite : de l'interface web vers les services, des services vers la base et les systèmes externes.
Le Contrôleur HTTP [Express] reçoit les requêtes de l'interface web et vérifie la session (que l'utilisateur est bien connecté). Il transmet les demandes de catalogue au Service Catalogue et les commandes au Service Commandes. Le Service Catalogue lit la base de données (SQL/TCP). Le Service Commandes la lit et y écrit, demande le débit au Client Paiement puis la confirmation aux Notifications.
Ces deux derniers composants parlent aux systèmes externes : le Client Paiement débite la carte (JSON/HTTPS), les Notifications envoient les e-mails de commande (SMTP).
Autour du conteneur ouvert restent visibles les éléments d'appui : l'Interface web, la Base de données, le Service de paiement et le Service de mail. Ils donnent au lecteur le point d'arrivée de chaque flèche sans qu'il ait à rouvrir la vue conteneurs. C'est aussi pourquoi un seul conteneur est ouvert à la fois : ouvrir l'interface web et l'API sur la même page mélangerait deux échelles et rendrait le dessin illisible.
Comment découper un conteneur en composants ?
Section intitulée « Comment découper un conteneur en composants ? »On découpe un conteneur par responsabilité, pas par dossier : chaque
composant répond à la question « que fait-il pour le reste du système ? ».
Le nom doit dire ce que le composant fait (Service Commandes, Client
Paiement), pas où il se trouve (src/lib, utils). Chaque relation
porte un verbe (« Demande le débit », « Transmet les commandes ») et, quand
elle franchit une frontière réseau, la technologie utilisée. Comme pour les
conteneurs, chaque composant garde sa technologie à côté de son nom.
Pour trouver les composants, trois sources suffisent. La structure du code montre les modules et les paquets déjà séparés. Les points d'entrée révèlent qui reçoit quoi : routes HTTP, tâches planifiées, ou consommateurs de messages (du code qui réagit à l'arrivée d'un message dans une file). Les dépendances externes (base, paiement, mail) indiquent quels composants doivent exister pour parler à chacune. Mon conseil, qui ne vient pas de c4model.com : un composant par système externe est souvent un bon premier découpage.
Gardez une limite de taille. C4 n'en fixe aucune ; ma règle empirique est qu'au-delà d'une dizaine de composants le diagramme devient difficile à lire. Deux issues : regrouper les composants voisins sous un nom plus large, ou renoncer au diagramme et décrire le conteneur en quelques lignes de texte.
À quoi ressemble le niveau code, et qui le lit ?
Section intitulée « À quoi ressemble le niveau code, et qui le lit ? »Le niveau code montre comment un seul composant est construit : ses classes, interfaces, objets, fonctions ou tables, et leurs liens. Il vise les mêmes lecteurs que le niveau composants, architectes et développeurs. Regardez, sur le schéma ci-dessous, comment le Service Commandes se décompose en quatre classes, et quelles méthodes elles exposent.
C'est un diagramme de classes de la notation UML (un langage de
modélisation graphique), ou un diagramme de tables pour une base de données.
Aucune connaissance d'UML n'est nécessaire pour le lire : une boîte est une
classe, la liste du haut donne ses données, celle du bas ses actions, et
un trait relie deux classes qui collaborent. Ici, ServiceCommandes utilise
DepotCommandes pour enregistrer et relire les commandes, et une Commande
contient des LigneCommande.
Le dessin n'affiche que les attributs et méthodes utiles au propos, pas la liste complète : celle-ci est dans le code. Et c'est le point clé du niveau 4 : c4model.com le déclare « Recommended? No », parce que « most IDEs can generate this level of detail on demand ». Un IDE (l'éditeur de code évolué des développeurs) produit déjà ce dessin, à jour, au moment où vous en avez besoin. La documentation du code (docstrings et référence générée) prolonge cette idée : elle reste synchronisée avec les sources au lieu de vieillir à côté.
Quand faut-il descendre d'un niveau, et quand s'arrêter ?
Section intitulée « Quand faut-il descendre d'un niveau, et quand s'arrêter ? »Il faut descendre d'un niveau seulement quand quelqu'un en a besoin, et que le dessin restera juste. Pour le code, c4model.com précise qu'il n'est pas recommandé « for anything but the most important or complex components ». Contexte et conteneurs suffisent à la plupart des équipes, comme le rappelle la leçon sur le modèle C4. L'arbre ci-dessous se suit de haut en bas : sans demande, on s'arrête ; si le dessin ne sera pas juste dans six mois (un horizon de repère, pas une règle de C4), on se limite à un seul conteneur ; sinon on génère le diagramme à la demande, et à défaut on décrit en texte.
La raison tient à l'obsolescence, que la FAQ de c4model.com décrit niveau par niveau (le tableau de la leçon sur le modèle C4 en donne la vitesse). Les composants peuvent changer souvent (« may change frequently ») et le code devient obsolète très vite quand la base de code évolue activement. Un diagramme de composants dessiné à la main vieillit donc vite. Pour le niveau code, la FAQ propose deux voies : ne pas le créer, ou le générer à la demande (« generate them on-demand using tooling such as your IDE »).
La FAQ associe aussi une source de génération à chaque niveau. Le tableau ci-dessous les liste ; chaque source est un outil qui connaît déjà la réalité du système, ce qui évite de la redessiner à la main.
| Niveau | Source de génération | En clair |
|---|---|---|
| Contexte | Catalogue de services (Backstage, ServiceNow) | L'inventaire central des systèmes de l'entreprise |
| Conteneurs | Journaux ou données OpenTelemetry | Les traces des appels réels entre services |
| Composants | Analyse statique | Un outil qui lit le code sans l'exécuter |
| Déploiement | Infrastructure as code (Terraform, CloudFormation) | Les fichiers qui décrivent l'infrastructure |
| Code | IDE | L'éditeur de code des développeurs |
Si aucune source ne convient, décrivez le conteneur en texte, dans le Service Overview par exemple. Pour décrire le modèle une seule fois et en dériver les vues, y compris celle des composants, voyez la leçon C4 en code : Structurizr porte les composants dans le même modèle que les conteneurs.
La règle à retenir : un dessin faux nuit plus qu'un dessin absent. Le lecteur fait confiance à un schéma, et il prendra une décision sur une information périmée. Si vous ne pouvez pas garantir la mise à jour, ne dessinez pas, ou générez.
Quelles erreurs fréquentes éviter ?
Section intitulée « Quelles erreurs fréquentes éviter ? »Les erreurs sur ces deux niveaux viennent presque toujours du même réflexe : dessiner trop de choses, trop tôt, à la main. Le tableau ci-dessous les regroupe avec leur correction ; il se lit en comparant chaque symptôme à votre diagramme.
| Erreur | Pourquoi c'est un problème | Correction |
|---|---|---|
| Ouvrir plusieurs conteneurs sur le même diagramme de composants | Deux échelles se mélangent, le lecteur ne sait plus ce qui s'exécute où | Un diagramme par conteneur, les autres en éléments d'appui |
| Prendre les dossiers du dépôt pour des composants | Le découpage décrit l'organisation des fichiers, pas les responsabilités | Nommer par ce que le composant fait pour le système |
| Dessiner le niveau code à la main et ne jamais le mettre à jour | Il peut vieillir très vite et devenir faux | Le générer depuis l'IDE à la demande |
| Oublier la technologie des composants | Le lecteur ne sait pas s'il s'agit d'Express, d'un module ou d'une bibliothèque | Une technologie à côté de chaque nom |
| Tracer des flèches sans verbe | La relation ne dit ni l'intention ni le sens | Un verbe par flèche, qui correspond à la direction |
La dernière ligne reprend la règle de notation vue dans la leçon sur le modèle C4 : chaque relation est unidirectionnelle et étiquetée, et le mot « Uses » seul est à éviter. Avant de publier, relisez aussi le titre et la légende du diagramme avec la checklist de cette leçon.
À retenir
Section intitulée « À retenir »- Un composant est un regroupement de code dans un conteneur, avec une responsabilité et une technologie ; il ne se déploie pas seul.
- La vue composants a pour périmètre un conteneur ; les autres éléments restent en appui, un seul conteneur est ouvert à la fois.
- On découpe par responsabilité, on nomme par ce que le composant fait, et chaque flèche porte un verbe.
- Ma règle empirique (elle ne vient pas de C4) : au-delà d'une dizaine de composants, on regroupe ou on renonce au diagramme.
- Le niveau code (classes, tables) n'est pas recommandé par défaut : l'IDE le génère à la demande.
- Les composants changent souvent, le code très vite : on génère plutôt que de dessiner à la main.
- Un dessin faux nuit plus qu'un dessin absent.
Contrôle de connaissances
Validez vos connaissances avec ce quiz interactif
Informations
- Le chronomètre démarre au clic sur Démarrer
- Questions à choix multiples, vrai/faux et réponses courtes
- Vous pouvez naviguer entre les questions
- Les résultats détaillés sont affichés à la fin
Lance le quiz et démarre le chronomètre
Vérification
(0/0)Score par domaine
Un domaine regroupe plusieurs guides et reçoit plusieurs questions : son score est plus fiable qu'un score par thème, qui porte souvent sur une seule question.
Bilan
Points forts
Aucun sujet réussi à 80 % sur au moins deux questions pour l’instant.
Points faibles
Aucun sujet sous le seuil de réussite.
À faire ensuite
Des indices pour retenter votre chance ?
Continuer le cours : Paysage, dynamique, déploiement : les vues complémentaires C4
Nouveau quiz complet avec des questions aléatoires
Retravailler uniquement les questions ratées
Retour à la liste des certifications