Diagram C4 to standardowy sposób wizualizacji architektonicznej zaprojektowany do modelowania systemów oprogramowania na wielu poziomach abstrakcji strukturalnej. Zaimplementowany zgodnie z zasadami Mermaid.js, silnik c4 silnik przestrzega czterech podstawowych poziomów modelu C4: Kontekst (makroekosystem), Pojemniki (aplikacje, usługi i bazy danych), Składniki (wewnętrzne moduły strukturalne), oraz Interakcje dynamiczne. Ten narzedzie eliminuje kłopoty z niestandardowym stylizowaniem CSS poprzez stosowanie spójnych, gotowych do prezentacji bloków architektonicznych opartych na Twoich deklaracjach tekstowych.
Zrozumienie abstrakcji i słów kluczowych diagramu C4
Mermaid obsługuje cztery specjalistyczne nagłówki inicjalizacji diagramów w zależności od poziomu szczegółowości wymaganego przez układ Twojego systemu:
C4Context: Skupia się na ogólnym obrazie, wyświetlając użytkowników, podstawowe ekosystemy oprogramowania oraz wysokiego poziomu zależności zewnętrznych.C4Container: Przybliża o jeden poziom, aby rozłożyć samodzielne aplikacje, interfejsy frontendowe, mikroserwisy, systemy przechowywania baz danych oraz kolejki.C4Component: Przebija głębiej w pojemnik, aby pokazać wewnętrzne moduły poziomu kodu, takie jak Kontrolery, Usługi i Repozytoria.C4Dynamic: Skupia się na śledzeniu interakcji danych w czasie rzeczywistym lub sekwencji transakcji krok po kroku między blokami infrastruktury.
Podstawowa struktura składni
Każdy diagram C4 zaczyna się od odpowiedniego nagłówka poziomu, po którym następuje opcjonalna deklaracja tytułu i rozdzielonych przecinkami makroelementów. Nawiasy zawierają parametry, a ciągi znaków są ograniczone podwójnymi cudzysłowami.
C4Context
tytuł "Szablon kontekstu systemu dla Internet Core"
Osoba(klient, "Klient bankowy", "Klient banku posiadający konta osobiste.")
System(system_bankowy, "System bankowości internetowej", "Umożliwia klientom przeglądanie informacji o koncie.")
Rel(klient, system_bankowy, "Używa", "HTTPS")
Pełna taksonomia makr elementów C4
Biblioteka C4 w Mermaid oferuje obszerny zestaw specjalistycznych makr, które jasno rozróżniają między wewnętrznymi składnikami, systemami zewnętrznymi oraz warstwami baz danych na wszystkich poziomach abstrakcji.
1. Makra Osoba i Użytkownik
Osoba(alias, etykieta, [opis], [sprite], [tagi]): Modeluje wewnętrznego użytkownika lub interesariusza.Osoba_Zew(alias, etykieta, [opis], [sprite], [tagi]): Modeluje zewnętrznego użytkownika (np. dostawcę zewnętrzny lub audytora) poza granicami Twojej głównej organizacji.
2. Makra Systemu i Ekosystemu Oprogramowania
System(alias, etykieta, [opis], [sprite], [tagi]): Reprezentuje wewnętrzny, objęty zakresem zespół systemów oprogramowania pod Twoją bezpośrednią kontrolą.System_Zew(alias, etykieta, [opis], [sprite], [tagi]): Modeluje kluczowy zewnętrzny system oprogramowania zarządzany przez stronę trzecią (np. dostawcy tożsamości, podstawowe księgi bankowe).SystemBd(alias, etykieta, [opis], [sprite], [tagi]): Wyświetla pole przechowywania danych na poziomie systemu w kształcie walca.SystemBd_Zew(alias, etykieta, [opis], [sprite], [tagi]): Wyświetla zewnętrzny poziom bazy danych zarządzany przez stronę trzecią.
3. Makra Warstwy Kontenera (Warstwa C4Container)
Kontener(alias, etykieta, technologia, [opis], [sprite], [tagi]): Modeluje osobną uruchomioną aplikację, serwer API lub interfejs frontonowy.KontenerBd(alias, etykieta, technologia, [opis], [sprite], [tagi]): Wyświetla otoczenie silnika bazy danych relacyjnej lub nierełacyjnej na poziomie kontenera.Kontener_Zew(alias, etykieta, technologia, [opis], [sprite], [tagi]): Reprezentuje zewnętrzny kontener chmury lub usługę aplikacji.KontenerBd_Zew(alias, etykieta, technologia, [opis], [sprite], [tagi]): Reprezentuje zewnętrzny, zarządzany poziom przechowywania danych w chmurze.
4. Makra Warstwy Komponentu (Warstwa C4Component)
Komponent(alias, etykieta, technologia, [opis], [sprite], [tagi]): Mapuje wewnętrzny moduł poziomu kodu, warstwę lub kontroler klasy.KomponentBd(alias, etykieta, technologia, [opis], [sprite], [tagi]): Modeluje wewnętrzny system przechowywania mikrokomponentów lub system buforowania plików na niskim poziomie.
Kontenery graniczne i otaczanie strukturalne
Aby wskazać strefy bezpieczeństwa, corporate zapory ogniowe lub logiczne granice aplikacji, Mermaid oferuje trzy dedykowane otoczki kontenerów w nawiasach. Elementy zagnieżdżone wewnątrz są wizualnie grupowane razem.
Enterprise_Boundary(alias, label) { ... }: Otacza systemy najwyższego poziomu w szerokim wizualnym obszarze reprezentującym całkowity obszar infrastruktury korporacyjnej lub firmowej.System_Boundary(alias, label) { ... }: Grupuje blisko powiązane kontenery aplikacji lub mikroserwisy w jednym pudełku jednolitego ekosystemu oprogramowania.Container_Boundary(alias, label) { ... }: Izoluje składniki poziomu kodu w jednym warstwach kontekstu modułu aplikacji.
Zaawansowane operatory kierunkowe relacji
Łączenie bloków na diagramach C4 opiera się na Rel makro lub jego jawnie skierowanych wariantach. Zamiast przekazywać surowe linie schematu przepływu, śledzisz połączenia semantycznie, deklarując wektory technologiczne bezpośrednio wewnątrz bloków logicznych.
| Token składni relacji | Kierunek wizualnej strzałki | Kontekst dopasowania użycia |
|---|---|---|
Rel(from, to, label, [tech]) |
Dynamiczny / Automatyczny | Domyślna relacja. Pozwól algorytmowi układu określić najlepszą trasę linii. |
BiRel(from, to, label, [tech]) |
Podwójna strzałka (<–>) | Wskazuje dwukierunkowe interaktywne wymiany, protokoły dwukierunkowe lub procesy synchronizacji. |
Rel_Back(from, to, label, [tech]) |
Odwrócona strzałka z góry (<–) | Rysuje relację w przód w logice kodu, ale odwraca widoczną strzałkę wizualną w tył. |
Rel_Neighbor(from, to, label, [tech]) |
Preferencja układu poziomego | Wymusza, aby węzeł docelowy pozostał bezpośrednio obok węzła źródłowego w tej samej poziomej linii. |
Rel_Down(from, to, label, [tech]) / Rel_D(...) |
Prosto w dół (v) | Wymusza pionowy przepływ danych w dół do warstw baz danych lub kolejnych procesów tła. |
Rel_Up(z, do, etykieta, [technologia]) / Rel_U(...) |
Prosto w górę (^) | Wymusza, aby ścieżki relacji poruszały się prosto w górę do składników interfejsu użytkownika klienta. |
Rel_Lewo(z, do, etykieta, [technologia]) / Rel_L(...) |
Prosto w lewo (<-) | Kieruje ścieżki poziomo w lewą stronę elementu kanwy. |
Rel_Prawo(z, do, etykieta, [technologia]) / Rel_R(...) |
Prosto w prawo (->) | Kieruje ścieżki poziomo w prawą stronę elementu kanwy. |
Niestandardowe dynamiczne stylizowanie i etykietowanie (przesłanianie kształtów C4)
Aby oznaczyć starsze aplikacje, wyróżnić systemy premium lub podkreślić bezpieczne przepływy danych, możesz tworzyć niestandardowe style przy użyciu silnika etykiet elementów. Zdefiniuj macierz właściwości etykiety na początku dokumentu, a następnie dołącz etykietę do definicji swoich elementów.
Słowa kluczowe modyfikacji stylizacji:
UpdateElementStyle(nazwaElementu, kolorTła, kolorCzcionki, [kolorObramowania], [cieniowanie]): Bezpośrednie zastąpienie domyślnej palety tła wyraźnie określonego pola elementu.UpdateRelStyle(z, do, kolorLinii, kolorTekstu): Wyraźnie celuje w trasę połączenia, aby zmienić kolor ścieżek linii lub opisów połączeń.
C4Context
tytuł "Niestandardowa kolorowa mapa architektury globalnej"
System(legacy_api, "Stare jądro rozliczeń", "Przetwarza odnowienia subskrypcji.")
System(modern_portal, "Portal pulpitu klienta", "Nowoczesny silnik przeglądarki internetowej dla użytkownika.")
%% Bezpośrednie dostosowania kolorów
UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Szczegółowy projekt z rzeczywistego świata: mapa kontenera granic systemu e-commerce dla przedsiębiorstwa
To kompleksowy, wielowarstwowy szablon kontenera śledzi ekosystem e-commerce online. Izoluje wewnętrzne serwery główne przy użyciuSystem_Boundary kontener blokowy, implementuje zewnętrzne relacje powiadomień chmury za pośrednictwemSystem_Ext, mapuje wewnętrzne magazyny bazy danych relacyjnych wraz z zewnętrznymi mikroserwisami śledzenia i ustala ścieżki komunikacji przy użyciu jawnych parametrów stosu technologicznego.
C4Container
tytuł "Szablon kontenera dla platformy e-commerce dla przedsiębiorstwa"
Osoba(klient, "Klient internetowy", "Przegląda pozycje katalogu i dodaje produkty do cyfrowego koszyka.")
System_Ext(brama_platności, "Usługa API Stripe", "Zewnętrzny magazyn kart kredytowych i silnik przetwarzania.")
GranicaSystemu(skalę_e-commerce, "Granica centralna e-commerce") {
Kontener(aplikacja_frontu, "Aplikacja internetowa sklepu", "Next.js, React", "Dostarcza zasoby statyczne i obsługuje sesje koszyka użytkownika.")
Kontener(usługa_koszyka, "Mikroserwis do kasy", "Node.js, Express", "Przetwarza przepływy pracy koszyka i oblicza podatki.")
KontenerDb(baza_danych_zamówień, "Baza danych księgi zamówień", "PostgreSQL", "Przechowuje linie historycznych transakcji i bezpieczne zapisy księgowości.")
}
%% Ścieżki interakcji architektonicznych
Rel(klient, aplikacja_frontu, "Przegląda produkty i składa zamówienia przy użyciu", "HTTPS/Przeglądarka")
Rel_Dolna(aplikacja_frontu, usługa_koszyka, "Wysyła dane transakcji zakupowych przez", "JSON/REST API")
Rel_Prawa(usługa_koszyka, baza_danych_zamówień, "Trwa przechowywanie stanów transakcyjnych wewnątrz", "SQL/Połączenie JDBC")
Rel_Lewa(usługa_koszyka, brama_platności, "Autoryzuje wywołania opłaconych transakcji z", "Bezpieczne TLS/HTTPS API")
Typowe błędy składniowe i ograniczenia systemowe
Podczas kompilowania czystych map C4 dla frameworków oprogramowania, zwróć uwagę na te parametry wykonania, aby zapobiec uszkodzeniu diagramu:
- Formatowanie separatora przecinków: W przeciwieństwie do prawie każdego innego schematu Mermaid, makra C4 wymagają ścisłych przecinków między parametrami:
Osoba(id, "Etykieta", "Opis"). Pominięcie separatora przecinka spowoduje całkowity awarię budowniczego układu. - Zarezerwowane cudzysłowy etykiet: Pola wyświetlania, tagi technologiczne i bloki opisów wewnątrz makr *muszą* być otoczone jasnymi podwójnymi cudzysłowami. Wstawienie surowego tekstu do pól bez otoczenia cudzysłowami powoduje błędy parsowania, które uszkadzają diagram.
- Kolejność zagnieżdżania granic: Gdy otaczasz elementy wewnątrz
GranicaSystemulubGranicaPrzedsiębiorstwabloku, musisz jawnie wyczyścić zawartość jego obszaru roboczego przy użyciu standardowych nawiasów klamrowych{ }. Pozostawienie otwartego nawiasu granicy lub niepoprawne dopasowanie ich powoduje uszkodzenie układu renderowania. - Inicjalizacja dynamicznych aliasów: Nie możesz rysować relacji (
Rel) do identyfikatora aliasu, który nie został jawnie zainicjowany przez blok makra elementu powyżej. Zachowaj ciągłość deklaracji od góry do dołu.