클린 아키텍처와 헥사고날 아키텍처 실전 구현: 포트와 어댑터 패턴으로 도메인 독립성 확보

src/
  domain/           # 도메인 레이어 (엔티티, 밸류 오브젝트)
    entities/
      Order.ts
      Product.ts
    value-objects/
      Money.ts
      OrderStatus.ts
  application/      # 애플리케이션 레이어 (유스케이스, 포트)
    ports/
      inbound/
        CreateOrderUseCase.ts
        GetOrderUseCase.ts
      outbound/
        OrderRepository.ts
        PaymentGateway.ts
        EventPublisher.ts
    services/
      CreateOrderService.ts
      GetOrderService.ts
  infrastructure/   # 인프라스트럭처 레이어 (어댑터)
    adapters/
      inbound/
        http/
          OrderController.ts
        messaging/
          OrderEventListener.ts
      outbound/
        persistence/
          TypeOrmOrderRepository.ts
        payment/
          StripePaymentAdapter.ts
        messaging/
          KafkaEventPublisher.ts
    config/
      DependencyContainer.ts

// domain/value-objects/Money.ts
export class Money {
  private constructor(
    private readonly amount: number,
    private readonly currency: string
  ) {
    if (amount < 0) {
      throw new Error('Amount cannot be negative')
    }
  }

  static of(amount: number, currency: string = 'KRW'): Money {
    return new Money(amount, currency)
  }

  add(other: Money): Money {
    this.ensureSameCurrency(other)
    return Money.of(this.amount + other.amount, this.currency)
  }

  multiply(factor: number): Money {
    return Money.of(this.amount * factor, this.currency)
  }

  isGreaterThan(other: Money): boolean {
    this.ensureSameCurrency(other)
    return this.amount > other.amount
  }

  getAmount(): number {
    return this.amount
  }

  private ensureSameCurrency(other: Money): void {
    if (this.currency !== other.currency) {
      throw new Error('Currency mismatch')
    }
  }
}

// domain/value-objects/OrderStatus.ts
export enum OrderStatus {
  PENDING = 'PENDING',
  CONFIRMED = 'CONFIRMED',
  PAID = 'PAID',
  SHIPPED = 'SHIPPED',
  DELIVERED = 'DELIVERED',
  CANCELLED = 'CANCELLED',
}

// domain/entities/Order.ts
import { Money } from '../value-objects/Money'
import { OrderStatus } from '../value-objects/OrderStatus'

export interface OrderItem {
  productId: string
  productName: string
  quantity: number
  unitPrice: Money
}

export class Order {
  private constructor(
    private readonly id: string,
    private readonly customerId: string,
    private items: OrderItem[],
    private status: OrderStatus,
    private readonly createdAt: Date
  ) {}

  static create(id: string, customerId: string, items: OrderItem[]): Order {
    if (items.length === 0) {
      throw new Error('Order must have at least one item')
    }
    return new Order(id, customerId, items, OrderStatus.PENDING, new Date())
  }

  confirm(): void {
    if (this.status !== OrderStatus.PENDING) {
      throw new Error('Only pending orders can be confirmed')
    }
    this.status = OrderStatus.CONFIRMED
  }

  pay(): void {
    if (this.status !== OrderStatus.CONFIRMED) {
      throw new Error('Only confirmed orders can be paid')
    }
    this.status = OrderStatus.PAID
  }

  cancel(): void {
    if (this.status === OrderStatus.SHIPPED || this.status === OrderStatus.DELIVERED) {
      throw new Error('Cannot cancel shipped or delivered orders')
    }
    this.status = OrderStatus.CANCELLED
  }

  getTotalAmount(): Money {
    return this.items.reduce(
      (total, item) => total.add(item.unitPrice.multiply(item.quantity)),
      Money.of(0)
    )
  }

  getId(): string {
    return this.id
  }
  getCustomerId(): string {
    return this.customerId
  }
  getStatus(): OrderStatus {
    return this.status
  }
  getItems(): ReadonlyArray<OrderItem> {
    return [...this.items]
  }
}

// application/ports/inbound/CreateOrderUseCase.ts
export interface CreateOrderCommand {
  customerId: string
  items: Array<{
    productId: string
    productName: string
    quantity: number
    unitPrice: number
  }>
}

export interface CreateOrderResult {
  orderId: string
  totalAmount: number
  status: string
}

