헥사고날 아키텍처 (Hexagonal Architecture) 심층 탐구

헥사고날 아키텍처 (Hexagonal Architecture) 심층 탐구
(Claude helped me put this article together.)

 

FACT ^{주장/현상/관념}

헥사고날 아키텍처(Hexagonal Architecture)는 마이크로서비스 아키텍처(MSA)에서 다음과 같은 핵심 가치를 제공합니다:
    (1) 명확한 서비스 경계 설정
    (2) 서비스 간 독립성 확보
    (3) 지속적인 진화와 확장 지원
    (4) 높은 테스트 용이성
    (5) 도메인 중심의 서비스 설계

이를 통해 복잡한 분산 시스템을 더 체계적이고 관리하기 쉬운 방식으로 설계할 수 있습니다. 헥사고날 아키텍처에 대해 왜 이와같이 설명하는지 핵심 개념을 좀 더 깊이 알아보겠습니다.

---

CHECK ^{검증/실상/검토}

1. 헥사고날 아키텍처의 기원

   창시자

• Alistair Cockburn
  • 애자일 소프트웨어 개발 방법론의 전문가
  • 2005년에 이 아키텍처 패턴 소개
  • 소프트웨어 설계의 복잡성 감소와 시스템 유연성 향상을 목적

   용어의 유래

• "육각형(Hexagonal)"은 비유적 표현
• 시스템의 중심(도메인)을 육각형으로 표현
• 실제 육각형 모양을 반드시 따를 필요는 없음

2. 핵심 구성 요소

FIGURE: Hexagonal Architecture [1]

 

   2.1 도메인 (Domain Core)

• 시스템의 핵심 비즈니스 로직 포함
• 외부 시스템과 완전히 분리
• 순수한 비즈니스 로직만 존재

   2.2 포트 (Ports)

• 애플리케이션의 인터페이스 역할
• 도메인과 외부 시스템 간 통신 계약 정의
• 두 가지 종류의 포트
  • 인바운드 포트: 도메인 로직을 호출하는 인터페이스
  • 아웃바운드 포트: 도메인이 외부 시스템과 상호작용하는 인터페이스

   2.3 어댑터 (Adapters)

• 포트를 구체적인 기술이나 프레임워크에 연결
• 외부 시스템과의 실제 통신 구현
• 두 가지 유형
  • 1차 어댑터(주도하는 어댑터): 사용자 인터페이스, API 컨트롤러
  • 2차 어댑터(주도되는 어댑터): 데이터베이스, 외부 서비스 클라이언트

3. Ports vs Adapters: 코드 구현 관점의 차이

   3.1 Ports (포트)

• 인터페이스 또는 추상화된 계약
• 애플리케이션 코어와 외부 시스템 간의 통신 규약
• 구체적인 구현 없이 메서드 시그니처만 정의

// 인바운드 포트 예시
public interface OrderServicePort {
    // 추상화된 메서드 시그니처만 존재
    Order createOrder(Customer customer);
    void cancelOrder(String orderId);
}

// 아웃바운드 포트 예시
public interface OrderRepositoryPort {
    // 데이터 저장/조회를 위한 추상 메서드
    void save(Order order);
    Order findById(String orderId);
}

   3.2 Adapters (어댑터)

• 포트의 실제 구현체
• 특정 기술이나 프레임워크와 연동
• 외부 시스템과의 실제 통신 로직 포함

// 1차 어댑터 (REST 컨트롤러)
@RestController
public class OrderRestAdapter implements OrderServicePort {
    private OrderService orderService;

    @Override
    public Order createOrder(Customer customer) {
        // HTTP 요청 처리 로직
        // 비즈니스 로직 호출
        return orderService.createOrder(customer);
    }
}

// 2차 어댑터 (JPA 저장소)
@Repository
public class JpaOrderRepositoryAdapter implements OrderRepositoryPort {
    @PersistenceContext
    private EntityManager entityManager;

    @Override
    public void save(Order order) {
        // JPA를 사용한 실제 데이터베이스 저장 로직
        entityManager.persist(order);
    }
}

   3.3 주요 차이점

1. 추상화 수준
   • Ports: 추상적, 계약 정의
   • Adapters: 구체적, 실제 구현
2. 의존성 방향
   • Ports: 도메인 코어에 의존
   • Adapters: 포트 인터페이스 구현, 외부 시스템과 연결
3. 변경 용이성
   • Ports: 거의 변경되지 않음
   • Adapters: 외부 시스템 변경에 따라 수정 가능

   3.4 주요 특징 및 장점

• 높은 모듈성
• 쉬운 테스트 가능성
• 기술적 변경에 대한 최소한의 영향
• 비즈니스 로직의 독립성 보장

4. 시스템 흐름 구조

1. 가장 중심: 도메인 (비즈니스 로직)
2. 중간 계층: 포트 (인터페이스)
3. 가장 바깥 경계: 어댑터 (외부 시스템 연결)

FIGURE: Inbound/Outbound Flowchart

flowchart LR subgraph "Inbound (들어오는 방향)" direction LR PrimaryAdapter["Primary Adapter\n(REST 컨트롤러)"] --> InboundPort["Inbound Port\n(서비스 인터페이스)"] InboundPort --> Domain["Domain\n(비즈니스 로직)"] end subgraph "Outbound (나가는 방향)" direction LR Domain --> OutboundPort["Outbound Port\n(리포지토리 인터페이스)"] OutboundPort --> SecondaryAdapter["Secondary Adapter\n(데이터베이스 구현)"] end

Inbound (들어오는 방향)

• Primary Adapter → Inbound Port → Domain

Outbound (나가는 방향)

• Domain → Outbound Port → Secondary Adapter

5. 적용 범위

• 시스템 전체 아키텍처 설계에 적용 가능
• 개별 모듈/컴포넌트 수준에서도 적용 가능
• 시스템의 크기와 복잡도에 따라 유연하게 조정 가능

---

WRAP-UP ^{결어/종합/대안}

Alistair Cockburn의 헥사고날 아키텍처는 단일 시스템의 모듈부터 전체 시스템 아키텍처까지 유연하게 적용할 수 있는 설계 패턴입니다. 
주요 포인트는
  1. 단순히 육각형 모양을 따르는 것이 아니라, 시스템의 관심사를 분리하고 결합도를 낮추는 아키텍처 원칙
  2. 시스템 전체 또는 개별 컴포넌트 수준에서 모두 적용 가능
  3. 비즈니스 로직의 독립성과 시스템의 유연성을 높이는 것이 핵심 목표

적용 방식은 상황과 시스템의 복잡도에 따라 달라질 수 있으며, 개발팀의 요구사항에 맞게 유연하게 조정할 수 있습니다.

 

2025.03.25.
AUDITORIS

 

[1] Hexagonal Architecture 그림 출처: https://medium.com/@jittakal/hexagonal-architecture-in-action-a-deep-dive-into-building-a-todo-task-api-aae3b460151a