1. 아키텍처 도입 배경

• 기존 단일 컨트롤러 방식에서는 API 명세에 따라 컨트롤러가 다수의 유스케이스와 서비스 로직을 직접 의존하게 됨
• 이로 인해 의존성 주입의 복잡성 증가, 비즈니스 로직 재사용성 저하, 컨트롤러 테스트 난이도 증가 등의 문제가 발생
• 이를 해결하기 위해 헥사고날 아키텍처를 기반으로 클린한 책임 분리 구조를 설계하고자 함

2. 헥사고날 아키텍처의 핵심 개념

• 애플리케이션을 도메인 로직과 외부 입출력 시스템(웹, DB 등)으로 명확히 분리
• 핵심 개념:
  • Port: 내부/외부 시스템과 도메인 사이의 인터페이스
  • Adapter: Port의 구현체, 외부 시스템과의 실제 연결 담당
  • UseCase: 도메인 관점의 핵심 비즈니스 로직 단위

3. Facade 패턴 도입 이유

• 컨트롤러에서 다수의 UseCase를 직접 호출할 경우, 다음과 같은 문제가 발생:
  • 컨트롤러가 너무 많은 의존성을 가짐
  • API가 변화할 때마다 컨트롤러 코드의 변경 빈도 증가
  • UseCase 간 조합 로직이 컨트롤러에 노출됨으로써 재사용 어려움
• 이에 따라, 중간에 Facade 레이어를 도입하여 다음 역할을 수행:
  • 하나의 API 흐름에 필요한 단위 UseCase들을 조합
  • 단일 트랜잭션 단위를 묶고, 비즈니스 시나리오 단위로 책임을 위임
  • 컨트롤러는 Facade만 주입받음으로써 의존성 간소화 및 책임 분리

4. 구조 설계 원칙

• Controller → Facade → UseCase(Service) → Port(Interface) → Adapter(Impl) 의 방향성 유지
• 모든 핵심 비즈니스 로직은 UseCase에 존재하며, Facade는 조합자 역할만 수행
• UseCase는 가능한 한 작고 명확한 단위 책임을 가지며, API 1:1 대응이 아닌 도메인 행위 단위로 구성
• Facade는 하나의 흐름(API 단위)에 맞춰 UseCase들을 적절히 조합하여 트랜잭션 관리

5. 구조 예시 : 회원가입 API 흐름