📦 멀티 모듈 가이드

구조 개요

mo-it/
├── gradle/libs.versions.toml  # 의존성 버전 관리
├── build.gradle.kts           # 공통 Gradle 설정 (subprojects 블록)
├── settings.gradle.kts        # 모듈 정의
├── common/                    # 공통 유틸, Exception, Response DTO
├── core/                      # 도메인 Entity, Service, Port Interface
├── api/                       # REST Controller
├── persistence/               # JPA Entity, Repository 구현
└── app/                       # Spring Boot 실행

---

공통 Gradle 설정

모든 모듈의 공통 설정은 루트 build.gradle.kts 의 subprojects 블록에서 관리합니다.

// build.gradle.kts (루트)
subprojects {
    apply(plugin = "org.jetbrains.kotlin.jvm")
    apply(plugin = "org.jetbrains.kotlin.plugin.spring")
    apply(plugin = "io.spring.dependency-management")

    // 공통 의존성
    dependencies {
        "implementation"("com.fasterxml.jackson.module:jackson-module-kotlin")
        "implementation"("org.jetbrains.kotlin:kotlin-reflect")
        "testImplementation"("org.jetbrains.kotlin:kotlin-test-junit5")
    }

    // 공통 설정 (Java 21, JUnit 등)
    configure<JavaPluginExtension> {
        toolchain { languageVersion.set(JavaLanguageVersion.of(21)) }
    }

    tasks.withType<Test> { useJUnitPlatform() }
}

장점: 각 모듈의 build.gradle.kts가 매우 간결해집니다.

---

의존성 버전 관리 (Version Catalog)

gradle/libs.versions.toml 에서 의존성 버전을 중앙 관리합니다.

[versions]
kotlin = "1.9.25"
spring-boot = "3.2.3"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

사용법:

// 모듈 build.gradle.kts
dependencies {
    implementation(libs.spring.boot.starter.web)
}

---

모듈별 역할

모듈	역할	패키지
common	공통 Exception, Response DTO	com.moit.common.*
core	도메인, 서비스, 포트 인터페이스	com.moit.core.*
api	REST Controller, 요청/응답 DTO	com.moit.api.*
persistence	JPA Entity, Repository 구현체	com.moit.persistence.*
app	Spring Boot Main, 설정 파일	com.moit

---

의존성 흐름

app
 ├── api          ──→ core ──→ common
 ├── persistence  ──→ core ──→ common
 └── core         ──→ common

규칙:

• 화살표 방향으로만 의존 가능
• common은 다른 모듈에 의존하지 않음
• core는 persistence를 모름 (인터페이스만 정의)

---

새 기능 추가 가이드

1. 새 도메인 추가 (예: User)

// 1️⃣ core/domain/User.kt - 도메인 모델
data class User(
    val id: Long?,
    val email: String,
    val name: String
)

// 2️⃣ core/port/UserRepository.kt - 포트 인터페이스
interface UserRepository {
    fun findById(id: Long): User?
    fun save(user: User): User
}

// 3️⃣ core/service/UserService.kt - 비즈니스 로직
@Service
class UserService(private val userRepository: UserRepository) {
    fun getById(id: Long) = userRepository.findById(id)
}

2. Repository 구현 (persistence 모듈)

// persistence/entity/UserEntity.kt
@Entity
class UserEntity(
    @Id @GeneratedValue
    val id: Long? = null,
    val email: String,
    val name: String
)

// persistence/repository/UserJpaRepository.kt
interface UserJpaRepository : JpaRepository<UserEntity, Long>

// persistence/repository/UserRepositoryImpl.kt
@Repository
class UserRepositoryImpl(
    private val jpaRepository: UserJpaRepository
) : UserRepository {
    override fun findById(id: Long) = jpaRepository.findByIdOrNull(id)?.toDomain()
    override fun save(user: User) = jpaRepository.save(user.toEntity()).toDomain()
}

3. Controller 추가 (api 모듈)

// api/controller/UserController.kt
@RestController
@RequestMapping("/api/users")
class UserController(private val userService: UserService) {
    @GetMapping("/{id}")
    fun getById(@PathVariable id: Long) = ApiResponse.success(userService.getById(id))
}

---

의존성 추가

1. libs.versions.toml에 추가

[libraries]
spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security" }

2. 모듈에서 사용

// build.gradle.kts
dependencies {
    implementation(libs.spring.boot.starter.security)
}

---

확장 가이드

infra 모듈 추가 (Redis, Kafka 등)

1. settings.gradle.kts에 추가:

include("infra")

2. infra/build.gradle.kts 생성:

dependencies {
    implementation(project(":core"))
    implementation("org.springframework.boot:spring-boot-starter-data-redis")
}

3. core 모듈에 캐시 포트 정의, infra에서 구현

---

빌드 & 실행

# 전체 빌드
./gradlew clean build

# 앱 실행
./gradlew :app:bootRun

# 특정 모듈 빌드
./gradlew :core:build

# 테스트 실행
./gradlew test

---

FAQ

Q. 공통 설정은 어디서 관리하나요?

A. 루트 build.gradle.kts의 subprojects 블록에서 관리합니다.

Q. 의존성 버전은 어디서 관리하나요?

A. gradle/libs.versions.toml 파일에서 중앙 관리합니다.

Q. 순환 의존이 발생했어요

A. 모듈 순서를 확인하세요: common → core → api/persistence → app

Q. 새 모듈을 추가하려면?

A. settings.gradle.kts에 include 추가 후, build.gradle.kts 생성

Q. 왜 core와 persistence가 분리돼 있나요?

A. core는 순수 비즈니스 로직, persistence는 DB 기술에 종속. 나중에 DB 변경 시 core는 수정 없음