Spring Boot 4 Complete Guide · Lekcja

Moduły aplikacji i weryfikacja granic

Definiuj i egzekwuj granice modułów za pomocą weryfikacji struktury i dokumentacji Spring Modulith.

Moduły aplikacji i weryfikacja granic to bezpłatna lekcja Spring Boot 4 Complete Guide na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Spring Boot 4 Complete Guide, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Spring Boot 4 Complete Guide zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Why Module Boundaries Matter

A Spring Boot monolith tends to rot: any class can @Autowired any other, and over time everything depends on everything. Spring Modulith brings discipline by treating top-level packages under your main application package as application modules.

Each direct sub-package of the main package is one module.
Code inside a module's root package and a special api sub-package is public.
All other nested packages are internal and may not be referenced from other modules.

This lets you keep a single deployable while enforcing the boundaries you would get from microservices.

A Modular Package Layout

Consider an e-commerce app with the main class in com.shop. Each business concern becomes a direct sub-package. Spring Modulith infers the modules order, inventory, and notification from this structure alone — no XML, no annotations required.

Classes directly in com.shop.order are the module's public API; classes in com.shop.order.internal are hidden from other modules.

com.shop
├── ShopApplication.java
├── order
│   ├── OrderService.java          // public API
│   └── internal
│       └── OrderRepository.java   // internal
├── inventory
│   ├── InventoryService.java
│   └── internal
│       └── StockLevel.java
└── notification
    └── NotificationService.java

Adding the Modulith Dependency

Spring Modulith ships as a BOM plus a set of starters. For boundary verification and documentation you need spring-modulith-starter-core on the test classpath (and usually the test starter).

The BOM aligns all Modulith artifact versions with your Spring Boot version.
spring-modulith-starter-test brings the ApplicationModules verification API into the test scope.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.modulith</groupId>
      <artifactId>spring-modulith-bom</artifactId>
      <version>1.4.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-test</artifactId>
  <scope>test</scope>
</dependency>

Bootstrapping the Module Model

The entry point for everything is ApplicationModules.of(...). You pass it your main application class; Modulith scans the package structure and builds an in-memory model of every module and its allowed dependencies.

Calling verify() on that model fails fast if any module reaches into another module's internals or forms an illegal cyclic dependency.

import org.springframework.modulith.core.ApplicationModules;

class ModularityTests {

    static final ApplicationModules modules =
            ApplicationModules.of(ShopApplication.class);

    @org.junit.jupiter.api.Test
    void verifiesModularStructure() {
        modules.verify();
    }
}

What verify() Actually Checks

A single call to verify() enforces several structural rules at once:

No internal access: a module may only depend on another module's public types (root package or api package), never its internal sub-packages.
No cycles: module dependencies must form a directed acyclic graph; A→B→A fails the build.
Declared dependencies only: if a module restricts its allowed dependencies with @ApplicationModule(allowedDependencies = ...), any undeclared dependency is rejected.

Run it as a normal JUnit test so violations break CI before they ever ship.

Restricting Allowed Dependencies

By default a module may depend on any other module's public API. To tighten that, place a package-info.java in the module's root package and annotate it with @ApplicationModule.

Here the order module is allowed to use only inventory. If someone later wires NotificationService into the order module, verify() fails immediately.

@org.springframework.modulith.ApplicationModule(
    allowedDependencies = { "inventory" }
)
package com.shop.order;

import org.springframework.modulith.ApplicationModule;

Named Interfaces for Selective Exposure

Sometimes a module needs to expose a second public surface beyond its root package. A named interface marks an extra package as public and lets other modules target it explicitly.

Annotate the package with @NamedInterface("spi"); then a consumer can declare a dependency on order :: spi rather than the whole module.

// com/shop/order/spi/package-info.java
@org.springframework.modulith.NamedInterface("spi")
package com.shop.order.spi;

import org.springframework.modulith.NamedInterface;

// Consumer module restricts itself to that named interface
@org.springframework.modulith.ApplicationModule(
    allowedDependencies = { "order :: spi" }
)
package com.shop.billing;

Decoupling with Application Events

The cleanest way to keep modules independent is to avoid direct service calls altogether. Instead of injecting InventoryService into the order module, publish a Spring ApplicationEventPublisher event and let inventory listen.

This inverts the dependency: order no longer needs to know inventory exists, which keeps the verified dependency graph small and acyclic.

@org.springframework.stereotype.Service
class OrderService {

    private final org.springframework.context.ApplicationEventPublisher events;

    OrderService(org.springframework.context.ApplicationEventPublisher events) {
        this.events = events;
    }

