프로젝트가 커지면서 단일 구조에 한계를 느끼고 백엔드, 프론트엔드 등을 분리하는 멀티 프로젝트 전환을 시도할 때가 있습니다. 하지만 생각처럼 간단하지 않은 경우가 많죠. 이 글에서는 가장 흔히 겪는 문제와 그 해결 과정을 단계별로 기록하고, 느낀 점을 공유합니다.
문제 상황
프로젝트의 성장을 고려해 기존의 단일 Gradle 프로젝트를 멀티 프로젝트 구조로 변경하기로 했습니다. 첫 시도는 단순했습니다.
backend라는 새 폴더를 만든다.- 기존
src폴더를backend폴더 안으로 드래그 앤 드롭한다.
하지만 IDE는 이 이동을 허용하지 않았습니다. src 폴더는 이미 루트 프로젝트의 소스 디렉토리로 확고하게 인식되어 있었고, IDE는 이 구조를 임의로 깨뜨리는 것을 막고 있었습니다. 단순한 파일 이동이 아니라, 빌드 시스템이 납득할 수 있는 '리팩토링'이 필요하다는 것을 깨달았습니다.
해결 단계
문제를 해결하기 위해 Gradle이 프로젝트 구조를 이해하는 방식에 따라, 다음과 같은 단계를 순서대로 진행했습니다.
1단계: 모듈 선언 (settings.gradle.kts)
가장 먼저 루트 디렉토리의 settings.gradle.kts 파일에 backend를 새로운 하위 모듈로 포함하겠다고 명시적으로 선언했습니다. 이 파일은 Gradle에게 전체 프로젝트의 구성을 알려주는 지도와 같습니다.
// settings.gradle.kts
rootProject.name = "my-project"
include("backend") // 'backend'를 하위 프로젝트로 공식 등록2단계: 빌드 설정 이전 (build.gradle.kts)
다음으로, 기존 루트 build.gradle.kts 파일에 있던 백엔드 전용 설정(Spring Boot 플러그인, 관련 의존성 등)을 backend 폴더에 새로 만든 build.gradle.kts 파일로 모두 옮겼습니다. 이를 통해 각 모듈이 자신만의 빌드 책임을 갖도록 역할을 분리했습니다.
- 루트
build.gradle.kts: 모든 모듈에 적용될 공통 설정만 남김 backend/build.gradle.kts: 백엔드에만 필요한 특정 설정을 모두 이전
3단계: Gradle 프로젝트 동기화 (Reload)
변경된 구성 정보를 IDE와 Gradle이 받아들이도록 동기화했습니다. IntelliJ IDEA의 Gradle 탭에서 'Reload All Gradle Projects' 버튼을 클릭하자, IDE가 backend를 단순한 폴더가 아닌 정식 모듈로 인식하기 시작했습니다. 이 단계가 가장 중요했습니다.
4단계: 소스 코드 이동
모든 준비가 끝나자, 마침내 루트에 있던 src 폴더를 backend 모듈 폴더 안으로 옮길 수 있었습니다. IDE는 이제 이 작업을 유효한 리팩토링으로 인지하고 정상적으로 처리해주었습니다.
✅ 회고
이번 리팩토링을 통해 배운 가장 중요한 것은 빌드 시스템과 소통하는 법이었습니다. 단순히 파일을 옮기는 물리적인 행위가 아니라, settings.gradle.kts를 통해 의도를 먼저 설명하고(1단계), 각자의 역할을 분리한 뒤(2단계), 그 내용을 프로젝트 전체에 인지시키는(3단계) 과정이 핵심이었습니다.
문제가 발생했을 때 현상에만 집중하기보다, 그 현상이 나타나는 근본 원인(IDE와 Gradle의 프로젝트 인식 방식)을 이해하려 했던 것이 올바른 해결책으로 이어졌습니다. 잘 정돈된 멀티 프로젝트 구조는 당장의 깔끔함은 물론, 미래의 확장성과 유지보수성까지 확보해준다는 점에서 꼭 필요한 과정이었다고 생각합니다.
