de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Przechodzenie do samego dna: zrozumienie diagramów kodu C4 – co to są, kiedy przynoszą wartość i praktyczne przykłady PlantUML

Co to jest diagram kodu C4?

Diagram kodu toPoziom 4— najgłębszy, najszczegółowiejszy poziom w modelu C4 Simona Brown.

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

Pokazuje:

  • Klasy, interfejsy, wyliczenia, rejestracje, lub inne konstrukcje poziomu kodu, które implementują określonykomponent (z poziomu 3).

  • Związki między tymi klasami (dziedziczenie, kompozycja, zależność, realizacja interfejsów itp.).

  • Kluczoweelementy projektowe takie jak wzorce stosowane wewnątrz komponentu (np. repozytoria, usługi, DTO, encje domeny, fabryki).

W praktyce ten poziom to niemal zawszediagram klas UML (lub uproszczona wersja), skupiona na jednym (lub bardzo małej liczbie) komponentach.

Ważna wyjaśnienie:

  • Poziom 4 tonie nie dotyczy całego kodu źródłowego.

  • Nie jestniewymagane do pokazania każdej klasy.

  • Mapuje tylko istotną strukturępotrzebną do zrozumienia, jak faktycznie budowana jest złożona lub krytyczna część.

  • Oficjalna rekomendacja C4: idealnie generowana automatyczniez kodu źródłowego (przez narzędzia takie jak Doxygen, Javadoc + wtyczki UML, yWorks, Structurizr, CodeSee itp.) zamiast rysowana ręcznie.

Kiedy tworzyć diagram kodu

Twórz diagramy poziomu 4 oszczędnie — tylko w tych sytuacjach:

  • Składnik jest bardzo złożony, krytyczny dla misji, lub trudny do zrozumieniaz samego kodu źródłowego (np. skomplikowana logika domeny, intensywne wykorzystanie wzorców projektowych, przepływy kryptograficzne, maszyny stanów, kod dziedziczony pełen długu technicznego).

  • Pracujesz w bardzo regulowanym sektorze (finanse, medycyna, lotnictwo, obrona), gdzie audytorzy lub zespoły zgodności wymagają jasnego odwzorowania architektura → projekt → implementacja.

  • W trakcie dużego przekształcenia, przytłaczania składnika dziedziczonego, lub wprowadzania nowego wzorca architektonicznego (heksagonalny, czysty, pionowy przekrój, agregaty DDD) — widoki przed/po pomagają przekazać zmianę.

  • Wprowadzanie starszych programistów lub architektówktórzy muszą szybko zrozumieć nieoczywistą wewnętrzną strukturę krytycznego pod kątem ryzyka fragmentu kodu.

  • Już zainwestowałeś w automatyczne generowanienarzędzia — więc utrzymanie poziomu 4 kosztuje niemal nic.

  • Zespół zgodził się, że „żywa dokumentacja”na poziomie klasy jest wartościowa dla tego konkretnego podsystemu.

Nie twórz diagramów poziomu 4, gdy:

  • Struktura składników jest oczywista dzięki dobremu nazewnictwu, małej wielkości lub czystemu kodowi (większość nowoczesnych mikroserwisów mieści się w tej kategorii).

  • Masz już dobrze napisane testy jednostkowe/integracyjne, jasne interfejsy, oraz objaśniające komentarze.

  • Większość zespołu łatwo porusza się po kodzie.

  • Koszty utrzymania przewyższają korzyści (ręcznie rysowane diagramy klas bardzo szybko się wygryzają).

Simon Brown i większość praktyków podkreśla: Większość zespołów nigdy nie potrzebuje poziomu 4. Poziomy 1 i 2zaspokajają 80–90% potrzeb komunikacji; Poziom 3zajmuje się większością pozostałych przypadków. Poziom 4 to wyjątek, a nie reguła.