    void placeOrder(String sku, int qty) {
        // ... persist order ...
        events.publishEvent(new OrderPlaced(sku, qty));
    }
}

record OrderPlaced(String sku, int qty) {}

Listening Across Modules

The inventory module consumes the event without any compile-time link back to order — it only depends on the published event type. Spring Modulith encourages @ApplicationModuleListener, which combines @Async, @Transactional(propagation = REQUIRES_NEW), and @TransactionalEventListener so the listener runs in its own transaction after the publisher commits.

@org.springframework.stereotype.Component
class InventoryEventHandler {

    @org.springframework.modulith.events.ApplicationModuleListener
    void on(OrderPlaced event) {
        // runs async, in a fresh transaction, after commit
        decrementStock(event.sku(), event.qty());
    }

    private void decrementStock(String sku, int qty) { /* ... */ }
}

Generating Living Documentation

The same module model can render documentation. Documenter produces C4-style component diagrams (PlantUML) and an Asciidoctor module canvas describing each module's dependencies, exposed types, and events.

Because the diagrams are derived from real code during the test run, they never drift out of date — regenerating is just re-running the test.

import org.springframework.modulith.docs.Documenter;

@org.junit.jupiter.api.Test
void writeDocumentation() {
    var modules = ApplicationModules.of(ShopApplication.class);
    new Documenter(modules)
            .writeModulesAsPlantUml()      // overview diagram
            .writeIndividualModulesAsPlantUml()
            .writeModuleCanvases();        // target/modulith-docs
}

A Standalone Cycle Check

The boundary idea — reject dependency cycles — is simple enough to model in plain Java. This runnable program builds a tiny module graph and reports whether a cycle exists, mirroring what verify() does for real modules.

import java.util.*;

public class CycleCheck {
    static Map<String, List<String>> graph = new HashMap<>();

    static void dependsOn(String a, String b) {
        graph.computeIfAbsent(a, k -> new ArrayList<>()).add(b);
    }

    static boolean hasCycle(String node, Set<String> stack, Set<String> seen) {
        if (stack.contains(node)) return true;
        if (seen.contains(node)) return false;
        seen.add(node);
        stack.add(node);
        for (String next : graph.getOrDefault(node, List.of()))
            if (hasCycle(next, stack, seen)) return true;
        stack.remove(node);
        return false;
    }

    public static void main(String[] args) {
        dependsOn("order", "inventory");
        dependsOn("inventory", "order"); // illegal cycle
        boolean cyclic = false;
        for (String m : graph.keySet())
            cyclic |= hasCycle(m, new HashSet<>(), new HashSet<>());
        System.out.println("Cycle detected: " + cyclic);
    }
}

Quick Check

You annotate the order module with @ApplicationModule(allowedDependencies = { "inventory" }). A new commit injects NotificationService (from the notification module) into a bean inside order. What happens?

Recap

You learned how Spring Modulith turns a Spring Boot monolith into a set of verified modules:

Modules are the direct sub-packages of your main application package; root and api/named-interface packages are public, the rest internal.
ApplicationModules.of(App.class).verify() enforces no internal access, no cycles, and declared-only dependencies as a JUnit test.
@ApplicationModule(allowedDependencies = ...) tightens the graph; @NamedInterface exposes extra public surfaces selectively.
Prefer application events with @ApplicationModuleListener to decouple modules instead of direct service calls.
Documenter generates always-current PlantUML diagrams and module canvases from the same model.

Często zadawane pytania

Czy lekcja „Moduły aplikacji i weryfikacja granic” jest bezpłatna?

Tak — pełny tekst „Moduły aplikacji i weryfikacja granic” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Spring Boot 4 Complete Guide, przejdź na CoddyKit PRO. Kurs Spring Boot 4 Complete Guide zawiera 4 lekcji w sumie.

Co nauczysz się w „Moduły aplikacji i weryfikacja granic”?

Definiuj i egzekwuj granice modułów za pomocą weryfikacji struktury i dokumentacji Spring Modulith. Ćwiczysz Spring Boot 4 Complete Guide z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Spring Boot 4 Complete Guide?

Nie wymagamy żadnego doświadczenia. Spring Boot 4 Complete Guide w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Moduły aplikacji i weryfikacja granic”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Spring Boot 4 Complete Guide?

Tak. Każda lekcja Spring Boot 4 Complete Guide zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Moduły aplikacji i weryfikacja granic
Wewnętrzne zdarzenia aplikacji i listenery
Transakcyjne publikowanie zdarzeń i outbox
Testowanie integracji modułów i scenariuszy

← Powrót do Spring Boot 4 Complete Guide