---
id: P-REINFORCE-WIKI-ARCH-HEXAGONAL
title: "헥사고날 아키텍처 (Hexagonal Architecture / Ports and Adapters)"
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", "Modularity", "Decoupling"]
raw_sources: ["Datacollector_Export_2026-05-02"]
last_reinforced: 2026-05-02
github_commit: ""
---

# [[헥사고날 아키텍처 (Hexagonal Architecture / Ports and Adapters)]]

## 1. 개요
헥사고날 아키텍처(Hexagonal Architecture)는 애플리케이션의 핵심 비즈니스 로직을 외부 기술(DB, UI, 프레임워크 등)로부터 분리하고 격리하여 유지보수성과 테스트 용이성을 극대화하는 설계 패턴이다. 모든 외부 요소는 인터페이스인 '포트(Port)'를 통해 시스템에 연결되며, 구체적인 기술적 세부 사항은 '어댑터(Adapter)'가 담당하는 구조적 특징을 가진다.

## 2. 핵심 구성 요소
- **도메인 (Inside)**: 시스템의 본질인 비즈니스 로직과 규칙. 외부 프레임워크나 인프라 기술에 전혀 의존하지 않는 순수한 코드로 구성된다.
- **포트 (Ports)**: 외부 세계가 도메인과 소통하기 위한 명세(인터페이스).
    - **입력 포트 (Inbound)**: 외부 요청(API 호출, CLI 등)이 도메인 기능을 사용하기 위한 통로.
    - **출력 포트 (Outbound)**: 도메인이 외부 자원(DB, 메시지 큐 등)에 접근하기 위해 사용하는 통로.
- **어댑터 (Outside)**: 포트 인터페이스를 구체적으로 구현하거나 호출하는 인프라 계층.
    - **입력 어댑터 (Driving)**: 컨트롤러, CLI 핸들러 등 요청을 도메인 명령으로 변환.
    - **출력 어댑터 (Driven)**: 영속성(Persistence) 구현체, 메시지 송신부 등 기술적 행위 수행.

## 3. 실전 적용 가치
- **기술 스택 교체 용이성**: 비즈니스 로직을 전혀 수정하지 않고도 DB를 교체하거나 API 스펙을 변경하는 등 유연한 운영 가능.
- **테스트 격리**: 인프라 환경 없이도 도메인 로직만 고립시켜 단위 테스트를 수행할 수 있어 검증 속도와 신뢰성 향상.
- **의존성 역전 (DIP)**: 도메인이 인프라에 의존하는 것이 아니라, 인프라(어댑터)가 도메인의 명세(포트)에 맞게 구현되도록 강제하여 코드의 순수성 보존.

## 4. 트레이드오프 및 주의사항
- **구현 복잡도**: 포트와 어댑터 계층을 나누고 다수의 인터페이스와 매퍼(Mapper)를 작성해야 하므로 초기 개발 리소스와 보일러플레이트 코드가 증가함.
- **과잉 설계 (Over-engineering)**: 도메인 로직이 단순한 CRUD 수준일 경우, 헥사고날 아키텍처의 도입은 시스템을 불필요하게 복잡하게 만들 수 있음.
- **학습 곡선**: 전통적인 계층형 아키텍처에 익숙한 개발팀에게는 패러다임 전환을 위한 교육 비용이 발생함.

## 5. 지식 연결 (Related)
- [[Domain_Driven_Design]]: 헥사고날 아키텍처 내부(도메인)를 채우는 모델링 기법.
- [[Clean_Architecture]]: 유사한 격리 철학을 동심원 모델로 표현한 아키텍처.
- [[CQRS_Pattern]]: 조회와 명령의 효율성을 위해 헥사고날과 흔히 결합되는 패턴.

## 🧪 검증 상태 (Validation)
- **정보 상태**: 검증 완료 (Verified)
- **출처 신뢰도**: A
- **검토 이유**: 기술 종속성에서 벗어나 비즈니스 로직의 수명을 극대화하기 위한 현대적 아키텍처의 표준 명세 정립.