Zanim przejdziemy do konkretnych układów architektonicznych, takich jak modele C4 lub przebiegi sekwencji, istotne jest zrozumienie podstawowych zasad, które regulująPlaybook PlantUML. PlantUML opiera się na czystym, bardzo intuicyjnym systemie notacji tekstowej. Gdy zrozumiesz, jak silnik otwiera dokumenty, nadaje nazwy elementom strukturalnym i kieruje linie połączeń, tworzenie układu dowolnego złożonego systemu staje się zupełnie naturalne.
Ten szybki przewodnik obejmuje globalne mechanizmy składni strukturalnej, które stosuje się we wszystkich typach diagramów PlantUML w środowisku VPasCode.
1. Obowiązkowe otoki dokumentu
Każdy blok kodu PlantUML musi zaczynać się i kończyć jawnymi znacznikami frameworku. Te znaczniki informują parser VPasCode o uruchomieniu odpowiedniego silnika renderowania na kanwie podglądu:
@startuml— Ta dokładna linia musi znajdować się na samym początku skryptu. Niczego nie może jej poprzedzać.@enduml— Ta dokładna linia musi znajdować się na samym końcu skryptu, oznaczając zakończenie bloku danych diagramu.
Każdy kod napisany poza tymi dwoma znacznikami zostanie bezpiecznie zignorowany przez kompilator, albo może spowodować ostrzeżenie weryfikacji składni w panelu diagnostycznym środowiska pracy.
2. Deklarowanie elementów: ID w porównaniu z etykietami wyświetlania
Podczas modelowania systemu oprogramowania tworzysz różne elementy strukturalne, takie jak składniki, bazy danych, aktorzy lub mikroserwisy. W PlantUML możesz jawnie zadeklarować element, definiując jego typ, wewnętrzny skrót ID oraz przyjazną dla użytkownika nazwę wyświetlania ujętą w cudzysłowy:
component microservice_id jako "Payment Processing API"
database db_id jako "User Transaction SQL"Dlaczego jest to najlepsza praktyka: Używanie krótkiego, czystego wewnętrznego ID (takiego jakmicroservice_id) znacznie przyspiesza rysowanie linii relacji w przyszłości. Jeśli kiedykolwiek będziesz musiał zmienić etykietę widoczną dla klienta z „Payment Processing API” na „Global Checkout Service”, musisz zmienić ją tylko w jednym wierszu kodu, a nie aktualizować dziesiątki linii w całym skrypcie.
3. Opanowanie strzałek relacji i kierunkowego routingu
Połączenia między węzłami systemu rysuje się za pomocą kombinacji kresek (-) i nawiasów strzałek (>). Długość kresek i uwzględnienie słów kluczowych kierunkowych dają Ci pośredni kontrolę nad tym, jak silnik automatycznego układu skaluje Twój diagram:
- Podstawowe połączenia:
A --> Brysuje standardową strzałkę kierunkową wskazującą od elementu A bezpośrednio do elementu B. - Linie zależności kropkowane: Zastępowanie kresek kropkami tworzy linię kropkowaną, która jest standardem branżowym wskazującym na zależności asynchroniczne lub wywołania sieciowe:
A ..> B. - Wymuszanie orientacji układu: Chociaż silnik układu automatycznie rozdziela pola, możesz jawnie kontrolować orientację, wstawiając słowo kluczowe kierunku bezpośrednio w ciągu strzałki:
A -up-> B(Wymusza renderowanie B powyżej A)A -down-> B(Wymusza renderowanie B poniżej A)A -left-> B(Wymusza renderowanie B po lewej stronie A)A -right-> B(Wymusza renderowanie B po prawej stronie A)
4. Dodawanie kontekstu w linii: etykiety i komentarze kodu
Jasna dokumentacja bardzo dużo zależy na umieszczaniu odpowiedniego kontekstu wokół Twoich linii wizualnych i skryptów tekstowych:
Etykietowanie linii połączeń
Możesz dodać objaśniający tekst bezpośrednio do dowolnej linii połączenia, dodając dwukropek (“:) tuż po swoim mapowaniu relacji:
client_id --> api_id : "HTTPS POST /v1/checkout"Pisanie komentarzy kodu
Jeśli chcesz zostawić notatkę administracyjną, credit projektowy lub wyjaśnienie architektoniczne w pliku skryptu bez renderowania pola wizualnego na płótnie, użyj znaku pojedynczego cudzysłowu (“'). Informuje to silnik, aby całkowicie pominął analizę tej linii:
' TODO: Musimy zaktualizować to pole graniczne, gdy zakończy się migracja DevOps
[Stary monolit] --> [Nowy mikroserwis]Teraz, gdy znasz ogólne składnie otoczki, deklaracje komponentów i parametry strzałek kierunkowych PlantUML, jesteś idealnie przygotowany, aby rozpocząć budowanie zaawansowanych kształtów systemu. Przejdź do następnej strony, aby odblokować naszą kolekcję Diagramy architektury i projektowania najwyższego poziomu!