de_DEen_USes_ESfa_IRfr_FRhi_IN

Zoomer tout au bout : comprendre les diagrammes de code C4 – Ce qu’ils sont, quand ils apportent de la valeur, et des exemples pratiques avec PlantUML

Qu’est-ce qu’un diagramme de code C4 ?

Le diagramme de code estNiveau 4— le niveau le plus profond et le plus détaillé du modèle C4 de Simon Brown.

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

Il montre :

  • Classes, interfaces, énumérations, enregistrements, ou d’autres constructions au niveau du code qui implémentent un composant spécifiquecomposant (du niveau 3).

  • Relations entre ces classes (héritage, composition, dépendance, réalisation d’interfaces, etc.).

  • Éléments clésd’éléments de conception tels que les modèles appliqués à l’intérieur du composant (par exemple, répertoires, services, DTOs, entités métier, usines).

En pratique, ce niveau est presque toujours undiagramme de classes UML (ou une variante simplifiée) centré sur un (ou très peu) composants.

Précision importante :

  • Le niveau 4 estpas sur l’ensemble de la base de code.

  • Il ne s’agit paspasnécessaire pour afficher chaque classe.

  • Il cartographie seulement la structure essentiellenécessaire pour comprendre comment un composant complexe ou critique est réellement construit.

  • La recommandation officielle C4 : idéalement générée automatiquementà partir du code source (via des outils comme Doxygen, Javadoc + plugins UML, yWorks, Structurizr, CodeSee, etc.) plutôt que dessinée à la main.

Quand créer un diagramme de code

Créez les diagrammes de niveau 4 avec parcimonie — uniquement dans ces situations :

  • Le composant est très complexe, critique pour la mission, ou difficile à comprendreà partir du code source seul (par exemple, logique métier complexe, utilisation intensive de patrons de conception, flux cryptographiques, machines à états, code hérité chargé de dettes techniques).

  • Vous travaillez dans un secteur industrie fortement régulée (finance, santé, aérospatiale, défense) où les auditeurs ou les équipes de conformité exigent une cartographie explicite de l’architecture → conception → implémentation.

  • Pendant un refactoring majeur, le strangulation d’un composant hérité, ou l’introduction d’un nouveau patron architectural (hexagonal, propre, tranche verticale, agrégats DDD) — les vues avant/après aident à communiquer le changement.

  • Intégration de développeurs expérimentés ou architectesqui doivent rapidement comprendre la structure interne non évidente d’un morceau de code à haut risque.

  • Vous avez déjà investi dansgénération automatiquedes outils — donc le maintien du niveau 4 coûte presque rien.

  • L’équipe a convenu que« documentation vivante »au niveau de la classe est précieuse pour ce sous-système spécifique.

Ne créez PAS de diagrammes de niveau 4 lorsque :

  • La structure des composants est évidente grâce à une bonne nomenclature, à une taille réduite ou à un code propre (la plupart des microservices modernes rentrent dans cette catégorie).

  • Vous avez déjàde bons tests unitaires/intégration, des interfaces claires, etdes commentaires explicatifs.

  • La majorité de l’équipe peut naviguer facilement dans le code.

  • Le coût de maintenance dépasse l’avantage (les diagrammes de classes dessinés à la main deviennent vite obsolètes).

Simon Brown et la plupart des praticiens insistent :La plupart des équipes n’ont jamais besoin du niveau 4. Les niveaux 1 + 2couvrent 80 à 90 % des besoins de communication ;Le niveau 3gère le reste. Le niveau 4 est l’exception, pas la règle.