export interface CreateOrderUseCase {
  execute(command: CreateOrderCommand): Promise<CreateOrderResult>
}

// application/ports/outbound/OrderRepository.ts
import { Order } from '../../domain/entities/Order'

export interface OrderRepository {
  save(order: Order): Promise<void>
  findById(id: string): Promise<Order | null>
  findByCustomerId(customerId: string): Promise<Order[]>
}

// application/ports/outbound/PaymentGateway.ts
export interface PaymentRequest {
  orderId: string
  amount: number
  currency: string
}

export interface PaymentResult {
  transactionId: string
  success: boolean
  errorMessage?: string
}

export interface PaymentGateway {
  processPayment(request: PaymentRequest): Promise<PaymentResult>
}

// application/ports/outbound/EventPublisher.ts
export interface DomainEvent {
  eventType: string
  aggregateId: string
  payload: Record<string, unknown>
  occurredAt: Date
}

export interface EventPublisher {
  publish(event: DomainEvent): Promise<void>
}

// application/services/CreateOrderService.ts
import {
  CreateOrderUseCase,
  CreateOrderCommand,
  CreateOrderResult,
} from '../ports/inbound/CreateOrderUseCase'
import { OrderRepository } from '../ports/outbound/OrderRepository'
import { PaymentGateway } from '../ports/outbound/PaymentGateway'
import { EventPublisher } from '../ports/outbound/EventPublisher'
import { Order, OrderItem } from '../../domain/entities/Order'
import { Money } from '../../domain/value-objects/Money'
import { v4 as uuidv4 } from 'uuid'

export class CreateOrderService implements CreateOrderUseCase {
  constructor(
    private readonly orderRepository: OrderRepository,
    private readonly paymentGateway: PaymentGateway,
    private readonly eventPublisher: EventPublisher
  ) {}

  async execute(command: CreateOrderCommand): Promise<CreateOrderResult> {
    // 1. 도메인 객체 생성
    const orderItems: OrderItem[] = command.items.map((item) => ({
      productId: item.productId,
      productName: item.productName,
      quantity: item.quantity,
      unitPrice: Money.of(item.unitPrice),
    }))

    const order = Order.create(uuidv4(), command.customerId, orderItems)

    // 2. 주문 확인
    order.confirm()

    // 3. 결제 처리
    const paymentResult = await this.paymentGateway.processPayment({
      orderId: order.getId(),
      amount: order.getTotalAmount().getAmount(),
      currency: 'KRW',
    })

    if (!paymentResult.success) {
      order.cancel()
      await this.orderRepository.save(order)
      throw new Error('Payment failed: ' + (paymentResult.errorMessage || 'Unknown error'))
    }

    // 4. 결제 완료 처리
    order.pay()

    // 5. 저장
    await this.orderRepository.save(order)

    // 6. 도메인 이벤트 발행
    await this.eventPublisher.publish({
      eventType: 'OrderCreated',
      aggregateId: order.getId(),
      payload: {
        customerId: order.getCustomerId(),
        totalAmount: order.getTotalAmount().getAmount(),
        itemCount: order.getItems().length,
      },
      occurredAt: new Date(),
    })

    return {
      orderId: order.getId(),
      totalAmount: order.getTotalAmount().getAmount(),
      status: order.getStatus(),
    }
  }
}

// infrastructure/adapters/outbound/persistence/TypeOrmOrderRepository.ts
import { OrderRepository } from '../../../application/ports/outbound/OrderRepository'
import { Order, OrderItem } from '../../../domain/entities/Order'
import { Repository, DataSource } from 'typeorm'

// TypeORM 엔티티 (인프라 관심사)
import { OrderEntity } from './entities/OrderEntity'
import { OrderItemEntity } from './entities/OrderItemEntity'

export class TypeOrmOrderRepository implements OrderRepository {
  private readonly repository: Repository<OrderEntity>

  constructor(dataSource: DataSource) {
    this.repository = dataSource.getRepository(OrderEntity)
  }

  async save(order: Order): Promise<void> {
    const entity = this.toEntity(order)
    await this.repository.save(entity)
  }

  async findById(id: string): Promise<Order | null> {
    const entity = await this.repository.findOne({
      where: { id },
      relations: ['items'],
    })
    return entity ? this.toDomain(entity) : null
  }

