Spring Modulith로 모놀리식을 모듈화하기: 스프링 모듈리스 아키텍처 완벽 가이드

Spring Modulith로 모놀리식을 모듈화하기: 스프링 모듈리스 아키텍처 완벽 가이드

 

현대의 소프트웨어 개발에서 모놀리식 애플리케이션의 복잡성은 계속해서 증가하고 있습니다.

많은 개발팀이 마이크로서비스로의 전환을 고려하지만, 그 과정에서 발생하는 운영 복잡성과 분산 시스템의 어려움에 직면하게 됩니다.

이러한 상황에서 스프링 모듈리스는 모놀리식 애플리케이션의 장점을 유지하면서도 모듈화 아키텍처의 이점을 제공하는 혁신적인 접근 방식입니다.

Spring Modulith는 Spring 생태계에서 모듈화 아키텍처를 구현하기 위한 강력한 도구로, 기존 모놀리식 애플리케이션을 체계적으로 모듈화할 수 있는 프레임워크입니다.

---

Spring Modulith란 무엇인가?

Spring Modulith는 Spring Boot 애플리케이션 내에서 모듈 경계를 명확히 정의하고 관리할 수 있게 해주는 프레임워크입니다.

전통적인 모놀리식 애플리케이션에서 발생하는 코드 간의 강한 결합과 복잡한 의존성 문제를 해결하기 위해 설계되었습니다.

Spring Modulith 아키텍처 개념도

 

Spring Modulith의 핵심 개념은 '응용 프로그램 모듈'입니다.

각 모듈은 독립적인 비즈니스 기능을 담당하며, 명확한 API를 통해서만 다른 모듈과 상호작용합니다.

이러한 접근 방식은 마이크로서비스의 모듈성을 제공하면서도 모놀리식 배포의 단순함을 유지합니다.

 

모듈화 아키텍처의 주요 특징은 다음과 같습니다:

• 명확한 모듈 경계: 각 모듈은 독립적인 패키지 구조를 가짐
• 제한된 접근성: 모듈 간 직접적인 내부 클래스 접근 방지
• 이벤트 기반 통신: 모듈 간 느슨한 결합을 위한 이벤트 발행/구독 패턴
• 테스트 격리: 각 모듈을 독립적으로 테스트 가능

---

스프링 모듈리스 도입의 필요성

기존 모놀리식 애플리케이션에서 발생하는 주요 문제점들을 살펴보겠습니다.

 

코드 복잡성 증가

시간이 지남에 따라 모놀리식 애플리케이션의 코드베이스는 점점 복잡해집니다.

서로 다른 비즈니스 로직이 얽혀있어 새로운 기능을 추가하거나 기존 기능을 수정할 때 예상치 못한 부작용이 발생할 수 있습니다.

 

팀 간 협업의 어려움

대규모 개발팀에서는 여러 팀이 같은 코드베이스에서 작업하게 됩니다.

명확한 모듈 경계가 없으면 팀 간 작업 영역이 겹치면서 충돌이 발생하고 개발 속도가 저하됩니다.

 

유지보수 비용 증가

강하게 결합된 코드는 작은 변경사항도 광범위한 영향을 미칠 수 있습니다.

이는 회귀 테스트의 범위를 넓히고 배포 위험을 증가시켜 전체적인 유지보수 비용을 상승시킵니다.

Spring Modulith는 이러한 문제들을 해결하기 위한 효과적인 솔루션을 제공합니다.

---

Spring Modulith 프로젝트 구조와 설정

Spring Modulith를 활용한 프로젝트의 기본 구조를 살펴보겠습니다.

 

프로젝트 초기 설정

먼저 build.gradle 또는 pom.xml에 Spring Modulith 의존성을 추가해야 합니다:

dependencies {
    implementation 'org.springframework.modulith:spring-modulith-starter-core'
    testImplementation 'org.springframework.modulith:spring-modulith-starter-test'
}

 

모듈 패키지 구조

권장되는 패키지 구조는 다음과 같습니다:

src/main/java/com/example/application/
├── Application.java
├── order/
│   ├── OrderService.java
│   ├── OrderRepository.java
│   └── internal/
│       └── OrderProcessor.java
├── inventory/
│   ├── InventoryService.java
│   ├── InventoryRepository.java
│   └── internal/
│       └── StockCalculator.java
└── customer/
    ├── CustomerService.java
    ├── CustomerRepository.java
    └── internal/
        └── CustomerValidator.java

각 최상위 패키지(order, inventory, customer)가 하나의 모듈을 나타내며, internal 패키지는 해당 모듈의 내부 구현사항을 포함합니다.

 

Spring Modulith 패키지 구조 다이어그램

 

모듈 설정 클래스

각 모듈은 독립적인 설정을 가질 수 있습니다:

@Configuration
@ComponentScan
public class OrderModuleConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public OrderService orderService(OrderRepository repository) {
        return new OrderService(repository);
    }
}

