C4 Component Diagram: Vollständiger Leitfaden mit Beispielen

Das Component-Diagramm ist Ebene 3 des C4-Modells -- und es ist die Ebene mit dem schlechtesten Ruf. Ebene 1 (System Context) ist leicht zu zeichnen und ändert sich selten. Ebene 2 (Container) bildet sauber auf das ab, was Sie deployen. Aber Ebene 3? Sie zoomt in das Innere eines einzelnen Containers hinein, was bedeutet, dass sie sich jedes Mal ändert, wenn ein Entwickler ein Package umstrukturiert. Die meisten Teams überspringen sie entweder ganz oder zeichnen sie einmal und lassen sie vergammeln.

Das ist schade, denn ein gut gepflegtes Component-Diagramm ist das mit Abstand nützlichste Artefakt für einen Entwickler, der in eine Codebasis einsteigt. Es beantwortet die Frage, die jeder Neuling stellt: „Wo lebt eigentlich die Logik für X?"

Dieser Leitfaden behandelt, was ein C4-Component-Diagramm ist, wie es sich von einem UML-Component-Diagramm unterscheidet, wann sich Ebene 3 den Pflegeaufwand wert ist (und wann nicht), ein vollständig durchgearbeitetes Beispiel, die Fehler, die Component-Diagramme nutzlos machen, und wie Sie sie korrekt halten, ohne alles von Hand zu erledigen.

Wenn Sie mit dem C4-Modell selbst noch nicht vertraut sind, beginnen Sie mit unserem vollständigen Leitfaden zum C4-Modell und kommen Sie dann hierher zurück.

Was ist ein C4-Component-Diagramm?

Ein Component-Diagramm öffnet einen Container -- eine deploybare Einheit aus Ihrem Container-Diagramm -- und enthüllt die Komponenten darin.

In C4-Begriffen ist eine Komponente eine kohärente Gruppierung verwandter Funktionalität hinter einer wohldefinierten Schnittstelle. Denken Sie an die wichtigsten Bausteine innerhalb einer Anwendung:

• Eine HTTP-Controller- oder Handler-Gruppe
• Ein Domain-Service, der einen Ausschnitt der Geschäftslogik besitzt
• Ein Repository oder eine Datenzugriffsschicht
• Ein Client, der eine externe API kapselt
• Eine Middleware, ein Interceptor oder ein Background Worker

Das Schlüsselwort ist Gruppierung. Eine Komponente ist eine Abstraktion über Code, keine einzelne Klasse oder Datei. Die OrderService-Komponente mag sich über ein Dutzend Dateien erstrecken, aber konzeptionell ist sie eine Sache: der Teil des Containers, der für die Bestell-Geschäftslogik zuständig ist. Wie die Glossardefinition es formuliert, ist eine C4-Komponente „eine übergeordnete Gruppierung von Code mit einer einzigen Verantwortlichkeit" -- keine 1:1-Abbildung auf eine Klasse der Programmiersprache.

Was das Component-Diagramm beantwortet

• Wie ist dieser Container intern strukturiert?
• Welche Komponente besitzt welche Verantwortlichkeit?
• Wie arbeiten Komponenten zusammen, um eine Anfrage zu bearbeiten?
• Wo entstehen Aufrufe an Datenbanken und externe Systeme?

Was es bewusst weglässt

• Einzelne Klassen, Schnittstellen und Funktionen (das ist Ebene 4, das Code-Diagramm)
• Die Interna anderer Container
• Deployment- und Infrastrukturdetails

Ein Container pro Diagramm, nur Komponenten. Wenn Sie sich dabei ertappen, Klassen zu zeichnen, haben Sie zu weit hineingezoomt.

C4-Component-Diagramm vs. UML-Component-Diagramm

Das verwirrt die Leute ständig, denn auch UML hat etwas, das „Component-Diagramm" heißt -- und es ist nicht dasselbe.

Ein UML-Component-Diagramm modelliert Softwarekomponenten als Einheiten mit angebotenen und benötigten Schnittstellen (die berühmte Lollipop-und-Socket-Notation), oft mit Betonung auf physischem Packaging, Artefakten und Deployment-Beziehungen. Es kommt mit formalen Notationsregeln und einem präzisen Metamodell.

