[Architecture]헥사고날 아키텍처 (Hexagonal Architecture

🔷 헥사고날 아키텍처(Hexagonal Architecture)란?

• 목적: 비즈니스 로직(도메인, 유스케이스)을 외부 기술(DB, UI, 메시지 큐, API 등)로부터 분리해서 핵심 로직을 안정적으로 보호하고, 기술 요소는 쉽게 교체할 수 있도록 하는 아키텍처 패턴
• 다른 이름: Ports and Adapters 패턴

🧩 핵심 개념

https://dzone.com/articles/hexagonal-architecture-in-java-2

  1. 애플리케이션 코어 (Application Core)

1. • 도메인 모델(엔티티, 값 객체 등)
   • 유스케이스(애플리케이션 서비스)
   • 외부 기술에 전혀 의존하지 않는 순수한 로직
2. 포트 (Ports)
   • 코어와 외부 세계를 연결하는 추상 인터페이스
   • 두 가지로 나뉨
     • 인커밍 포트 (Incoming Port)
       → 외부에서 코어를 호출할 때 사용 (예: REST Controller가 호출하는 UseCase 인터페이스)
     • 아웃고잉 포트 (Outgoing Port)
       → 코어에서 외부로 나갈 때 사용 (예: Repository 인터페이스, 외부 API 호출 인터페이스)
3. 어댑터 (Adapters)
   • 포트 인터페이스를 실제 구현하는 기술적 요소
   • 두 가지로 나뉨
     • 드라이빙 어댑터 (Driving Adapter)
       → 인커밍 포트를 구현하는 외부 기술 (예: Controller, CLI, Event Listener)
     • 드리븐 어댑터 (Driven Adapter)
       → 아웃고잉 포트를 구현하는 외부 기술 (예: DB Repository, 메시지 브로커, 외부 API 클라이언트)

⚙️ 동작 흐름 예시

• 사용자가 **Controller(드라이빙 어댑터)**를 통해 요청 →
• Controller는 인커밍 포트(UseCase 인터페이스) 호출 →
• 애플리케이션 코어가 비즈니스 로직 수행 →
• 필요하다면 아웃고잉 포트(Repository 인터페이스) 호출 →
• **드리븐 어댑터(DB, 외부 API 구현체)**가 응답 →
• 최종 결과를 사용자에게 반환

📂 헥사고날 아키텍처 예시 구조 (Java)

📦 com.example.project
 ┣ 📁 application            // 애플리케이션 서비스 (유스케이스, 인커밍 포트)
 │  ┣ 📁 port
 │  │  ┣ 📁 in
 │  │  │  ┗ 📄 CreateOrderUseCase.java
 │  │  ┗ 📁 out
 │  │     ┗ 📄 OrderRepository.java
 │  ┗ 📁 service
 │     ┗ 📄 CreateOrderService.java
 │
 ┣ 📁 domain                 // 도메인 모델 (순수 비즈니스 로직)
 │  ┣ 📁 model
 │  │  ┣ 📄 Order.java
 │  │  ┗ 📄 Product.java
 │  ┗ 📁 logic
 │     ┗ 📄 OrderValidator.java
 │
 ┣ 📁 adapter                // 어댑터 (포트의 실제 구현)
 │  ┣ 📁 in
 │  │  ┗ 📁 web
 │  │     ┗ 📄 OrderController.java
 │  ┗ 📁 out
 │     ┗ 📁 persistence
 │        ┣ 📁 jpa
 │        │  ┣ 📄 OrderJpaEntity.java
 │        │  ┣ 📄 SpringDataOrderRepository.java
 │        │  ┗ 📄 JpaOrderRepositoryAdapter.java
 │        ┗ 📁 external
 │           ┗ 📄 PaymentApiAdapter.java
 │
 ┣ 📁 config                 // DI, 설정 관련
 │  ┗ 📄 ApplicationConfig.java
 │
 ┗ 📄 Application.java       // 메인 실행 파일 (Spring Boot 등)

🧩 구조 설명

• application
  • 포트(인터페이스)와 서비스(유스케이스) 정의
  • 핵심 비즈니스 로직을 직접 호출하는 진입점
• domain
  • 순수 도메인 모델 (Entity, Value Object, 도메인 로직)
  • 외부 기술과 무관 → 테스트와 유지보수 용이
• adapter
  • in → 드라이빙 어댑터 (Controller, CLI, Event Listener 등)
  • out → 드리븐 어댑터 (DB, 외부 API, 메시지 브로커 구현체)
• config
  • Spring DI 설정, Bean 등록

---

🤝 DDD , 헥사고날 아키텍처  두 개념의 관계

• 🧩 DDD (Domain-Driven Design) = “무엇을 중심으로 개발할까?” → 비즈니스 도메인
• 정의: 비즈니스 도메인의 복잡성을 관리하기 위한 개발 방법론
  • 핵심 목표: 기술이 아니라 **도메인 로직(비즈니스 규칙)**을 중심에 두고 개발
  • 3계층 구조로 구현하는 게 일반적:
    1. Application Layer
       • 도메인과 저장소를 활용해 유스케이스 실행 (서비스, API 제공)
    2. Domain Model Layer
       • 엔티티/밸류 객체/애그리거트를 통해 비즈니스 로직 수행
    3. Infrastructure Layer
       • DB, 메시지 큐, 외부 API 등 외부와의 연결 담당
• 헥사고날 아키텍처 (Hexagonal Architecture, Ports & Adapters)  = “그 도메인을 어떻게 지켜줄까?” → 아키텍처적 구조

 

• 정의: 포트(인터페이스)와 어댑터(구현체) 개념을 활용해
  도메인 로직을 외부 기술(DB, UI, 프레임워크)로부터 격리하는 아키텍처 패턴
• 핵심 목표:
  • 도메인 로직이 외부 기술에 영향을 받지 않도록 보호
  • 기술 요소는 쉽게 교체 가능 (DB → Redis, REST → gRPC 등)

 

• 정리
  1. DDD는 비즈니스를 코드로 옮기는 방법론
     → 도메인 중심 설계
  2. 헥사고날은 그 설계를 기술로부터 지켜주는 아키텍처
     → 포트와 어댑터로 결합도 최소화
  3. 두 개념은 서로 보완적
     • DDD로 모델링 → 헥사고날로 구조화 → 유지보수성과 확장성 향상

---

 

📊  헥사고날 아키텍처(Hexagonal, Ports & Adapters)와 클린 아키텍처(Clean Architecture)

구분 헥사고날 아키텍처 클린 아키텍처

제안자	Alistair Cockburn	Robert C. Martin
구조	코어 + 포트 + 어댑터	동심원 계층 구조
핵심 개념	포트와 어댑터	엔티티, 유스케이스, 인터페이스 어댑터
목표	기술 독립성, 유연한 확장	책임 분리, 의존성 규칙 강화
복잡도	상대적으로 단순	상대적으로 세밀하고 복잡
적용 예시	DB 교체, API/메시징 교체	대규모 시스템, 계층 분리 철저히 필요할 때

• 헥사고날은 비교적 단순해서 기술 독립성을 확보하는 데 강점
• 클린 아키텍처는 계층을 세밀히 나눠 복잡한 시스템에서 유지보수에 강점
• 둘 다 “도메인 로직을 보호한다”는 공통 목적을 갖고 있음
• 실제 현장에서는 헥사고날을 먼저 적용하고, 시스템이 커지면 클린 아키텍처로 확장하는 경우가 많음