---

모듈 간 통신 및 이벤트 처리

Spring Modulith에서 모듈 간 통신은 주로 이벤트 기반으로 이루어집니다.

이는 모듈 간의 직접적인 의존성을 제거하고 느슨한 결합을 유지하는 데 중요한 역할을 합니다.

 

이벤트 발행

주문 모듈에서 주문 완료 이벤트를 발행하는 예시입니다:

@Service
public class OrderService {

    private final ApplicationEventPublisher eventPublisher;
    private final OrderRepository orderRepository;

    public Order completeOrder(Long orderId) {
        Order order = orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));

        order.complete();
        orderRepository.save(order);

        // 이벤트 발행
        eventPublisher.publishEvent(new OrderCompletedEvent(order.getId(), order.getCustomerId()));

        return order;
    }
}

 

이벤트 수신

재고 모듈에서 주문 완료 이벤트를 수신하여 재고를 업데이트합니다:

@Component
public class InventoryEventHandler {

    private final InventoryService inventoryService;

    @EventListener
    public void handleOrderCompleted(OrderCompletedEvent event) {
        inventoryService.updateStock(event.getOrderId());
    }
}

 

비동기 이벤트 처리

대용량 처리를 위해 비동기 이벤트 처리도 지원합니다:

@Async
@EventListener
public void handleOrderCompletedAsync(OrderCompletedEvent event) {
    // 비동기 처리 로직
    customerService.updateCustomerStatistics(event.getCustomerId());
}

 

이벤트 기반 통신의 장점은 다음과 같습니다:

• 디커플링: 모듈 간 직접적인 의존성 제거
• 확장성: 새로운 이벤트 리스너 추가가 용이
• 신뢰성: 이벤트 발행/수신 실패에 대한 처리 가능

---

모듈 경계 검증 및 테스트

반응형

Spring Modulith의 가장 강력한 기능 중 하나는 모듈 경계를 자동으로 검증하는 것입니다.

 

모듈 구조 검증

다음과 같은 테스트 코드로 모듈 구조를 검증할 수 있습니다:

@ModulithTest
public class ModuleStructureTest {

    @Test
    void verifyModuleStructure() {
        ApplicationModules modules = ApplicationModules.of(Application.class);
        modules.verify();
    }

    @Test
    void createModuleDocumentation() throws IOException {
        ApplicationModules modules = ApplicationModules.of(Application.class);

        new Documenter(modules)
            .writeDocumentation()
            .writeIndividualModulesAsPlantUml();
    }
}

 

모듈 간 의존성 테스트

잘못된 모듈 간 의존성을 감지하는 테스트:

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

    modules.stream()
        .filter(module -> module.getName().equals("order"))
        .forEach(module -> {
            assertThat(module.getDirectDependencies())
                .extracting(ApplicationModule::getName)
                .doesNotContain("inventory", "customer");
        });
}

 

통합 테스트

특정 모듈만을 대상으로 하는 슬라이스 테스트:

@ModuleTest
class OrderModuleIntegrationTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCompleteOrderSuccessfully() {
        // 주문 모듈만을 대상으로 한 테스트
        Order order = orderService.createOrder(createOrderRequest());
        Order completedOrder = orderService.completeOrder(order.getId());

        assertThat(completedOrder.getStatus()).isEqualTo(OrderStatus.COMPLETED);
    }
}

 

모듈 의존성 그래프 및 테스트 결과

---

실제 적용 사례 및 모범 사례

Spring Modulith를 실제 프로젝트에 적용할 때 고려해야 할 모범 사례들을 살펴보겠습니다.

 

점진적 마이그레이션 전략

기존 모놀리식 애플리케이션을 한 번에 모듈화하는 것은 위험합니다.

다음과 같은 단계적 접근 방식을 권장합니다:

1. 경계 식별: 비즈니스 도메인을 기반으로 모듈 경계 정의
2. 패키지 재구성: 식별된 모듈별로 패키지 구조 재편
3. 의존성 분석: 기존 클래스 간 의존성 분석 및 정리
4. 이벤트 도입: 직접 의존성을 이벤트 기반 통신으로 전환
5. 테스트 추가: 모듈 경계 검증 테스트 작성

모듈 설계 원칙

효과적인 모듈 설계를 위한 핵심 원칙들:

단일 책임 원칙

각 모듈은 하나의 명확한 비즈니스 책임을 가져야 합니다.

주문 처리, 재고 관리, 고객 관리와 같이 구체적이고 응집력 있는 기능을 담당해야 합니다.

인터페이스 분리

모듈 간 통신은 명확히 정의된 인터페이스를 통해서만 이루어져야 합니다.

internal 패키지의 클래스들은 다른 모듈에서 직접 접근할 수 없도록 해야 합니다.

의존성 역전

상위 레벨 모듈이 하위 레벨 모듈에 의존하지 않도록 추상화를 활용해야 합니다.

 

