DDD 이론 10: Domain Events

Domain Event는 도메인에서 발생한 비즈니스적으로 의미 있는 사건입니다. 과거에 일어난 일이므로 불변이며, 과거형으로 명명합니다.

// Domain Event 기본 구조
interface DomainEvent {
  readonly eventId: string;        // 이벤트 고유 ID
  readonly occurredAt: Date;       // 발생 시각
  readonly aggregateId: string;    // 관련 Aggregate ID
  readonly aggregateType: string;  // Aggregate 타입
  readonly eventType: string;      // 이벤트 타입
}

// 구체적인 Domain Event
class OrderConfirmedEvent implements DomainEvent {
  readonly eventId: string;
  readonly occurredAt: Date;
  readonly aggregateId: string;
  readonly aggregateType = 'Order';
  readonly eventType = 'OrderConfirmed';

  constructor(
    readonly orderId: OrderId,
    readonly customerId: CustomerId,
    readonly items: ReadonlyArray<{
      productId: string;
      quantity: number;
      unitPrice: number;
    }>,
    readonly totalAmount: number
  ) {
    this.eventId = crypto.randomUUID();
    this.occurredAt = new Date();
    this.aggregateId = orderId.value;
  }
}

// Aggregate에서 이벤트 발행
class Order extends AggregateRoot<OrderId> {
  confirm(): void {
    this.ensureCanConfirm();
    this._status = OrderStatus.CONFIRMED;
    
    // 도메인 이벤트 등록
    this.addDomainEvent(new OrderConfirmedEvent(
      this.id,
      this._customerId,
      this._items.map(item => ({
        productId: item.productId.value,
        quantity: item.quantity.value,
        unitPrice: item.unitPrice.amount
      })),
      this._totalAmount.amount
    ));
  }
}

// 이벤트 핸들러 인터페이스
interface EventHandler<T extends DomainEvent> {
  handle(event: T): Promise<void>;
}

// 재고 차감 핸들러
class ReserveInventoryHandler implements EventHandler<OrderConfirmedEvent> {
  constructor(private readonly inventoryRepository: InventoryRepository) {}

  async handle(event: OrderConfirmedEvent): Promise<void> {
    for (const item of event.items) {
      const inventory = await this.inventoryRepository.findByProductId(
        ProductId.from(item.productId)
      );
      
      inventory.reserve(Quantity.of(item.quantity));
      await this.inventoryRepository.save(inventory);
    }
  }
}

// 알림 발송 핸들러
class SendOrderConfirmationHandler implements EventHandler<OrderConfirmedEvent> {
  constructor(
    private readonly customerRepository: CustomerRepository,
    private readonly emailService: EmailService
  ) {}

  async handle(event: OrderConfirmedEvent): Promise<void> {
    const customer = await this.customerRepository.findById(
      CustomerId.from(event.customerId.value)
    );
    
    await this.emailService.send({
      to: customer.email.value,
      subject: '주문이 확정되었습니다',
      template: 'order-confirmed',
      data: { orderId: event.orderId.value, items: event.items }
    });
  }
}

// 이벤트 디스패처
class EventDispatcher {
  private handlers: Map<string, EventHandler<any>[]> = new Map();

  register<T extends DomainEvent>(
    eventType: string,
    handler: EventHandler<T>
  ): void {
    const existing = this.handlers.get(eventType) || [];
    this.handlers.set(eventType, [...existing, handler]);
  }

  async dispatch(event: DomainEvent): Promise<void> {
    const handlers = this.handlers.get(event.eventType) || [];
    
    await Promise.all(
      handlers.map(handler => handler.handle(event))
    );
  }
}

// 이벤트 중복 처리 방지
class IdempotentEventHandler<T extends DomainEvent> implements EventHandler<T> {
  constructor(
    private readonly inner: EventHandler<T>,
    private readonly processedEventRepository: ProcessedEventRepository
  ) {}

  async handle(event: T): Promise<void> {
    // 이미 처리된 이벤트인지 확인
    const alreadyProcessed = await this.processedEventRepository.exists(
      event.eventId
    );
    
    if (alreadyProcessed) {
      console.log(`Event ${event.eventId} already processed, skipping`);
      return;
    }

    // 이벤트 처리
    await this.inner.handle(event);

    // 처리 완료 기록
    await this.processedEventRepository.save({
      eventId: event.eventId,
      processedAt: new Date()
    });
  }
}

