Spring Modulith — 모놀리스 안에서 모듈 경계를 지키는 방법

// build.gradle
implementation 'org.springframework.modulith:spring-modulith-starter-core'
testImplementation 'org.springframework.modulith:spring-modulith-starter-test'

// 이벤트 영속화가 필요하면
implementation 'org.springframework.modulith:spring-modulith-starter-jpa'

com.example.shop/
├── ShopApplication.java     ← 메인 클래스
├── order/                   ← order 모듈
│   ├── Order.java          ← 공개 API (루트 패키지)
│   ├── OrderService.java   ← 공개 API
│   └── internal/           ← 내부 구현 (외부 접근 금지)
│       ├── OrderRepository.java
│       └── OrderValidator.java
├── payment/                 ← payment 모듈
│   ├── PaymentService.java
│   └── internal/
│       └── PaymentGateway.java
├── inventory/               ← inventory 모듈
│   ├── InventoryService.java
│   └── internal/
│       └── StockRepository.java
└── notification/            ← notification 모듈
    ├── NotificationService.java
    └── internal/
        └── EmailSender.java

@Test
void verifyModuleStructure() {
    ApplicationModules modules =
        ApplicationModules.of(ShopApplication.class);

    // 모듈 경계 위반, 순환 참조 검증
    modules.verify();
}

@Test
void printModuleStructure() {
    ApplicationModules modules =
        ApplicationModules.of(ShopApplication.class);

    // 모듈 구조 출력
    modules.forEach(System.out::println);
}

## order ##
> Logical name: order
> Base package: com.example.shop.order
> Direct dependencies: [payment, inventory]
> Spring beans: [OrderService, internal.OrderRepository, internal.OrderValidator]

## payment ##
> Logical name: payment
> Base package: com.example.shop.payment
> Direct dependencies: []

org.springframework.modulith.core.Violations:
- Module 'payment' depends on non-exposed type
  com.example.shop.order.internal.OrderRepository within module 'order'

// order 모듈의 공개 API (루트 패키지)
public record OrderCompleted(
    Long orderId,
    Long customerId,
    BigDecimal totalAmount,
    LocalDateTime completedAt
) {}

// order 모듈
@Service
@RequiredArgsConstructor
public class OrderService {
    private final ApplicationEventPublisher events;

    @Transactional
    public Order completeOrder(Long orderId) {
        Order order = orderRepository.findById(orderId).orElseThrow();
        order.complete();
        orderRepository.save(order);

        // 이벤트 발행 — 누가 구독하는지 알 필요 없음
        events.publishEvent(new OrderCompleted(
            order.getId(),
            order.getCustomerId(),
            order.getTotalAmount(),
            LocalDateTime.now()
        ));

        return order;
    }
}

// notification 모듈 — order 모듈을 직접 의존하지 않음
@Component
public class OrderNotificationHandler {

    @ApplicationModuleListener  // @EventListener + @Async + @Transactional
    void on(OrderCompleted event) {
        emailService.send(
            event.customerId(),
            "주문이 완료되었습니다. 주문번호: " + event.orderId()
        );
    }
}

// inventory 모듈
@Component
public class InventoryHandler {

    @ApplicationModuleListener
    void on(OrderCompleted event) {
        stockService.decreaseStock(event.orderId());
    }
}

// build.gradle
implementation 'org.springframework.modulith:spring-modulith-starter-jpa'

# application.yml
spring:
  modulith:
    republish-outstanding-events-on-restart: true  # 재시작 시 미완료 이벤트 재발행
    events:
      jdbc:
        schema-initialization:
          enabled: true  # 테이블 자동 생성

@ApplicationModuleTest  // order 모듈만 로드
class OrderModuleTest {

    @Autowired
    private OrderService orderService;

    @Test
    void completeOrder_publishesEvent(Scenario scenario) {
        // given
        Long orderId = createTestOrder();

        // when & then — 이벤트 발행 검증
        scenario.stimulate(() -> orderService.completeOrder(orderId))
            .andWaitForEventOfType(OrderCompleted.class)
            .matching(event -> event.orderId().equals(orderId))
            .toArriveAndVerify(event -> {
                assertThat(event.totalAmount())
                    .isGreaterThan(BigDecimal.ZERO);
            });
    }
}

@ApplicationModuleTest(mode = BootstrapMode.DIRECT_DEPENDENCIES)
// STANDALONE: 해당 모듈만
// DIRECT_DEPENDENCIES: 직접 의존하는 모듈 포함
// ALL_DEPENDENCIES: 모든 의존 모듈 포함

@Test
void generateDocumentation() {
    ApplicationModules modules =
        ApplicationModules.of(ShopApplication.class);

    // PlantUML, Asciidoc 형식의 문서 생성
    new Documenter(modules)
        .writeModulesAsPlantUml()          // 모듈 다이어그램
        .writeIndividualModulesAsPlantUml() // 개별 모듈 다이어그램
        .writeModuleCanvases();            // 모듈 캔버스
}

// build.gradle
implementation 'org.springframework.modulith:spring-modulith-events-kafka'

// 이벤트에 외부화 어노테이션 추가
@Externalized("order-events::#{orderId()}")  // topic::routing-key
public record OrderCompleted(
    Long orderId,
    Long customerId,
    BigDecimal totalAmount
) {}