멀티모듈

최규진·2025년 4월 8일

멀티모듈이란?

하나의 큰 프로젝트를 여러 개의 작은 모듈로 나누어 구성한 형태입니다. 각 모듈은 독립적으로 개발되고, 빌드되며, 다른 모듈과 의존 관계를 맺을 수 있습니다.

왜 멀티모듈을 쓰는가?

관심사의 분리
기능별로 코드를 나누어 유지보수성과 가독성을 높일 수 있습니다.
ex) core, api, domain, service, batch, web, common, infra 등으로 나누기.
재사용성 향상
공통 모듈을 만들어 여러 서비스에서 재사용 가능합니다.
빌드 성능 향상
변경된 모듈만 빌드하면 되기 때문에 전체 빌드보다 빠를 수 있습니다.
협업 효율 증가
여러 명이 동시에 작업할 때 충돌을 줄일 수 있습니다.

구조 예시

1. 전체 구조

spring-multi-module/
├── build.gradle (루트)
├── settings.gradle
├── common/         → 공통 유틸, DTO, 예외처리 등
│   └── build.gradle
├── domain/         → JPA Entity, Repository
│   └── build.gradle
├── service/        → 비즈니스 로직 (Service 계층)
│   └── build.gradle
├── api/            → Controller, main 실행 (Spring Boot app)
│   └── build.gradle

각 모듈마다 build.gradle이 필요한 이유는 각 모듈마다 필요한 라이브러리(dependencies)가 다르고, 독립적으로 설정할 수 있도록 설계되기 때문입니다.

2. settings.gradle

rootProject.name = 'spring-multi-module'
include 'common', 'domain', 'service', 'api'

3. api 모듈, service 모듈, domain 모듈, common 모듈 4가지가 있는데, api 모듈을 예로 들어보겠습니다.

api/build.gradle
plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'java'
}
dependencies {
    implementation project(':service')
    implementation project(':domain')
    implementation project(':common')
    implementation 'org.springframework.boot:spring-boot-starter-web'
}
위의 부분에서 dependencies 안에 있는 implementation이 멀티 모듈 핵심 부분이라고 말할 수 있습니다.
project(:모듈명)은 다른 모듈을 참조하겠다는 의미입니다. api 모듈은 단독으로 실행되지만, 실제 동작은 다른 모듈 (service, domain, common)에 의존합니다.
api에서 실행은 하지만 로직은 모듈에게 맡긴다는 뜻으로 해석하면 됩니다.

멀티 모듈 구성 종류

1. 레이어별 모듈 분리 (Layered Architecture)

📦 user-domain         → User 도메인만 담당
📦 product-domain      → Product 도메인만 담당
📦 user-api            → UserController 전용 API
📦 product-api         → 상품 API
📦 common
📦 core                → 공통 규칙, 보안, 인터페이스

대부분의 서비스에서 기본으로 사용하는 구조

2. 기능 기반 모듈 분리 (Feature-based Modularity)
📦 user-domain         → User 도메인만 담당
📦 product-domain      → Product 도메인만 담당
📦 user-api            → UserController 전용 API
📦 product-api         → 상품 API
📦 common
📦 core                → 공통 규칙, 보안, 인터페이스
대규모 서비스에서 도메인 독립성을 위해 나누는 구조
모놀리식 -> MSA 전환에 유리

3. API/BATCH/EXTERNAL 분리

📦 api              → 웹 요청 처리 (Controller)
📦 batch            → 스케줄 기반 처리 (Spring Batch 등)
📦 external-api     → 외부 시스템 연동 (카카오, 네이버 API 등)
📦 service
📦 domain
📦 common

한 프로젝트 안에서 다양한 실행 목적의 앱을 분리, 성능 분산

4. 모듈 간 의존 방향 설계

common  ← domain  ← service  ← api
                          ↑
                     (batch, external 등)

5. 도메인간 의존 차단

📦 user-domain
│   └── UserService.java
│
📦 product-domain
│   └── ProductInfoProvider.java (인터페이스)
│
📦 product-adapter
    └── ProductInfoProviderImpl.java (product-domain의 구현)

도메인 간 강한 결합 방지, 테스트와 MSA 전환에 유리

멀티모듈 vs MSA

구분	설명	Git Repo	실행 방식
멀티모듈	하나의 프로젝트 안에 여러 모듈로 분리	1개	주로 하나의 앱 실행
MSA	완전히 다른 프로젝트로 분리	여러 개	서비스 마다 실행 되어, 각각 다른 포트로 실행