Dlaczego używać diagramów kodu? (Gdy przynoszą wartość)

  • Łączy architekturę ↔ realizację — Pokazuje, jak komponenty najwyższego poziomu są faktycznie zrealizowane w kodzie.

  • Ujednolica skomplikowaną wewnętrzną architekturę — Wskazuje na wykorzystanie wzorców (Strategia, Fabryka, Dekorator, Repozytorium), naruszenia warstw, silne powiązania lub sprytne modelowanie domeny.

  • Wsparcie audytów i zgodności — Pokazuje, że decyzje architektoniczne są realizowane w kodzie.

  • Wsparcie dyskusji nad refaktoryzacją i migracją — Struktury klas przed i po ułatwiają zrozumienie propozycji.

  • Zmniejsz „wiedzę plemienną” — Pomaga nowym seniorom szybciej zrozumieć trudne fragmenty niż czytanie wszystkich plików źródłowych.

  • Wersje generowane automatycznie stają się „żywymi dokumentami” — Jeśli narzędzia są w miejscu, pozostają dokładne praktycznie bez wysiłku.

Jak stworzyć świetny diagram kodu (krok po kroku + najlepsze praktyki)

  1. Wybierz JEDEN komponent — Zazwyczaj z diagramu poziomu 3, gdzie złożoność wewnętrzna uzasadnia powiększenie.

  2. Zdecyduj: rysowany ręcznie czy generowany?

    • Rysowany ręcznie → tylko do warsztatów, propozycji lub obszarów zbyt chaotycznych dla narzędzi automatycznych.

    • Generowany → zalecane (PlantUML można nadal użyć do stylizacji/ dopasowania wyjścia).

  3. Skup się na istotnych elementach — Pokaż:

    • Kluczowe klasy i interfejsy

    • Ważne relacje (→ zależność, — kompozycja, <| realizacja, ^ dziedziczenie)

    • Agregaty, encje, obiekty wartości (styl DDD)

    • Krytyczne wzorce lub antywzorce, które chcesz wyróżnić

  4. Zachowaj mały rozmiar — Maksymalnie 8–15 klas. Jeśli większy → podziel na skupione diagramy (np. „kawałek uwierzytelniania”, „encje przetwarzania zamówień”).

  5. Najlepsze praktyki

    • Zalecaj generowanie automatyczne gdy to możliwe (mniejsza utrata aktualności).

    • Używaj składni PlantUML classDiagram — czytelna i wersjonowalna.

    • Dodaj notatki dla nieoczywistych decyzji (np. „Używa anemicznego modelu domeny – zaplanowana refaktoryzacja”).

    • Unikaj pokazywania wszystkiego — pomijaj trywialne gettery/settery, klasy pomocnicze.

    • Przechowuj w repozytorium → traktuj jako kod (zatwierdzaj pliki .puml obok komponentu).

    • Używaj oszczędnie — jeden na złożony komponent, nie na każdy mikroserwis.

    • Połącz z dynamiczne widoki (sekwencja/współpraca), jeśli przepływ w czasie wykonywania jest ważniejszy niż struktura statyczna.

Przykład PlantUML – Komponent uwierzytelniania (rozszerzenie stylu Big Bank plc)

Oto realistyczny przykład poziomu 4, przybliżający Komponent zabezpieczeń / uwierzytelniania z wcześniejszych diagramów aplikacji API.

PlantUML Edit PlantUML in VPasCode 
@startuml
tytuł C4 Poziom 4 – Diagram kodu: Uwierzytelnianie w aplikacji API

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

abstrakcyjna klasa 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
}

interfejs 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>
}

' Relacje
JwtAuthenticationProvider -up-> JwtTokenProvider : używa
JwtAuthenticationProvider -up-> UserDetailsService : używa
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : używa
UserRepository --> User : zwraca

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  Podstawowy przepływ uwierzytelniania dla sesji bezstanowych opartych na JWT
end note

note bottom of JwtTokenProvider
  Podpisuje i weryfikuje JWT przy użyciu HS512
end note

@enduml
Edit PlantUML in VPasCode

Ten mały diagram:

  • Skupia się wyłącznie na wewnętrznych aspektach uwierzytelniania

  • Pokazuje kluczowe klasy, interfejsy i zależności

  • Wyróżnia wzorce (dostawca, repozytorium)

  • Używa notatek do dostarczania kontekstu

Wklej do dowolnego renderera PlantUML — dostosuj do swojego domeny (np. zastąp JWT przez OAuth2, dodaj klasy MFA itp.).

Przypomnienie podsumowujące: Poziom 4 jest potężny, ale rzadki. Używaj go świadomie, preferuj generowanie automatyczne i nigdy nie pozwól, by stało się to zbędną pracą. Największą wartość w C4 dają poziomy 1–3. Szczęśliwego (wybieranego) modelowania!

Zasób

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