멀티모듈 아키텍처의 종류와 적용 경험

1. 멀티모듈 아키텍처란?

멀티모듈 아키텍처(Multi-Module Architecture)는 하나의 프로젝트를 여러 모듈로 나누어 관리하는 방식으로, 각 모듈이 독립적으로 개발 및 테스트될 수 있도록 설계합니다. 이는 코드의 응집도를 높이고, 유지보수성과 확장성을 극대화하는 데 큰 도움이 됩니다.

다양한 프로젝트 요구사항에 따라 멀티모듈 아키텍처의 종류는 여러 가지가 있으며, 각기 다른 장단점을 가집니다. 이 글에서는 멀티모듈 아키텍처의 주요 유형, 우리가 실제로 도입한 방식, 그리고 이를 통해 배운 점들을 공유합니다.

2. 멀티모듈 아키텍처의 종류

2.1 레이어 기반(Layered) 멀티모듈

설명: API, 서비스, 도메인, 인프라 계층과 같은 레이어(layer)별로 모듈을 나누는 방식입니다.

예시:

├── api        # Controller 및 외부 요청 처리
├── service    # 비즈니스 로직과 흐름 제어
├── domain     # 핵심 도메인 모델과 비즈니스 규칙
└── infra      # 데이터베이스 및 외부 시스템 연동

장점: 계층별로 책임이 명확하고 코드 구조가 직관적이며, 유지보수가 용이합니다.
단점: 복잡한 비즈니스 로직이 서비스 계층에 집중될 위험이 있습니다.

2.2 도메인 기반(Domain-Driven) 멀티모듈

설명: 도메인 중심 설계(DDD)를 따르며, 도메인 단위로 모듈을 나누는 방식입니다.

예시:

├── account       # 계정 관련 도메인
├── order         # 주문 관련 도메인
└── inventory     # 재고 관리 도메인

장점: 비즈니스 로직이 도메인 중심으로 분리되어 명확한 책임 분리가 가능합니다.
단점: 도메인 경계를 정의하는 것이 복잡하며 초기 설계에 시간이 소요될 수 있습니다.

2.3 기능 기반(Feature-Based) 멀티모듈

설명: 애플리케이션의 기능 단위로 모듈을 분리합니다.

예시:

├── user          # 사용자 관리 기능
├── payment       # 결제 기능
└── notification  # 알림 기능

장점: 기능 단위로 독립적인 개발이 가능하여 팀 단위 개발에 적합합니다.
단점: 공통 기능이 중복될 수 있으며, 모듈 간 의존성 관리가 어렵습니다.

3. 우리가 도입한 멀티모듈 아키텍처

저희 프로젝트에서는 레이어 기반(Layered) 멀티모듈 아키텍처를 도입했습니다. 프로젝트의 성격상 API 계층과 비즈니스 로직, 데이터 접근 계층을 명확히 분리하는 것이 유지보수에 적합하다고 판단했습니다.

레이어 기반 멀티모듈을 선택한 이유
다양한 서비스에서 공통적으로 사용하는 모듈이 있었으며, 이를 효과적으로 재사용할 필요가 있었습니다. 초기 설계에서 도메인 경계를 명확히 정의하기 어려웠고, 프로젝트 확장성 측면에서 계층별 분리가 유리했습니다. API, 서비스, 인프라 계층을 명확히 나누어 책임 분리를 극대화하고, 협업 효율성을 높일 수 있었습니다.

📂 모듈 구조

my-project
 ├── api         # API 인터페이스 및 외부 요청 처리
 ├── service     # 애플리케이션 로직과 트랜잭션 관리
 ├── domain      # 핵심 도메인 로직과 비즈니스 규칙
 ├── infra       # 데이터 접근 계층과 외부 시스템 연동
 └── common      # 공통 설정, 유틸리티, 예외 처리 등

모듈별 역할과 주요 특징

api 모듈: Controller 및 외부 요청을 처리하며, Swagger를 통한 문서화를 제공합니다.
service 모듈: 애플리케이션의 흐름 제어 및 Transaction 관리를 수행합니다.
domain 모듈: 핵심 비즈니스 로직과 엔티티(Entity)가 포함되어 있습니다.
infra 모듈: 데이터베이스 접근 및 외부 API 연동을 담당합니다.
common 모듈: 공통 설정과 응답 객체, 예외 정의를 담당합니다.

4. 멀티모듈 아키텍처의 장단점

✅ 장점

유지보수성 향상: 코드가 명확히 분리되어 특정 모듈만 수정하거나 교체할 수 있습니다.
팀 단위 개발 용이: 각 팀이 모듈 단위로 독립적인 작업이 가능합니다.
재사용성 증가: 공통 모듈을 여러 서비스에서 쉽게 재사용할 수 있습니다.
빌드 시간 단축: 모듈별로 빌드 및 테스트가 가능하여 빌드 시간을 줄일 수 있습니다.

❌ 단점

복잡한 초기 설계: 모듈 경계를 명확히 정의하는 데 시간이 많이 소요될 수 있습니다.
의존성 관리의 어려움: 모듈 간 순환 의존성(Circular Dependency)을 피하기 위한 추가 설계가 필요합니다.
과도한 모듈화: 작은 프로젝트에서는 모듈이 너무 많아 오히려 복잡도가 증가할 수 있습니다.

5. 회고: 우리가 배운 것들

이번 프로젝트에서 새로운 멀티모듈 아키텍처를 경험하며 다양한 교훈을 얻을 수 있었습니다. 초기 설계 시 모듈 간 역할 정의의 중요성을 깨달았으며, 이를 통해 더 나은 설계 방식과 개선 방안을 고민하는 계기가 되었습니다.

시행착오 및 개선점

모듈 간 순환 의존성 문제: 특정 모듈이 다른 모듈을 참조하면서 의존성 순환이 발생하는 문제를 경험했습니다. 이를 해결하기 위해 의존성 역전 원칙(DIP)을 적용했습니다.
초기 설계의 중요성: 모듈을 나누는 기준을 명확히 하지 않으면 오히려 복잡도가 증가할 수 있음을 경험했고, 초기에 명확한 경계를 정의하는 것이 중요함을 깨달았습니다.