Hexagonal Architecture Pattern

📌 Brief Summary

헥사고날 아키텍처(Hexagonal Architecture)는 알리스테어 콕번(Alistair Cockburn)이 고안한 아키텍처로, '포트와 어댑터(Ports and Adapters)' 패턴으로도 불립니다 [1]. 이 패턴의 핵심은 비즈니스 로직(도메인)을 데이터베이스, 프레임워크, 사용자 인터페이스(UI) 등 외부 요소로부터 완전히 격리하는 것입니다 [1, 2]. 이를 통해 기술 스택의 변경이나 외부 시스템의 교체에 영향을 받지 않는 유연하고 결합도가 낮은 시스템을 구축할 수 있으며, 테스트 용이성과 유지보수성이 극대화됩니다 [1-3].

📖 Core Content

헥사고날 아키텍처는 기술적 세부 사항으로부터 비즈니스 도메인 로직을 독립시키기 위해 고안되었으며 [4], 다음과 같은 핵심 구성 요소와 원리를 통해 작동합니다.

비즈니스 로직 중심의 의존성 역전: 모든 의존성 방향은 아키텍처의 중심(비즈니스 로직)을 향하도록 설계됩니다 [4]. 도메인 로직은 외부의 데이터베이스나 UI 라이브러리 등에 대해 전혀 알지 못하며, 오직 추상화된 포트를 통해서만 외부와 소통합니다 [4].
도메인 (Domain/Core): 외부 시스템에 대한 의존성 없이 비즈니스 로직과 규칙만을 포함하는 애플리케이션의 중심부입니다 [2].
포트 (Ports): 중심부의 도메인이 외부 세계와 상호작용하는 방법을 정의하는 추상화된 인터페이스입니다 [2, 5].
- 인바운드(Driving) 포트: 사용자의 요청이나 API 호출 등 외부에서 코어로 들어오는 상호작용을 정의합니다 [2].
- 아웃바운드(Driven) 포트: 코어 로직이 외부 서비스나 데이터 저장소와 상호작용하는 방식을 정의합니다 [2, 5].
어댑터 (Adapters): 도메인과 외부 시스템 사이의 간극을 연결하는 구체적인 구현체입니다 [5].
- 기본(Primary) 어댑터: HTTP 요청 등을 코어가 이해할 수 있는 명령으로 변환하여 인바운드 포트를 호출합니다 [2].
- 보조(Secondary) 어댑터: 아웃바운드 포트를 구현하여 데이터베이스 쿼리를 실행하거나 외부 API와 통신합니다 [2, 5].
경계 기반의 보안 (Security by Boundary Design): 포트는 일종의 '문지기(Gatekeeper)' 역할을 하여, 코어 로직에 접근하기 전에 유효성 검사 및 접근 제어를 강제합니다 [6]. 이는 UI 계층에서 데이터베이스에 직접 접근하는 불안전한 관행을 원천적으로 차단합니다 [6].

⚖️ Trade-offs & Caveats

헥사고날 아키텍처를 도입할 때 얻을 수 있는 이점과 감수해야 할 기술적 반대 급부(Trade-off)는 다음과 같습니다.

장점 (Pros):
- 탁월한 테스트 용이성: 외부 시스템(DB, UI 등)에 의존하지 않으므로 비즈니스 핵심 로직만 격리하여 빠르고 안정적으로 단위 테스트(Unit Testing)를 수행할 수 있습니다 [7, 8].
- 기술 교체의 유연성: 비즈니스 로직의 수정 없이도 어댑터만 교체하면 REST API를 GraphQL로 바꾸거나, SQL 데이터베이스를 NoSQL로 쉽게 전환할 수 있습니다 [3, 9].
- 유지보수성: 외부 의존성의 변화가 핵심 로직에 영향을 주지 않으므로 장기적인 시스템 유지보수와 진화가 용이합니다 [4, 7].
단점 및 제약 사항 (Cons/Caveats):
- 초기 설계의 복잡성 및 학습 곡선: 포트와 어댑터를 설계하고 추상화 계층을 추가하는 과정은 초기에 복잡성을 유발하며 가파른 학습 곡선을 요구합니다 [7]. 주니어 개발자로 구성된 팀에게는 도입이 어려울 수 있습니다 [10].
- 보일러플레이트 코드 증가: 어댑터 구현을 위해 반복적으로 작성해야 하는 보일러플레이트 코드(Boilerplate code)가 늘어나 개발 계층이 추가됩니다 [7].
- 성능 오버헤드: 추상화 계층이 추가됨에 따라 약간의 성능 오버헤드가 발생할 수 있습니다 [7].
- 단순 앱에 대한 과잉 엔지니어링 (Over-engineering): 최소한의 로직만 필요한 단순한 CRUD 애플리케이션이나 일정이 촉박한 프로젝트에 적용하기에는 과도한 엔지니어링이 될 수 있습니다 [11, 12].

🔗 Knowledge Connections

[구조 및 설계 패러다임]

