B컷전문 | 개발과 인생의 이야기

Spring Boot에서 멀티 모듈 구조를 설계하는 방법을 소개합니다. 도메인 분리, 공통 모듈 구성, 계층화 전략, 의존성 관리 등 실무 적용 사례 중심으로 설명합니다.

---

Spring Boot 고급 시리즈 10편 – 멀티 모듈 아키텍처 전략: 실무 서비스 구조 분리 가이드

Spring Boot 기반 프로젝트가 커지고 도메인이 복잡해질수록,
하나의 src/main 폴더에 모든 기능을 넣는 방식은 유지보수와 협업의 한계를 드러냅니다.

이번 편에서는 멀티 모듈(Multi-Module) 구조를 통해 프로젝트를 수평/수직으로 나누고,
도메인 중심 개발과 팀 간 협업에 적합한 구조를 만드는 방법을 실제 운영 사례를 바탕으로 설명합니다.

---

🧱 1. 멀티 모듈 구조가 필요한 이유

상황 멀티 모듈의 효과

서비스가 커지며 도메인이 많아짐	도메인 단위로 모듈 분리 가능
팀원이 늘어나며 충돌 빈도 ↑	모듈 단위 협업 구조화 가능
공통 코드 중복	core 또는 common 모듈로 재사용 가능
테스트 시간 증가	모듈 단위 테스트/빌드로 효율 ↑
운영 환경 최적화 필요	API, Admin, Batch 등 환경별 분리 가능

---

🧩 2. 기본적인 멀티 모듈 구성 예시

myapp-backend/
├── build.gradle (root)
├── settings.gradle
├── modules/
│   ├── core/                 # 공통 유틸리티, 상수, 공통 응답 등
│   ├── domain-user/          # 사용자 도메인 (Entity + Service)
│   ├── domain-order/         # 주문 도메인
│   ├── api/                  # API Layer (Controller + UseCase)
│   ├── batch/                # 배치 전용 모듈
│   └── infra/                # 외부 연동, JPA 구현체, Redis 등

• 핵심은 기능별, 계층별로 책임이 명확하게 분리되는 구조입니다.
• core는 모든 모듈이 의존 가능하지만, 다른 모듈은 교차 의존하지 않도록 관리해야 합니다.

---

✅ 3. settings.gradle 구성

rootProject.name = 'myapp'

include 'modules:core'
include 'modules:domain-user'
include 'modules:domain-order'
include 'modules:api'
include 'modules:batch'
include 'modules:infra'

---

⚙️ 4. 의존성 관리 전략 (Gradle 기준)

🔸 예시: api/build.gradle.kts

dependencies {
    implementation(project(":modules:core"))
    implementation(project(":modules:domain-user"))
    implementation(project(":modules:domain-order"))
    implementation(project(":modules:infra"))
    implementation("org.springframework.boot:spring-boot-starter-web")
}

🔸 모듈 간 의존 방향 원칙

모듈 의존 대상

core	없음 (기본 모듈)
domain-*	core만 의존
infra	core, domain-*
api	모든 도메인 및 인프라에 의존
batch	core, domain-*, infra (필요 시)

❗ 도메인 간 직접 참조 금지 → 반드시 API 또는 공용 인터페이스를 통해 연결

---

🧠 실무 설계 팁

항목 전략

모듈 최소화	모듈은 도메인 또는 기술 단위로 명확히 정의
순환 참조 방지	A → B, B → A 불가. 필요시 이벤트 발행 또는 Port-Adapter 패턴 적용
공통 코드 관리	core 모듈에 Response DTO, Exception, Security 설정 등 공용화
모듈별 테스트	api 모듈에서 통합 테스트, domain-* 모듈은 단위 테스트 중심
빌드 속도 최적화	Gradle 병렬 빌드 + 테스트 분리로 CI 시간 단축 가능

---

📦 확장 구조 예시: MSA 전환 대비 구조

modules/
├── shared-common/      # 모든 서비스 공통 유틸
├── user-service/       # 독립적 user 마이크로서비스
│   ├── user-api/
│   ├── user-domain/
│   └── user-infra/
├── order-service/
│   ├── order-api/
│   ├── order-domain/
│   └── order-infra/

• 각 서비스는 도메인 독립성을 갖춘 독자적인 구조
• 향후 MSA 또는 모듈형 모노리스로 전환 가능

---

✅ 마무리 요약

항목 요약

도입 이유	협업 구조화, 빌드 분리, 책임 분리, 테스트 단위화
핵심 전략	도메인 중심 분리, 공통 모듈 분리, 계층화
의존 관계	core ← domain ← infra ← api
권장 구조	최소한 core/domain/api, 필요시 infra, batch 확장
실전 효과	유지보수 효율 ↑, 운영 안정성 ↑, CI/CD 속도 개선 ↑

---

📌 다음 시리즈 예고

🎯 Spring Boot 고급 실전 리팩토링 시리즈로 이어집니다:

• Controller Fat → UseCase 중심 구조 전환
• Service 정리 및 응집도 향상
• 레거시 코드 기반 도메인 재구성 전략