Spring Modulith v praxi: Od kódu k živým architektonickým diagramům

Váš architektonický diagram v Confluence je šest měsíců starý. Ten na wiki stále ukazuje Auth modul, který byl sloučen do Usera už v lednu. Tabule v zasedačce? Někdo ji smazal, aby nakreslil retrospektivu sprintu.

Architektonická dokumentace má zásadní problém: udržují ji lidé a lidé zapomínají. Kód se mění denně. Diagramy se mění, když si někdo vzpomene. Nakonec je mezera tak velká, že všichni přestanou diagramům věřit a začnou číst přímo kód — čímž se celý smysl diagramů ztrácí.

Spring Modulith to řeší tím, že generuje architektonickou dokumentaci přímo z vašeho kódu. Diagramy jsou vždy přesné, protože vycházejí ze stejného zdroje pravdy jako vaše aplikace: ze struktury modulů.

V předchozím článku jsme si ukázali, jak Modulith vynucuje hranice modulů. Tento článek je o tom, jak tyto hranice zviditelnit — automaticky, při každém buildu.

Co Documenter generuje

Spring Modulith obsahuje třídu Documenter, která z vašich ApplicationModules produkuje tři typy výstupu:

1. C4 Component diagramy

PlantUML diagram zobrazující všechny moduly a jejich závislosti — pohled C4 Level 3 (Component) na vaši aplikaci:

class DocumentationTests {

    ApplicationModules modules = ApplicationModules.of(Application.class);

    @Test
    void generateArchitectureDocs() {
        new Documenter(modules)
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml();
    }
}

writeModulesAsPlantUml() generuje přehledový diagram všech modulů a jejich vztahů. writeIndividualModulesAsPlantUml() generuje zaměřený diagram pro každý modul, zobrazující pouze jeho přímé závislosti — užitečné, když je celkový diagram příliš hustý.

Výstup jde do spring-modulith-docs/ ve vašem build adresáři. Každý soubor je .puml PlantUML zdrojový soubor, který se vykreslí jako C4 component diagram.

Můžete přepínat mezi C4 a UML styly:

var options = DiagramOptions.defaults()
    .withStyle(DiagramStyle.UML);

new Documenter(modules)
    .writeModulesAsPlantUml(options);

2. Application Module Canvases

new Documenter(modules)
    .writeModuleCanvases();

Generuje AsciiDoc tabulku pro každý modul obsahující:

Toto je dokumentace, kterou je nejtěžší udržovat ručně. Jaké eventy publikuje modul Venue? Jaké konfigurační properties vystavuje modul Notification? Canvas na tyto otázky odpovídá z reálného kódu, ne z něčí paměti.

3. Souhrnný dokument

new Documenter(modules)
    .writeAggregatingDocument();

Generuje jediný all-docs.adoc, který propojí všechny diagramy a canvasy do jednoho navigovatelného dokumentu. Toto je to, co publikujete.

Vše najednou

V praxi generujete vše v jednom testu:

@Test
void generateFullDocumentation() {
    var modules = ApplicationModules.of(Application.class);

    new Documenter(modules)
        .writeModulesAsPlantUml()
        .writeIndividualModulesAsPlantUml()
        .writeModuleCanvases()
        .writeAggregatingDocument();
}

Pět řádků. To je celý váš pipeline pro architektonickou dokumentaci.

Renderování v CI

Documenter produkuje PlantUML zdrojové soubory. Pro jejich převod na obrázky potřebujete renderovací krok. Zde je GitHub Actions workflow, který generuje dokumentaci, vykreslí diagramy a nasadí na GitHub Pages:

# .github/workflows/architecture-docs.yml
name: Architecture Documentation

