헥사고날 아키텍처란?

헥사고날 아키텍처란?

1. 헥사고날 아키텍처의 개념

1-1. 정의 및 기원

 헥사고날 아키텍처(Hexagonal Architecture)는 Alistair Cockburn이 2005년에 처음 제안한 개념으로, ‘포트와 어댑터(Ports and Adapters)’ 아키텍처라는 이름으로도 널리 알려져 있다. 이 구조는 기존의 레이어드 아키텍처에서 발생하던 문제, 즉 도메인 로직이 프레임워크나 외부 기술에 종속되는 현상을 해결하기 위해 고안되었다.

 

 핵심 철학은 애플리케이션의 핵심 도메인을 외부와 철저히 분리하고, 포트와 어댑터를 통해서만 상호작용을 허용하는 것이다. 이를 통해 도메인 로직의 순수성을 유지하고, 테스트 용이성과 시스템 유연성을 극대화할 수 있다. 단순히 코드 구조가 아니라, 비즈니스 규칙 중심 설계의 실천 철학이라 볼 수 있다.

1-2. 왜 '헥사고날'인가?

 ‘헥사고날’이라는 이름은 아키텍처의 시각적 표현에서 유래했다. 다각형(육각형) 형태로 중앙에 도메인을 두고, 각 측면에 다양한 어댑터(DB, UI, 메시지 브로커 등) 가 부착된 모습을 갖는다. 중요한 점은 각 어댑터가 어떤 방향이든 도메인과 연결될 수 있다는 점이며, 이는 방향성과 기술 종속성으로부터의 자유를 상징한다. 즉, 웹 UI, REST API, CLI, 외부 이벤트 등 다양한 형태의 입력을 모두 대등하게 취급할 수 있고, DB, 이메일, 캐시, 메시지 큐 등 다양한 출력 수단도 대칭적으로 연결 가능하다는 의미다.

1-3. 핵심 철학과 설계 목표

 헥사고날 아키텍처의 핵심 목표는 세 가지다:

1. 의존성 반전: 도메인이 외부에 의존하지 않고, 외부가 도메인에 의존하게 만든다.
2. 기술 독립성: 도메인은 어떤 프레임워크, 라이브러리, DB 기술과도 독립적으로 존재한다.
3. 유지보수성과 테스트 용이성 확보: 시스템의 진화와 테스트가 외부 기술에 구속되지 않고 수행 가능하다.

 이 구조는 단순히 소프트웨어 계층을 분리하는 것이 아니라, 애플리케이션의 생존성과 변화 대응력 자체를 설계하는 방식이라고 할 수 있다.

1-4. 기존 계층형 아키텍처와의 차이점

 기존의 3계층 혹은 4계층 레이어드 아키텍처는 Controller → Service → Repository → DB 형태로 상하 방향성에 의존한다. 그러나 이는 종종 하위 계층에 기술 의존이 집중되면서 도메인이 오염되는 문제를 낳는다. 헥사고날 아키텍처는 이를 방지하기 위해 중심에 도메인을 두고, 입출력을 모두 포트와 어댑터로 구성하여 방사형 구조로 전환한다. 모든 외부 기능은 어댑터로 구현되며, 도메인은 인터페이스(Port)만 바라본다. 이는 궁극적으로 도메인을 테스트 가능하고, 변경에 강한 구조로 만든다.

---

2. 구조 구성 요소와 역할

2-1. 도메인(핵심 애플리케이션)

 도메인은 시스템의 심장이다. 여기에 비즈니스 정책, 엔티티, 밸류 객체, 도메인 서비스, 애그리거트 등의 핵심 모델이 존재하며, 시스템이 무엇을 해야 하는지를 정의한다. 이 계층은 어떤 외부 라이브러리, 프레임워크, DB, API에도 의존하지 않아야 하며, 그 자체로 테스트 가능해야 한다.

 

 도메인은 단순한 데이터 모델이 아니라, 업무 규칙과 프로세스를 담은 로직 중심의 계층이다. 따라서 도메인을 설계할 때는 기술이 아닌 비즈니스 용어와 흐름에 집중해야 하며, 진정한 의미에서 ‘프레임워크에 구속받지 않는 소프트웨어 설계’가 구현된다.

