Opanowanie wizualizacji architektury: Jak zbudować diagram kontekstu systemu C4 w PlantUML

Dlaczego warto stosować podejście diagramów jako kodu dla modeli C4?

Tradycyjne narzędzia do rysowania typu „przeciągnij i upuść” często prowadzą do nieustawionych pudełek, niespójnego stylu i żmudnych ręcznych aktualizacji za każdym razem, gdy architektura się zmienia. Wykorzystując “”narzędzie typu diagram jako kod”takie jak darmowy edytor PlantUML, Twoja dokumentacja pozostaje zsynchronizowana z kodem, kontrolowana wersjonowanie i czysta. Korzystając z “”VPasCode”, otrzymujesz renderowanie w czasie rzeczywistym i automatyczne wykrywanie formatu, co sprawia, że wizualizacja architektury oprogramowania staje się bezproblemowa.

Studium przypadku z warsztatu masterclass: Architektura sklepu spożywczego online

Aby pokazać, jak zbudować solidny diagram kontekstu systemu, przyjrzyjmy się platformie sklepu spożywczego online. Ta architektura musi uwzględniać użytkowników końcowych, zewnętrznych kierowców dostaw, podstawowy system sklepu spożywczego oraz usługi stron trzecich, takie jak bramki płatności i dostawcy logistyczni.

Oto pełny kod źródłowy PlantUML, który przeanalizujemy krok po kroku:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
skinparam vpDiagramType C4modelSystemContextDiagram

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

title System Context diagram for Online Grocery Store

Person(customer, "Customer", "Browses the store, orders groceries, and schedules delivery")
Person_Ext(driver, "Delivery Driver", "Delivers orders to customers")

Enterprise_Boundary(grocery_co, "Online Grocery Store") {
  System(grocery_system, "Online Grocery Store System", "Allows customers to order groceries online and manages fulfillment")
}

System_Ext(payment, "Payment Gateway", "Processes card and digital wallet payments")
System_Ext(shipping, "Logistics Provider", "Plans delivery routes and schedules drivers")

Rel(customer, grocery_system, "Browses products and places orders", "HTTPS")
Rel(grocery_system, payment, "Processes payments via", "HTTPS/API")
Rel(grocery_system, shipping, "Creates delivery jobs via", "HTTPS/API")
Rel(driver, grocery_system, "Views delivery assignments", "HTTPS")

@enduml

Krok po kroku: przegląd kodu

1. Konfigurowanie środowiska podstawowego

Zaczynam od zainicjowania skryptu standardowymi znacznikami PlantUML i zaimportowania oficjalnych makr biblioteki standardowej C4-PlantUML. Odwołując się do “”C4_Context.puml", odblokowujemy elementy semantyczne dostosowane specjalnie do diagramów kontekstu systemu.

• Dołączenie biblioteki: !include .../C4_Context.pumlładowanie standardowych kształtów, kolorów i reguł stylizacji dla osób, systemów i granic.
• Typowanie i układ diagramu:Ustawienie “”skinparam vpDiagramType C4modelSystemContextDiagram"zapewnia poprawną integrację w ramach “”VPasCode”, podczas gdy “”LAYOUT_TOP_DOWN()"czysto organizuje hierarchię wizualną od góry do dołu. Aktywuję również LAYOUT_WITH_LEGEND()w celu automatycznego wygenerowania pomocniczego przewodnika referencyjnego w prawym dolnym rogu płótna.

2. Definiowanie aktorów i użytkowników

Następnie muszę zdefiniować ludzkie aktorów interagujących z naszym ekosystemem. Różnicuję między standardowymi użytkownikami systemu a podmiotami zewnętrznymi, używając specyficznych makr C4:

• Podstawowy użytkownik:Tworzę głównego użytkownika, używając Person(customer, "Klient", ...)który inicjuje zamówienia i przegląda stan magazynowy.
• Zewnętrzny aktor:Definiuję kierowcę dostawczego, używając Person_Ext(kierowca, "Kierowca Dostawczy", ...)aby podkreślić, że choć interagują z naszym procesem realizacji zamówień, istnieją poza naszym podstawowym wewnętrznym perymetrem bezpieczeństwa.

3. Określanie granic organizacyjnych i systemów podstawowych

Jasność architektoniczna wymaga wyraźnych granic. Aby zdefiniować, co posiada nasza firma, a co zależy od zewnętrznych dostawców, ustanawiam granicę przedsiębiorstwa:

• Granica przedsiębiorstwa:Używając Enterprise_Boundary(grocery_co, "Sklep Spożywczy Online")tworzy przerywany kontener wizualnie grupujący infrastrukturę wewnętrzną.
• System wewnętrzny:Wewnątrz tej granicy umieszczam nasz główny zasób oprogramowania, używając System(grocery_system, "System Sklepu Spożywczego Online", ...).

4. Integracja systemów zewnętrznych

Żadna nowoczesna platforma e-commerce nie działa w izolacji. Definiuję zewnętrzne zależności poza granicą przedsiębiorstwa, używając specjalistycznych makr systemów zewnętrznych:

• Obsługa płatności: System_Ext(płatnosci, "Brama Płatności", ...)reprezentuje transakcje finansowe stron trzecich.
• Logistyka i wysyłka: System_Ext(logistyka, "Dostawca Logistyczny", ...)obsługuje planowanie tras i przypisywanie kierowców.

5. Mapowanie relacji i protokołów

Aby połączyć architekturę, mapuję kierunkowe interakcje i protokoły komunikacyjne przy użyciu Rel() makro:

• Przepływ klienta: Rel(klient, system_sklepu, "Przegląda produkty i składa zamówienia", "HTTPS")ilustruje, jak użytkownicy bezpiecznie łączą się z platformą główną.
• Integracje backendowe:Mapuję zależności backendowe, takie jak przetwarzanie płatności i dostawcy usług wysyłkowych, z jawnymi etykietami protokołów ("HTTPS/API") aby dostarczyć inżynierom natychmiastowego kontekstu technicznego.

Podsumowanie & Spróbuj sam

Tworzenie czystych diagramów architektury oprogramowania nie wymaga uciążliwych narzędzi desktopowych ani skomplikowanych konfiguracji plików. Łącząc potężny składnię C4 PlantUML z VPasCode, możesz pisać, renderować i udostępniać diagramy architektury w kilka sekund.

Gotowy, by spróbować zbudować własną architekturę systemu? Przejdź do darmowego edytora online VPasCode, wklej ten fragment kodu i obserwuj renderowanie swojego diagramu w czasie rzeczywistym!