Saga는 여러 서비스에 걸친 비즈니스 트랜잭션을 이벤트로 조율하는 패턴입니다. 분산 트랜잭션 대신 보상 트랜잭션으로 일관성을 유지합니다.

// Choreography 기반 Saga (이벤트 체인)
// 주문 → 결제 → 재고 → 배송

// 1. 주문 서비스
class OrderService {
  async createOrder(command: CreateOrderCommand): Promise<void> {
    const order = Order.create(command);
    await this.orderRepository.save(order);
    // OrderCreated 이벤트 발행 → 결제 서비스가 구독
  }

  // 결제 실패 시 보상
  @OnEvent('PaymentFailed')
  async handlePaymentFailed(event: PaymentFailedEvent): Promise<void> {
    const order = await this.orderRepository.findById(event.orderId);
    order.cancel('결제 실패');
    await this.orderRepository.save(order);
  }
}

// 2. 결제 서비스
class PaymentService {
  @OnEvent('OrderCreated')
  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
    try {
      const payment = await this.processPayment(event);
      // PaymentCompleted 이벤트 발행 → 재고 서비스가 구독
    } catch (error) {
      // PaymentFailed 이벤트 발행 → 주문 서비스가 보상
    }
  }
}

// 3. 재고 서비스
class InventoryService {
  @OnEvent('PaymentCompleted')
  async handlePaymentCompleted(event: PaymentCompletedEvent): Promise<void> {
    try {
      await this.reserveInventory(event.items);
      // InventoryReserved 이벤트 발행
    } catch (error) {
      // InventoryReservationFailed 발행 → 결제 환불 트리거
    }
  }

  // 배송 실패 시 보상
  @OnEvent('ShipmentFailed')
  async handleShipmentFailed(event: ShipmentFailedEvent): Promise<void> {
    await this.releaseInventory(event.items);
  }
}

// 이벤트 버전 관리 전략
// 1. 하위 호환성 유지 (필드 추가만)
interface OrderCreatedEventV1 {
  orderId: string;
  customerId: string;
  items: OrderItem[];
  totalAmount: number;
}

interface OrderCreatedEventV2 extends OrderCreatedEventV1 {
  // 새 필드 추가 (선택적)
  couponCode?: string;
  discountAmount?: number;
}

// 2. 이벤트 업캐스터 (구버전 → 신버전 변환)
class OrderCreatedEventUpcaster {
  canUpcast(event: any): boolean {
    return event.eventType === 'OrderCreated' && !event.version;
  }

  upcast(event: OrderCreatedEventV1): OrderCreatedEventV2 {
    return {
      ...event,
      couponCode: undefined,
      discountAmount: 0
    };
  }
}

// 3. 이벤트 핸들러에서 버전 처리
class OrderCreatedHandler {
  async handle(event: OrderCreatedEventV1 | OrderCreatedEventV2): Promise<void> {
    const discountAmount = 'discountAmount' in event 
      ? event.discountAmount 
      : 0;
    
    // 버전에 관계없이 처리
  }
}

처리 실패한 이벤트를 별도 큐에 저장하여 나중에 분석하고 재처리합니다.

// DLQ 처리 전략
class EventConsumer {
  private readonly maxRetries = 3;

  async consume(event: DomainEvent): Promise<void> {
    let retryCount = 0;

    while (retryCount < this.maxRetries) {
      try {
        await this.handler.handle(event);
        return; // 성공
      } catch (error) {
        retryCount++;
        
        if (this.isRetryable(error) && retryCount < this.maxRetries) {
          await this.delay(this.calculateBackoff(retryCount));
          continue;
        }
        
        // 재시도 불가 또는 최대 재시도 초과
        await this.sendToDeadLetterQueue(event, error, retryCount);
        return;
      }
    }
  }

  private calculateBackoff(retryCount: number): number {
    // 지수 백오프: 1초, 2초, 4초...
    return Math.pow(2, retryCount - 1) * 1000;
  }

