Wstęp

Diagramy klas PlantUML opisują statyczną strukturę systemu: jego klasy, atrybuty, operacje i relacje. Piszesz specyfikację tekstową i renderujesz ją jako diagram, co sprawia, że źródło jest łatwe do edycji i utrzymania w systemie kontroli wersji.
1. Minimalny diagram
Diagram klasy zaczyna się od @startuml i kończy się na @enduml:

@startuml
class User
class Order
User --> Order : places
@enduml
PlantUML może wnioskować o klasach na podstawie deklaracji relacji, ale ich jawne deklarowanie ułatwia przeglądanie i utrzymanie większych diagramów.
2. Klasy, atrybuty i metody
Umieść atrybuty i operacje w nawiasach klamrowych. Dwukropek oddziela nazwę członka od jego typu; nawiasy okrągłe oznaczają operację.

@startuml
class User {
-id: int
-email: String
+login(password: String): boolean
+logout(): void
}
@enduml
Markery widoczności to:
-
+public -
-private -
#protected -
~package-private
Możesz również wpisać typ przed nazwą elementu — na przykład, +String email lub +void logout(). PlantUML obsługuje zarówno znane notacje elementów podobne do kodu, jak i te markery widoczności.
Elementy statyczne i abstrakcyjne
Użyj {static} lub {classifier} dla elementów statycznych oraz {abstract} dla elementów abstrakcyjnych:

@startuml
abstract class PaymentMethod {
{abstract} +authorize(amount: Decimal): boolean
{static} +supportedCurrencies: String[]
}
class CardPayment {
+authorize(amount: Decimal): boolean
}
PaymentMethod <|-- CardPayment
@enduml
Klasa abstrakcyjna może być również zadeklarowana za pomocą klasa abstrakcyjna.
3. Relacje
Kształt strzałki przekazuje typ relacji. Kierunek linii jest wybierany na podstawie kolejności nazw; użyj etykiet, aby wyjaśnić jej znaczenie.
| Relacja | Notacja PlantUML | Typowe znaczenie |
|---|---|---|
| Dziedziczenie / generalizacja | `Rodzic < | — Dziecko` |
| Realizacja interfejsu | `Interfejs < | .. Klasa` |
| Kompozycja | Całość *-- Część |
Życie części jest zarządzane przez całość |
| Agregacja | Całość o-- Część |
Całość grupuje lub odnosi się do części, które mogą istnieć niezależnie |
| Asocjacja skierowana | A --> B |
A ma relację nawigacyjną do B |
| Zależność | A ..> B |
A używa lub zależy od B |
Są to standardowe notacje relacji PlantUML.

@startuml
interface Repository
class SqlRepository
class OrderService
class Order
class OrderLine
Repository <|.. SqlRepository
OrderService ..> Repository : uses
Order *-- "1..*" OrderLine : contains
@enduml
Wybieraj ostrożnie:Kompozycja i agregacja wyrażają różne semantyki cyklu życia. Używaj kompozycji tylko wtedy, gdy część jest w sensowny sposób własnością całości; używaj zwykłego powiązania, gdy żadna interpretacja własności nie pasuje.
4. Mnożność, nazwy ról i etykiety
Mnożność określa, ile obiektów może uczestniczyć na każdym końcu powiązania. Powszechne formy obejmują "1", "0..1", "*", oraz "1..*".

@startuml
class Customer
class Order
Customer "1" --> "0..*" Order : places
@enduml
Tutaj każdy Zamówienie jest powiązane z jednym Klientem, podczas gdy klient Klientem może złożyć zero lub więcej zamówień. Odczytuj mnożności od przeciwnej strony: liczba przy “Zamówienie opisuje, ile zamówień może być powiązanych z klientem.
Dla większej precyzji dodaj nazwy ról lub ograniczenia:

@startuml
class Zespół
class Zawodnik
Zespół "1" o-- "0..*" Zawodnik : członkowie
notatka na łączu
Zawodnik może przenosić się między zespołami.
koniec notatki
@enduml
5. Interfejsy, wyliczenia, stereotypy i pakiety
PlantUML obsługuje deklaracje takie jak interfejs, wyliczenie, klasa abstrakcyjna, oraz stereotypy zapisane między << a >>.

@startuml
package "Zamawianie" {
interface BramkaPłatności {
+charge(amount: Decimal): WynikPłatności
}
enum StatusZamówienia {
NOWE
OPŁACONE
ANULOWANE
}
class Zamówienie <<Entity>> {
+id: UUID
+status: StatusZamówienia
}
class UsługaZakupu <<Service>> {
+checkout(order: Zamówienie): WynikPłatności
}
UsługaZakupu ..> BramkaPłatności : wywołuje
Zamówienie --> StatusZamówienia
}
@enduml
Pakiety wizualnie grupują powiązane typy. Używaj stereotypów takich jak “<<Entity>>" lub “<<Service>>" gdy dodają użyteczny kontekst; unikaj dodawania etykiet, które jedynie powtarzają to, co już mówi nazwa klasy.
6. Notatki, aliasy i układ
Notatki mogą wyjaśniać decyzje projektowe lub precyzować ograniczenia bez przeciążania nazw klas. Aliasie pomagają, gdy wyświetlana nazwa zawiera spacje lub znaki interpunkcyjne.

