PlantUML dynamiczne diagramy z warunkami

Dynamiczne diagramy sekwencji w PlantUML: implementacja ze zmiennymi i warunkami

PlantUML obsługuje preprocesowanie ze zmiennymi i warunkami, co umożliwia tworzenie dynamicznych diagramów sekwencji. Użytkownik może kontrolować poziom szczegółowości za pomocą przełączników, ukrywając lub pokazując zagnieżdżoną logikę bez konieczności tworzenia oddzielnych artefaktów.

Rozważmy zadanie dokumentowania metody API tworzenia zamówienia, która wywołuje dziesiątki wewnętrznych kontroli. Pełny diagram staje się nieporęczny, a nawigacja między kilkoma statycznymi wariantami jest nieefektywna.

Przygotowanie tekstu diagramu

Bazowy tekst diagramu jest rozszerzany zmiennymi i warunkami. Przykład:

participant Bob as b
participant Alicja as a

!$aliceThoughts = "Nie"
!$bobThoughts = "Nie"

b -> a: Cześć!

!if ($aliceThoughts == "Tak")
activate a
a->a: O Boże, on mi napisał!
a->a: Co robić, jak być..
create participant Liza as l
a -> l: Bob mi napisał, co robić?
activate l
l -> a: Po prostu mu odpowiedz, Boże
deactivate l
!endif

a->b: Cześć!
deactivate a

!if ($bobThoughts == "Tak")
activate b
b->b: Ona odpowiedziała o_O
!endif

b->a: Hmm... Jak się masz?
deactivate b

Zmienne $aliceThoughts i $bobThoughts kontrolują wyświetlanie bloków. Preprocesor PlantUML ocenia warunki podczas renderowania.

Interfejs HTML do zarządzania

Przełączniki są implementowane za pomocą formularzy HTML z JavaScript. Użytkownik wybiera poziom szczegółowości, kod dynamicznie aktualizuje tekst diagramu i generuje obraz.

<form>
  <label for="aliceThoughts">Pokaż myśli Alicji:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">Nie</option>
    <option value="yes">Tak</option>
  </select>
</form>

<form>
  <label for="bobThoughts">Pokaż myśli Boba:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">Nie</option>
    <option value="yes">Tak</option>
  </select>
</form>

JavaScript śledzi zmiany w elementach select, podstawia wartości w szablonie PlantUML i wywołuje enkoder do generowania URL.

Kodowanie tekstu dla API PlantUML

PlantUML udostępnia HTTP API do renderowania: https://www.plantuml.com/plantuml/png/<encoded_text>. Obsługiwane formaty to PNG, SVG.

Prosta metoda (hex)

Przekształca tekst UTF-8 na hex z prefiksem ~h:

function toHex(uml) {
  const umlFormatted = `@startuml\r\n${uml}\r\n@enduml`;
  const utf8 = unescape(encodeURIComponent(umlFormatted));
  var result = '';
  for (var i=0; i<utf8.length; i++) {
    result += utf8.charCodeAt(i).toString(16).padStart(2, '0');
  }
  return `https://www.plantuml.com/plantuml/png/~h${result}`;
}

Nadaje się do krótkich diagramów. Ograniczenie — długość URL (około 8KB).

Skomplikowana metoda (deflate + niestandardowe base64)

• Kompresja deflate.
• Kodowanie w base64 PlantUML: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

Pozwala przetwarzać duże diagramy dzięki kompresji.

function encodePlantUml(data) {
    const base64Map = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_';
    let result = '';
    for (let i = 0; i < data.length; i += 3) {
        const b1 = data[i];
        const b2 = i + 1 < data.length ? data[i + 1] : 0;
        const b3 = i + 2 < data.length ? data[i + 2] : 0;
        result += base64Map[b1 >> 2];
        result += base64Map[((b1 & 3) << 4) | (b2 >> 4)];
        result += base64Map[((b2 & 15) << 2) | (b3 >> 6)];
        result += base64Map[b3 & 63];
    }
    return result;
}

Wdrażanie w Confluence

HTML+JS jest wstawiany przez makro Confluence. Brak zależności od backendu — renderowanie odbywa się w przeglądarce przez publiczny serwer PlantUML. Dla środowisk korporacyjnych zaleca się lokalny serwer PlantUML.

Zalety podejścia:

• Interaktywność bez nawigacji między artefaktami.
• Obsługa złożonej logiki poprzez preprocesowanie.
• Minimalne zasoby: HTML, JS, API PlantUML.
• Kompatybilność z Confluence.

Ograniczenia implementacji

• Długość URL dla kodowania hex.
• Zależność od zewnętrznego serwera PlantUML (rozwiązanie: lokalne wdrożenie).
• Ograniczenia preprocesora PlantUML: brak złożonych obliczeń, tylko podstawowe operacje.

| Metoda | Maksymalny rozmiar tekstu | Złożoność |

|-------|---------------------------|-----------|

| Hex | ~2000 znaków | Niska |

| Deflate | ~50k+ znaków | Wysoka |

Co jest ważne

• Preprocesing PlantUML umożliwia warunki !if i zmienne dla dynamiki.
• Przełączniki HTML+JS aktualizują diagram w czasie rzeczywistym.
• API PlantUML generuje PNG po encoded URL bez backendu.
• Hex nadaje się do prostych przypadków, deflate — do dużych diagramów.
• Rozwiązanie działa w Confluence bez zależności VPN.

— Editorial Team