2nd/10_Wiki/Topics/Ports_and_Adapters.md

---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: Ports and Adapters
last_updated: 2026-05-02
---

# Ports and Adapters

## 📌 Brief Summary
포트와 어댑터(Ports and Adapters)는 앨리스터 코크번(Alistair Cockburn)이 고안한 아키텍처 패턴으로, 헥사고날 아키텍처(Hexagonal Architecture)라는 이름으로도 널리 알려져 있습니다 [1]. 이 패턴의 핵심은 비즈니스 로직을 데이터베이스, 프레임워크, 사용자 인터페이스(UI) 등 외부 요소로부터 완전히 격리하여 느슨하게 결합된 컴포넌트 기반 애플리케이션을 만드는 것입니다 [1, 2]. 비즈니스 로직을 아키텍처의 중앙에 두고 의존성 역전을 극대화하며, 외부 세계와는 오직 추상화된 포트(Port)와 이를 구현하는 어댑터(Adapter)를 통해서만 소통하게 합니다 [3].

## 📖 Core Content
* **핵심 설계 원칙 (Core Design Principles)**
  포트와 어댑터 아키텍처는 기술적인 세부 사항으로부터 비즈니스 도메인 로직을 독립시키기 위해 고안되었습니다 [3]. 관심사의 분리(Separation of Concerns)와 의존성 역전(Dependency Inversion) 원칙을 극대화하여, 모든 의존성의 방향이 아키텍처의 중앙에 위치한 비즈니스 로직을 향하도록 설계합니다 [3]. 이를 통해 기술 스택이 변경되더라도 핵심 비즈니스 로직은 수정할 필요가 없게 됩니다 [3].

* **주요 구성 요소 (Key Components)**
  * **도메인/코어 (Domain/Core)**: 애플리케이션의 핵심 위치에 있으며, 외부 시스템에 대한 의존성 없이 비즈니스 로직과 규칙을 캡슐화합니다 [2, 4].
  * **포트 (Ports)**: 도메인 코어가 외부 세계와 상호작용하는 방식을 정의하는 추상화된 인터페이스입니다 [2, 4]. 인바운드(Driving) 포트는 사용자나 외부 시스템이 코어 로직을 호출하는 방식을 정의하며, 아웃바운드(Driven) 포트는 코어가 외부 서비스(예: 데이터베이스 연동)와 상호작용하는 방식을 설명합니다 [2].
  * **어댑터 (Adapters)**: 외부 시스템과 도메인 사이의 간극을 메우는 구체적인 구현체입니다 [3, 4]. 기본(Primary) 어댑터는 HTTP 요청 등을 코어가 이해할 수 있는 명령으로 변환하고, 보조(Secondary) 어댑터는 아웃바운드 포트를 실질적으로 구현(예: 데이터베이스 영속성 처리)합니다 [2, 4].

* **보안 및 규정 준수 (Security and Compliance)**
  포트와 어댑터 패턴은 시스템의 가장자리(경계)에서 보안을 강제할 수 있도록 설계되어 있습니다 [5]. 포트는 일종의 문지기 역할을 하여, 핵심 로직과 상호작용하기 전에 유효성 검사 및 접근 제어를 의무화합니다 [5]. 이로 인해 UI 계층에서 데이터베이스에 직접 접근하는 등의 안전하지 않은 관행을 원천적으로 방지하며, 데이터 처리 정책을 어댑터 수준에서 일관되게 시행할 수 있어 규정 준수(예: HIPAA)를 간소화합니다 [5, 6].

## ⚖️ Trade-offs & Caveats
**장점 (Pros):**
* **뛰어난 테스트 용이성**: 비즈니스 규칙이 기술적 세부사항과 완전히 분리되어 있으므로, 데이터베이스나 UI 없이도 코어 로직만을 고립시켜 단위 테스트(Unit Test)를 쉽게 수행할 수 있습니다 [7-9].
* **기술 교체의 유연성**: 데이터베이스를 SQL에서 NoSQL로 변경하거나, REST를 GraphQL로 마이그레이션할 때 도메인 로직의 수정 없이 새로운 어댑터만 구현하여 교체할 수 있습니다 [4, 9].
* **장기적인 유지보수성**: UI나 데이터베이스의 변화가 핵심 비즈니스 규칙에 영향을 미치지 않으므로 시스템의 장기적인 신뢰성과 유지보수성이 향상됩니다 [8, 9].

**단점 및 제약 사항 (Cons & Caveats):**
* **초기 도입의 복잡성**: 포트와 어댑터를 설계하기 위한 초기 학습 곡선이 가파르고 설계 복잡도가 높아, 단순한 CRUD 애플리케이션이나 마감일이 촉박한 프로젝트에 적용하기에는 과도한 엔지니어링(Overkill)이 될 수 있습니다 [7-9].
* **보일러플레이트 코드 증가**: 어댑터를 위한 반복적인(Boilerplate) 코드가 다수 발생하여 시스템에 추가적인 추상화 계층을 만들게 됩니다 [8].
* **성능 오버헤드**: 추가된 추상화 계층들을 거쳐야 하므로 약간의 성능 오버헤드나 지연이 발생할 수 있습니다 [8].

