헥사고날 아키텍처 — 포트와 어댑터
DB에 결박된 로직의 비극에서 시작해, 코어-포트-어댑터로 의존 방향을 뒤집고, 코어 무수정으로 어댑터(웹→테스트, Postgres→인메모리)를 갈아 끼우는 것까지 실행한다.
1 / 5흔한 비극부터 — 비즈니스 로직이 웹 프레임워크와 DB에 직접 기대 있습니다. 'DB를 바꾸자', '배치에서도 쓰자', '테스트 좀 빠르게'가 전부 대공사가 됩니다.
웹 컨트롤러주문 로직 (Postgres SQL이 안에!)Postgres
웹 컨트롤러 → 주문 로직: 호출주문 로직 → Postgres: SQL 직접 — 결합
로직이 기술 상세를 아는 순간, 기술 교체 = 로직 수술이 된다.
단계 목록 · 키보드 ←/→ 이동, Space 재생
헥사고날의 본질은 육각형 그림이 아니라 규칙 하나다 — 의존 화살표는 항상 도메인 코어를 향하고, 코어는 포트(인터페이스)만 알며, 기술 상세(웹·DB·큐)는 가장자리의 어댑터로 밀려난다.
왜 헷갈리는가
"계층형(컨트롤러→서비스→리포지토리)이랑 뭐가 달라?" — 방향이 다르다. 계층형은 서비스가 리포지토리 구현을 향해 아래로 의존하지만, 헥사고날은 코어가 인터페이스를 선언하고 DB 어댑터가 그것을 향해 '안쪽으로' 꽂힌다(의존 역전). 그 뒤집기 하나가 교체·테스트 가능성을 만든다.
애니메이션이 보여주는 것
첫 장면의 비극 — 주문 로직 안에 SQL이 있으면 DB 교체·배치 재사용·빠른 테스트가 전부 로직 수술이 된다. 헥사 구조에서 코어는 OrderRepository라는 포트만 알고, Postgres 어댑터가 그 포트를 구현하며 안쪽으로 꽂힌다.
교체 장면이 보상이다 — 테스트가 인메모리 어댑터를 꽂고 밀리초 만에 도메인 규칙을 검증한다. 코어는 한 줄도 안 바뀐다. 웹 대신 CLI·큐 소비자·배치가 꽂히는 것도 같은 원리다: 들어오는 문(인바운드)과 나가는 문(아웃바운드)이 전부 포트다.
실무 감각
도입과 절제의 기준.
- 값을 하는 곳: 도메인 규칙이 복잡하고 오래 살 시스템, 기술 스택 교체가 예상되는 곳, 도메인 테스트를 초 단위로 돌리고 싶은 팀.
- 과한 곳: 단순 CRUD — 포트·매핑·DTO의 격식만 남는다. '규칙이 없는 곳에 코어를 만들지 말 것'.
- 클린·어니언 아키텍처는 같은 원리(의존은 안쪽으로)의 다른 그림 — 이름 논쟁보다 방향 규칙이 본체다.
- 흔한 위반: 코어 엔티티에 ORM 어노테이션·프레임워크 타입이 스미는 것 — 가장자리의 방언이 코어에 들어오는 순간 교체 가능성이 죽는다.
- DDD와의 궁합: 헥사고날이 '어디에 선을 긋나'라면 DDD는 '코어 안을 어떻게 채우나' — 함께 쓰이는 이유.
기억할 것
- 규칙 하나: 의존은 항상 안쪽(코어)으로 — 코어는 아무것도 향하지 않는다.
- 포트 = 코어가 선언한 인터페이스, 어댑터 = 가장자리의 구현.
- 보상은 교체와 테스트 — DB 없이 도는 밀리초 도메인 테스트.
- CRUD뿐인 앱에는 과하다 — 규칙이 복잡할수록 값을 한다.