Fix: Restore unified Topics folder and reorganize specialized category folders
This commit is contained in:
Antigravity Agent
@@ -1,49 +1,70 @@
|
||||
---
|
||||
id: P-REINFORCE-WIKI-ARCH-HEXAGONAL
|
||||
title: "헥사고날 아키텍처 (Hexagonal Architecture / Ports and Adapters)"
|
||||
category: Dev
|
||||
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: ""
|
||||
tags: [Architecture, Design Patterns, DDD, SOLID]
|
||||
title: Hexagonal Architecture (Ports and Adapters)
|
||||
description: 도메인 로직을 외부 인프라스트럭처로부터 격리하여 시스템의 유연성과 테스트 용이성을 극대화하는 아키텍처 설계 패턴
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
# [[헥사고날 아키텍처 (Hexagonal Architecture / Ports and Adapters)]]
|
||||
# Hexagonal Architecture
|
||||
|
||||
## 1. 개요
|
||||
헥사고날 아키텍처(Hexagonal Architecture)는 애플리케이션의 핵심 비즈니스 로직을 외부 기술(DB, UI, 프레임워크 등)로부터 분리하고 격리하여 유지보수성과 테스트 용이성을 극대화하는 설계 패턴이다. 모든 외부 요소는 인터페이스인 '포트(Port)'를 통해 시스템에 연결되며, 구체적인 기술적 세부 사항은 '어댑터(Adapter)'가 담당하는 구조적 특징을 가진다.
|
||||
## 📌 Brief Summary
|
||||
헥사고날 아키텍처(Hexagonal Architecture), 또는 **포트와 어댑터(Ports and Adapters)** 패턴은 소프트웨어의 핵심인 비즈니스 로직(도메인)을 데이터베이스, UI, 프레임워크와 같은 외부 요소로부터 완전히 격리하는 설계 방식입니다. 시스템을 내부(Inside/Domain)와 외부(Outside/Infrastructure)로 명확히 분리하며, 모든 상호작용은 정의된 인터페이스인 **포트(Port)**와 이를 구현하는 **어댑터(Adapter)**를 통해서만 이루어집니다. 이를 통해 기술 스택의 변경이 비즈니스 로직에 미치는 영향을 최소화하고, 독립적인 테스트가 가능한 견고한 시스템을 구축합니다.
|
||||
|
||||
## 2. 핵심 구성 요소
|
||||
- **도메인 (Inside)**: 시스템의 본질인 비즈니스 로직과 규칙. 외부 프레임워크나 인프라 기술에 전혀 의존하지 않는 순수한 코드로 구성된다.
|
||||
- **포트 (Ports)**: 외부 세계가 도메인과 소통하기 위한 명세(인터페이스).
|
||||
- **입력 포트 (Inbound)**: 외부 요청(API 호출, CLI 등)이 도메인 기능을 사용하기 위한 통로.
|
||||
- **출력 포트 (Outbound)**: 도메인이 외부 자원(DB, 메시지 큐 등)에 접근하기 위해 사용하는 통로.
|
||||
- **어댑터 (Outside)**: 포트 인터페이스를 구체적으로 구현하거나 호출하는 인프라 계층.
|
||||
- **입력 어댑터 (Driving)**: 컨트롤러, CLI 핸들러 등 요청을 도메인 명령으로 변환.
|
||||
- **출력 어댑터 (Driven)**: 영속성(Persistence) 구현체, 메시지 송신부 등 기술적 행위 수행.
|
||||
---
|
||||
|
||||
## 3. 실전 적용 가치
|
||||
- **기술 스택 교체 용이성**: 비즈니스 로직을 전혀 수정하지 않고도 DB를 교체하거나 API 스펙을 변경하는 등 유연한 운영 가능.
|
||||
- **테스트 격리**: 인프라 환경 없이도 도메인 로직만 고립시켜 단위 테스트를 수행할 수 있어 검증 속도와 신뢰성 향상.
|
||||
- **의존성 역전 (DIP)**: 도메인이 인프라에 의존하는 것이 아니라, 인프라(어댑터)가 도메인의 명세(포트)에 맞게 구현되도록 강제하여 코드의 순수성 보존.
|
||||
## 📖 Core Content
|
||||
|
||||
## 4. 트레이드오프 및 주의사항
|
||||
- **구현 복잡도**: 포트와 어댑터 계층을 나누고 다수의 인터페이스와 매퍼(Mapper)를 작성해야 하므로 초기 개발 리소스와 보일러플레이트 코드가 증가함.
|
||||
- **과잉 설계 (Over-engineering)**: 도메인 로직이 단순한 CRUD 수준일 경우, 헥사고날 아키텍처의 도입은 시스템을 불필요하게 복잡하게 만들 수 있음.
|
||||
- **학습 곡선**: 전통적인 계층형 아키텍처에 익숙한 개발팀에게는 패러다임 전환을 위한 교육 비용이 발생함.
|
||||
### 1. 핵심 원리: 의존성 역전 (DIP)
|
||||
전통적인 계층형 아키텍처(Layered Architecture)는 상위 계층이 하위 계층(특히 DB나 외부 라이브러리)에 직접 의존하여 기술적 변경에 취약했습니다. 헥사고날 아키텍처는 **의존성 역전 원칙(Dependency Inversion Principle)**을 극한으로 활용하여, 도메인과 인프라 모두가 추상화된 인터페이스(포트)에 의존하게 만듭니다.
|
||||
|
||||
## 5. 지식 연결 (Related)
|
||||
- [[Domain_Driven_Design]]: 헥사고날 아키텍처 내부(도메인)를 채우는 모델링 기법.
|
||||
- [[Clean_Architecture]]: 유사한 격리 철학을 동심원 모델로 표현한 아키텍처.
|
||||
- [[CQRS_Pattern]]: 조회와 명령의 효율성을 위해 헥사고날과 흔히 결합되는 패턴.
|
||||
### 2. 주요 구성 요소
|
||||
* **도메인 (Inside):** 애플리케이션의 핵심 비즈니스 로직과 규칙을 포함하는 순수 코드 영역입니다. 외부 프레임워크나 데이터베이스 기술에 대한 지식이 전혀 없는 상태로 유지됩니다.
|
||||
* **포트 (Ports):** 내부와 외부를 연결하는 명세(Interface)입니다.
|
||||
* **입력 포트 (Inbound/Driving Ports):** 외부(UI, API 호출 등)에서 도메인 기능을 호출할 때 사용하는 인터페이스입니다.
|
||||
* **출력 포트 (Outbound/Driven Ports):** 도메인이 외부 자원(DB, 메시지 큐, 외부 API)에 접근해야 할 때 사용하는 인터페이스입니다.
|
||||
* **어댑터 (Outside):** 포트를 구체적으로 구현하거나 호출하는 인프라 계층입니다.
|
||||
* **입력 어댑터:** REST Controller, CLI, WebSockets 등 외부 요청을 도메인이 이해할 수 있는 형식으로 변환하여 입력 포트를 호출합니다.
|
||||
* **출력 어댑터:** 도메인의 요청을 받아 실제 DB(JPA, MongoDB), 외부 메일 서버, 알림 서비스 등으로 전달하는 구체적인 기술 구현체입니다.
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
- **정보 상태**: 검증 완료 (Verified)
|
||||
- **출처 신뢰도**: A
|
||||
- **검토 이유**: 기술 종속성에서 벗어나 비즈니스 로직의 수명을 극대화하기 위한 현대적 아키텍처의 표준 명세 정립.
|
||||
### 3. 실전 설계 전략 (Framework Specific)
|
||||
* **Spring Boot (Java):** 도메인 모델을 `@Entity` 등 프레임워크 어노테이션에서 분리하여 POJO로 구성합니다. `@Configuration`을 사용하여 어댑터 구현체를 런타임에 도메인 서비스에 주입합니다.
|
||||
* **NestJS (TypeScript):** 모듈 시스템과 DI를 활용합니다. `Domain`, `Application`, `Infrastructure`, `Presentation` 계층을 폴더 구조로 명확히 나누고, 인터페이스 기반 프로그래밍을 강제합니다.
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Trade-offs & Caveats
|
||||
|
||||
### ✅ Benefits
|
||||
* **높은 테스트 용이성:** 외부 DB나 API 없이도 모킹(Mocking)을 통해 도메인 로직만 완벽하게 테스트할 수 있습니다.
|
||||
* **기술 독립성:** 데이터베이스나 메시징 시스템을 교체할 때 도메인 코드를 수정할 필요가 없습니다.
|
||||
* **유지보수성:** 비즈니스 규칙이 한곳에 집중되어 있어 코드 파악과 변경이 용이합니다.
|
||||
|
||||
### ⚠️ Challenges
|
||||
* **초기 복잡성:** 단순한 CRUD 앱의 경우, 수많은 인터페이스와 매핑 객체(DTO/Mapper)가 오버헤드로 작용할 수 있습니다.
|
||||
* **보일러플레이트:** 계층 간 데이터 변환을 위한 코드가 늘어납니다.
|
||||
* **학습 곡선:** 전통적인 계층 구조에 익숙한 팀에게는 패러다임 전환을 위한 비용이 발생합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Knowledge Connections
|
||||
|
||||
### Related Concepts
|
||||
* [[Dependency_Inversion_Principle]]: 헥사고날 아키텍처의 기술적 토대가 되는 원칙입니다.
|
||||
* [[Clean_Architecture]]: 비즈니스 로직을 중심에 두는 유사한 철학의 아키텍처 패턴입니다.
|
||||
* [[Domain_Driven_Design]]: 헥사고날 아키텍처 내부(도메인)를 채우는 모델링 방법론을 제공합니다.
|
||||
* [[Dependency_Injection]]: 포트와 어댑터를 런타임에 결합하는 실무 도구입니다.
|
||||
|
||||
### Practical Application Contexts
|
||||
* **System Design:** UI나 DB를 먼저 설계하지 않고, 비즈니스 유스케이스와 포트를 먼저 정의하는 '도메인 중심' 접근을 권장합니다.
|
||||
* **Maintenance:** 레거시 시스템을 점진적으로 개선할 때, 외부 통신부를 어댑터로 격리하여 안전하게 로직을 추출할 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Adjacent Topics
|
||||
* [[Test_Driven_Development]]: 헥사고날의 격리성을 활용하여 테스트 중심 개발을 가속화합니다.
|
||||
* [[CQRS]]: 대규모 시스템에서 명령(Write)과 조회(Read) 포트를 분리하여 성능을 극대화하는 전략과 궁합이 좋습니다.
|
||||
* [[Microservices]]: 각 마이크로서비스 내부 아키텍처로 헥사고날을 적용하여 서비스 간 독립성을 확보합니다.
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-02*
|
||||
|
||||
Reference in New Issue
Block a user