헥사고날 아키텍처

1. 한 줄 정의

도메인(비즈니스 로직)을 중앙에 두고, 외부 세계와의 모든 통신을 port(인터페이스)와 adapter(구현)로 분리하는 아키텍처.

— Alistair Cockburn, 2005

이름의 유래는 다이어그램을 그렸을 때 도메인 둘레가 육각형(hexagon)으로 보였기 때문. 사실 면의 개수는 의미 없고, "외부와 닿는 면이 여러 개"라는 점이 핵심.

2. 왜 쓰는가

3. 3계층 구조

4. 호출 흐름 — "매물 등록" 시나리오

1. HTTP request → POST /properties 도착
2. API route (driving adapter) 가 Pydantic schema 로 검증 → RegisterPropertyUseCase 호출
3. Use case 가 PropertyRepository port 의 .save() 호출 — 구현은 모름
4. SqlAlchemyPropertyRepository (driven adapter) 가 실제 PostgreSQL 에 INSERT
5. Use case 가 EmbeddingPort.embed() 호출 → VertexAiEmbeddingAdapter 가 LLM 호출 → Qdrant 저장
6. Use case 가 NotificationPort.publish() 호출 → RedisPubSubAdapter 가 Socket.io 로 broadcast
7. API route 가 결과를 JSON 으로 응답

use case 코드 어디에도 sqlalchemy, google.genai, redis 라는 단어가 등장하지 않는다. 그것이 헥사고날의 증거.

5. 코드로 보기 — 매물 등록 use case

5-1. Port (도메인이 정의하는 인터페이스)

# domains/properties/ports/property_repository.py
from abc import ABC, abstractmethod
from domains.properties.entities import Property

class PropertyRepository(ABC):
    @abstractmethod
    async def save(self, property: Property) -> Property: ...

    @abstractmethod
    async def find_by_id(self, id: str) -> Property | None: ...

5-2. Use Case (port 만 의존)

# domains/properties/use_cases/register_property.py
from dataclasses import dataclass
from domains.properties.ports import PropertyRepository, EmbeddingPort
from domains.properties.entities import Property

@dataclass
class RegisterPropertyUseCase:
    repo: PropertyRepository       # ← 인터페이스만 알고 있음
    embedder: EmbeddingPort

    async def execute(self, cmd: RegisterPropertyCommand) -> Property:
        prop = Property.create(cmd.address, cmd.price, cmd.area)
        saved = await self.repo.save(prop)
        await self.embedder.embed(saved.id, saved.description)
        return saved

5-3. Adapter (port 의 구체 구현)

# adapters/database/sqlalchemy_property_repository.py
from sqlalchemy.ext.asyncio import AsyncSession
from domains.properties.ports import PropertyRepository
from domains.properties.entities import Property

class SqlAlchemyPropertyRepository(PropertyRepository):
    def __init__(self, session: AsyncSession):
        self.session = session

    async def save(self, property: Property) -> Property:
        row = PropertyORM.from_entity(property)
        self.session.add(row)
        await self.session.flush()
        return row.to_entity()

5-4. Composition Root (route 에서 wiring)

# api/properties.py
from fastapi import APIRouter, Depends

router = APIRouter()

@router.post("/properties")
async def register(
    body: RegisterPropertySchema,
    session: AsyncSession = Depends(get_db),
    embedder: EmbeddingPort = Depends(get_embedder),
):
    use_case = RegisterPropertyUseCase(
        repo=SqlAlchemyPropertyRepository(session),  # ← 여기서만 SQLAlchemy 등장
        embedder=embedder,
    )
    result = await use_case.execute(body.to_command())
    return PropertyResponse.from_entity(result)

5-5. Test — fake adapter 로 격리

# tests/unit/test_register_property.py
class FakePropertyRepo(PropertyRepository):
    def __init__(self):
        self.items = []
    async def save(self, p):
        self.items.append(p); return p
    async def find_by_id(self, id):
        return next((x for x in self.items if x.id == id), None)

async def test_register():
    repo, embedder = FakePropertyRepo(), FakeEmbedder()
    uc = RegisterPropertyUseCase(repo, embedder)
    result = await uc.execute(RegisterPropertyCommand(...))
    assert result.id in [p.id for p in repo.items]
    # DB·LLM 컨테이너 없이 비즈니스 로직만 검증

6. 어디살지 프로젝트에 어떻게 적용됐는가

backend/src/app/ 의 실제 구조:

domains/{domain}/         # 38개 도메인 (auth, properties, contracts, ai, …)
├── entities/              # 순수 모델 (외부 의존 0)
├── ports/                 # ABC 인터페이스
└── use_cases/             # 비즈니스 로직 (port 만 의존)

core/
├── ports/                 # 공용 port (Repository, UoW, Clock, TokenService, …)
├── result.py              # Result[T, E] 모나드 — exception 대신 명시적 에러
└── errors.py              # DomainError 계층

adapters/                  # port 의 구체 구현
├── database/              # SQLAlchemy 2.0 async repo
├── infra/                 # Qdrant, Redis, S3, Dramatiq
├── oauth/                 # Google, Kakao, Naver
├── auth/                  # PasswordHasher, TokenService
└── realtime/              # Socket.io 어댑터

api/                       # FastAPI route (composition root)
workers/                   # Dramatiq actors (composition root)

7. 규칙·금지

8. 다른 아키텍처와 비교

Hexagonal · Onion · Clean 셋은 본질이 같다 — 의존성 역전을 통한 도메인 보호. 다이어그램이 다를 뿐.

9. FAQ