Hexagonal Architecture

📌 한 줄 통찰 (The Karpathy Summary)

헥사고날 아키텍처(포트와 어댑터 패턴)는 알리스테어 코크번(Alistair Cockburn)이 고안한 아키텍처 패턴으로, 핵심 비즈니스(도메인) 로직을 사용자 인터페이스나 데이터베이스 같은 외부 시스템으로부터 완전히 고립시키는 구조다 [1-3]. 시스템의 각 요소가 정의된 '포트'와 '어댑터'를 통해서만 통신하도록 느슨하게 결합하여 테스트 용이성과 유지보수성을 극대화하는 것이 핵심 목적이다 [1, 3].

📖 구조화된 지식 (Synthesized Content)

아키텍처 철학과 구조적 특징: 헥사고날 아키텍처는 전통적인 N-Tier(계층형) 아키텍처의 한계를 극복하기 위해 설계되었으며 육각형 모양은 계층적 구조가 아닌 여러 개의 연결 지점(포트)을 시각적으로 나타내는 메타포다 [4]. 이 패턴은 의존성 역전 원칙(DIP)을 활용하여 도메인 로직이 외부 콘크리트 클래스에 직접 의존하지 않고 생성자 등을 통해 의존성을 주입받도록 구성된다 [5].
포트(Ports)와 어댑터(Adapters):
- 포트(Ports): 시스템이 수행해야 하는 유즈케이스와 기능을 정의하는 인터페이스다 [6, 7]. 시스템이 무엇을 할 수 있는지를 명시하며, 비즈니스 로직으로 진입하는 입구 역할을 수행한다 [6].
- 어댑터(Adapters): 핵심 비즈니스 로직과 외부 세계 사이의 상호작용을 변환하고 연결하는 구현체다 [7, 8].
  - 프라이머리 어댑터(Primary Adapters): 외부 요청을 받아 시스템 내부로 전달하는 역할을 하며, HTTP 컨트롤러, API 게이트웨이, CLI 등이 이에 해당한다 [8, 9].
  - 세컨더리 어댑터(Secondary Adapters): 시스템의 결과를 데이터베이스, 외부 API, 메시지 브로커 등의 외부 시스템으로 출력하는 역할을 담당한다 [9].
실무적 계층 분리와 DTO(데이터 전송 객체) 처리: 실전 프로젝트에서 헥사고날 아키텍처는 주로 도메인(Domain), 애플리케이션(Application), 인프라/어댑터(Infrastructure/Adapter) 계층으로 나뉜다 [3, 10]. 도메인 엔티티를 외부 통신에 직접 노출하지 않기 위해 데이터 전송 객체(DTO)를 사용하며, 이 DTO들은 외부 인터랙션과 인프라의 결합을 막기 위해 애플리케이션 계층(Application Layer)에 정의되고 유지되어야 한다 [11, 12].

⚠️ 모순 및 업데이트 (Contradictions & RL Update)

장점 (Trade-offs/Benefits): 핵심 도메인 코드가 외부 프레임워크나 데이터베이스 기술에 의존하지 않으므로, 기술 스택 변경 시(예: RDBMS에서 NoSQL로 전환) 도메인 로직을 수정할 필요가 없어 유지보수성과 적응성이 매우 뛰어나다 [10, 13, 14]. 또한 개별 컴포넌트들을 완전히 분리하여 단위 테스트 및 통합 테스트를 작성하기가 매우 쉬워진다 [13, 15].
제약 사항 (Caveats): 도메인, 애플리케이션, 인프라 간에 포트 인터페이스를 정의하고 DTO와 엔티티 간 매핑을 수행해야 하므로 상당한 보일러플레이트 코드가 발생한다 [10, 16, 17]. 따라서 마감 기한이 매우 촉박하거나 비즈니스 규칙이 단순하고 작은 애플리케이션에서는 이러한 엄격한 분리가 불필요한 오버헤드와 복잡성을 유발할 수 있다 [17]. 이런 경우에는 오히려 단순한 계층형 아키텍처(Layered Architecture)가 더 나은 대안이 될 수 있다 [17].

🔗 지식 연결 (Graph)

[관계 유형 A: 아키텍처/기반 기술]

Clean Architecture
- 연결 이유: 로버트 C. 마틴의 클린 아키텍처는 헥사고날 아키텍처와 유사하게 관심사를 분리하고 도메인 로직을 보호하는 철학을 공유하는 구조적 패턴이다 [2].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처의 경계를 설정하고 내부 비즈니스 로직을 외부의 프레임워크나 DB로부터 고립시키는 설계 원칙의 본질을 폭넓게 이해할 수 있다 [2].
Layered Architecture
- 연결 이유: 헥사고날 아키텍처의 복잡성이 부담될 때 선택할 수 있는 대안적 설계 방식이자 헥사고날 아키텍처가 극복하고자 했던 전통적인 패턴이다 [2, 17].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수직적 다층 구조(N-Tier)가 갖는 의존성의 한계와 이를 다각도의 입출력(포트) 구조로 재편한 헥사고날 아키텍처의 구조적 차이점을 명확히 파악할 수 있다 [2, 4].