2-2. 포트(Ports)

 포트는 도메인과 외부를 연결하는 인터페이스다. Input Port(Driving Port) 는 외부 요청(예: REST API, 메시지 이벤트 등)이 도메인을 호출하기 위한 진입점이며, Output Port(Driven Port) 는 도메인이 외부 자원을 호출할 때 사용하는 인터페이스다. 예를 들어, 사용자의 주문 요청이 들어오면 Input Port가 이를 받아 도메인 서비스를 호출하고, 결과적으로 Output Port를 통해 결제 시스템이나 이메일 전송 서비스에 접근한다. 중요한 점은 도메인은 포트 인터페이스만 의존하고, 그 구현체가 무엇인지 모른다는 것이다. 이로 인해 테스트 시에는 구현체 대신 목(Mock)을 주입해 손쉽게 테스트할 수 있다.

2-3. 어댑터(Adapters)

 어댑터는 포트를 구현한 구체 클래스이며, 실제 입출력 동작을 수행한다. REST Controller, GraphQL Resolver, Kafka Consumer, Spring Data Repository, FileStorage 모듈 등이 여기에 해당한다. 예를 들어, UserRestController는 CreateUserPort를 구현하고 있으며, 클라이언트 요청을 받아 포트를 통해 도메인 로직을 호출한다. 반대로, 도메인 계층에서는 SendMailPort라는 인터페이스만 알고 있고, 이 포트를 구현한 JavaMailSenderAdapter가 실제 동작을 담당한다. 이처럼 어댑터는 도메인을 변경하지 않고도 기술 스택을 유연하게 교체할 수 있는 구조를 제공한다.

2-4. 어플리케이션 서비스 계층

 Application Service는 도메인 로직의 오케스트레이터다. 단일 책임 원칙에 따라 UseCase 단위로 나뉘며, Input Port를 구현한다. 이 계층은 유효성 검증, 트랜잭션 관리, 로깅, 흐름 제어 등을 담당하며, 복잡한 로직은 모두 도메인에 위임해야 한다. 이 계층은 도메인을 호출하고, 외부 시스템을 Output Port를 통해 접근하며, 결과를 반환한다. 명확하게 책임을 나누면 도메인 계층은 항상 ‘깨끗하게’ 유지되며, Application 계층은 프로세스 흐름만 제어하는 경량 계층으로 남게 된다.

---

3. 헥사고날 아키텍처의 핵심 장점

3-1. 도메인 순수성(Purity)의 철저한 확보

 헥사고날 구조의 최대 장점은 도메인이 외부 기술로부터 철저히 분리된다는 점이다. 이는 비즈니스 규칙이 ‘깨끗한 코드’ 상태로 유지되는 기반이 되며, 장기적인 유지보수 비용을 획기적으로 줄일 수 있다. 개발 중 어떤 프레임워크가 변경되거나, DB를 교체하거나, 외부 API 방식이 REST에서 gRPC로 바뀌더라도, 도메인은 영향을 받지 않는다. 이렇게 순수한 도메인은 추후 마이크로서비스로 분리되거나 SaaS API로 외부에 제공될 때도 재사용이 가능하다.

3-2. 기술 독립성과 유연성 확보

 포트와 어댑터를 활용하면, 기술 교체나 멀티 채널 지원이 매우 유연해진다. 예를 들어 웹 UI 외에도 CLI, 모바일 앱, 외부 API 등 다양한 클라이언트가 동일한 포트를 통해 도메인에 접근할 수 있다. 각 어댑터는 자신의 채널에 특화되어 있으므로, 하나의 변경이 전체 시스템에 영향을 주지 않는다. 또한 같은 포트를 구현한 어댑터를 여러 개 두는 것도 가능하다. 예: UserRepositoryPort를 RDB, Redis, 외부 API 기반 어댑터로 병렬로 구현하고 전략에 따라 선택적으로 사용할 수 있다.