## 🔗 Knowledge Connections
### Related Concepts

#### [아키텍처/기반 원리]
- [[의존성 역전 원칙 (Dependency Inversion)]]
  - 연결 이유: 포트와 어댑터의 가장 근본적인 토대가 되는 원리로, 비즈니스 로직이 인프라에 의존하지 않고 인프라가 비즈니스 로직에 의존하게 만듭니다 [3].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처 중앙으로 향하는 단방향 의존성 흐름과 이를 달성하기 위해 포트(인터페이스)가 어떻게 활용되는지 이해할 수 있습니다.
- [[클린 아키텍처 (Clean Architecture)]]
  - 연결 이유: 로버트 C. 마틴이 제안한 아키텍처로, 헥사고날(포트와 어댑터) 아키텍처의 개념을 세련되게 다듬고 확장한 모델입니다 [10, 11].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 내부 계층(Entities, Use Cases)과 외부 계층(Interface Adapters, Frameworks)을 동심원 구조로 나누어 비즈니스 로직을 어떻게 더 체계적으로 보호하는지 학습할 수 있습니다.

#### [설계 및 구현 전략]
- [[도메인 주도 설계 (Domain-Driven Design, DDD)]]
  - 연결 이유: 포트와 어댑터 아키텍처는 코어(Domain)에 비즈니스 로직을 응집시키는 구조이므로 DDD 원칙과 구조적으로 잘 부합합니다 [9].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 마이크로서비스 또는 모놀리스 내에서 도메인 모델을 식별하고, 해당 모델을 외부 시스템(포트와 어댑터)과 어떻게 결합해야 하는지 방향을 잡을 수 있습니다.

### Deeper Research Questions
- 단순한 계층형 아키텍처(Layered Architecture) 기반의 레거시 시스템을 포트와 어댑터 패턴으로 점진적 리팩토링할 때 피해야 할 주요 위험 요소는 무엇인가?
- 포트와 어댑터 설계 시, '인바운드 포트'와 '아웃바운드 포트'의 인터페이스를 분리하는 기준(Interface Segregation)을 실무에서 어떻게 설정해야 하는가?
- 마이크로서비스 아키텍처(MSA) 내부의 개별 서비스를 포트와 어댑터 구조로 설계할 때, 서비스 간의 비동기 메시징(EDA)은 어느 계층의 어댑터에서 처리하는 것이 가장 이상적인가?
- 포트와 어댑터가 추가적인 추상화 계층으로 인해 유발할 수 있는 성능 오버헤드를 어떻게 효과적으로 측정하고 최적화할 수 있는가?
- 도메인 모델이 외부 데이터 소스의 구조와 크게 다를 때, 어댑터(Adapter) 계층에서 발생하는 데이터 매핑 및 변환 로직의 복잡성을 어떻게 관리할 것인가?

### Practical Application Contexts
- **Implementation:** 애플리케이션 개발 시 외부 써드파티 API(예: 결제 게이트웨이 교체, 알림 서비스 변경)의 연동이 잦을 경우, 비즈니스 로직 변경 없이 어댑터의 교체만으로 구현을 유연하게 대처할 수 있습니다 [4, 12].
- **System Design:** 장기적인 수명과 고도화된 비즈니스 규칙을 가진 복잡한 도메인(예: 이커머스, 뱅킹)을 설계할 때, 진화하는 인프라 기술로부터 도메인을 보호하기 위해 채택됩니다 [7, 12].
- **Operation / Maintenance:** 데이터베이스 인프라나 UI 프레임워크가 준비되지 않은 상태에서도 비즈니스 핵심 로직의 단위 테스트를 완벽하게 진행할 수 있어 안정적이고 독립적인 유지보수 운영이 가능합니다 [8, 9].
- **Learning Path:** 전통적 계층형 아키텍처(Layered)의 한계점인 '강한 결합도' 문제를 학습한 후, 이를 타파하기 위한 의존성 역전 및 고수준 아키텍처 설계(클린 아키텍처 등)로 넘어가는 과정에서 필수적으로 학습해야 합니다 [10, 13].
- **My Project Relevance:** 현재 다루고 있는 프로젝트가 잦은 외부 기술 변경을 겪거나, 핵심 비즈니스 로직의 테스트 커버리지를 높여야 하는 상황이라면 이 패턴을 통한 리팩토링을 전략적으로 고려해볼 수 있습니다.

### Adjacent Topics
- [[계층형 아키텍처 (Layered Architecture)]]
  - 확장 방향: 가장 대중적으로 사용되는 N-Tier 아키텍처로, 시간이 지남에 따라 각 계층이 강하게 결합되거나 비즈니스 로직이 분산되는 한계를 포트와 어댑터가 어떻게 극복하는지 비교 분석할 수 있습니다 [13, 14].
- [[마이크로서비스 아키텍처 (Microservices Architecture)]]
  - 확장 방향: 분산된 마이크로서비스 환경에서 각 독립적인 서비스의 내부 설계를 헥사고날(포트와 어댑터) 패턴으로 구성할 경우 얻어지는 테스트 독립성과 유연성의 시너지를 연구할 수 있습니다 [9, 15].

---
*Last updated: 2026-05-02*