Clean Architecture
- 연결 이유: 헥사고날 아키텍처의 개념을 확장하여 추상화 수준에 따라 동심원 형태의 계층으로 분리한 로버트 C. 마틴(Uncle Bob)의 아키텍처 패턴입니다 [13].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 비즈니스 로직을 외부와 격리한다는 동일한 철학이 어떻게 더 세분화된 엔티티(Entities)와 유스케이스(Use Cases)로 나뉘는지 이해할 수 있습니다 [14].
Layered Architecture Pattern
- 연결 이유: 소프트웨어를 프레젠테이션, 비즈니스, 데이터 등 수평적 계층으로 나누는 전통적인 접근법입니다 [15, 16].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 하향식 의존성(Top-down)을 가지는 계층형 구조가 시간이 지남에 따라 어떻게 강한 결합(Tight coupling)을 유발하는지 비교함으로써, 헥사고날 아키텍처의 '의존성 역전' 필요성을 명확히 인지할 수 있습니다 [12, 16, 17].

[핵심 설계 원칙]

Domain-Driven Design (DDD)
- 연결 이유: 헥사고날 아키텍처는 도메인 규칙을 보호하는 것을 목적으로 하므로, 도메인 중심의 비즈니스 로직을 설계하는 DDD와 자연스럽게 조화를 이룹니다 [3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시스템 중앙에 위치하는 '코어(Core)'를 어떤 비즈니스 모델과 경계(Bounded Context)를 기준으로 식별하고 분리할 것인지 학습할 수 있습니다 [3, 18].
Ports and Adapters
- 연결 이유: 헥사고날 아키텍처의 물리적인 작동 방식을 설명하는 구현 패턴입니다 [1].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시스템의 내부와 외부가 인터페이스(Port)와 구현체(Adapter)를 통해 어떻게 느슨하게 결합(Loosely coupled)되는지 실무적인 코드 레벨에서 이해할 수 있습니다 [1, 6].

Deeper Research Questions

헥사고날 아키텍처에서 인바운드(Driving) 포트와 아웃바운드(Driven) 포트는 시스템 설계 관점에서 어떤 차이가 있으며, 각각 어떻게 구현되는가?
클린 아키텍처(Clean Architecture)나 양파 아키텍처(Onion Architecture)와 비교했을 때, 헥사고날 아키텍처가 갖는 고유한 차별점과 가장 적합한 도입 환경은 무엇인가?
단순한 CRUD 기반 애플리케이션에 헥사고날 아키텍처를 적용했을 때 발생하는 기술적 비용(보일러플레이트 코드 증가 등)을 어떻게 최소화할 수 있는가?
마이크로서비스 아키텍처(MSA) 환경 내의 단일 서비스에 헥사고날 아키텍처를 도입할 때, 서비스 간 비동기 통신(예: Kafka, RabbitMQ)을 위한 포트와 어댑터는 어떻게 설계해야 하는가?
어댑터(Adapter) 계층에서 강제되는 입력 유효성 검사(Validation) 및 역할 기반 접근 제어(RBAC)가 핵심 도메인의 보안을 어떻게 보장하는지에 대한 구체적인 메커니즘은 무엇인가?

Practical Application Contexts

Implementation: 핵심 비즈니스 로직을 외부 인프라(DB, UI 프레임워크)에 종속되지 않는 순수한 코드로 작성하고, 외부 연동은 추상화된 포트(인터페이스)를 구현하는 어댑터 클래스를 통해 주입하는 방식으로 코드를 구성합니다 [2, 5].
System Design: 멀티 채널(API, 웹 UI, 배치 프로세스 등)을 지원해야 하거나, 프레임워크 및 데이터베이스 기술을 향후 쉽게 교체할 수 있도록 확장 가능하고 느슨하게 결합된 시스템을 설계할 때 채택합니다 [2, 11].
Operation / Maintenance: 레거시 시스템을 점진적으로 클라우드나 새로운 기술 스택으로 마이그레이션할 때, 비즈니스 코어는 그대로 유지한 채 어댑터만 교체하여 안정적이고 유연한 유지보수 전략을 실행할 수 있습니다 [4, 7].
Learning Path: Layered Architecture의 잦은 변경으로 인한 취약성(Tight Coupling)을 경험한 후, 의존성 역전(Dependency Inversion) 원칙의 가치를 이해하고 도메인 주도 설계(DDD)와 결합된 아키텍처 패턴을 심화 학습하는 경로로 활용됩니다 [12, 17, 19].
My Project Relevance: 제3자 결제 게이트웨이(Stripe, PayPal 등)나 외부 배송 API 연동이 잦아 외부 서비스 변경이 핵심 비즈니스(주문, 결제 처리)에 영향을 주지 않아야 하는 핀테크 혹은 이커머스 프로젝트에 매우 적합합니다 [20].

Adjacent Topics

Microservices Architecture Pattern
- 확장 방향: 마이크로서비스 생태계 내에서 각 개별 서비스(Microservice)의 내부 코드를 어떻게 구조화할 것인가에 대한 전략으로 헥사고날 패턴과 함께 결합하여 연구할 수 있습니다 [3, 21].
Modular Monolith
- 확장 방향: 분산 아키텍처(MSA)의 네트워크 오버헤드나 복잡성을 피하면서도, 단일 애플리케이션 내부에서 모듈 간의 강한 격리와 응집도를 어떻게 달성할 수 있는지에 대해 헥사고날 아키텍처와 비교/융합하여 확장할 수 있습니다 [22].

Last updated: 2026-05-02

10 KiB Raw Blame History