on:
  push:
    branches: [main]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Generate Modulith documentation
        run: ./gradlew test --tests '*DocumentationTests*'

      - name: Render PlantUML to SVG
        uses: cloudbees/plantuml-github-action@master
        with:
          args: -tsvg build/spring-modulith-docs/*.puml

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: build/spring-modulith-docs

Každý push do main přegeneruje architektonickou dokumentaci. Diagramy na GitHub Pages jsou vždy synchronizované s kódem. Nikdo si nemusí pamatovat, že je má aktualizovat.

Kam to publikovat: Spektrum možností

Ne každý tým potřebuje GitHub Pages. Zde je srovnání možností:

Možnost 1: Nechat v repozitáři

Nejjednodušší přístup — commitnout vygenerované dokumenty do adresáře docs/architecture/. Funguje to, pokud vaše publikum jsou vývojáři, kteří už jsou v repozitáři.

Výhody: nulová infrastruktura, verzované společně s kódem, diffy ukazují architektonické změny. Nevýhody: přístupné jen lidem s přístupem k repozitáři, surový PlantUML se na GitHubu nevykreslí (museli byste commitovat i vykreslené SVG).

Možnost 2: GitHub Pages (doporučený default)

Ideální kompromis pro většinu týmů. CI generuje dokumentaci, vykreslí diagramy a nasadí na GitHub Pages. Kdokoli s odkazem vidí aktuální architekturu — bez přístupu ke Gitu.

Tady by měla většina týmů začít. Je to zdarma, automatizované a dostatečné pro 80 % případů.

Možnost 3: IcePanel

IcePanel je kolaborativní nástroj pro modelování architektury s plnou podporou C4. Přidává interaktivní průzkum — stakeholdeři mohou procházet od system contextu přes kontejnery ke komponentám bez znalosti PlantUML.

IcePanel má REST API, což znamená, že můžete pushovat výstup Modulithu do IcePanelu z CI. To propojuje přesnost generovanou z kódu s interaktivním vizuálním průzkumem.

Zvažte IcePanel, když:

• Netechničtí stakeholdeři potřebují prozkoumat architekturu
• Chcete porovnání současného vs. budoucího stavu
• Více týmů přispívá do stejného systému a potřebuje sdílený vizuální jazyk

Možnost 4: Structurizr

Structurizr je referenční C4 nástroj od Simona Browna (tvůrce C4 modelu). Používá vlastní DSL pro definici architektonických modelů, ze kterých generuje všechny úrovně C4 diagramů.

Structurizr je více názorový než IcePanel — modelujete v kódu (Structurizr DSL), ne ve vizuálním editoru. To sedí týmům, které chtějí “architecture as code” od začátku do konce.

Kompromis: Structurizr DSL je samostatný model oddělený od vašich Spring Modulith modulů. Museli byste je propojit — buď generováním Structurizr DSL z výstupu Modulithu, nebo udržováním obojího. Pro většinu týmů je GitHub Pages s nativním PlantUML výstupem Modulithu jednodušší.

Pipeline

Celkový pohled:

Plná čára: výchozí pipeline, který funguje pro většinu týmů. Tečkované čáry: volitelné integrace, když přerostete statické stránky.

Co vám to dá

S Documenterem zapojeným do CI:

• Architektonické diagramy jsou vždy přesné — jsou generované z kódu, ne kreslené ručně
• Module canvasy dokumentují to, co ruční dokumentace přehlíží — eventy, listenery, konfigurační properties, aggregate roots
• Noví členové týmu mohou prozkoumat architekturu dřív, než přečtou jediný řádek kódu
• Architektonické změny jsou viditelné v PR — pokud modul získá novou závislost, diagram se změní ve stejném commitu
• Žádná údržba — nikdo nemusí “aktualizovat architektonickou dokumentaci”, protože není co ručně aktualizovat

Nejlepší architektonická dokumentace je ta, která nevyžaduje disciplínu k údržbě. Prostě se to děje.

Toto je 2. díl série Spring Modulith v praxi. 1. díl: Vynucování architektury v rostoucím monolitu.

Titulní foto: Sven Mieke na Unsplash.