[관계 유형 B: 구현/활용 도구]

Spring Boot
- 연결 이유: 실전 백엔드 환경에서 헥사고날 아키텍처 패턴이 가장 활발하게 채택되고 구현되는 대표적인 Java 기반 프레임워크다 [3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 의존성 주입(DI) 컨테이너와 Spring Data JPA 등을 활용해 실제 코드 상에서 어떻게 포트와 어댑터를 연결하고 구성하는지 구체적인 템플릿 구현 방식을 이해할 수 있다 [3, 18, 19].
DTO (Data Transfer Object)
- 연결 이유: 헥사고날 구조에서 상호작용 계층(UI/Controller)과 애플리케이션 계층 사이의 데이터를 캡슐화하여 도메인을 보호하는 데 쓰이는 필수 데이터 전송 매개체다 [11, 20].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 컨트롤러, 유즈케이스, 도메인 엔티티 간에 데이터를 어떻게 매핑하고 전달해야 아키텍처의 캡슐화 경계가 파괴되지 않는지 구체적인 데이터 흐름을 배울 수 있다 [11, 12].

Deeper Research Questions

대규모 엔터프라이즈 환경에서 헥사고날 아키텍처의 DTO와 도메인 엔티티 간 데이터 매핑(Mapper) 로직이 초래하는 성능 오버헤드와 보일러플레이트를 어떻게 효율적으로 통제할 수 있는가?
Spring Boot 생태계의 AOP(관점 지향 프로그래밍)나 인터셉터 같은 횡단 관심사 기술을 헥사고날 아키텍처의 어느 계층(Layer)에 배치하는 것이 아키텍처 원칙에 가장 부합하는가?
도메인 계층 내부에 비즈니스 룰 유효성 검사를 구현할 때, 프레임워크 종속적인 검증 라이브러리(예: Jakarta Validation)의 사용을 어디까지 허용해야 하는가?
프라이머리 어댑터(Controller 등)에서 수신한 외부 요청을 애플리케이션 계층의 DTO로 변환하는 책임은 정확히 어떤 컴포넌트가 담당해야 결합도를 최소화할 수 있는가?
NestJS와 Spring Boot 환경에서 각각 헥사고날 아키텍처를 구현할 때, 두 프레임워크의 의존성 주입(DI) 시스템 차이가 포트와 어댑터 연결 방식에 어떤 영향을 미치는가?

Practical Application Contexts

Implementation: Java 및 Spring Boot 환경에서 구현할 때, 핵심 비즈니스 로직(도메인 서비스)은 프레임워크 기능에 의존하지 않도록 순수한 형태(POJO)로 작성하고 외부 DB와의 통신은 JPA를 사용하는 리포지토리 어댑터(Repository Adapter)가 처리하도록 구현한다 [3, 18, 19].
System Design: 다수의 UI 플랫폼(웹, 앱)과 다수의 외부 연동(결제 API, 메시징 큐)을 동시에 지원해야 하는 대규모 시스템 설계 시, 코어 로직은 그대로 둔 채 새로운 통신 규격에 맞는 어댑터만 추가(Plug-in)하도록 설계한다 [13].
Operation / Maintenance: 서비스 운영 도중 데이터베이스를 변경하거나 외부 서비스 제공자를 교체하더라도 애플리케이션 계층과 도메인 계층의 코드는 일절 건드리지 않고 인프라 어댑터만 교체함으로써 유지보수 리스크를 극적으로 낮춘다 [10, 16].
Learning Path: 전통적인 MVC 계층 구조를 학습한 개발자가 의존성 역전 원칙(DIP)과 도메인 분리의 중요성을 깨달은 후, 아키텍처 설계 역량을 엔터프라이즈 수준으로 끌어올리기 위해 필수로 거쳐야 하는 심화 학습 과정이다 [2, 5].
My Project Relevance: 요구사항이 지속적으로 변동하고 외부 시스템 통합이 잦으며 복잡한 비즈니스 룰을 장기적으로 확장해야 하는 서버 백엔드 프로젝트에 핵심적인 기본 뼈대로 적용될 수 있다 [13].

Adjacent Topics

Domain-Driven Design (DDD)
- 확장 방향: 헥사고날 아키텍처에서 가장 안쪽에 고립되는 '도메인'을 어떻게 식별하고 값 객체(Value Object)나 애그리거트(Aggregate)로 올바르게 모델링할 것인지에 대한 심층적인 비즈니스 설계 방법론으로 학습을 확장할 수 있다.

Last updated: 2026-05-03

Last updated: 2026-05-03

Raw Source: 00_Raw/2026-05-03/Hexagonal Architecture.md

9.2 KiB Raw Blame History