Ein C4-Component-Diagramm ist lockerer und pragmatischer. Es ist schlicht Ebene 3 einer Zoom-Hierarchie: Boxen für Komponenten, Pfeile für Beziehungen, eine kurze Textbeschreibung an jeder. Es gibt keine spezielle Notation zu lernen. Der Wert ergibt sich aus der Hierarchie -- jede Komponenten-Box lebt innerhalb eines bestimmten Containers, der innerhalb eines bestimmten Systems lebt -- nicht aus der Notation selbst.

In der Praxis: Wenn jemand in einem C4-Kontext um ein „Component-Diagramm" bittet, will er eine strukturelle Karte des Inneren eines Containers, die ein neuer Entwickler in zwei Minuten lesen kann. Wenn er Lollipop-Schnittstellen und <<artifact>>-Stereotypen will, fragt er nach UML.

Wann lohnt sich die Pflege von Ebene 3?

Hier die ehrliche Antwort, die die meisten Leitfäden auslassen: Ebene 3 ist die Ebene mit dem schlechtesten Aufwand-zu-Stabilität-Verhältnis im gesamten C4-Modell.

Context-Diagramme ändern sich ein paar Mal im Jahr. Container-Diagramme ändern sich, wenn Sie einen Service hinzufügen oder entfernen -- vielleicht monatlich. Component-Diagramme ändern sich jedes Mal, wenn jemand ein Package refaktoriert, einen Service extrahiert oder ein Modul umbenennt. Wenn Sie sie von Hand pflegen, melden Sie sich zur ständigen Gartenarbeit an, und in dem Moment, in dem Sie aufhören, beginnt das Diagramm zu lügen.

Seien Sie also bewusst darüber, wo Sie diesen Aufwand investieren.

Erstellen Sie ein Component-Diagramm, wenn:

• Der Container wirklich komplex ist. Eine Backend-API mit 15 Packages, mehreren Schichten und nicht offensichtlichen Grenzen verdient eine Karte. Ein CRUD-Service mit drei Endpunkten nicht.
• Die Struktur ein bewusstes Design verkörpert. Wenn Sie hexagonale Architektur, CQRS oder ein sauberes Schichtungsschema verwenden, macht das Component-Diagramm die beabsichtigte Struktur explizit -- und gibt Ihnen etwas, worauf Sie zeigen können, wenn ein Pull Request sie verletzt.
• Mehrere Teams denselben Container berühren. Geteilter Code braucht ein geteiltes mentales Modell.
• Onboarding ein Engpass ist. Wenn neue Entwickler Wochen brauchen, um sich in einem Container zurechtzufinden, zahlt sich ein Component-Diagramm bereits mit der ersten Einstellung aus.

Überspringen Sie es, wenn:

• Der Container klein ist und seine Ordnerstruktur selbsterklärend ist.
• Der Container von Dritten stammt (Sie zeichnen nicht das Innere von Redis).
• Niemand sich verpflichtet, es aktuell zu halten. Ein veraltetes Component-Diagramm ist schlimmer als keines -- es schickt Entwickler selbstbewusst zu Code, der nicht mehr existiert.

Genau deshalb ist Ebene 3 die Ebene, die die meisten Teams entweder überspringen oder automatisieren. Komponenten aus der tatsächlichen Codestruktur zu generieren -- und sie dagegen zu verifizieren -- beseitigt die Pflegesteuer, die handgezeichnete Diagramme tötet. Mehr dazu unten.

Ein durchgearbeitetes Beispiel: Innerhalb eines API-Containers

Machen wir das konkret. Nehmen Sie die E-Commerce-Plattform aus unserem C4-Modell-Leitfaden und zoomen Sie in einen einzelnen Container hinein: die Order API (Go). Auf Ebene 2 ist sie eine Box. Auf Ebene 3 öffnet sie sich in Komponenten.

Die Komponenten

Die Beziehungen

[Auth Middleware] --> [Order Controller] : Passes authenticated requests
[Auth Middleware] --> [Admin Controller] : Passes authenticated requests (admin role)
[Order Controller] --> [Order Service] : Delegates business operations
[Admin Controller] --> [Order Service] : Delegates back-office operations
[Order Service] --> [Order Repository] : Reads/writes orders
[Order Service] --> [Payment Client] : Authorizes and captures payments
[Order Service] --> [Email Adapter] : Triggers transactional emails
[Order Service] --> [Event Publisher] : Emits domain events
[Order Repository] --> [Order Database (PostgreSQL)] : SQL
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Email Adapter] --> [Email Service (SendGrid)] : HTTPS/REST
[Event Publisher] --> [Message Queue (Kafka)] : Publishes events