Pourquoi utiliser des diagrammes de code ? (Lorsqu’ils apportent de la valeur)

  • Ponctuer l’architecture ↔ l’implémentation— Montre comment les composants de haut niveau sont réellement réalisés dans le code.

  • Clarifier la conception interne complexe— Révèle l’utilisation de motifs (Stratégie, Factory, Decorateur, Repository), les violations de découpage en couches, le couplage étroit ou une modélisation intelligente du domaine.

  • Soutien aux audits et à la conformité — Démontre que les décisions architecturales sont bien appliquées dans le code.

  • Aider les discussions sur le refactoring et la migration — Les structures de classes avant/après rendent les propositions concrètes.

  • Réduire le « savoir tribal » — Aide les nouveaux recrutés seniors à comprendre plus rapidement les parties complexes que par la lecture de tous les fichiers sources.

  • Les versions générées automatiquement deviennent des « documents vivants » — Si des outils sont en place, elles restent précises avec presque aucun effort.

Comment créer un excellent diagramme de code (étape par étape + meilleures pratiques)

  1. Choisissez UN composant — Généralement issu d’un diagramme de niveau 3 où la complexité interne justifie le zoom.

  2. Décider : dessiné à la main ou généré ?

    • Dessiné à la main → uniquement pour les ateliers, les propositions ou les zones trop chaotiques pour les outils automatiques.

    • Généré → préféré (PlantUML peut encore être utilisé pour styliser/ajuster la sortie).

  3. Concentrez-vous sur l’essentiel — Montrez :

    • Classes/interfaces clés

    • Relations importantes (→ dépendance, — composition, <| réalisation, ^ héritage)

    • Agrégats, entités, objets valeur (style DDD)

    • Schémas critiques ou anti-schémas que vous souhaitez mettre en évidence

  4. Gardez-le simple — Maximum 8 à 15 classes. Si plus grand → diviser en diagrammes ciblés (par exemple, « tranche d’authentification », « entités de traitement de commande »).

  5. Meilleures pratiques

    • Privilégiez la génération automatique lorsque c’est possible (moins de déphasage).

    • Utilisez syntaxe PlantUML classDiagram syntaxe — propre et versionnable.

    • Ajoutez notes pour les décisions non évidentes (par exemple : « Utilise un modèle de domaine anémique – refonte prévue »).

    • Éviter d’afficher tout — omettre les accesseurs/setteurs triviaux, les classes utilitaires.

    • Stockez dans le référentiel → traitez comme du code (validez les fichiers .puml près du composant).

    • Utilisez avec parcimonie — un par composant complexe, pas par microservice.

    • Combinez avec vues dynamiques (sequence/collaboration) si le flux à l’exécution est plus important que la structure statique.

Exemple PlantUML – Composant d’authentification (extension du style Big Bank plc)

Voici un exemple réaliste de niveau 4 zoomant sur le Composant de sécurité / d’authentification issu des diagrammes d’application API précédents.

@startuml
title C4 Niveau 4 – Diagramme de code : Authentification dans l'application API

skinparam monochrome true
skinparam shadowing false
skinparam class {
  BackgroundColor White
  BorderColor Black
  ArrowColor Black
}

classe abstraite AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

interface UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' Relations
JwtAuthenticationProvider -up-> JwtTokenProvider : utilise
JwtAuthenticationProvider -up-> UserDetailsService : utilise
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : utilise
UserRepository --> User : retourne

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  Flux d'authentification principal pour les sessions sans état basées sur JWT
end note

note bottom of JwtTokenProvider
  Signe et vérifie les JWTs en utilisant HS512
end note

@enduml

Ce petit diagramme :

  • Se concentre uniquement sur les détails internes de l’authentification

  • Montre les classes clés, les interfaces et les dépendances

  • Met en évidence des modèles (fournisseur, répertoire)

  • Utilise des notes pour le contexte

Collez dans n’importe quel rendu PlantUML — personnalisez pour votre domaine (par exemple : remplacez JWT par OAuth2, ajoutez des classes MFA, etc.).

Rappel sommaire: Le niveau 4 est puissant mais rare. Utilisez-le intentionnellement, privilégiez la génération automatique, et n’autorisez jamais qu’il devienne du travail fastidieux. La plus grande valeur du C4 provient des niveaux 1 à 3. Bonne modélisation (sélective) !

Ressource

Cette publication est également disponible en Deutsch, English, Español, فارسی : liste des langues séparées par une virgule, English : dernière langue.