Spring Boot 모듈 400개짜리 코드베이스에서 얻은 교훈들

모듈이 400개라니, 대체 어떻게 관리하는 걸까?

한국에서 Spring Boot는 사실상 백엔드 개발의 표준이라고 해도 과언이 아닌데요. 대부분의 프로젝트는 모듈 몇 개에서 시작해서, 잘해봤자 수십 개 수준에서 운영되곤 하죠. 그런데 한 엔지니어링 팀이 무려 400개의 모듈로 구성된 Spring Boot 코드베이스를 운영하면서 터득한 실전 교훈들을 공유했어요. 단순히 "이렇게 하면 좋다"가 아니라, 실제로 대규모 코드베이스를 굴리면서 부딪힌 문제들과 해결책을 담고 있어서 실무에서 바로 참고할 만한 내용이 많아요.

멀티 모듈의 핵심: 의존성을 어떻게 끊느냐

400개 모듈이라고 하면 감이 안 올 수 있는데, 핵심은 각 모듈이 자기 역할만 딱 하고 다른 모듈에 최소한으로 의존하게 만드는 것이에요. 이걸 "관심사의 분리(Separation of Concerns)"라고 부르는데요, 쉽게 말하면 식당에서 주방, 홀, 계산대가 각자 맡은 일만 하는 것처럼 코드도 역할별로 칼같이 나누는 거예요.

이 프로젝트에서 강조하는 첫 번째 원칙은 API 모듈과 구현 모듈을 분리하는 것이에요. 예를 들어 user-api라는 모듈에는 인터페이스와 DTO(데이터 전달 객체)만 넣고, 실제 로직은 user-service라는 별도 모듈에 두는 식이죠. 이렇게 하면 다른 모듈이 user 기능을 쓸 때 구현 세부사항에 의존하지 않게 되거든요. 나중에 구현을 통째로 갈아끼워도 다른 모듈은 영향을 안 받아요.

두 번째로 중요한 건 Gradle 빌드 설정을 일관되게 관리하는 것인데요. 400개 모듈이 각각 build.gradle을 제멋대로 작성하면 카오스가 되겠죠. 이 팀은 Convention Plugin이라는 방식을 써서, 공통적으로 적용되는 빌드 설정을 플러그인 형태로 만들어 놓고 각 모듈에서 한 줄로 가져다 쓰게 했어요. "이 모듈은 Spring Boot 웹 모듈이야"라고 선언만 하면 필요한 의존성, 테스트 설정, 코드 스타일 검사가 자동으로 적용되는 거죠.

빌드 시간과의 전쟁

모듈이 많아지면 피할 수 없는 문제가 빌드 시간이에요. 400개 모듈을 매번 전부 빌드하면 시간이 어마어마하게 걸리거든요. 이 팀이 소개하는 전략 중 하나는 Gradle의 빌드 캐시와 병렬 빌드를 적극 활용하는 것이에요. 변경되지 않은 모듈은 캐시에서 가져오고, 서로 의존 관계가 없는 모듈들은 동시에 빌드하는 거예요.

또 하나 인상적인 건 테스트 격리 전략이에요. 통합 테스트에서 Spring 컨텍스트를 모듈마다 따로 띄우면 메모리랑 시간이 엄청 들잖아요. 이 팀은 테스트용 공통 컨텍스트 설정을 별도 모듈로 빼서 재사용하게 만들었어요. 덕분에 CI 파이프라인에서 테스트 실행 시간을 크게 줄일 수 있었다고 해요.

그리고 순환 의존성(Circular Dependency) 문제도 빠질 수 없는데요. 이게 뭐냐면, A 모듈이 B를 참조하고 B가 다시 A를 참조하는 상황이에요. 모듈이 많아지면 이런 순환 고리가 은근히 생기거든요. 이 팀은 아키텍처 테스트 도구인 ArchUnit을 활용해서 순환 의존성이 생기면 CI에서 빌드가 실패하도록 강제했어요. 문제가 커지기 전에 자동으로 잡아내는 거죠.

기존 방식과 뭐가 다른가

사실 한국에서도 멀티 모듈 프로젝트는 많이 시도하는데요, 대부분 모놀리스에서 출발해서 서비스 단위로 모듈을 나누는 수준에서 멈추는 경우가 많아요. 예를 들면 api, domain, infrastructure 정도의 3-layer 구조로 나누는 거죠. 이 접근법 자체는 나쁘지 않지만, 프로젝트가 커지면 domain 모듈이 점점 비대해지는 문제가 생겨요.

이 400개 모듈 프로젝트의 접근법은 좀 더 세분화된 편인데요. 도메인 단위로 쪼개고, 그 안에서 다시 API/구현/테스트 픽스처로 분리하는 구조예요. 마이크로서비스로 가지 않으면서도 모놀리스의 장점(단일 배포, 트랜잭션 관리 용이)을 유지하면서 코드 조직만 깔끔하게 가져가는 전략이죠. 이걸 모듈러 모놀리스(Modular Monolith)라고 부르기도 하는데, 최근 마이크로서비스의 복잡성에 지친 팀들이 다시 주목하고 있는 아키텍처 패턴이에요.

비슷한 맥락에서 Netflix나 Airbnb 같은 회사들도 무조건 마이크로서비스로 가기보다 모듈러 모놀리스를 전략적으로 선택하는 사례가 늘고 있어요. Spring 진영에서도 Spring Modulith라는 프레임워크를 공식적으로 밀고 있는데, 이번 글에서 다루는 패턴들과 방향성이 상당히 비슷해요.

한국 개발자에게 주는 시사점

한국 SI나 스타트업에서 Spring Boot를 쓰고 계시다면, 당장 400개 모듈까지 갈 필요는 없지만 몇 가지 실천법은 바로 적용해볼 만해요. 우선 Convention Plugin 패턴은 모듈이 10개만 넘어도 효과가 확실하거든요. build.gradle 복붙하다가 버전 안 맞아서 삽질하는 일을 없앨 수 있어요.

또 API 모듈을 분리하는 패턴은 팀 간 협업이 많은 프로젝트에서 특히 유용해요. 다른 팀이 우리 서비스를 연동할 때 구현 모듈 전체를 의존성으로 끌고 오는 게 아니라 가벼운 API 모듈만 참조하면 되니까요. 빌드 시간도 줄고 결합도도 낮아지는 일석이조 효과를 얻을 수 있어요.

마지막으로, ArchUnit 같은 아키텍처 테스트를 CI에 넣어두면 코드 리뷰에서 잡기 힘든 구조적 문제를 자동으로 감지할 수 있어요. "이 패키지는 저 패키지를 참조하면 안 돼"라는 규칙을 테스트 코드로 선언해두면 되거든요.