Beachten Sie, dass die Datenbank, Stripe, SendGrid und Kafka an den Rändern erscheinen. Sie sind keine Komponenten dieses Containers -- sie sind benachbarte Container und externe Systeme -- aber zu zeigen, wo die ausgehenden Aufrufe entstehen, ist genau das, was das Diagramm nützlich macht.

Was dieses Diagramm einem neuen Entwickler verrät

In dreißig Sekunden lernt ein Entwickler, der zu diesem Team stößt:

1. Der Request-Pfad: Middleware → Controller → Service → Repository. Es gibt genau einen Ort, an dem Geschäftslogik lebt, und das ist nicht der Controller.
2. Die Grenzen: Alle externen Aufrufe gehen über dedizierte Adapter (Payment Client, Email Adapter). Wenn Sie mit Stripe sprechen müssen, erweitern Sie den Client; Sie importieren das SDK nicht in einem Controller.
3. Die Seiteneffekte: Bestellungen erzeugen Events auf Kafka und E-Mails über SendGrid. Wenn eine E-Mail nicht versendet wird, wissen Sie, welche zwei Komponenten Sie prüfen müssen.
4. Wo Code hinzuzufügen ist: Ein neues „Geschenkkarten"-Feature braucht offensichtlich Änderungen im Controller, im Service und möglicherweise einen neuen Client -- und das Diagramm zeigt das zu befolgende Muster.

Der letzte Punkt wird unterschätzt. Ein Component-Diagramm beschreibt nicht nur Struktur -- es schreibt sie vor. Es zeigt Mitwirkenden, wie „konsistent mit dieser Codebasis" aussieht.

Häufige Fehler bei Component-Diagrammen

Eine Klasse auf eine Komponente abbilden

Der häufigste Fehler. Wenn Ihr Container 80 Klassen hat und Ihr Component-Diagramm 80 Boxen, haben Sie ein Klassendiagramm mit zusätzlichen Schritten gezeichnet. Komponenten sind Gruppierungen: OrderController (eine Komponente) könnte fünf Handler-Klassen abdecken. Streben Sie 5-15 Komponenten pro Container an. Wenn Sie über 20 sind, sind Ihre Abstraktionen zu feingranular -- oder Ihr Container tut zu viel.

Jeden Container auf Ebene 3 dokumentieren

Symmetrie ist verlockend: „Wir haben 12 Container, also brauchen wir 12 Component-Diagramme." Widerstehen Sie dem. Die meisten dieser Diagramme werden nie gelesen und nie aktualisiert. Dokumentieren Sie die zwei oder drei Container, bei denen Komplexität tatsächlich wehtut, und lassen Sie die Ordnerstruktur für den Rest sprechen.

Das Diagramm vergammeln lassen

Ebene 3 driftet schneller als jede andere Ebene. Ein im Januar gezeichnetes Component-Diagramm beschreibt einen Container, der bis Juni wahrscheinlich nicht mehr existiert. Jedes Refactoring, jedes extrahierte Package, jedes umbenannte Modul vergrößert die Lücke. Und ein selbstbewusst falsches Diagramm ist schlimmer als gar keines: Es schickt Entwickler auf die Jagd nach Komponenten, die vor zwei Quartalen gelöscht wurden. Wenn Sie die Pflege nicht automatisieren können, setzen Sie wenigstens „Component-Diagramm aktualisieren" auf die Pull-Request-Checkliste für diesen Container.

Komponenten ohne Verantwortlichkeiten zeichnen

