de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

C4 Model Level 3 Deep Dive: Opanowanie diagramów składników w celu ujawnienia struktury wewnętrznej i odpowiedzialności

Co to jest diagram składników C4?

Diagram składników toPoziom 3 w modelu C4 Simona Brown. Przybliża jedno określone środowisko (z diagramu środowiska poziomu 2), aby pokazać:

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

  • Z logicznych elementów budowlanych (składników), które tworzą to środowisko.

  • Jak te składniki oddziałują na siebie.

  • Odpowiedzialności i technologie implementacji (w wyższym poziomie niż klasy — myśl o Spring Beans, modułach, usługach, kontrolerach, fasadach itp.).

  • Kluczowe interfejsy lub umowy między składnikami (często wynikające z relacji).

Ważna wyjaśnienie: „Składnik” w C4 to nie klasa. To logiczne grupowanie klas za dobrze zdefiniowanym interfejsem — coś, co ma jasną odpowiedzialność, może być rozwijane/testowane/wdrażane dość niezależnie (w ramach środowiska), ale nie jest nie oddzielnie wdrażalne jak środowisko.

Przykłady składników:

  • Kontroler REST / Kontroler Web

  • Usługa / Przypadek użycia / Usługa aplikacji

  • Repozytorium / Obiekt dostępu do danych

  • Model domeny / Encja

  • Bezpieczeństwo / Moduł uwierzytelniania

  • Wysyłacz powiadomień

  • Facade do systemu zewnętrznego

  • Silnik reguł biznesowych

  • Warstwa buforowania

Diagram pozostaje logiczny / wystarczająco niezależny od implementacji — bez atrybutów klas, sygnatur metod ani pełnych szczegółów klasy UML (to poziom 4 kodu, który jest opcjonalny i rzadki).

Kiedy tworzyć diagram komponentów

Twórz (i utrzymuj) diagram komponentów tylko wtedy, gdy:

  • Wybrany kontener to dostatecznie złożony że jego struktura wewnętrzna nie jest oczywista z nazwy i opisu samego.

  • Nowi członkowie zespołu (szczególnie programiści backendu) często pytają: „Jak faktycznie zaimplementowana jest funkcja X wewnątrz tej usługi/interfejsu API?”

  • Jesteś refaktoryzując, dzieliąc, lub wyodrębniając logikę wewnątrz kontenera i musisz wyjaśnić granice/odpowiedzialności.

  • Przeprowadzasz szczegółowe dyskusje projektowe, przeglądy kodu, lub przekazywanie obowiązków w trybie on-call dla konkretnego kontenera.

  • Chcesz zarejestrować kluczowe decyzje architektoniczne wewnątrz kontenera (np. architektura heksagonalna, pionowy przekrój, rozdzielenie CQRS, punkt wymuszania zabezpieczeń).

  • Zidentyfikowałeś długi techniczny, klasy bożyste, lub silne powiązania wewnątrz kontenera i chcesz wizualizować stan przed oczyszczeniem.

  • Przyłączasz do zespołu starszych programistów/architektów, którzy muszą szybko zrozumieć strukturę modułów.

Nie twórz diagramów komponentów dla:

  • Proste kontenery (interfejs CRUD z jednym kontrolerem + jedną usługą + jednym repozytorium — oczywista struktura).

  • Największość mikroserwisów (często na tyle małych, że wystarczy poziom kontenera).

  • Kontenery front-end (aplikacje React/Vue — zwykle lepiej pokazywać za pomocą drzew komponentów lub storybook).

  • Kiedy poziom 2 (kontener) + dobra struktura kodu/nazewnictwo już przekazuje wszystko, co potrzebne.

Simon Brown poleca: Większość zespołów może zatrzymać się na poziomie 1 + 2. Przechodź do poziomu 3 tylko dla złożonych / ryzykownych / kluczowych / o wysokim tempie zmian kontenerów.

Dlaczego używać diagramów komponentów? (Główne korzyści)

  • Ujednolica odpowiedzialności wewnętrzne — Pokazuje rozdzielenie odpowiedzialności (np. kontrolery vs usługi vs dostęp do danych vs integracja zewnętrzna).

  • Wykrywa powiązania i zależności — Ujawnia komponenty bogów, cykliczne zależności lub nadmierną zależność od kodu infrastruktury.

  • Ułatwia lepsze wdrażanie i przekazywanie wiedzy — Deweloperzy szybciej rozumieją granice modułów niż czytając wszystkie pliki źródłowe.

  • Kieruje refaktoryzacją i ewolucją — Wizualna podstawa przed/po podzieleniu monolitu lub wprowadzeniu wzorców (porty i adaptery, pionowe kawałki).

  • Umożliwia przeglądy architektury i modelowanie zagrożeń — Wskazuje, gdzie odbywa się weryfikacja, autoryzacja, rejestrowanie itp.

  • Architektura jako kod — Gdy przechowywane w PlantUML → wersjonowane razem z kodem, możliwe do porównania, przeglądalne w PR.

  • Skaluje komunikację — Starszy deweloper dba o odpowiedzialności komponentów; młodsi dbają o miejsce umieszczenia nowego kodu.

Jak stworzyć świetny diagram komponentów (krok po kroku + najlepsze praktyki)

  1. Wybierz JEDEN kontener — Zacznij od najbardziej złożonego lub krytycznego pod kątem biznesowym (często głównego interfejsu API / usługi backendowej).

  2. Skopiuj kontekst z poziomu 2 — Uwzględnij zewnętrzne akcje (inne kontenery, osoby, zewnętrzne systemy), które oddziałują na ten kontener.

  3. Narysuj granicę kontenera — Użyj Granica_Kontenera w PlantUML, aby jasno określić „wewnątrz tego kontenera”.

  4. Zidentyfikuj komponenty — Zadaj pytania:

    • Jakie są główne moduły / Spring Beans / pakiety / ograniczone konteksty wewnątrz?

    • Gdzie docierają przychodzące żądania? (kontrolery/obsługi)

    • Gdzie jest koordynowana logika biznesowa?

    • Gdzie dostęp do danych / buforowane / weryfikowane?

    • Gdzie obsługiwane są kwestie dotykające całej aplikacji? (bezpieczeństwo, rejestrowanie)

    • Czy są warstwy fasad / warstwy anty-zakłócenia dla systemów dziedziczonych/zewnętrznych?

  5. Dodaj technologię i krótki opis — Nazwa, technologia (Spring Service, .NET Handler, Go Module itp.), krótki cel (< 15 słów).

  6. Zdefiniuj interakcje — Pokaż kierunek i cel (Używa, Wywołuje, Odczytuje z, Publikuje zdarzenia do). Protokół często pomijany na tym poziomie.

  7. Najlepsze praktyki

    • Ogranicz zakres — Maksymalnie 6–12 składników na diagram. Jeśli więcej → utwórz skupione podwidoki (np. „kawałek uwierzytelniania”).

    • Nadaj znaczące nazwy — Preferuj „Usługa umieszczania zamówień” przed „OrderService”.

    • Pokaż odpowiedzialność, a nie klasy — Unikaj wymieniania każdej klasy; grupuj logicznie.

    • Używaj ikon oszczędnie — Tylko wtedy, gdy pomagają wyjaśnić technologię (ikony Spring, .NET).

    • Włącz legendę — Pomaga nowym czytelnikom.

    • Utrzymuj czysty układ — UŁOŻENIE_Z_LEGENDĄ(), UŁOŻENIE_Z_GÓRY_NA_DÓŁ().

    • Wersja w repozytorium — Pliki .puml obok kodu kontenera.

    • Iteruj — Aktualizuj podczas szczytów refaktoryzacji lub kwartalnych przeglądów stanu architektury.

Przykład PlantUML – System internetowego bankowości aplikacja API (styl klasyczny Big Bank plc)

Oto przykład produkcyjny wykorzystujący oficjalną bibliotekę C4-PlantUML — najczęściej cytowany przykład z rzeczywistego świata.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