  async findByCustomerId(customerId: string): Promise<Order[]> {
    const entities = await this.repository.find({
      where: { customerId },
      relations: ['items'],
    })
    return entities.map((e) => this.toDomain(e))
  }

  private toEntity(order: Order): OrderEntity {
    // 도메인 -> 영속성 변환 로직
    const entity = new OrderEntity()
    entity.id = order.getId()
    entity.customerId = order.getCustomerId()
    entity.status = order.getStatus()
    entity.totalAmount = order.getTotalAmount().getAmount()
    return entity
  }

  private toDomain(entity: OrderEntity): Order {
    // 영속성 -> 도메인 변환 로직
    // Order.reconstitute() 같은 팩토리 메서드를 사용
    return Order.create(entity.id, entity.customerId, /* items mapping */ [])
  }
}

// infrastructure/adapters/inbound/http/OrderController.ts
import { Router, Request, Response } from 'express'
import { CreateOrderUseCase } from '../../../application/ports/inbound/CreateOrderUseCase'

export class OrderController {
  private readonly router: Router

  constructor(private readonly createOrderUseCase: CreateOrderUseCase) {
    this.router = Router()
    this.setupRoutes()
  }

  private setupRoutes(): void {
    this.router.post('/orders', this.createOrder.bind(this))
  }

  private async createOrder(req: Request, res: Response): Promise<void> {
    try {
      const result = await this.createOrderUseCase.execute({
        customerId: req.body.customerId,
        items: req.body.items,
      })
      res.status(201).json(result)
    } catch (error) {
      if (error instanceof Error) {
        res.status(400).json({ error: error.message })
      } else {
        res.status(500).json({ error: 'Internal server error' })
      }
    }
  }

  getRouter(): Router {
    return this.router
  }
}

// infrastructure/config/DependencyContainer.ts
import { DataSource } from 'typeorm'
import { CreateOrderService } from '../../application/services/CreateOrderService'
import { TypeOrmOrderRepository } from '../adapters/outbound/persistence/TypeOrmOrderRepository'
import { StripePaymentAdapter } from '../adapters/outbound/payment/StripePaymentAdapter'
import { KafkaEventPublisher } from '../adapters/outbound/messaging/KafkaEventPublisher'
import { OrderController } from '../adapters/inbound/http/OrderController'

export class DependencyContainer {
  private static instance: DependencyContainer

  private constructor(private readonly dataSource: DataSource) {}

  static async create(dataSource: DataSource): Promise<DependencyContainer> {
    if (!DependencyContainer.instance) {
      DependencyContainer.instance = new DependencyContainer(dataSource)
    }
    return DependencyContainer.instance
  }

  createOrderController(): OrderController {
    // 아웃바운드 어댑터 생성
    const orderRepository = new TypeOrmOrderRepository(this.dataSource)
    const paymentGateway = new StripePaymentAdapter()
    const eventPublisher = new KafkaEventPublisher()

    // 유스케이스 생성 (포트 구현체 주입)
    const createOrderService = new CreateOrderService(
      orderRepository,
      paymentGateway,
      eventPublisher
    )

    // 인바운드 어댑터 생성
    return new OrderController(createOrderService)
  }
}

# domain/entities/order.py
from dataclasses import dataclass, field
from enum import Enum
from datetime import datetime
from typing import List
from domain.value_objects.money import Money


class OrderStatus(Enum):
    PENDING = "PENDING"
    CONFIRMED = "CONFIRMED"
    PAID = "PAID"
    SHIPPED = "SHIPPED"
    CANCELLED = "CANCELLED"


@dataclass
class OrderItem:
    product_id: str
    product_name: str
    quantity: int
    unit_price: Money