Eine Box mit der Beschriftung OrderManager ohne Beschreibung ist Rauschen. Jede Komponente sollte eine einzeilige Verantwortlichkeitsaussage tragen („Validiert JWT-Tokens und injiziert die Nutzeridentität"). Wenn Sie diesen Satz nicht schreiben können, ist die Komponentengrenze wahrscheinlich falsch.

Implementierungsdetails statt Struktur zeigen

Generics, Entwurfsmuster, Hilfsutilities -- nichts davon gehört auf Ebene 3. Wenn der interessante Teil einer Komponente wie sie implementiert ist, ist das eine Aufgabe für das Code-Diagramm (oder, häufiger, für den Code selbst).

Wie Archyl Component-Diagramme korrekt hält

Alles oben weist auf dieselbe Schlussfolgerung hin: Component-Diagramme sind wertvoll, aber sie von Hand zu pflegen ist ein aussichtsloses Spiel. Genau dieses Problem wurde Archyl gebaut zu lösen.

AI Discovery extrahiert Komponenten aus dem Code

Statt Komponenten von Hand zu zeichnen, verbinden Sie Ihr Repository und führen die AI Discovery aus. Archyl analysiert Ihre Codestruktur -- Packages, Module, Schichten, Namenskonventionen -- und schlägt ein C4-Modell vor, einschließlich der Komponenten innerhalb jedes Containers und der Beziehungen zwischen ihnen. Ein Go-Service mit den Packages handlers/, service/ und repository/ kommt als genau die Art von Component-Diagramm zurück, die im obigen Beispiel gezeigt wird. Sie prüfen die Vorschläge, nehmen sie an oder passen sie an, und Sie haben in Minuten ein Ebene-3-Modell.

Drift-Erkennung kennzeichnet Abweichungen

Das ist der Teil, der Ebene 3 am Leben hält. Weil Archyl Komponenten mit tatsächlichen Dateien und Verzeichnissen in Ihrem Repository verknüpft, kann es kontinuierlich prüfen, ob die dokumentierten Komponenten noch im Code existieren. Wenn jemand ein Package löscht, ein Modul umbenennt oder eine Schicht umstrukturiert, sinkt der Drift-Score und die betroffenen Komponenten werden gekennzeichnet. Ihr Component-Diagramm hört auf, eine Momentaufnahme zu sein, und wird zu einem überwachten Vertrag.

Architecture as Code

Wenn Sie explizite Definitionen der Discovery vorziehen, unterstützt Archyl das Definieren Ihres C4-Modells -- Systeme, Container, Komponenten und Beziehungen -- in YAML, das in Ihrem Repository lebt. Ihr Component-Diagramm wird versioniert, in Pull Requests geprüft und automatisch gerendert. In Kombination mit der Drift-Erkennung gibt Ihnen das Ebene-3-Dokumentation mit den Pflegeeigenschaften von Code.

FAQ

Was ist der Unterschied zwischen einem C4-Component-Diagramm und einem UML-Component-Diagramm?

Ein UML-Component-Diagramm ist eine formale Notation mit angebotenen/benötigten Schnittstellen, Artefakten und Stereotypen, fokussiert auf die Modellierung von Komponenten als verpackte Einheiten. Ein C4-Component-Diagramm ist Ebene 3 der C4-Zoom-Hierarchie: eine pragmatische Boxen-und-Pfeile-Ansicht der Komponenten innerhalb eines bestimmten Containers. C4 hat keine formalen Notationsanforderungen -- sein Wert ergibt sich aus der konsistenten Hierarchie (System → Container → Komponente → Code), nicht aus den Symbolen.

Ist eine Komponente dasselbe wie eine Klasse?

Nein. Eine C4-Komponente ist eine kohärente Gruppierung von Code hinter einer wohldefinierten Schnittstelle -- sie kann als eine Klasse, ein Dutzend Klassen, ein Package oder ein Modul implementiert sein. Wenn Ihr Component-Diagramm eine Box pro Klasse hat, sind Sie eine Zoom-Ebene zu tief gegangen.

Braucht jeder Container ein Component-Diagramm?

Nein, und der Versuch, jeden Container auf Ebene 3 zu dokumentieren, ist einer der schnellsten Wege, C4 aufzugeben. Erstellen Sie Component-Diagramme nur für Container, die komplex sind, von mehreren Teams geteilt werden oder zentral fürs Onboarding sind. Für den Rest reichen das Container-Diagramm plus eine lesbare Ordnerstruktur.

Wie viele Komponenten sollte ein Component-Diagramm zeigen?

Etwa 5 bis 15. Weniger als 5, und das Diagramm sagt Ihnen wahrscheinlich nichts, was das Container-Diagramm nicht schon gesagt hat. Mehr als 20, und entweder sind Ihre Komponentengrenzen zu feingranular oder der Container selbst sollte aufgeteilt werden.

Wollen Sie Component-Diagramme, die korrekt bleiben? Probieren Sie Archyl kostenlos aus und generieren Sie in Minuten ein C4-Modell -- Komponenten inklusive -- aus Ihrer Codebasis. Oder lesen Sie weiter: Was ist das C4-Modell? Ein vollständiger Leitfaden | Leitfaden zum C4-Container-Diagramm | Leitfaden zum C4-Code-Diagramm | Component-Diagramm im Glossar.