대규모 Spring 기반 프로젝트가 확장될수록 빌드 시간 증가, 의존성 혼잡, 유지보수 어려움 등 다양한 문제가 발생합니다.
이러한 문제를 해결하기 위해 실무에서 널리 도입되는 방식이 멀티 모듈 아키텍처입니다.
아래 내용은 우아한형제들 기술블로그와 향로님의 글을 기반으로 정리한 것이며,
여기에 실무적인 관점에서 필요한 내용을 추가로 보완하였습니다.
멀티 모듈이 필요한 이유
Spring 기반의 단일 모듈 프로젝트는 초기에는 개발 속도가 빠르고 구조가 단순해 보입니다.
그러나 규모가 커질수록 다음과 같은 문제가 발생합니다.
- 기능간 경계가 모호하여 의존성이 복잡해집니다.
- 작은 변경에도 전체 빌드 및 전체 테스트가 필요합니다.
- 일부 기능만 수정해도 전체 서비스 재배포가 필요합니다.
- 패키지 분리만으로는 설계의 강제력이 부족합니다.
멀티 모듈은 이러한 구조적 문제를 물리적 단위(모듈)로 분리함으로써 해결합니다.
멀티 모듈 아키텍처의 핵심 목표
1) 명확한 경계 설정
각 모듈은 독립된 기능 단위로 존재하며, 모듈 간 불필요한 참조가 불가능합니다.
이를 통해 도메인 경계가 명확하게 강제됩니다.
2) 독립성 및 재사용성 향상
공통 기능, 도메인 기능, 인프라 기능 등을 분리함으로써
필요한 모듈만 재사용하거나 테스트할 수 있습니다.
3) 빌드 및 배포 효율성 확보
모듈 단위 캐싱과 증분 빌드가 적용되며,
테스트 또한 모듈 단위로 실행할 수 있어 속도가 비약적으로 향상됩니다.
대표적인 멀티 모듈 구조 예시
project
├── api // Controller, 외부 노출 계층
├── application // 유즈케이스, 서비스 로직
├── domain // 엔티티, 도메인 규칙, 도메인 서비스
├── infrastructure // DB, 메시징, 외부 API 구현체
└── common // 공통 유틸, 상수구조적 특징
API -> Application -> Domain방향으로 의존성이 흐릅니다.- Infrastructure 기술적 구현체가 위치하는 계층입니다.
- Domain은 가장 순수한 상태를 유지하며 어떠한 외부 모율에도 의존하지 않습니다.
- Application은 도메인을 기반으로 유즈케이스를 정의하는 계층입니다.
모듈 간 의존성 설계 원칙
멀티 모듈 아키텍처의 품질은 의존성 설계에 의해 결정됩니다.
1) Domain은 순수성을 유지해야 합니다.
Domain은 비즈니스 규칙과 엔티티만을 보유하며, DB/외부 API/Framework 등을 인지하지 않습니다.
2) Application은 유즈케이스를 정의합니다
도메인의 규칙을 활용하여 기능 흐름을 구성하며,
도메인과 인프라 사이를 중개하는 역할을 수행합니다.
3) Infrastructure는 기술 세부 구현체를 담습니다.
JPA Repository 구현체, 외부 API 연동, 메시지 브로커 연동 등이 여기에 포함됩니다.
4) DIP(의존성 역전 원칙) 적용
- 인터페이스는 domain 또는 application에 두고
- 구현체는 infra에 위치시키는 방식입니다.
이를 통해 "상위 정책이 하위 기술에 종속되지 않는 구조"가 완성됩니다.
멀티 모듈 적용 시 주의할 점
1) 모듈 과분리 방지
의미 있는 도메인 경계까지만 분리하는 것이 중요합니다.
2) common 모듈 비대화 방지
common은 “어디에도 속하지 않는 코드”가 아니라 “모두에게 공통적으로 필요한 최소한의 코드”만 포함해야 합니다.
3) 도메인 규칙의 위치 명확화
도메인 규칙이 application/service 계층에 혼재되면 경계가 무너집니다.
4) 인터페이스/구현체 분리
기술 구현체는 항상 infra에 위치시키고, 상위 계층은 인터페이스만 바라보도록 구성해야 합니다.
마무리
멀티 모듈 아키텍처는 단순한 구조 분리가 아니라,
프로젝트 전반의 변화 대응력과 유지보수성을 극적으로 개선하는 설계적 선택입니다.
다만, 개념을 이해하는 것만으로는 실제 프로젝트에 어떻게 적용되는지 감이 잘 오지 않을 수 있습니다.
다음 글에서는 이 개념들이 코드에서 어떻게 구현되고 동작하는지 정리할 예정입니다.
출처
멀티모듈 설계 이야기 with Spring, Gradle | 우아한형제들 기술블로그
Gradle 멀티 프로젝트 관리 by 향로 (기억보단 기록을)
