멀티모듈 핵심 개념 이해하기

“멀티모듈”이란?

하나의 Git 리포지터리(또는 빌드 루트) 안에 여러 개의 독립적인 서브프로젝트(Module)를 두고, 각 모듈을 별도 JAR 아티팩트로 빌드·테스트·배포할 수 있도록 구성한 아키텍처를 말합니다.
쉽게 말해 “한 솥에 끓이던 코드를 기능별로 여러 냄비에 나눠 담는 것” 이라 보면 됩니다.

---

1️⃣ 멀티모듈이 필요한 5가지 상황

• 빅 스프링 프로젝트 – 도메인·레이어가 방대해지며 컴파일·테스트 시간이 폭증할 때
• 팀 분업 – 핵심 도메인, 외부 API, 배치 잡을 다른 팀이 병렬로 개발할 때
• 재사용 라이브러리 – 공통 유틸·DTO·보안 모듈을 여러 서비스에서 가져다 쓰고 싶을 때
• 마이크로서비스 이행 – 모놀리스를 단계적으로 쪼개면서 모듈 단위로 분리 배포하고 싶을 때
• 버전 충돌 사고 – 의존성이 얽히고설켜 “Jar Hell”이 자주 터질 때

---

2️⃣ 멀티모듈 구조의 골격

root-project
 ├─ build.gradle.kts     ← 공통 플러그인·버전을 한곳에서 관리
 ├─ settings.gradle.kts  ← include("core", "api", "batch", "common-util")
 └─ modules
     ├─ core
     │   └─ build.gradle.kts
     ├─ api
     ├─ batch
     └─ common-util

• 루트: 전사적인 빌드 전략·버전 카탈로그·CI 태스크 정의
• 서브모듈: 각자 dependencies { implementation(project(":core")) } 식으로 필요한 모듈만 의존
• Gradle 캐시: 모듈 단위 인크리멘털 빌드 → 수정 없는 모듈은 다시 컴파일하지 않아 속도 급상승

---

3️⃣ 멀티모듈의 주요 장점

1. 빌드 속도 UP – 모듈 하나만 바꿔도 전체가 아닌 해당 모듈+의존 모듈만 재빌드
2. 의존성 격리 – 모듈 경계를 넘지 못하면 ‘스파게티’ 순환 의존이 원천 차단
3. 테스트 분리 – 모듈별 JUnit 태스크·Testcontainers로 DB, 외부 시스템 완전 고립
4. 독립 배포 – 라이브러리 모듈을 Maven Private Repo 또는 Docker 이미지로 따로 배포 가능
5. 점진적 리팩터링 – 큰 모놀리스도 기능 단위 모듈로 잘라가며 안전하게 개선

---

4️⃣ 최초 도입 체크리스트

• 도메인 경계가 선명한가? (예: 주문·결제·회원)
• 공통 유틸은 분리하되, 과도한 나눔은 오히려 복잡도 상승
• 빌드 스크립트 중복을 방지하려면 root subprojects { … } 또는 buildSrc 플러그인을 활용
• CI/CD 분할 - GitHub Actions matrix·Gradle parallel 옵션으로 모듈별 병행 파이프라인 구축
• IDE 성능 - 모듈이 지나치게 많으면 인덱싱 오버헤드 ↔ 기능·팀 규모에 맞는 적정 개수 유지

---

5️⃣ 흔한 오해 깨기

• “멀티모듈 = 무조건 빠르다?”
  → 모듈 간 지나친 상호 의존·복잡한 설정은 오히려 빌드 시간을 늘립니다. 경계를 명확히!
• “모놀리스와 충돌한다?”
  → 멀티모듈은 빌드·배포 관점의 모듈화입니다. 런타임엔 하나의 애플리케이션으로 구동될 수도 있습니다.
• “도입이 어렵다?”
  → Gradle 7+ java-platform, version catalog, java-test-fixtures 덕분에 설정 난이도가 대폭 낮아졌습니다.

---

✨ 마무리

멀티모듈은 “속도·품질·확장성” 세 마리 토끼를 잡기 위한 필수 전략입니다.
작은 프로젝트라도 모듈 경계를 미리 설계해 두면, 서비스가 성장해도 리스크 없이 스케일업할 수 있습니다.
다음 글에선 Gradle Version Catalog를 사용해 멀티모듈 의존성을 한 방에 관리하는 방법을 파헤쳐 보겠습니다!