tytuł Diagram składników: System internetowego bankowości – aplikacja API

' Aktorzy / zewnętrzne części poziomu kontenera
Kontener(spa, "Aplikacja jednostronicowa", "JavaScript & Angular", "Dostarcza interfejs internetowego bankowości przez przeglądarkę")
Kontener(mobile, "Aplikacja mobilna", "iOS/Android", "Dostarcza ograniczoną funkcjonalność bankowości mobilnej")
KontenerDb(baza_danych, "Baza danych bankowości", "PostgreSQL", "Przechowuje preferencje użytkownika, dane w pamięci podręcznej, sesje")
System_Ext(mainframe, "System bankowości główny", "Mainframe – główne konta i transakcje")

' Kontener, do którego się przybliżamy
Kontener_Ograniczony(api, "Aplikacja API") {
    Składnik(signInCtrl, "Kontroler logowania", "Spring MVC REST Controller", "Obsługuje uwierzytelnianie i tworzenie sesji")
    Składnik(accountsCtrl, "Kontroler podsumowania kont", "Spring MVC REST Controller", "Dostarcza sald i podsumowania kont")
    Składnik(resetPwdCtrl, "Kontroler resetu hasła", "Spring MVC REST Controller", "Zarządza przepływem resetu hasła")
    
    Składnik(bezpieczeństwo, "Składnik bezpieczeństwa", "Spring Bean", "Tokeny JWT, hashowanie haseł, sprawdzanie ról")
    Składnik(accountService, "Składnik zarządzania kontami", "Spring Bean / Usługa", "Koordynuje zapytania do kont i reguły biznesowe")
    Składnik(mainframeFacade, "Facade bankowości mainframe", "Spring Bean", "Warstwa antykorupcji dla starszego mainframe")
    Składnik(emailNotifier, "Składnik powiadomień e-mail", "Spring Bean", "Wysyła potwierdzenia i e-maile resetu")
}

' Relacje wewnątrz granicy
Rel(signInCtrl, bezpieczeństwo, "Używa")
Rel(accountsCtrl, accountService, "Używa")
Rel(resetPwdCtrl, bezpieczeństwo, "Używa")
Rel(resetPwdCtrl, emailNotifier, "Używa")
Rel(accountService, mainframeFacade, "Używa")
Rel(accountService, baza_danych, "Odczytuje i zapisuje do", "JDBC")
Rel(mainframeFacade, mainframe, "Używa", "XML/HTTPS")
Rel(emailNotifier, baza_danych, "Odczytuje preferencje użytkownika", "JDBC")

' Wejściowe wywołania z front-endów
Rel(spa, signInCtrl, "Używa", "JSON/HTTPS")
Rel(spa, accountsCtrl, "Używa", "JSON/HTTPS")
Rel(spa, resetPwdCtrl, "Używa", "JSON/HTTPS")
Rel(mobile, signInCtrl, "Używa", "JSON/HTTPS")
Rel(mobile, accountsCtrl, "Używa", "JSON/HTTPS")
Rel(mobile, resetPwdCtrl, "Używa", "JSON/HTTPS")

UŁOŻENIE_Z_LEGENDĄ()
UŁOŻENIE_Z_LEWEJ_NA_PRAWO()

@enduml

To generuje:

  • Jasna granica wokół kontenera API

  • Logiczne grupowanie kontrolerów, usług i fasad

  • Precyzyjne odpowiedzialności

  • Kluczowe interakcje i zależności

  • Automatyczna legenda dla czytelności

Wklej do renderera PlantUML (online lub IDE) — dostosuj nazwy/technologie do swojego systemu.

Użyj tego wzorca jako szablonu początkowego. Celem jest zawsze skuteczna komunikacja w zespole — nie piękno diagramu. Miłego modelowania!

Zasób diagramu komponentów C4

Ten post dostępny jest również w Deutsch, English, Español, فارسی, Français, English, Bahasa Indonesia, 日本語, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文