de_DEen_USes_ESfa_IRfr_FRhi_IN

Vollständig hineinzoomen: Verständnis von C4-Code-Diagrammen – Was sie sind, wann sie Wert hinzufügen und praktische PlantUML-Beispiele

Was ist ein C4-Code-Diagramm?

Das Code-Diagramm istEbene 4— die tiefste und detaillierteste Ebene im C4-Modell von Simon Brown.

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

Es zeigt:

  • Klassen, Schnittstellen, Aufzählungen, Aufzeichnungen, oder andere auf Code-Ebene befindliche Konstrukte, die ein bestimmtesKomponente (aus Ebene 3).

  • Beziehungen zwischen diesen Klassen (Vererbung, Zusammensetzung, Abhängigkeit, Realisierung von Schnittstellen usw.).

  • WichtigeDesign-Elemente wie Muster, die innerhalb der Komponente angewendet werden (z. B. Repositories, Services, DTOs, Domänenentitäten, Factorys).

In der Praxis ist diese Ebene fast immer einUML-Klassendiagramm (oder eine vereinfachte Variante), das sich auf eine (oder sehr wenige) Komponenten konzentriert.

Wichtige Klärung:

  • Ebene 4 befasst sich nichtnicht mit dem gesamten Codebase.

  • Es handelt sich nichtnicht erforderlich, um jede Klasse anzuzeigen.

  • Es zeigt nur die wesentliche Struktur notwendig, um zu verstehen, wie ein komplexer oder kritischer Bestandteil tatsächlich aufgebaut ist.

  • Die offizielle C4-Empfehlung: idealerweise automatisch generiert aus dem Quellcode (über Werkzeuge wie Doxygen, Javadoc + UML-Plugins, yWorks, Structurizr, CodeSee usw.) statt von Hand gezeichnet.

Wann man ein Code-Diagramm erstellen sollte

Erstellen Sie Level-4-Diagramme sparsam – nur in diesen Situationen:

  • Der Bestandteil ist sehr komplex, lebenswichtig, oder schwer verständlich aus dem Quellcode allein (z. B. komplexe Domänenlogik, intensiver Einsatz von Gestaltungsmustern, kryptografische Abläufe, Zustandsmaschinen, veralteter Code voller technischer Schulden).

  • Sie arbeiten in einer hoch regulierten Branche (Finanzwesen, Gesundheitswesen, Luft- und Raumfahrt, Verteidigung), in der Prüfer oder Compliance-Teams eine explizite Abbildung von Architektur → Design → Implementierung verlangen.

  • Während umfassender Umgestaltung, einen veralteten Bestandteil verdrängen, oder Einführung eines neuen Architekturmusters (hexagonal, sauber, vertikaler Schnitt, DDD-Aggregate) – Vorher/Nachher-Darstellungen helfen, die Änderung zu vermitteln.

  • Onboarding Senior-Entwickler oder Architektendie schnell die nicht offensichtliche interne Struktur eines hochriskanten Codeabschnitts verstehen müssen.

  • Sie haben bereits inAutomatisierte GenerierungTooling – daher entstehen für die Pflege von Level 4 praktisch keine Kosten.

  • Das Team hat vereinbart, dass„lebende Dokumentation“auf Klassenebene für dieses spezifische Subsystem wertvoll ist.

Erstellen Sie keine Diagramme der Ebene 4, wenn:

  • Die Komponentenstruktur ist anhand guter Namensgebung, geringer Größe oder sauberem Code offensichtlich (die meisten modernen Microservices fallen hierher).

  • Sie haben bereitsgute Einheit-/Integrationstests, klare Schnittstellen, underklärende Kommentare.

  • Der Großteil des Teams kann sich leicht im Code zurechtfinden.

  • Die Wartungskosten überwiegen den Nutzen (handgezeichnete Klassendiagramme werden sehr schnell veraltet).

Simon Brown und die meisten Praktiker betonen:Die meisten Teams benötigen Ebene 4 nie. Ebenen 1 + 2decken 80–90 % der Kommunikationsanforderungen ab;Ebene 3erledigt den größten Teil des Restes. Ebene 4 ist die Ausnahme, nicht die Regel.

Warum Code-Diagramme verwenden? (Wenn sie Wert schaffen)

  • Brücke zwischen Architektur ↔ Implementierung– Zeigt, wie hochrangige Komponenten tatsächlich im Code realisiert werden.

  • Komplexen internen Entwurf klären– Bringt die Verwendung von Mustern (Strategy, Factory, Decorator, Repository), Verstöße gegen die Schichtung, enge Kopplung oder geschickte Domänenmodellierung ans Licht.

  • Unterstützung von Audits und Compliance — Zeigt, dass architektonische Entscheidungen in den Code umgesetzt werden.

  • Unterstützung bei Refactoring- und Migrationsdiskussionen — Vorher/Nachher-Klassenstrukturen machen Vorschläge greifbar.

  • Reduzierung des „tribalen Wissens“ — Hilft neuen Senior-Mitarbeitern, komplexe Teile schneller zu verstehen als durch das Lesen aller Quelldateien.

  • Automatisch generierte Versionen werden zu „lebenden Dokumenten“ — Wenn die Werkzeuge vorhanden sind, bleiben sie mit fast keinem Aufwand aktuell.