  private async sendToDeadLetterQueue(
    event: DomainEvent,
    error: Error,
    retryCount: number
  ): Promise<void> {
    await this.dlqRepository.save({
      eventId: event.eventId,
      eventType: event.eventType,
      payload: JSON.stringify(event),
      error: error.message,
      stackTrace: error.stack,
      retryCount,
      failedAt: new Date()
    });
    
    // 알림 발송
    await this.alertService.notify({
      type: 'DLQ_EVENT',
      message: `Event ${event.eventId} moved to DLQ after ${retryCount} retries`
    });
  }
}

┌─────────────────────────────────────────────────────────────────────────┐
│                        이커머스 이벤트 흐름                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  [고객]                                                                  │
│    │                                                                    │
│    ▼ CreateOrder                                                        │
│  ┌─────────────┐                                                        │
│  │ Order       │──OrderCreated──▶┌─────────────┐                        │
│  │ Context     │                 │ Payment     │                        │
│  │             │◀─PaymentFailed──│ Context     │                        │
│  │             │◀─PaymentCompleted│            │                        │
│  └─────────────┘                 └─────────────┘                        │
│        │                               │                                │
│        │ OrderConfirmed                │ PaymentCompleted               │
│        ▼                               ▼                                │
│  ┌─────────────┐                 ┌─────────────┐                        │
│  │ Inventory   │◀────────────────│ Shipping    │                        │
│  │ Context     │ ShipmentFailed  │ Context     │                        │
│  │             │──InventoryReserved──▶         │                        │
│  └─────────────┘                 └─────────────┘                        │
│        │                               │                                │
│        │                               │ ShipmentDelivered              │
│        ▼                               ▼                                │
│  ┌─────────────┐                 ┌─────────────┐                        │
│  │ Notification│◀────────────────│ Analytics   │                        │
│  │ Context     │                 │ Context     │                        │
│  └─────────────┘                 └─────────────┘                        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

// ===== Order Context Events =====
interface OrderCreatedEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  customerId: string;
  items: Array<{
    productId: string;
    productName: string;
    quantity: number;
    unitPrice: number;
  }>;
  shippingAddress: {
    street: string;
    city: string;
    zipCode: string;
  };
  totalAmount: number;
}

interface OrderConfirmedEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  confirmedAt: Date;
}

interface OrderCancelledEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  reason: string;
  cancelledBy: 'CUSTOMER' | 'SYSTEM' | 'ADMIN';
}

// ===== Payment Context Events =====
interface PaymentCompletedEvent {
  eventId: string;
  occurredAt: Date;
  paymentId: string;
  orderId: string;
  amount: number;
  method: 'CARD' | 'BANK_TRANSFER' | 'VIRTUAL_ACCOUNT';
  transactionId: string;
}

interface PaymentFailedEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  reason: string;
  errorCode: string;
}

interface PaymentRefundedEvent {
  eventId: string;
  occurredAt: Date;
  paymentId: string;
  orderId: string;
  refundAmount: number;
  reason: string;
}

// ===== Inventory Context Events =====
interface InventoryReservedEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  reservations: Array<{
    productId: string;
    quantity: number;
    warehouseId: string;
  }>;
}

interface InventoryReservationFailedEvent {
  eventId: string;
  occurredAt: Date;
  orderId: string;
  failedItems: Array<{
    productId: string;
    requestedQuantity: number;
    availableQuantity: number;
  }>;
}

// ===== Shipping Context Events =====
interface ShipmentCreatedEvent {
  eventId: string;
  occurredAt: Date;
  shipmentId: string;
  orderId: string;
  carrier: string;
  trackingNumber: string;
  estimatedDelivery: Date;
}

interface ShipmentDeliveredEvent {
  eventId: string;
  occurredAt: Date;
  shipmentId: string;
  orderId: string;
  deliveredAt: Date;
  receivedBy: string;
}