@startuml
class "Zewnętrzne API płatności" as PaymentApi
class CheckoutService
CheckoutService ..> PaymentApi : submits payment
note right of CheckoutService
Retries transient failures.
Does not retry declined payments.
end note
left to right direction
@enduml
kierunek z lewej do prawej zmienia ogólny kierunek układu; domyślnie jest to kierunek od góry do dołu. Możesz również używać kierunków relacji takich jak “-left->" lub “-up-|>" aby kierować lokalnym rozmieszczeniem.
7. Bardziej pełny przykład
Ten przykład łączy widoczność, typy, metody, enumeracje, mnożności, kompozycję i zależność:

@startuml
left to right direction
package "Sprzedaż" {
class Customer {
-id: UUID
+name: String
+placeOrder(): Order
}
class Order {
-id: UUID
-status: OrderStatus
+addLine(product: Product, quantity: int): void
+total(): Decimal
}
class OrderLine {
-quantity: int
+lineTotal(): Decimal
}
class Product {
+sku: String
+price: Decimal
}
enum OrderStatus {
NEW
PAID
CANCELLED
}
interface PaymentGateway {
+charge(amount: Decimal): PaymentResult
}
class CheckoutService {
+checkout(order: Order): PaymentResult
}
Customer "1" --> "0..*" Order : places
Order *-- "1..*" OrderLine : contains
OrderLine "*" --> "1" Product : refers to
Order --> OrderStatus
CheckoutService ..> PaymentGateway : uses
}
@enduml
8. Narzędzia: Visual Paradigm VPasCode
VPasCode to przeglądarkowy edytor konwertujący tekst na diagramy od Visual Paradigm. Obsługuje diagramy klas PlantUML i zapewnia edytor kodu z podglądem na żywo, dzięki czemu możesz wpisywać lub wklejać kod PlantUML oraz sprawdzać wynik renderowania w trakcie pracy.

Typowy przepływ pracy:
-
Otwórz VPasCode i wybierz edytor PlantUML lub przykład PlantUML.
-
Zastąp tekst początkowy swoim diagramem, w tym
@startumloraz@enduml. -
Sprawdź podgląd na żywo; jeśli renderowanie się nie powiedzie, przeanalizuj wyróżniony błąd składni i jego wiersz.
-
Ulepsz diagram, a następnie wyeksportuj go lub udostępnij w razie potrzeby. VPasCode opisuje opcje eksportu do formatów SVG, PNG i PDF.
VPasCode oferuje również interfejs do wyboru motywów dla PlantUML, w tym motywy Visual Paradigm i Rose. Aby uzyskać spójne wyniki w zespole, przechowuj źródło PlantUML obok dokumentacji lub kodu, zamiast polegać wyłącznie na wyeksportowanym obrazie.
9. Typowe pułapki i dobre praktyki

-
Nie myl asocjacji z zależnością.Zależność zazwyczaj oznacza „użycie”; asocjacja często reprezentuje bardziej trwały związek strukturalny.
-
Unikaj nadmiernego stosowania kompozycji.Kompozycja wnosi silniejsze twierdzenie dotyczące cyklu życia niż proste połączenie.
-
Oznaczaj mnożności od przeciwnej strony.Liczba obok jednej klasy określa, ile instancji tej klasy może być powiązanych z jedną instancją po drugiej stronie.
-
Utrzymuj skupienie diagramów.Podziel bardzo duży model na pakiety lub osobne diagramy dla odrębnych obszarów zainteresowań.
-
Pokazuj szczegóły przydatne dla odbiorców.Przegląd koncepcyjny może wymagać tylko nazw klas i relacji; diagram na poziomie projektu może wymagać typów, widoczności i operacji.
-
Traktuj źródło jako utrzymywany artefakt.Przejrzyj zmiany w tekście, wyrenderuj po edycji i wygeneruj ponownie eksporty, gdy źródło ulegnie zmianie.
Szybka referencja

@startuml
class A {
+publicField: String
-privateField: int
#protectedMethod(): void
~packageMember(): boolean
}
interface I
abstract class Base
enum State { READY; DONE }
Base <|-- A
I <|.. A
A *-- B : kompozycja
A o-- C : agregacja
A --> D : asocjacja
A ..> I : zależność
@enduml
PlantUML obsługuje dodatkowe funkcje diagramów klas, w tym grupowanie członków, notatki, kolory i inne, gdy diagram wymaga dalszego dopracowania.