class Order:
    def __init__(
        self,
        order_id: str,
        customer_id: str,
        items: List[OrderItem],
        status: OrderStatus = OrderStatus.PENDING,
        created_at: datetime = None,
    ):
        if not items:
            raise ValueError("Order must have at least one item")
        self._id = order_id
        self._customer_id = customer_id
        self._items = items
        self._status = status
        self._created_at = created_at or datetime.utcnow()

    def confirm(self) -> None:
        if self._status != OrderStatus.PENDING:
            raise ValueError("Only pending orders can be confirmed")
        self._status = OrderStatus.CONFIRMED

    def pay(self) -> None:
        if self._status != OrderStatus.CONFIRMED:
            raise ValueError("Only confirmed orders can be paid")
        self._status = OrderStatus.PAID

    def cancel(self) -> None:
        if self._status in (OrderStatus.SHIPPED,):
            raise ValueError("Cannot cancel shipped orders")
        self._status = OrderStatus.CANCELLED

    @property
    def total_amount(self) -> Money:
        total = Money(0)
        for item in self._items:
            total = total.add(item.unit_price.multiply(item.quantity))
        return total

    @property
    def id(self) -> str:
        return self._id

    @property
    def customer_id(self) -> str:
        return self._customer_id

    @property
    def status(self) -> OrderStatus:
        return self._status

# application/ports/outbound/order_repository.py
from abc import ABC, abstractmethod
from typing import Optional, List
from domain.entities.order import Order


class OrderRepository(ABC):
    @abstractmethod
    async def save(self, order: Order) -> None:
        pass

    @abstractmethod
    async def find_by_id(self, order_id: str) -> Optional[Order]:
        pass

    @abstractmethod
    async def find_by_customer_id(self, customer_id: str) -> List[Order]:
        pass


# application/ports/outbound/payment_gateway.py
from abc import ABC, abstractmethod
from dataclasses import dataclass


@dataclass
class PaymentRequest:
    order_id: str
    amount: float
    currency: str


@dataclass
class PaymentResult:
    transaction_id: str
    success: bool
    error_message: str = ""


class PaymentGateway(ABC):
    @abstractmethod
    async def process_payment(self, request: PaymentRequest) -> PaymentResult:
        pass

# application/services/create_order_service.py
import uuid
from dataclasses import dataclass
from typing import List
from domain.entities.order import Order, OrderItem
from domain.value_objects.money import Money
from application.ports.outbound.order_repository import OrderRepository
from application.ports.outbound.payment_gateway import PaymentGateway, PaymentRequest


@dataclass
class CreateOrderCommand:
    customer_id: str
    items: List[dict]


@dataclass
class CreateOrderResult:
    order_id: str
    total_amount: float
    status: str


class CreateOrderService:
    def __init__(
        self,
        order_repository: OrderRepository,
        payment_gateway: PaymentGateway,
    ):
        self._order_repository = order_repository
        self._payment_gateway = payment_gateway

    async def execute(self, command: CreateOrderCommand) -> CreateOrderResult:
        # 도메인 객체 생성
        items = [
            OrderItem(
                product_id=item["product_id"],
                product_name=item["product_name"],
                quantity=item["quantity"],
                unit_price=Money(item["unit_price"]),
            )
            for item in command.items
        ]

        order = Order(
            order_id=str(uuid.uuid4()),
            customer_id=command.customer_id,
            items=items,
        )

        order.confirm()

        # 결제 처리
        payment_result = await self._payment_gateway.process_payment(
            PaymentRequest(
                order_id=order.id,
                amount=order.total_amount.amount,
                currency="KRW",
            )
        )

        if not payment_result.success:
            order.cancel()
            await self._order_repository.save(order)
            raise Exception(f"Payment failed: {payment_result.error_message}")

        order.pay()
        await self._order_repository.save(order)

        return CreateOrderResult(
            order_id=order.id,
            total_amount=order.total_amount.amount,
            status=order.status.value,
        )

// tests/domain/entities/Order.test.ts
import { Order, OrderItem } from '../../../domain/entities/Order'
import { Money } from '../../../domain/value-objects/Money'
import { OrderStatus } from '../../../domain/value-objects/OrderStatus'

describe('Order', () => {
  const sampleItems: OrderItem[] = [
    {
      productId: 'prod-1',
      productName: 'Widget',
      quantity: 2,
      unitPrice: Money.of(10000),
    },
  ]

  it('should create an order with PENDING status', () => {
    const order = Order.create('order-1', 'customer-1', sampleItems)
    expect(order.getStatus()).toBe(OrderStatus.PENDING)
  })

  it('should throw when creating order with empty items', () => {
    expect(() => Order.create('order-1', 'customer-1', [])).toThrow(
      'Order must have at least one item'
    )
  })

  it('should calculate total amount correctly', () => {
    const order = Order.create('order-1', 'customer-1', sampleItems)
    expect(order.getTotalAmount().getAmount()).toBe(20000)
  })

  it('should transition from PENDING to CONFIRMED', () => {
    const order = Order.create('order-1', 'customer-1', sampleItems)
    order.confirm()
    expect(order.getStatus()).toBe(OrderStatus.CONFIRMED)
  })

  it('should not allow paying before confirming', () => {
    const order = Order.create('order-1', 'customer-1', sampleItems)
    expect(() => order.pay()).toThrow('Only confirmed orders can be paid')
  })
})

