Hexagonal Architecture (Ports & Adapters)
아키텍처 개요
ONESHIM 서버는 Hexagonal Architecture(Ports & Adapters) 패턴을 채택하여, 비즈니스 로직을 외부 기술 의존성으로부터 완전히 격리합니다.
핵심 원칙
의존성 방향
모든 의존성은 외부에서 내부로 향합니다. Domain Core는 어떤 외부 기술에도 의존하지 않습니다.
계층별 책임
| 계층 | 책임 | 특징 |
|---|---|---|
| Domain Core | 순수 비즈니스 로직 | 외부 의존성 없음, 프레임워크 독립적 |
| Application Layer | 유스케이스 오케스트레이션 | CQRS 핸들러, 도메인 서비스 조합 |
| Ports | 외부 시스템과의 계약 정의 | 인터페이스만 정의, 구현 없음 |
| Adapters | 기술적 구현 | DB, API, 메시징 등의 실제 구현 |
Primary Adapters (Driving Side)
외부에서 시스템으로 들어오는 요청을 처리하는 어댑터입니다.
| 어댑터 | 역할 |
|---|---|
| Web API | REST 기반 HTTP 엔드포인트 제공 |
| gRPC | 고성능 서비스 간 통신 |
| WebSocket | 양방향 실시간 통신 |
| Event Subscribers | 비동기 이벤트 수신 및 처리 |
Application Layer
CQRS(Command Query Responsibility Segregation) 패턴을 적용하여 명령과 조회를 분리합니다.
Domain Core
비즈니스 로직의 핵심으로, 외부 기술에 대한 의존성이 전혀 없습니다.
| 구성요소 | 역할 |
|---|---|
| Aggregates | 비즈니스 규칙의 일관성 경계 정의 |
| Entities & Value Objects | 도메인 개념의 데이터 모델링 |
| Domain Services | 여러 엔티티에 걸친 비즈니스 로직 |
| Domain Policies | 변경이 잦은 복잡한 비즈니스 규칙 |
| Domain Events | 도메인 상태 변화 표현 및 전파 |
Secondary Adapters (Driven Side)
시스템에서 외부로 나가는 요청을 처리하는 어댑터입니다.
이 아키텍처의 장점
| 장점 | 설명 |
|---|---|
| 테스트 용이성 | Domain Core를 인프라 없이 단독 테스트 가능 |
| 기술 교체 용이 | DB, 메시징 등을 어댑터만 교체하여 변경 가능 |
| 관심사 분리 | 비즈니스 로직과 기술적 구현을 완전히 분리 |
| 독립적 배포 | 각 계층을 독립적으로 개발 및 배포 가능 |
| 점진적 마이그레이션 | 레거시 시스템을 어댑터 단위로 점진적 교체 가능 |
관련 문서: