모듈을 변경한 이유

목차

1.모듈을 변경하게 된 이유

2.적용 후

3.마무리

 

1.모듈을 변경하게 된 이유

 

프로젝트를 시작을 했을때 멀티모듈과 헥사고날 아키텍처를 도입했다. 도메인과 외부 세계를 분리하려는 시도였고, 이론적으로는 나쁘지 않았습니다. 아래는 당시의 구조입니다.

member/
├── api
│   └── controller
├── core
│   ├── service
│   ├── enumerate
│   ├── exception
│   ├── model
├── connector
│   ├── api-model
│   ├── in-connector
│   ├── out-connector
│   └── interfaces
├── infrastructure
│   ├── api-client
│   └── rdb

 

헥사고날 아키텍처의 철학을 반영하려 했지만, 실제 개발에서는 여러 문제에 부딪혔다:

• 패키지 네이밍과 위치가 일관되지 않음: api-model은 core와 connector 어디에도 애매하게 걸쳐 있었고, controller와의 책임 연관성이 떨어졌다.
• infra와 connector의 경계가 모호함: api-client가 infra에 위치해 있었지만, 실제로는 외부 API와 통신하는 adapter의 역할을 하고 있었다.
• 중복된 기능과 애매한 책임 분배: 외부 연동 로직이 connector와 infra 사이에 중복되거나 위치가 어색하게 분산되어 유지보수가 어려웠다.
• 이론은 헥사고날이었지만, 실제 구현은 이를 명확히 반영하지 못함

결과적으로, 헥사고날의 형태를 흉내 냈지만 실질적인 경계와 역할이 분리되지 않아 구조적으로 불안정한 상태가 되었다.

2.적용 후

이 문제를 해결하기 위해 다음과 같이 구조를 재정비했다.

member/
├── api
│   ├── controller
│   └── dto (api-model)
├── core
│   ├── service
│   ├── model
│   ├── exception
│   └── enumerate
├── connector
│   ├── in-bound
│   ├── out-bound
│   │   └── api-client
│   └── interfaces
├── infrastructure
│   └── rdb

 

변경 핵심 포인트

• api-model → api/dto로 이동: 외부 요청/응답 DTO는 controller와 같은 레이어에 배치
• api-client → connector/out-bound: 외부 API 연동은 어댑터 역할을 명확히 하기 위해 이동
• connector는 in-bound, out-bound, interfaces로 명확히 분리하여 EDA 기반 구조와 호환되게 구성
• infra는 오직 기술 종속적인 구현체(DB, Redis 등)만 포함하도록 책임 한정

이번 리팩토링으로 진짜 의미의 헥사고날 아키텍처가 구현되었다. 도메인 로직은 외부와 독립적으로 유지되며, 외부 시스템 연동은 어댑터로 완전히 분리되었다.

 

계층별 역할 정보 정리

계층	책임	예시
api	외부 요청 입구 (Controller, DTO)	MemberController, MemberRequest
core	도메인 로직과 내부 모델	MemberService, MemberModel
connector	외부 시스템과의 연결 (Kafka, OpenAPI 등)	MailOutConnector, KafkaConsumerListener, OpenAIClient
infrastructure	기술 구현 세부 (DB)	MemberRepository

 

실제 Notification 모듈 예시 구조

 

구성 요약:

• 외부 요청: controller, dto → api
• 도메인 로직: model, service → core
• 외부 시스템 연동 (메일, AI 등): connector → out-bound/api-client
• 기술 구현 (JPA 등): infrastructure

 

3.마무리

• 헥사고날 아키텍처는 폴더 구조를 나눈다고 만들어지는 것이 아니다.
• "도메인을 외부로부터 완전히 고립시킨다"는 철학을 실제 코드 설계와 흐름에 녹여야 의미가 있다.
• 이번 구조 개선으로 인해 Kafka 기반 DLQ 처리, WebSocket 알림, OpenAI 연동 등 다양한 컴포넌트를 모듈화된 형태로 깔끔하게 유지보수하고 확장할 수 있게 되었다.

📘 처음부터 헥사고날을 시도했지만, 이번에는 '제대로' 적용했다. 실패를 통해 기준을 세웠고, 그것이 진짜 아키텍처가 되었다.