---
category: Architecture
tags: [auto-wikified, technical-documentation, architecture]
title: Hexagonal Architecture (Ports and Adapters)
description: "헥사고날 아키텍처(포트와 어댑터 패턴)는 애플리케이션의 핵심 비즈니스 로직을 데이터베이스, UI, API 등 외부 기술적 종속성으로부터 완전히 고립시키기 위해 고안된 소프트웨어 아키텍처 패턴입니다."
last_updated: 2026-05-04
---

# Hexagonal Architecture (Ports and Adapters)

## 📌 Brief Summary
헥사고날 아키텍처(포트와 어댑터 패턴)는 애플리케이션의 핵심 비즈니스 로직을 데이터베이스, UI, API 등 외부 기술적 종속성으로부터 완전히 고립시키기 위해 고안된 소프트웨어 아키텍처 패턴입니다. [1-3] 2005년 Alistair Cockburn에 의해 처음 소개되었으며, 시스템을 더 유지보수하고 테스트 및 확장하기 쉽게 만드는 것을 주된 목적으로 합니다. [2] 내부 도메인 로직과 외부 세계 간의 상호작용은 명확한 규약을 가진 인터페이스인 '포트(Port)'와 이를 구체적으로 구현하는 '어댑터(Adapter)'를 통해서만 이루어집니다. [3-5]

## 📖 Core Content
*   **설계 철학과 구조적 메커니즘**
    *   육각형(Hexagon) 모양은 전통적인 N-티어(N-Tier) 계층 구조와 같이 수직적인 계층 관계를 내포하지 않는다는 것을 은유적으로 보여줍니다. [6] 다수의 연결 지점(포트)을 통해 다양한 어댑터를 쉽게 끼워 넣을 수(plug in) 있는 다형성을 시각적으로 나타냅니다. [6]
    *   비즈니스 로직과 외부 인프라의 강한 결합(Tight coupling)을 방지하기 위해 의존성 역전 원칙(Dependency Inversion Principle)을 적용합니다. [2, 7] 이를 통해 외부 기술 스택의 변경(예: 관계형 DB에서 NoSQL로의 전환)이 핵심 도메인 로직에 영향을 미치지 않도록 시스템을 보호합니다. [8]

*   **포트(Ports)와 어댑터(Adapters)의 역할 분리**
    *   **포트(Ports)**: 시스템의 진입점으로서 애플리케이션이 '무엇(What)'을 할 수 있는지 정의하는 인터페이스(유즈케이스)입니다. [5, 9] 입력(Inbound) 포트와 출력(Outbound) 포트로 나뉘며, 애플리케이션 계층에 속합니다. [8, 10]
    *   **어댑터(Adapters)**: 외부 시스템과 핵심 비즈니스 로직 사이에서 데이터를 변환하고 상호작용을 직접 처리하는 '어떻게(How)'에 해당하는 구현체입니다. [5, 11] 인프라 계층에 위치합니다. [10]
        *   **기본 어댑터 (Primary Adapters)**: 외부의 요청을 받아 애플리케이션 내부(포트)로 전달하는 입력 핸들러(Controller, CLI, API Gateway 등)입니다. [11, 12]
        *   **보조 어댑터 (Secondary Adapters)**: 애플리케이션의 결과를 외부 세계로 전달하는 출력 핸들러(Repository, 외부 API 클라이언트, 메시지 브로커 등)입니다. [12]

*   **계층 구조와 데이터 흐름(DTO) 관리**
    *   **도메인(Domain) 계층**: 순수한 비즈니스 규칙과 엔티티만 존재하며, 어떠한 외부 라이브러리나 프레임워크에도 의존하지 않아야 합니다. [8]
    *   **애플리케이션(Application) 계층**: 유즈케이스를 처리하는 계층으로, 외부 인프라와의 결합을 막기 위해 **DTO(Data Transfer Object)**는 이 계층에 정의되어야 합니다. [8, 13, 14] DTO를 통해 상호작용(UI) 계층과 애플리케이션 계층 간의 데이터 흐름을 도메인 오염 없이 관리합니다. [13, 15]
    *   **인프라/어댑터(Infrastructure/Adapter) 계층**: DTO와 내부 도메인/데이터베이스 엔티티 간의 변환(Mapping)을 담당하여, 내부 데이터 모델의 변경이 외부 API 스펙을 파괴하지 않도록 하는 안전장치 역할을 수행합니다. [8]

## ⚖️ Trade-offs & Caveats
*   **복잡도 및 오버헤드 증가**: 헥사고날 아키텍처는 고도의 모듈화와 테스트 용이성을 제공하지만, 모든 프로젝트에 적합한 것은 아닙니다. 시스템 구조가 단순하거나 마감일이 촉박한 소규모 프로젝트의 경우, 계층을 엄격히 분리하는 이 구조가 불필요한 오버헤드(Overhead)로 작용할 수 있습니다. [16]
*   **보일러플레이트 코드 발생**: 인터페이스(포트)와 구현체(어댑터)를 분리하고, 도메인 모델과 DTO, 데이터베이스 엔티티를 명확히 구분하여 매퍼(Mapper)를 통해 변환하는 과정이 필수적이므로 초기 개발 단계에서 작성해야 할 보일러플레이트 코드가 크게 증가합니다. [8]
*   **높은 아키텍처 이해도 요구**: DTO나 인터페이스를 어느 계층에 배치해야 하는지(예: 인프라 기술이 애플리케이션 계층으로 침투하지 않도록 DTO를 애플리케이션 계층에 올바르게 위치시켜야 함)와 같은 아키텍처적 판단이 지속적으로 요구되어, 팀원들에게 패턴에 대한 명확하고 높은 이해도가 강제됩니다. [10, 13, 14, 17]

--- 
*Last updated: 2026-05-03*