// Order Saga - Choreography 방식
class OrderSaga {
  // 상태 머신 정의
  private readonly stateMachine = {
    CREATED: {
      on: {
        PaymentCompleted: 'PAID',
        PaymentFailed: 'CANCELLED'
      }
    },
    PAID: {
      on: {
        InventoryReserved: 'INVENTORY_RESERVED',
        InventoryReservationFailed: 'REFUNDING'
      }
    },
    INVENTORY_RESERVED: {
      on: {
        ShipmentCreated: 'SHIPPED',
        ShipmentFailed: 'RELEASING_INVENTORY'
      }
    },
    SHIPPED: {
      on: {
        ShipmentDelivered: 'COMPLETED'
      }
    },
    // 보상 상태
    REFUNDING: {
      on: {
        PaymentRefunded: 'CANCELLED'
      }
    },
    RELEASING_INVENTORY: {
      on: {
        InventoryReleased: 'REFUNDING'
      }
    },
    CANCELLED: { final: true },
    COMPLETED: { final: true }
  };
}

// 각 Context의 이벤트 핸들러
class PaymentEventHandler {
  @OnEvent('OrderCreated')
  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
    try {
      const payment = await this.paymentService.processPayment({
        orderId: event.orderId,
        amount: event.totalAmount,
        customerId: event.customerId
      });
      
      await this.eventPublisher.publish(new PaymentCompletedEvent({
        paymentId: payment.id,
        orderId: event.orderId,
        amount: event.totalAmount,
        method: payment.method,
        transactionId: payment.transactionId
      }));
    } catch (error) {
      await this.eventPublisher.publish(new PaymentFailedEvent({
        orderId: event.orderId,
        reason: error.message,
        errorCode: error.code
      }));
    }
  }

  @OnEvent('InventoryReservationFailed')
  async handleInventoryFailed(event: InventoryReservationFailedEvent): Promise<void> {
    // 보상: 결제 환불
    const payment = await this.paymentRepository.findByOrderId(event.orderId);
    await this.paymentService.refund(payment.id, '재고 부족으로 인한 환불');
  }
}

class InventoryEventHandler {
  @OnEvent('PaymentCompleted')
  async handlePaymentCompleted(event: PaymentCompletedEvent): Promise<void> {
    const order = await this.orderQueryService.getOrder(event.orderId);
    
    try {
      const reservations = await this.inventoryService.reserve(order.items);
      
      await this.eventPublisher.publish(new InventoryReservedEvent({
        orderId: event.orderId,
        reservations
      }));
    } catch (error) {
      await this.eventPublisher.publish(new InventoryReservationFailedEvent({
        orderId: event.orderId,
        failedItems: error.failedItems
      }));
    }
  }

  @OnEvent('ShipmentFailed')
  async handleShipmentFailed(event: ShipmentFailedEvent): Promise<void> {
    // 보상: 재고 해제
    await this.inventoryService.release(event.orderId);
  }
}

// 이벤트 추적을 위한 Correlation ID
interface TrackedEvent extends DomainEvent {
  correlationId: string;  // 전체 흐름 추적
  causationId: string;    // 직접 원인 이벤트
}

// 이벤트 로그 저장
class EventLogger {
  async log(event: TrackedEvent): Promise<void> {
    await this.eventLogRepository.save({
      eventId: event.eventId,
      eventType: event.eventType,
      correlationId: event.correlationId,
      causationId: event.causationId,
      aggregateId: event.aggregateId,
      payload: JSON.stringify(event),
      occurredAt: event.occurredAt,
      context: this.getCurrentContext()
    });
  }
}

// Saga 상태 조회
class SagaMonitor {
  async getSagaStatus(orderId: string): Promise<SagaStatus> {
    const events = await this.eventLogRepository.findByCorrelationId(orderId);
    
    return {
      orderId,
      currentState: this.calculateCurrentState(events),
      timeline: events.map(e => ({
        eventType: e.eventType,
        occurredAt: e.occurredAt,
        context: e.context
      })),
      isCompleted: this.isTerminalState(events),
      hasFailed: this.hasFailureEvent(events)
    };
  }
}

// 대시보드 쿼리
class SagaDashboard {
  async getMetrics(timeRange: TimeRange): Promise<SagaMetrics> {
    return {
      totalSagas: await this.countSagas(timeRange),
      completedSagas: await this.countByState('COMPLETED', timeRange),
      failedSagas: await this.countByState('CANCELLED', timeRange),
      inProgressSagas: await this.countInProgress(timeRange),
      averageCompletionTime: await this.calculateAvgTime(timeRange),
      failureReasons: await this.groupFailureReasons(timeRange)
    };
  }
}