// tests/application/services/CreateOrderService.test.ts
import { CreateOrderService } from '../../../application/services/CreateOrderService'
import { OrderRepository } from '../../../application/ports/outbound/OrderRepository'
import { PaymentGateway } from '../../../application/ports/outbound/PaymentGateway'
import { EventPublisher } from '../../../application/ports/outbound/EventPublisher'

describe('CreateOrderService', () => {
  let service: CreateOrderService
  let mockOrderRepo: jest.Mocked<OrderRepository>
  let mockPayment: jest.Mocked<PaymentGateway>
  let mockEvents: jest.Mocked<EventPublisher>

  beforeEach(() => {
    mockOrderRepo = {
      save: jest.fn().mockResolvedValue(undefined),
      findById: jest.fn(),
      findByCustomerId: jest.fn(),
    }
    mockPayment = {
      processPayment: jest.fn().mockResolvedValue({
        transactionId: 'tx-1',
        success: true,
      }),
    }
    mockEvents = {
      publish: jest.fn().mockResolvedValue(undefined),
    }

    service = new CreateOrderService(mockOrderRepo, mockPayment, mockEvents)
  })

  it('should create and pay for an order successfully', async () => {
    const result = await service.execute({
      customerId: 'cust-1',
      items: [
        {
          productId: 'prod-1',
          productName: 'Widget',
          quantity: 1,
          unitPrice: 10000,
        },
      ],
    })

    expect(result.status).toBe('PAID')
    expect(mockOrderRepo.save).toHaveBeenCalledTimes(1)
    expect(mockPayment.processPayment).toHaveBeenCalledTimes(1)
    expect(mockEvents.publish).toHaveBeenCalledTimes(1)
  })

  it('should cancel order when payment fails', async () => {
    mockPayment.processPayment.mockResolvedValue({
      transactionId: '',
      success: false,
      errorMessage: 'Insufficient funds',
    })

    await expect(
      service.execute({
        customerId: 'cust-1',
        items: [
          {
            productId: 'prod-1',
            productName: 'Widget',
            quantity: 1,
            unitPrice: 10000,
          },
        ],
      })
    ).rejects.toThrow('Payment failed')

    expect(mockOrderRepo.save).toHaveBeenCalledTimes(1)
  })
})

// 나쁜 예: 도메인 엔티티가 TypeORM 데코레이터에 의존
import { Entity, Column, PrimaryColumn } from 'typeorm'

@Entity() // 인프라 프레임워크 의존!
export class Order {
  @PrimaryColumn()
  id: string

  @Column()
  status: string
  // ...
}

// 좋은 예: 도메인 엔티티는 순수 클래스로 유지
// 영속성 매핑은 인프라 레이어에서 별도의 Entity 클래스로 처리
export class Order {
  private readonly id: string
  private status: OrderStatus
  // 순수 비즈니스 로직만 포함
}

// 나쁜 예: 도메인 엔티티가 데이터 구조에 불과
export class Order {
  id: string
  status: string
  items: OrderItem[]
  totalAmount: number
  // getter/setter만 존재, 비즈니스 로직 없음
}

// 비즈니스 로직이 서비스에 모두 집중
export class OrderService {
  confirmOrder(order: Order): void {
    if (order.status !== 'PENDING') throw new Error('...')
    order.status = 'CONFIRMED'
    order.totalAmount = this.calculateTotal(order.items)
  }
}

// 좋은 예: 도메인 엔티티 안에 비즈니스 로직 캡슐화
export class Order {
  confirm(): void {
    if (this.status !== OrderStatus.PENDING) {
      throw new Error('Only pending orders can be confirmed')
    }
    this.status = OrderStatus.CONFIRMED
  }

  getTotalAmount(): Money {
    return this.items.reduce(
      (total, item) => total.add(item.unitPrice.multiply(item.quantity)),
      Money.of(0)
    )
  }
}