3-3. 테스트 전략의 단순화

 헥사고날 아키텍처는 테스트 가능한 구조를 원칙적으로 보장한다. 도메인은 외부 의존성이 없으므로 순수 단위 테스트가 가능하며, Output Port에 목 객체를 주입해 외부 시스템을 흉내 낼 수 있다. 반대로 어댑터 테스트에서는 실제 구현을 검증하고, 통합 테스트를 통해 전체 흐름을 점검할 수 있다. 이처럼 테스트가 구조적으로 분리되면, 테스트 커버리지를 높이면서도 테스트 유지보수가 쉬워지고, CI/CD 파이프라인에서도 효과적으로 적용할 수 있다.

3-4. 마이크로서비스 및 클린 아키텍처와의 연계성

 헥사고날 아키텍처는 클린 아키텍처의 원형이며, MSA 환경에서 서비스 단위 구조로 가장 적합한 형태다. 각 마이크로서비스가 하나의 헥사고날 구조를 가지면, 포트 단위로 API를 정의하고, 어댑터 단위로 기술 선택이 자유로워진다. 이 덕분에 서비스별로 다른 언어, 프레임워크, 통신 방식(gRPC, REST 등)을 사용할 수 있으며, 유지보수와 운영 전략을 독립적으로 수립할 수 있다. 결국 이는 시스템 전체의 복잡성을 분산시키고, 조직 내 팀 간 독립성과 책임을 강화하는 결과를 낳는다.

---

4. 헥사고날 아키텍처의 단점과 고려사항

4-1. 구조적 복잡성과 진입 장벽

 헥사고날 아키텍처는 이론적으로는 매우 이상적인 설계지만, 실제로 적용해 보면 구조가 상당히 복잡해진다. 하나의 유즈케이스를 구현하기 위해서도 Input Port, Application Service, Domain Service, Output Port, 어댑터 구현체 등 수많은 계층을 오가야 하며, 이는 초기 개발 속도를 떨어뜨리고 진입 장벽을 높이는 원인이 된다.

 

 또한 프로젝트 규모가 크지 않거나 도메인이 단순한 경우, 이렇게 많은 계층 분리는 오히려 비효율로 작용할 수 있다. CRUD 중심의 업무 시스템, 사내 관리 도구, 단기 이벤트 플랫폼 등에서는 구조 자체가 오버엔지니어링으로 비춰질 가능성도 크다. 이로 인해 일부 팀에서는 포트나 어댑터를 생략하거나, 한 클래스에서 포트와 유즈케이스를 동시에 구현하는 등의 절충안을 사용하지만, 이는 결국 헥사고날의 원칙을 무너뜨리고 구조적 왜곡을 초래할 수 있다.

4-2. 인터페이스 관리 부담과 중복

 헥사고날 아키텍처의 핵심은 의존성 역전이며, 이를 위해 모든 흐름이 인터페이스(Port)를 기준으로 작동한다. 그러나 이로 인해 Output Port와 Input Port를 포함해 매우 많은 수의 인터페이스가 생성되며, 각 포트마다 별도의 구현 클래스가 필요하다.

 

 이러한 구조는 추상화에 익숙하지 않은 개발자들에게 혼란을 줄 수 있고, 특히 인터페이스와 구현 클래스가 거의 1:1 대응인 경우 의미 없는 중복처럼 느껴질 수 있다. 예를 들어, 단순한 loadUser() 기능을 위해 Interface, Service, Repository, Adapter 등 4~5개의 클래스가 필요한 경우가 발생한다. 또한 포트의 설계를 잘못하면, 실제로는 비슷한 기능을 하는 포트가 여러 개 생겨 유지보수가 어려워지는 역설적인 상황이 발생할 수 있다. 포트 간 중복 기능, 네이밍 충돌, 인터페이스 설계 기준 모호 등의 문제는 반드시 표준화된 가이드라인으로 방지해야 한다.

