---
id: P-REINFORCE-WIKI-ARCH-HEXAGONAL
title: "헥사고날 아키텍처 (Hexagonal Architecture)"
category: "10_Wiki/🏗️ Topics_Arch"
status: verified
canonical_id: ""
aliases: ["포트와 어댑터 아키텍처", "Hexagonal Architecture", "Ports and Adapters"]
duplicate_of: ""
source_trust_level: A
confidence_score: 1.0
tags: ["Architecture", "Hexagonal", "DIP", "DDD", "Testability"]
raw_sources: ["Datacollector_Export_2026-05-02"]
last_reinforced: 2026-05-02
github_commit: ""
---

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

## 1. 개요
헥사고날 아키텍처(Hexagonal Architecture), 또는 **포트와 어댑터 아키텍처**는 시스템의 핵심 비즈니스 로직(도메인)을 외부 기술(DB, UI, 프레임워크 등)로부터 완전히 격리하는 설계 패턴이다. 비즈니스 로직을 내부(Inside)로, 기술적 세부 사항을 외부(Outside)로 정의하고 그 경계를 인터페이스(포트)로 관리한다.

## 2. 핵심 구성 요소
- **도메인 (Domain)**: 핵심 비즈니스 규칙과 모델. 외부 세계에 대해 전혀 알지 못하는 순수 코드로 작성됨.
- **포트 (Ports)**: 외부 세계와 도메인 간의 소통 규칙을 정의하는 인터페이스.
    - **입력 포트 (Inbound)**: 외부에서 도메인 기능을 호출하기 위한 통로 (예: Service Interface).
    - **출력 포트 (Outbound)**: 도메인이 외부 자원에 접근하기 위한 통로 (예: Repository Interface).
- **어댑터 (Adapters)**: 포트를 통해 들어오거나 나가는 데이터를 도메인 언어로 번역하는 구현체.
    - **입력 어댑터**: REST Controller, CLI, Web UI 등.
    - **출력 어댑터**: Database Implementation (JPA/SQL), Message Broker client, External API client 등.

## 3. 설계 원칙: 의존성 역전 (DIP)
- 고수준 모듈(도메인)이 저수준 모듈(어댑터)에 의존하지 않아야 한다.
- 도메인과 인프라 계층 모두가 도메인 내부에 정의된 **추상화(포트)**에 의존하게 하여 기술 종속성을 제거한다.

## 4. 트레이드오프
- **장점**: 프레임워크/DB 비의존성, 독립적인 단위 테스트 가능, 기술 스택 교체 용이.
- **단점**: 인터페이스 및 데이터 매핑 객체 증가로 인한 초기 설계 복잡도 및 보일러플레이트 코드 상승.

## 5. 지식 연결 (Related)
- [[Clean_Architecture]]: 헥사고날의 철학을 계승하여 동심원 계층으로 발전시킨 모델.
- [[Domain_Driven_Design]]: 헥사고날의 '내부'를 채우는 핵심 모델링 사상.
- [[Dependency_Injection]]: 헥사고날 구조를 실현하기 위한 핵심 구현 기술.

## 🧪 검증 상태 (Validation)
- **정보 상태**: 검증 완료 (Verified)
- **출처 신뢰도**: A
- **검토 이유**: 유지보수성과 확장성이 극대화된 현대적 애플리케이션 설계의 표준 가이드 확립.