Wie man ein großartiges Code-Diagramm erstellt (Schritt-für-Schritt-Anleitung + Best Practices)

  1. Wählen Sie EINEN Komponenten — Meist aus einem Level-3-Diagramm, bei dem die interne Komplexität die Vergrößerung rechtfertigt.

  2. Entscheiden: von Hand gezeichnet oder generiert?

    • Von Hand gezeichnet → nur für Workshops, Vorschläge oder Bereiche, die zu unübersichtlich für automatische Werkzeuge sind.

    • Generiert → bevorzugt (PlantUML kann weiterhin zur Formatierung/Anpassung der Ausgabe verwendet werden).

  3. Fokussieren Sie sich auf das Wesentliche — Zeigen Sie:

    • Wichtige Klassen/Schnittstellen

    • Wichtige Beziehungen (→ Abhängigkeit, — Zusammensetzung, <| Realisierung, ^ Vererbung)

    • Aggregatobjekte, Entitäten, Wertobjekte (DDD-Stil)

    • Kritische Muster oder Anti-Muster, die Sie hervorheben möchten

  4. Bleiben Sie klein — Maximal 8–15 Klassen. Bei größeren Diagrammen in fokussierte Diagramme aufteilen (z. B. „Authentifizierungs-Slice“, „Entitäten für Bestellverarbeitung“).

  5. Best Practices

    • Bevorzugen Sie Automatische Generierung sofern möglich (geringerer Verfall).

    • Verwenden Sie PlantUML classDiagram Syntax – sauber und versionierbar.

    • Fügen Sie Hinweisefür nicht offensichtliche Entscheidungen (z. B. „Verwendet anämisches Domänenmodell – geplante Umgestaltung“).

    • Zeigen Sie nicht an alles— lassen Sie einfache Getter/Setters und Hilfsklassen weg.

    • Im Repository speichern → als Code behandeln (committe .puml-Dateien nahe am Komponenten).

    • Sparsam verwenden — ein pro komplexes Komponenten, nicht pro Mikrodienst.

    • Kombinieren Sie mit dynamische Ansichten (Sequenz/Kooperation), wenn der Laufzeitfluss wichtiger ist als die statische Struktur.

PlantUML-Beispiel – Authentifizierungs-Komponente (Erweiterung im Stil von Big Bank plc)

Hier ist ein realistisches Level-4-Beispiel, das sich auf die Sicherheits-/Authentifizierungs-Komponente aus den früheren API-Anwendungsdiagrammen.

@startuml
title C4 Level 4 – Code-Diagramm: Authentifizierung innerhalb der API-Anwendung

skinparam monochrome true
skinparam shadowing false
skinparam class {
  Hintergrundfarbe Weiß
  Randfarbe Schwarz
  Pfeilfarbe Schwarz
}

abstrakte Klasse AuthenticationProvider {
  + authenticate(credentials): Authentication
}

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

class JwtTokenProvider {
  - geheimeSchlüssel: String
  - GültigkeitsdauerInMillisekunden: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

Schnittstelle UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

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

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

class User {
  - username: String
  - passwortHash: String
  - rollen: Set<Role>
}

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

' Beziehungen
JwtAuthenticationProvider -up-> JwtTokenProvider : verwendet
JwtAuthenticationProvider -up-> UserDetailsService : verwendet
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : verwendet
UserRepository --> User : gibt zurück

JwtAuthenticationToken .up.|> Authentication

Hinweis rechts von JwtAuthenticationProvider
  Primärer Authentifizierungsablauf für JWT-basierte zustandslose Sitzungen
end note

Hinweis unten bei JwtTokenProvider
  Signiert und überprüft JWTs mit HS512
end note

@enduml

Dieses kleine Diagramm:

  • Konzentriert sich ausschließlich auf die internen Abläufe der Authentifizierung

  • Zeigt zentrale Klassen, Schnittstellen und Abhängigkeiten

  • Hebt Muster hervor (Provider, Repository)

  • Verwendet Hinweise zur Kontextergänzung

Einfügen in jeden PlantUML-Renderer — anpassen an Ihr Domänenmodell (z. B. JWT durch OAuth2 ersetzen, MFA-Klassen hinzufügen usw.).

Zusammenfassungserinnerung: Level 4 ist mächtig, aber selten. Verwenden Sie es bewusst, bevorzugen Sie die automatische Generierung, und lassen Sie es niemals zu lästiger Arbeit werden. Der größte Wert im C4 kommt aus den Ebenen 1–3. Frohes (ausgewähltes) Modellieren!

Ressource

Der Artikel ist auch in English, Español, فارسی, Français and English verfügbar.