성능 최적화 고려사항

모듈화 아키텍처에서 성능을 최적화하는 방법들:

이벤트 처리 최적화: 비동기 이벤트 처리를 통해 응답 시간을 개선할 수 있습니다.

중요하지 않은 후속 처리들은 비동기로 처리하여 사용자 경험을 향상시킵니다.

캐싱 전략: 모듈 간 데이터 조회를 최소화하기 위해 적절한 캐싱 전략을 수립해야 합니다.

각 모듈은 자체적인 캐싱 메커니즘을 가질 수 있습니다.

---

모니터링 및 문제 해결

Spring Modulith 애플리케이션의 모니터링과 문제 해결 방법을 알아보겠습니다.

 

모듈 메트릭 수집

Spring Boot Actuator와 Micrometer를 활용하여 모듈별 메트릭을 수집할 수 있습니다:

@Component
public class OrderModuleMetrics implements ApplicationListener<OrderCompletedEvent> {

    private final MeterRegistry meterRegistry;
    private final Counter orderCompletedCounter;

    public OrderModuleMetrics(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.orderCompletedCounter = Counter.builder("orders.completed")
            .description("Number of completed orders")
            .register(meterRegistry);
    }

    @Override
    public void onApplicationEvent(OrderCompletedEvent event) {
        orderCompletedCounter.increment();
    }
}

 

이벤트 추적

모듈 간 이벤트 흐름을 추적하기 위한 로깅 설정:

@EventListener
public void handleOrderEvent(OrderCompletedEvent event) {
    log.info("Processing order completed event: orderId={}, customerId={}", 
             event.getOrderId(), event.getCustomerId());

    // 비즈니스 로직 처리

    log.info("Order event processing completed: orderId={}", event.getOrderId());
}

 

분산 추적

Spring Cloud Sleuth를 활용하여 모듈 간 이벤트 처리 과정을 추적할 수 있습니다.

이를 통해 복잡한 비즈니스 플로우에서 병목 지점을 식별하고 성능을 최적화할 수 있습니다.

---

마이크로서비스로의 진화 경로

728x90

Spring Modulith는 마이크로서비스로의 점진적 전환을 위한 중간 단계 역할을 할 수 있습니다.

 

모듈에서 서비스로 추출

잘 정의된 모듈은 독립된 마이크로서비스로 쉽게 추출할 수 있습니다:

1. 데이터베이스 분리: 모듈별 데이터 저장소 분리
2. API 인터페이스 정의: RESTful API 또는 GraphQL 엔드포인트 생성
3. 배포 독립성: 별도의 배포 파이프라인 구성
4. 서비스 디스커버리: 마이크로서비스 간 통신을 위한 서비스 레지스트리 도입

하이브리드 아키텍처

모든 모듈을 마이크로서비스로 전환할 필요는 없습니다.

비즈니스 요구사항에 따라 일부 모듈은 모놀리스 내에 유지하고,

일부는 독립된 서비스로 분리하는 하이브리드 접근 방식이 효과적일 수 있습니다.

 

전환 시 고려사항

마이크로서비스로 전환할 때 고려해야 할 요소들:

• 팀 구조: 각 서비스를 담당할 팀의 구성과 역량
• 운영 복잡성: 분산 시스템 운영에 필요한 인프라와 도구
• 데이터 일관성: 분산 트랜잭션 처리 방안
• 네트워크 지연: 서비스 간 통신으로 인한 성능 영향

---

결론

스프링 모듈리스는 모놀리식 애플리케이션의 장점을 유지하면서도 모듈화 아키텍처의 이점을 제공하는 혁신적인 접근 방식입니다.

Spring Modulith를 통해 개발팀은 복잡한 분산 시스템의 운영 부담 없이도 체계적이고 확장 가능한 애플리케이션을 구축할 수 있습니다.

 

핵심 이점 요약

모듈화 아키텍처의 주요 이점은 다음과 같습니다:

• 개발 생산성 향상: 명확한 모듈 경계로 인한 개발 효율성 증대
• 유지보수성 개선: 모듈 간 느슨한 결합으로 변경 영향도 최소화
• 팀 협업 최적화: 모듈별 팀 소유권 확립으로 협업 효율성 향상
• 점진적 진화: 마이크로서비스로의 자연스러운 전환 경로 제공

Spring Modulith는 단순히 코드를 정리하는 도구가 아니라, 지속 가능한 소프트웨어 아키텍처를 구축하기 위한 전략적 선택입니다.

기존 모놀리식 애플리케이션의 한계를 극복하고 싶다면, Spring Modulith를 활용한 모듈화 아키텍처 도입을 진지하게 고려해보시기 바랍니다.

---

참고 자료

• Spring Modulith 공식 문서
• Spring Boot 공식 문서
• Domain-Driven Design 참고서
• Microservices.io 패턴 가이드