4-3. 협업과 코드 리뷰 난이도 증가

 헥사고날 구조는 계층 간 흐름과 책임이 명확한 만큼, 각 구성 요소의 역할을 정확히 이해해야만 전체 맥락을 파악할 수 있다. 그러나 모든 개발자가 포트-어댑터 철학에 익숙한 것은 아니기 때문에, 협업과 코드 리뷰 단계에서 커뮤니케이션 오류가 자주 발생할 수 있다.

 

 예를 들어, 포트는 선언만 하고 실제 구현은 어댑터에서 이루어지므로, 포트를 보고도 해당 기능이 실제 어떤 동작을 하는지 바로 알기 어렵다. 이는 코드 추적성(traceability)을 떨어뜨리고, 리뷰 시 흐름을 빠르게 파악하는 데 시간을 소모하게 만든다. 또한 한 기능을 위해 여러 파일을 열어봐야 하기 때문에, 이해 비용이 높아지고 개발 생산성이 저하되는 부작용도 동반된다. 특히 경력자와 신입 간 이해도 격차가 커질 경우, 팀 내 기술 격차가 구조화되는 위험도 존재한다.

4-4. 잘못된 도입과 구조 오염 위험

 헥사고날 아키텍처는 도입 시점과 범위가 매우 중요하다. 아무런 전략 없이 ‘좋은 구조니까’라는 이유로 무작정 도입하면, 오히려 의미 없는 레이어 분리, 빈 도메인 계층, 어댑터에 쏠린 로직 등으로 인해 기존보다 나쁜 구조가 될 수 있다.

 

 예를 들어, 도메인 객체에 아무런 비즈니스 로직이 없고 Application Service나 어댑터에 실제 처리가 몰리는 경우, 구조만 헥사고날일 뿐 실제는 기능 중심 레이어드 구조의 변형에 불과하다. 이는 헥사고날의 장점을 전혀 살리지 못하는 결과를 낳는다. 이와 같은 구조 오염은 테스트 코드 작성, 리팩토링, 기능 분리 등에서 지속적으로 문제를 발생시키며, 결국 '헥사고날은 실용적이지 않다'는 잘못된 인식으로 이어질 수 있다.

---

5. 레이어드 아키텍처와의 비교

5-1. 방향성과 의존성의 구조적 차이

 레이어드 아키텍처는 전통적으로 상위 계층이 하위 계층을 호출하는 단방향 수직 구조로 구성된다. 예를 들어 컨트롤러는 서비스 계층을 호출하고, 서비스는 레포지토리 계층을 호출하는 방식이다. 이런 구조는 위에서 아래로 흐르는 논리적 호출 흐름이 명확하여 설계가 직관적이고 초반 구현이 빠르다.

 

 반면 헥사고날 아키텍처는 의존성의 방향을 완전히 반전(Inverted Dependency) 시킨다. 도메인은 외부 어댑터를 알지 못하며, 모든 의존은 포트 인터페이스를 통해서만 연결된다. 즉, 외부가 도메인을 호출하는 구조이며, 도메인은 어떤 기술에도 의존하지 않는다. 이 차이는 특히 기술 스택 변경, 외부 시스템 통합, 이벤트 기반 처리 등에서 큰 차이를 만든다. 헥사고날은 외부 요소 변경 시에도 도메인을 수정할 필요가 없기 때문에, 기술 변화에 대한 내성이 강한 구조라고 볼 수 있다.

5-2. 테스트 전략과 범위의 차이

 레이어드 아키텍처는 일반적으로 서비스 계층 중심 테스트가 이루어진다. 그러나 이 계층은 종종 도메인 로직, 트랜잭션, 외부 호출 등이 혼재되기 때문에, 단위 테스트보다는 통합 테스트에 의존하게 되는 경향이 있다. 또한 외부 시스템과 강하게 연결된 경우 테스트 더블(mock/stub) 구성도 번거롭다.

 

 반면 헥사고날은 포트와 어댑터가 분리되어 있고, 도메인은 순수 자바 클래스(Pojo)로 설계되어 있어 순수한 단위 테스트 작성이 훨씬 쉽다. Output Port를 Mock 처리함으로써 외부 연동 없이 도메인의 핵심 정책만 검증할 수 있다. 또한 Input Port를 통해 유즈케이스 단위 테스트도 깔끔하게 가능하다. 즉, 헥사고날은 구조적으로 테스트 경계를 명확히 나눌 수 있으며, 도메인 테스트와 인프라 테스트를 철저히 분리할 수 있는 구조다. 이는 테스트 자동화와 품질 확보 측면에서 큰 이점을 제공한다.

5-3. 유지보수성과 기술 독립성의 차이

 레이어드는 기술 계층 간 결합도가 높다. 예를 들어, 서비스 계층에서 특정 ORM, 트랜잭션 처리 방식, DB 쿼리 프레임워크에 의존할 경우, 기술 변경 시 도메인 코드까지 영향을 받는 문제가 발생한다. 이는 장기적으로 기술 부채로 축적된다. 헥사고날은 이런 기술 종속을 포트로 추상화하고, 어댑터에 격리시키기 때문에 기술 스택 교체가 도메인에 영향을 주지 않는다. 예를 들어, 기존에 MySQL 기반으로 동작하던 시스템을 PostgreSQL, MongoDB로 교체하거나 메시징 시스템을 Kafka에서 RabbitMQ로 바꾸는 경우에도 어댑터만 수정하면 된다. 이러한 설계는 특히 장기 운영되는 시스템에서 유지보수성과 기술 교체 비용을 낮추며, 기술 생존 주기와 도메인의 생명 주기를 분리할 수 있게 만든다.

5-4. 학습 곡선과 조직 내 도입 난이도

 레이어드는 비교적 단순하고 직관적인 구조이며, 대부분의 웹 프레임워크(Spring, .NET, Django 등)에서 기본 템플릿으로 제공된다. 그래서 개발자들이 구조에 익숙하고, 온보딩이나 교육이 빠르다. 특히 단기간 MVP 개발에는 효율적이다. 그러나 헥사고날은 인터페이스, 추상화, 계층 간 의존 역전 등 개념적 진입 장벽이 높다. 설계 원칙을 모르면 구조가 왜 그런지 이해하기 어렵고, 구현 패턴이 팀마다 다를 경우 혼란이 가중될 수 있다.

 

 또한 폴더 구조, 네이밍 컨벤션, 역할 분리 기준이 사전에 정립되지 않으면, 개발자마다 해석이 달라져 프로젝트 전체의 일관성이 깨질 위험도 존재한다. 따라서 헥사고날을 도입하려면 반드시 팀 단위 교육, 구조 템플릿 설계, 리뷰 기준 정립이 선행되어야 한다.

---

6. 포트 및 어댑터 설계 전략

6-1. Input Port 설계 원칙과 패턴

 Input Port는 도메인을 외부에서 호출할 수 있도록 정의한 진입점 인터페이스다. 주로 Application 계층에 정의되며, 유즈케이스 단위의 명확한 인터페이스 설계가 중요하다. 예: RegisterUserUseCase, PlaceOrderUseCase 등. 메서드는 도메인 언어(Ubiquitous Language)를 따르는 방식으로, 비즈니스 의도를 명확히 드러내야 한다.

 

 Input Port는 단일 책임 원칙(SRP)을 따라야 하며, 유즈케이스 하나당 하나의 포트를 갖는 것이 이상적이다. 예를 들어 registerUser()와 verifyUserEmail()은 각기 다른 유즈케이스이므로, 하나의 포트에 섞지 않고 분리해야 유지보수성이 높아진다. 이 포트는 주로 웹 컨트롤러, 메시지 소비기, CLI 명령 등과 연결되며, 이러한 어댑터는 포트를 구현(implements)함으로써 Application 계층의 UseCase를 실행하게 된다. 명확한 책임 분리가 선행된 Input Port는 API 명세 문서화, 계약 테스트, 인터페이스 변경 관리에도 효과적이다.

6-2. Output Port 설계 원칙과 테스트 활용

 Output Port는 도메인이 외부 시스템(DB, 메일 서버, 메시지 큐 등)과 통신해야 할 때 사용하는 인터페이스다. 도메인은 해당 포트를 통해 외부 호출을 요청하며, 실제 구현은 어댑터 계층에서 제공한다. 중요한 설계 원칙은 Output Port는 도메인의 요구만을 기준으로 정의되어야 하며, 구현체의 기술 세부사항을 반영해서는 안 된다. 예를 들어 loadUserById(Long id)라는 포트는 단순히 사용자를 로드하는 기능만을 표현하고, 그것이 JPA인지 Redis인지, 또는 REST 호출인지는 구현체가 결정해야 한다.

 

 이러한 Output Port는 단위 테스트에서 목(Mock)으로 대체하기 매우 용이하다. 테스트 환경에서는 실제 DB나 외부 시스템을 호출하지 않고, Port 인터페이스를 가짜 객체로 대체하여 도메인 로직만 순수하게 검증할 수 있다. 이처럼 Output Port는 아키텍처의 테스트 가능성을 설계 차원에서 보장하는 핵심 요소다.

6-3. 어댑터 구현 전략: 기술과 도메인의 완전 분리

 어댑터(Adapter)는 Input/Output 포트를 실제 구현하는 구체 클래스다. Input 어댑터는 사용자 입력이나 외부 호출을 받아 Input Port를 호출하며, Output 어댑터는 Output Port를 구현하여 외부 시스템에 작업을 위임한다. 예: OrderRestController, JpaUserRepositoryAdapter, SmtpMailSenderAdapter, KafkaOrderProducerAdapter 등. 이때 가장 중요한 원칙은 도메인 코드와 기술 코드의 경계를 명확히 유지하는 것이다. 어댑터는 외부 기술(프레임워크, DB, 네트워크 등)에 깊게 관여하지만, 도메인 객체를 직접 조작해서는 안 된다. 대신 DTO를 변환하거나 Mapper를 이용해 도메인 객체와의 연결을 수행해야 한다. 또한 어댑터는 가능하면 작고 단순하게 유지하며, 실패 가능성이 있는 외부 호출(예: 네트워크, DB 장애 등)에 대해 타임아웃, 리트라이, 서킷브레이커 같은 안정성 패턴을 적용할 수 있도록 구성하는 것이 좋다.

6-4. 디렉터리 구조 및 네이밍 컨벤션

 헥사고날 아키텍처는 디렉터리 구조와 명명 규칙이 일관되지 않으면 구현 일관성 유지에 어려움을 겪는다. 따라서 다음과 같은 정형화된 구조를 유지하는 것이 좋다

└── member
    ├── domain
    │   ├── Member.java
    │   ├── MemberService.java
    ├── application
    │   └── port
    │       ├── in
    │       │   └── RegisterMemberUseCase.java
    │       └── out
    │           └── LoadMemberPort.java
    ├── adapter
    │   ├── in
    │   │   └── web
    │   │       └── MemberController.java
    │   └── out
    │       └── persistence
    │           └── JpaMemberRepository.java

• domain에는 비즈니스 규칙 중심의 엔티티, 밸류, 서비스가 위치함
• application.port.in은 유즈케이스 단위의 Input Port 인터페이스
• application.port.out은 외부 시스템 연동을 위한 Output Port
• adapter.in은 웹, 메시지 등 입력 채널
• adapter.out은 DB, 메일, 파일 등 출력 채널

 이 구조는 IDE 검색, 테스트 코드 정리, 리뷰 시 흐름 파악에 매우 유리하며, 신규 인원 온보딩 시 빠른 구조 파악에도 효과적이다.

6-5. 실제 적용 사례 및 확장 전략

 실제 대규모 프로젝트에서는 각 도메인(Bounded Context) 단위로 위 구조를 반복 구성하며, 내부 모듈 간 의존성은 interface 기반으로만 연결한다. 또한 Output Port를 한 도메인에서 정의하고, 이를 다른 도메인의 어댑터가 구현하는 형태도 가능하다.

 

 예를 들어 OrderService의 Output Port인 SendPaymentRequestPort는 PaymentAdapter가 구현하며, 이는 결제 도메인과 주문 도메인의 협력을 느슨하게 유지하면서도 역할을 연결하는 구조가 된다. 이처럼 포트와 어댑터는 단순히 기술 추상화의 도구가 아니라, 도메인 간 경계를 정리하고 협력을 정의하는 설계 메커니즘이기도 하다. 따라서 도입 초기부터 설계 기준과 이름 짓기, 범위 설정에 신중해야 한다.