클린 아키텍처 완전 가이드: SOLID부터 헥사고날, DDD, 레이어드까지 — 시니어로 가는 설계 원칙

비용
  ^
  |           /  아키텍처 없음
  |          /
  |         /
  |        /
  |      /    ___--- 좋은 아키텍처
  |    /  ---
  |  / --
  | /--
  +-------------------> 시간

// BAD: User 클래스가 비즈니스 로직, 영속성, 알림을 모두 담당
class UserService {
  createUser(name: string, email: string) {
    // 검증 로직
    if (!email.includes('@')) throw new Error('Invalid email')

    // DB 저장 (영속성 관심사)
    const query = `INSERT INTO users (name, email) VALUES ('${name}', '${email}')`
    database.execute(query)

    // 이메일 발송 (알림 관심사)
    const mailClient = new SmtpClient()
    mailClient.send(email, 'Welcome!', 'Thanks for joining')

    // 로깅 (인프라 관심사)
    console.log(`User created: ${name}`)
  }
}

// GOOD: 각 클래스가 하나의 변경 이유만 가짐
class UserValidator {
  validate(name: string, email: string): void {
    if (!email.includes('@')) throw new Error('Invalid email')
    if (name.length < 2) throw new Error('Name too short')
  }
}

class UserRepository {
  save(user: User): Promise<User> {
    return this.db.users.create({ data: user })
  }
}

class WelcomeEmailSender {
  send(email: string): Promise<void> {
    return this.mailService.send({
      to: email,
      subject: 'Welcome!',
      body: 'Thanks for joining',
    })
  }
}

class CreateUserUseCase {
  constructor(
    private validator: UserValidator,
    private repository: UserRepository,
    private emailSender: WelcomeEmailSender
  ) {}

  async execute(name: string, email: string): Promise<User> {
    this.validator.validate(name, email)
    const user = await this.repository.save({ name, email })
    await this.emailSender.send(email)
    return user
  }
}

// BAD: 새 결제 수단마다 if문 추가 필요
class PaymentProcessor {
  process(payment: Payment) {
    if (payment.type === 'credit_card') {
      // 카드 결제 처리
      this.processCreditCard(payment)
    } else if (payment.type === 'paypal') {
      // 페이팔 결제 처리
      this.processPayPal(payment)
    } else if (payment.type === 'bitcoin') {
      // 새 결제 수단 추가할 때마다 기존 코드 수정!
      this.processBitcoin(payment)
    }
  }
}

// GOOD: 새 결제 수단 추가 시 기존 코드 수정 불필요
interface PaymentStrategy {
  process(payment: Payment): Promise<PaymentResult>
}

class CreditCardStrategy implements PaymentStrategy {
  async process(payment: Payment): Promise<PaymentResult> {
    // 카드 결제 처리
    return { success: true, transactionId: 'cc-123' }
  }
}

class PayPalStrategy implements PaymentStrategy {
  async process(payment: Payment): Promise<PaymentResult> {
    // 페이팔 결제 처리
    return { success: true, transactionId: 'pp-456' }
  }
}

// 새 결제 수단은 새 클래스만 추가하면 됨
class KakaoPayStrategy implements PaymentStrategy {
  async process(payment: Payment): Promise<PaymentResult> {
    return { success: true, transactionId: 'kp-789' }
  }
}

class PaymentProcessor {
  private strategies: Map<string, PaymentStrategy>

  constructor(strategies: Map<string, PaymentStrategy>) {
    this.strategies = strategies
  }

  async process(payment: Payment): Promise<PaymentResult> {
    const strategy = this.strategies.get(payment.type)
    if (!strategy) throw new Error(`Unknown payment type: ${payment.type}`)
    return strategy.process(payment)
  }
}

// BAD: Square가 Rectangle의 불변 조건을 위반
class Rectangle {
    protected int width;
    protected int height;

    public void setWidth(int w) { this.width = w; }
    public void setHeight(int h) { this.height = h; }
    public int getArea() { return width * height; }
}

class Square extends Rectangle {
    // LSP 위반: setWidth가 height도 변경
    @Override
    public void setWidth(int w) {
        this.width = w;
        this.height = w; // 부모와 다른 동작!
    }

    @Override
    public void setHeight(int h) {
        this.width = h;
        this.height = h;
    }
}

// 클라이언트 코드가 깨짐
void resize(Rectangle r) {
    r.setWidth(5);
    r.setHeight(10);
    assert r.getArea() == 50; // Square이면 실패! (100)
}

// GOOD: 공통 인터페이스로 설계
interface Shape {
    int getArea();
}

class Rectangle implements Shape {
    private final int width;
    private final int height;

    Rectangle(int width, int height) {
        this.width = width;
        this.height = height;
    }

    public int getArea() { return width * height; }
}

class Square implements Shape {
    private final int side;

    Square(int side) { this.side = side; }

    public int getArea() { return side * side; }
}

// BAD: 모든 기기가 모든 기능을 구현해야 함
interface SmartDevice {
  print(): void
  scan(): void
  fax(): void
  copyDocument(): void
}

// 프린터는 scan, fax를 구현할 수 없음
class SimplePrinter implements SmartDevice {
  print() {
    /* OK */
  }
  scan() {
    throw new Error('Not supported')
  } // 강제 구현
  fax() {
    throw new Error('Not supported')
  } // 강제 구현
  copyDocument() {
    throw new Error('Not supported')
  }
}

// GOOD: 역할별 분리된 인터페이스
interface Printer {
  print(): void
}

interface Scanner {
  scan(): void
}

interface FaxMachine {
  fax(): void
}

// 필요한 인터페이스만 구현
class SimplePrinter implements Printer {
  print() {
    /* 인쇄 처리 */
  }
}

class AllInOnePrinter implements Printer, Scanner, FaxMachine {
  print() {
    /* 인쇄 */
  }
  scan() {
    /* 스캔 */
  }
  fax() {
    /* 팩스 */
  }
}

// BAD: 비즈니스 로직이 구체적 구현에 의존
class OrderService {
  private mysqlDb = new MySQLDatabase() // 구체 클래스에 의존
  private smtpMail = new SmtpEmailClient() // 구체 클래스에 의존

  createOrder(order: Order) {
    this.mysqlDb.insert('orders', order)
    this.smtpMail.send(order.userEmail, 'Order confirmed')
  }
}
// MySQL을 PostgreSQL로 바꾸려면 OrderService 수정 필요!

// GOOD: 인터페이스(추상화)에 의존
interface OrderRepository {
  save(order: Order): Promise<Order>
}

interface NotificationService {
  notify(userId: string, message: string): Promise<void>
}

class OrderService {
  constructor(
    private repository: OrderRepository, // 추상화에 의존
    private notification: NotificationService // 추상화에 의존
  ) {}

  async createOrder(order: Order): Promise<Order> {
    const saved = await this.repository.save(order)
    await this.notification.notify(order.userId, 'Order confirmed')
    return saved
  }
}

// 인프라 계층에서 구현
class PostgresOrderRepository implements OrderRepository {
  async save(order: Order): Promise<Order> {
    return this.prisma.order.create({ data: order })
  }
}

class SlackNotificationService implements NotificationService {
  async notify(userId: string, message: string): Promise<void> {
    await this.slackClient.postMessage({ channel: userId, text: message })
  }
}

┌─────────────────────────────┐
│     Presentation Layer      │  ← Controller, View
├─────────────────────────────┤
│     Application Layer       │  ← Service, DTO
├─────────────────────────────┤
│       Domain Layer          │  ← Entity, Business Logic
├─────────────────────────────┤
│    Infrastructure Layer     │  ← Repository, External API
└─────────────────────────────┘

의존성 방향: 위 → 아래 (Presentation → Infrastructure)

src/main/java/com/example/shop/
  controller/
    OrderController.java
  service/
    OrderService.java
  domain/
    Order.java
    OrderItem.java
  repository/
    OrderRepository.java
    JpaOrderRepository.java
  dto/
    CreateOrderRequest.java
    OrderResponse.java

// Presentation Layer
@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(
            @RequestBody CreateOrderRequest request) {
        OrderResponse response = orderService.createOrder(request);
        return ResponseEntity.status(201).body(response);
    }
}

// Application Layer
@Service
@Transactional
public class OrderService {

    private final OrderRepository orderRepository;
    private final ProductRepository productRepository;

    public OrderResponse createOrder(CreateOrderRequest request) {
        Product product = productRepository.findById(request.getProductId())
            .orElseThrow(() -> new NotFoundException("Product not found"));

        Order order = Order.create(
            request.getUserId(),
            product,
            request.getQuantity()
        );

        Order saved = orderRepository.save(order);
        return OrderResponse.from(saved);
    }
}

// Domain Layer
@Entity
public class Order {
    @Id @GeneratedValue
    private Long id;
    private String userId;
    private BigDecimal totalAmount;
    private OrderStatus status;

    public static Order create(String userId, Product product, int quantity) {
        Order order = new Order();
        order.userId = userId;
        order.totalAmount = product.getPrice().multiply(BigDecimal.valueOf(quantity));
        order.status = OrderStatus.CREATED;
        return order;
    }

    public void cancel() {
        if (this.status != OrderStatus.CREATED) {
            throw new IllegalStateException("Only CREATED orders can be cancelled");
        }
        this.status = OrderStatus.CANCELLED;
    }
}

┌─────────────────────────────────────────────────┐
│  Frameworks & Drivers (Web, DB, External)       │
│  ┌─────────────────────────────────────────┐    │
│  │  Interface Adapters (Controllers, GW)   │    │
│  │  ┌─────────────────────────────────┐    │    │
│  │  │  Application (Use Cases)        │    │    │
│  │  │  ┌─────────────────────────┐    │    │    │
│  │  │  │     Entities            │    │    │    │
│  │  │  │   (Domain Models)       │    │    │    │
│  │  │  └─────────────────────────┘    │    │    │
│  │  └─────────────────────────────────┘    │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

의존성 방향: 바깥 → 안쪽 (Frameworks → Entities)

// Entities - 어떤 프레임워크에도 의존하지 않음
class Order {
  private items: OrderItem[] = []
  private status: OrderStatus = 'CREATED'

  addItem(product: Product, quantity: number): void {
    if (quantity <= 0) throw new Error('Quantity must be positive')
    if (this.status !== 'CREATED') throw new Error('Cannot modify confirmed order')
    this.items.push(new OrderItem(product, quantity))
  }

  get totalAmount(): Money {
    return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero('KRW'))
  }

  confirm(): void {
    if (this.items.length === 0) throw new Error('Cannot confirm empty order')
    this.status = 'CONFIRMED'
  }
}

// Use Cases
interface OrderRepository {
  save(order: Order): Promise<Order>
  findById(id: string): Promise<Order | null>
}

interface PaymentGateway {
  charge(amount: Money, paymentMethod: PaymentMethod): Promise<PaymentResult>
}

class CreateOrderUseCase {
  constructor(
    private orderRepo: OrderRepository,
    private paymentGateway: PaymentGateway,
    private eventPublisher: DomainEventPublisher
  ) {}

  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
    const order = new Order(input.userId)

    for (const item of input.items) {
      order.addItem(item.product, item.quantity)
    }

    order.confirm()

    const paymentResult = await this.paymentGateway.charge(order.totalAmount, input.paymentMethod)

    if (!paymentResult.success) {
      throw new PaymentFailedError(paymentResult.reason)
    }

    const saved = await this.orderRepo.save(order)
    await this.eventPublisher.publish(new OrderCreatedEvent(saved.id))

    return { orderId: saved.id, totalAmount: order.totalAmount.toString() }
  }
}

// Interface Adapter - Controller
class OrderController {
  constructor(private createOrderUseCase: CreateOrderUseCase) {}

  async handleCreateOrder(req: HttpRequest): Promise<HttpResponse> {
    try {
      const input = this.mapToInput(req.body)
      const output = await this.createOrderUseCase.execute(input)
      return { status: 201, body: output }
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        return { status: 402, body: { error: error.message } }
      }
      return { status: 500, body: { error: 'Internal server error' } }
    }
  }

  private mapToInput(body: any): CreateOrderInput {
    return {
      userId: body.userId,
      items: body.items,
      paymentMethod: body.paymentMethod,
    }
  }
}

src/main/java/com/example/shop/
  domain/                    # Entities
    model/
      Order.java
      OrderItem.java
      Money.java
    event/
      OrderCreatedEvent.java
  application/               # Use Cases
    port/
      in/
        CreateOrderUseCase.java
      out/
        OrderRepository.java
        PaymentGateway.java
    service/
      OrderApplicationService.java
  adapter/                   # Interface Adapters + Frameworks
    in/
      web/
        OrderController.java
        CreateOrderRequest.java
    out/
      persistence/
        JpaOrderRepository.java
        OrderJpaEntity.java
      payment/
        StripePaymentGateway.java
  config/
    BeanConfiguration.java

src/
  domain/
    entities/
      order.entity.ts
      order-item.entity.ts
      money.value-object.ts
    events/
      order-created.event.ts
  application/
    ports/
      order.repository.port.ts
      payment.gateway.port.ts
    use-cases/
      create-order.use-case.ts
      cancel-order.use-case.ts
  infrastructure/
    adapters/
      in/
        http/
          order.controller.ts
          dto/
            create-order.dto.ts
      out/
        persistence/
          prisma-order.repository.ts
        payment/
          stripe-payment.gateway.ts
    config/
      module.config.ts

// domain 계층 - 외부 의존성 ZERO
// Order.ts에 import 문을 보면:
// - express 없음
// - prisma 없음
// - typeorm 없음
// 순수 TypeScript/Java 코드만 존재

class Order {
  // 순수 비즈니스 로직만 포함
  // DB가 MySQL이든 MongoDB든 상관없음
  // 웹 프레임워크가 Express든 Fastify든 상관없음
}

              ┌──────────┐
     HTTP ──▶ │          │ ──▶ PostgreSQL
              │   Port   │
     CLI ──▶  │    &     │ ──▶ Redis
              │  Domain  │
   gRPC ──▶  │   Core   │ ──▶ Kafka
              │          │
    Test ──▶  │          │ ──▶ Mock DB
              └──────────┘

  [Driving Adapters]  [Core]  [Driven Adapters]
    (입력 측)        (비즈니스)    (출력 측)

// ===== PORTS (인터페이스 정의) =====

// Driving Port (인바운드) - 외부가 애플리케이션을 호출
interface CreateOrderPort {
  createOrder(command: CreateOrderCommand): Promise<OrderId>
}

interface CancelOrderPort {
  cancelOrder(orderId: string): Promise<void>
}

// Driven Port (아웃바운드) - 애플리케이션이 외부를 호출
interface LoadOrderPort {
  findById(id: string): Promise<Order | null>
}

interface SaveOrderPort {
  save(order: Order): Promise<Order>
}

interface SendNotificationPort {
  sendOrderConfirmation(order: Order): Promise<void>
}

// ===== DOMAIN CORE (핵심 비즈니스 로직) =====

class Order {
  private readonly id: string
  private items: OrderItem[] = []
  private status: OrderStatus = 'PENDING'

  constructor(
    id: string,
    private readonly customerId: string
  ) {
    this.id = id
  }

  addItem(productId: string, price: Money, quantity: number): void {
    this.ensureModifiable()
    this.items.push(new OrderItem(productId, price, quantity))
  }

  confirm(): void {
    if (this.items.length === 0) {
      throw new DomainError('Cannot confirm empty order')
    }
    this.status = 'CONFIRMED'
  }

  cancel(): void {
    if (this.status === 'SHIPPED') {
      throw new DomainError('Cannot cancel shipped order')
    }
    this.status = 'CANCELLED'
  }

  private ensureModifiable(): void {
    if (this.status !== 'PENDING') {
      throw new DomainError('Order is not modifiable')
    }
  }

  get totalAmount(): Money {
    return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero('KRW'))
  }
}

// ===== APPLICATION SERVICE (유스케이스 구현) =====

class OrderService implements CreateOrderPort, CancelOrderPort {
  constructor(
    private readonly loadOrder: LoadOrderPort,
    private readonly saveOrder: SaveOrderPort,
    private readonly notification: SendNotificationPort
  ) {}

  async createOrder(command: CreateOrderCommand): Promise<OrderId> {
    const order = new Order(generateId(), command.customerId)

    for (const item of command.items) {
      order.addItem(item.productId, new Money(item.price, 'KRW'), item.quantity)
    }

    order.confirm()
    const saved = await this.saveOrder.save(order)
    await this.notification.sendOrderConfirmation(saved)

    return saved.id
  }

  async cancelOrder(orderId: string): Promise<void> {
    const order = await this.loadOrder.findById(orderId)
    if (!order) throw new NotFoundError('Order not found')

    order.cancel()
    await this.saveOrder.save(order)
  }
}

// ===== ADAPTERS (구체적 구현) =====

// Driving Adapter - REST Controller
class OrderRestController {
  constructor(private createOrderPort: CreateOrderPort) {}

  async handlePost(req: Request, res: Response): Promise<void> {
    const command: CreateOrderCommand = {
      customerId: req.body.customerId,
      items: req.body.items,
    }
    const orderId = await this.createOrderPort.createOrder(command)
    res.status(201).json({ orderId })
  }
}

// Driven Adapter - Database
class PostgresOrderAdapter implements LoadOrderPort, SaveOrderPort {
  constructor(private prisma: PrismaClient) {}

  async findById(id: string): Promise<Order | null> {
    const data = await this.prisma.order.findUnique({
      where: { id },
      include: { items: true },
    })
    return data ? this.toDomain(data) : null
  }

  async save(order: Order): Promise<Order> {
    await this.prisma.order.upsert({
      where: { id: order.id },
      create: this.toPersistence(order),
      update: this.toPersistence(order),
    })
    return order
  }

  private toDomain(data: PrismaOrder): Order {
    /* 매핑 */
  }
  private toPersistence(order: Order): PrismaOrderData {
    /* 매핑 */
  }
}

// Driven Adapter - Notification
class EmailNotificationAdapter implements SendNotificationPort {
  constructor(private mailer: MailClient) {}

  async sendOrderConfirmation(order: Order): Promise<void> {
    await this.mailer.send({
      to: order.customerEmail,
      subject: 'Order Confirmed',
      body: `Your order #${order.id} has been confirmed.`,
    })
  }
}

비즈니스: "고객이 주문을 생성하고, 결제가 승인되면 주문이 확정된다"
코드:     customer.createOrder() → payment.approve() → order.confirm()

비즈니스: "배송이 시작되면 주문을 취소할 수 없다"
코드:     order.cancel() → if (status === 'SHIPPED') throw Error

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Order Context   │  │ Payment Context  │  │ Shipping Context │
│                  │  │                  │  │                  │
│  Order           │  │  Payment         │  │  Shipment        │
│  OrderItem       │  │  Transaction     │  │  Package         │
│  Customer (id,   │  │  Customer (id,   │  │  Customer (id,   │
│   name, email)   │  │   paymentMethod) │  │   address)       │
│                  │  │                  │  │                  │
│  "Customer"는    │  │  "Customer"는    │  │  "Customer"는    │
│  주문자 정보     │  │  결제자 정보     │  │  수령인 정보     │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
         └───── Context Map (컨텍스트 매핑) ───────┘

public class Order {
    private final OrderId id;  // 고유 식별자
    private OrderStatus status;
    private List<OrderItem> items;
    private Money totalAmount;

    // 비즈니스 로직이 엔티티 안에 존재 (Rich Domain Model)
    public void addItem(Product product, int quantity) {
        validateModifiable();
        OrderItem item = new OrderItem(product, quantity);
        this.items.add(item);
        recalculateTotal();
    }

    public void confirm() {
        if (items.isEmpty()) {
            throw new OrderEmptyException("Cannot confirm empty order");
        }
        this.status = OrderStatus.CONFIRMED;
        registerEvent(new OrderConfirmedEvent(this.id));
    }

    // equals/hashCode는 id 기반
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Order)) return false;
        return id.equals(((Order) o).id);
    }
}

public record Money(BigDecimal amount, Currency currency) {

    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount cannot be negative");
        }
        Objects.requireNonNull(currency);
    }

    public Money add(Money other) {
        validateSameCurrency(other);
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public Money multiply(int quantity) {
        return new Money(this.amount.multiply(BigDecimal.valueOf(quantity)), this.currency);
    }

    public static Money zero(Currency currency) {
        return new Money(BigDecimal.ZERO, currency);
    }

    private void validateSameCurrency(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchException(
                "Cannot operate on different currencies"
            );
        }
    }
}

// 사용 예시
Money price = new Money(BigDecimal.valueOf(15000), Currency.KRW);
Money total = price.multiply(3);  // 45000 KRW

// Order가 Aggregate Root
// OrderItem은 Order를 통해서만 접근/수정 가능
public class Order {  // Aggregate Root
    private final OrderId id;
    private final CustomerId customerId;
    private List<OrderItem> items = new ArrayList<>();  // 내부 엔티티
    private ShippingAddress address;  // 값 객체
    private Money totalAmount;        // 값 객체

    // 외부에서 OrderItem을 직접 생성/수정 불가
    // 반드시 Order를 통해서만 조작
    public void addItem(ProductId productId, Money price, int qty) {
        OrderItem item = new OrderItem(productId, price, qty);
        this.items.add(item);
        recalculateTotal();
    }

    public void removeItem(ProductId productId) {
        this.items.removeIf(item -> item.getProductId().equals(productId));
        recalculateTotal();
    }
}

public record OrderConfirmedEvent(
    OrderId orderId,
    CustomerId customerId,
    Money totalAmount,
    Instant occurredAt
) implements DomainEvent {

    public OrderConfirmedEvent(OrderId orderId, CustomerId customerId, Money totalAmount) {
        this(orderId, customerId, totalAmount, Instant.now());
    }
}

// Aggregate Root에서 이벤트 등록
public class Order extends AbstractAggregateRoot<Order> {

    public void confirm() {
        this.status = OrderStatus.CONFIRMED;
        registerEvent(new OrderConfirmedEvent(this.id, this.customerId, this.totalAmount));
    }
}

// 이벤트 핸들러
@Component
public class OrderConfirmedEventHandler {

    @EventListener
    public void handleOrderConfirmed(OrderConfirmedEvent event) {
        // 결제 처리 트리거
        // 재고 차감 트리거
        // 확인 이메일 발송
    }
}

// Domain 계층에 인터페이스 정의
public interface OrderRepository {
    Order findById(OrderId id);
    OrderId save(Order order);
    void delete(Order order);
    List<Order> findByCustomerId(CustomerId customerId);
}

// Infrastructure 계층에서 구현
@Repository
public class JpaOrderRepository implements OrderRepository {

    private final SpringDataOrderRepository springDataRepo;
    private final OrderMapper mapper;

    @Override
    public Order findById(OrderId id) {
        return springDataRepo.findById(id.getValue())
            .map(mapper::toDomain)
            .orElseThrow(() -> new OrderNotFoundException(id));
    }

    @Override
    public OrderId save(Order order) {
        OrderJpaEntity entity = mapper.toJpaEntity(order);
        OrderJpaEntity saved = springDataRepo.save(entity);
        return new OrderId(saved.getId());
    }
}

1. Domain Events (주황색 포스트잇) - 과거형으로 작성
   "주문이 생성되었다" "결제가 승인되었다" "상품이 배송되었다"

2. Commands (파란색 포스트잇) - 이벤트를 발생시키는 행위
   "주문 생성" "결제 승인" "배송 시작"

3. Aggregates (노란색 포스트잇) - 커맨드를 처리하는 주체
   "Order" "Payment" "Shipment"

4. Bounded Contexts 발견 - 관련 있는 것들을 그룹핑
   Order Context | Payment Context | Shipping Context

src/
  order/                          # Bounded Context
    domain/                       # 헥사고날의 Core
      model/
        Order.java                # Aggregate Root (Entity)
        OrderItem.java            # Entity
        Money.java                # Value Object
        OrderStatus.java          # Value Object (Enum)
      event/
        OrderConfirmedEvent.java  # Domain Event
      service/
        OrderDomainService.java   # Domain Service
    application/                  # 헥사고날의 Port 정의 + Use Case
      port/
        in/
          CreateOrderUseCase.java    # Driving Port
          CancelOrderUseCase.java
        out/
          LoadOrderPort.java         # Driven Port
          SaveOrderPort.java
          PaymentPort.java
      service/
        OrderApplicationService.java # Use Case 구현
    infrastructure/               # 헥사고날의 Adapter
      adapter/
        in/
          web/
            OrderController.java     # Driving Adapter
          messaging/
            OrderEventListener.java
        out/
          persistence/
            JpaOrderRepository.java  # Driven Adapter
            OrderJpaEntity.java
          payment/
            StripePaymentAdapter.java

비즈니스 로직 복잡도
  ^
  │  DDD + Hexagonal
  │  ┌──────────────┐
  │  │              │
  │  │  Sweet Spot  │
  │  │              │
  │  └──────────────┘
  │     Clean Architecture
  │  ┌──────────────┐
  │  │              │
  │  └──────────────┘
  │     Layered
  │  ┌──────────────┐
  │  └──────────────┘
  └──────────────────────> 프로젝트 규모/팀 크기

프로젝트 시작
  │
  ├─ 비즈니스 로직이 단순한가? ──YES──▶ 레이어드 아키텍처
  │
  NO
  │
  ├─ 외부 시스템 통합이 많은가? ──YES──▶ 헥사고날 아키텍처
  │
  NO
  │
  ├─ 도메인 전문가와 협업 가능? ──YES──┐
  │                                    │
  NO                                   ▼
  │                          비즈니스 로직이 매우 복잡?
  │                              │           │
  │                             YES          NO
  │                              │           │
  │                              ▼           ▼
  │                         DDD + Hexagonal  클린 아키텍처
  │
  └──▶ 클린 아키텍처 (안전한 기본 선택)

public record Money(BigDecimal amount, String currency) {

    public Money {
        Objects.requireNonNull(amount, "Amount must not be null");
        Objects.requireNonNull(currency, "Currency must not be null");
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount cannot be negative");
        }
    }

    public static Money of(long amount, String currency) {
        return new Money(BigDecimal.valueOf(amount), currency);
    }

    public static Money zero(String currency) {
        return new Money(BigDecimal.ZERO, currency);
    }

    public Money add(Money other) {
        assertSameCurrency(other);
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public Money multiply(int quantity) {
        return new Money(this.amount.multiply(BigDecimal.valueOf(quantity)), this.currency);
    }

    public boolean isGreaterThan(Money other) {
        assertSameCurrency(other);
        return this.amount.compareTo(other.amount) > 0;
    }

    private void assertSameCurrency(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException(
                "Currency mismatch: " + this.currency + " vs " + other.currency
            );
        }
    }
}

public class OrderItem {
    private final String productId;
    private final String productName;
    private final Money unitPrice;
    private int quantity;

    public OrderItem(String productId, String productName, Money unitPrice, int quantity) {
        if (quantity <= 0) throw new IllegalArgumentException("Quantity must be positive");
        this.productId = productId;
        this.productName = productName;
        this.unitPrice = unitPrice;
        this.quantity = quantity;
    }

    public Money getSubtotal() {
        return unitPrice.multiply(quantity);
    }

    public void changeQuantity(int newQuantity) {
        if (newQuantity <= 0) throw new IllegalArgumentException("Quantity must be positive");
        this.quantity = newQuantity;
    }
}

public class Order {
    private final String id;
    private final String customerId;
    private final List<OrderItem> items = new ArrayList<>();
    private OrderStatus status;
    private Money totalAmount;
    private final Instant createdAt;
    private final List<DomainEvent> domainEvents = new ArrayList<>();

    public Order(String id, String customerId) {
        this.id = id;
        this.customerId = customerId;
        this.status = OrderStatus.PENDING;
        this.totalAmount = Money.zero("KRW");
        this.createdAt = Instant.now();
    }

    public void addItem(String productId, String productName, Money price, int quantity) {
        ensureModifiable();
        this.items.add(new OrderItem(productId, productName, price, quantity));
        recalculateTotal();
    }

    public void confirm() {
        if (items.isEmpty()) {
            throw new OrderDomainException("Cannot confirm empty order");
        }
        if (status != OrderStatus.PENDING) {
            throw new OrderDomainException("Only pending orders can be confirmed");
        }
        this.status = OrderStatus.CONFIRMED;
        domainEvents.add(new OrderConfirmedEvent(this.id, this.customerId, this.totalAmount));
    }

    public void cancel() {
        if (status == OrderStatus.SHIPPED || status == OrderStatus.DELIVERED) {
            throw new OrderDomainException("Cannot cancel order in status: " + status);
        }
        this.status = OrderStatus.CANCELLED;
        domainEvents.add(new OrderCancelledEvent(this.id, this.customerId));
    }

    public void markAsShipped(String trackingNumber) {
        if (status != OrderStatus.CONFIRMED) {
            throw new OrderDomainException("Only confirmed orders can be shipped");
        }
        this.status = OrderStatus.SHIPPED;
        domainEvents.add(new OrderShippedEvent(this.id, trackingNumber));
    }

    private void ensureModifiable() {
        if (status != OrderStatus.PENDING) {
            throw new OrderDomainException("Order is not modifiable");
        }
    }

    private void recalculateTotal() {
        this.totalAmount = items.stream()
            .map(OrderItem::getSubtotal)
            .reduce(Money.zero("KRW"), Money::add);
    }

    public List<DomainEvent> getDomainEvents() {
        return Collections.unmodifiableList(domainEvents);
    }

    public void clearDomainEvents() {
        domainEvents.clear();
    }
}

// Driving Port
public interface CreateOrderUseCase {
    CreateOrderResult execute(CreateOrderCommand command);
}

public record CreateOrderCommand(
    String customerId,
    List<OrderItemCommand> items
) {}

public record OrderItemCommand(
    String productId,
    String productName,
    long price,
    int quantity
) {}

// Driven Ports
public interface OrderRepository {
    Optional<Order> findById(String id);
    Order save(Order order);
}

public interface EventPublisher {
    void publish(List<DomainEvent> events);
}

// Use Case 구현
@Service
@Transactional
public class CreateOrderService implements CreateOrderUseCase {

    private final OrderRepository orderRepository;
    private final EventPublisher eventPublisher;
    private final IdGenerator idGenerator;

    public CreateOrderService(
            OrderRepository orderRepository,
            EventPublisher eventPublisher,
            IdGenerator idGenerator) {
        this.orderRepository = orderRepository;
        this.eventPublisher = eventPublisher;
        this.idGenerator = idGenerator;
    }

    @Override
    public CreateOrderResult execute(CreateOrderCommand command) {
        Order order = new Order(idGenerator.generate(), command.customerId());

        for (OrderItemCommand item : command.items()) {
            order.addItem(
                item.productId(),
                item.productName(),
                Money.of(item.price(), "KRW"),
                item.quantity()
            );
        }

        order.confirm();
        Order saved = orderRepository.save(order);
        eventPublisher.publish(saved.getDomainEvents());
        saved.clearDomainEvents();

        return new CreateOrderResult(saved.getId(), saved.getTotalAmount().toString());
    }
}

// CancelOrderUseCase
public interface CancelOrderUseCase {
    void execute(String orderId);
}

@Service
@Transactional
public class CancelOrderService implements CancelOrderUseCase {

    private final OrderRepository orderRepository;
    private final EventPublisher eventPublisher;

    @Override
    public void execute(String orderId) {
        Order order = orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));

        order.cancel();
        orderRepository.save(order);
        eventPublisher.publish(order.getDomainEvents());
        order.clearDomainEvents();
    }
}

// Driven Adapter - JPA Repository
@Repository
public class JpaOrderRepositoryAdapter implements OrderRepository {

    private final SpringDataOrderRepository jpaRepo;
    private final OrderPersistenceMapper mapper;

    @Override
    public Optional<Order> findById(String id) {
        return jpaRepo.findById(id).map(mapper::toDomain);
    }

    @Override
    public Order save(Order order) {
        OrderJpaEntity entity = mapper.toJpaEntity(order);
        OrderJpaEntity saved = jpaRepo.save(entity);
        return mapper.toDomain(saved);
    }
}

// Driven Adapter - Kafka Event Publisher
@Component
public class KafkaEventPublisher implements EventPublisher {

    private final KafkaTemplate<String, String> kafkaTemplate;
    private final ObjectMapper objectMapper;

    @Override
    public void publish(List<DomainEvent> events) {
        for (DomainEvent event : events) {
            String topic = resolveTopic(event);
            String payload = serialize(event);
            kafkaTemplate.send(topic, event.getAggregateId(), payload);
        }
    }

    private String resolveTopic(DomainEvent event) {
        if (event instanceof OrderConfirmedEvent) return "order.confirmed";
        if (event instanceof OrderCancelledEvent) return "order.cancelled";
        if (event instanceof OrderShippedEvent) return "order.shipped";
        return "order.unknown";
    }

    private String serialize(DomainEvent event) {
        try {
            return objectMapper.writeValueAsString(event);
        } catch (Exception e) {
            throw new EventPublishException("Failed to serialize event", e);
        }
    }
}

// Driving Adapter - REST Controller
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    private final CreateOrderUseCase createOrderUseCase;
    private final CancelOrderUseCase cancelOrderUseCase;

    @PostMapping
    public ResponseEntity<CreateOrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        CreateOrderCommand command = request.toCommand();
        CreateOrderResult result = createOrderUseCase.execute(command);
        return ResponseEntity.status(201).body(CreateOrderResponse.from(result));
    }

    @DeleteMapping("/{orderId}")
    public ResponseEntity<Void> cancelOrder(@PathVariable String orderId) {
        cancelOrderUseCase.execute(orderId);
        return ResponseEntity.noContent().build();
    }
}

class OrderTest {

    @Test
    void shouldCalculateTotalAmount() {
        Order order = new Order("order-1", "customer-1");
        order.addItem("prod-1", "Keyboard", Money.of(50000, "KRW"), 2);
        order.addItem("prod-2", "Mouse", Money.of(30000, "KRW"), 1);

        assertEquals(Money.of(130000, "KRW"), order.getTotalAmount());
    }

    @Test
    void shouldNotConfirmEmptyOrder() {
        Order order = new Order("order-1", "customer-1");

        assertThrows(OrderDomainException.class, () -> order.confirm());
    }

    @Test
    void shouldNotCancelShippedOrder() {
        Order order = createConfirmedOrder();
        order.markAsShipped("TRACK-123");

        assertThrows(OrderDomainException.class, () -> order.cancel());
    }

    @Test
    void shouldRegisterDomainEventOnConfirm() {
        Order order = new Order("order-1", "customer-1");
        order.addItem("prod-1", "Keyboard", Money.of(50000, "KRW"), 1);
        order.confirm();

        List<DomainEvent> events = order.getDomainEvents();
        assertEquals(1, events.size());
        assertInstanceOf(OrderConfirmedEvent.class, events.get(0));
    }
}

class MoneyTest {

    @Test
    void shouldAddSameCurrency() {
        Money a = Money.of(1000, "KRW");
        Money b = Money.of(2000, "KRW");

        assertEquals(Money.of(3000, "KRW"), a.add(b));
    }

    @Test
    void shouldRejectDifferentCurrency() {
        Money krw = Money.of(1000, "KRW");
        Money usd = Money.of(1, "USD");

        assertThrows(IllegalArgumentException.class, () -> krw.add(usd));
    }

    @Test
    void shouldRejectNegativeAmount() {
        assertThrows(IllegalArgumentException.class,
            () -> new Money(BigDecimal.valueOf(-1), "KRW"));
    }
}

class CreateOrderServiceTest {

    private CreateOrderService sut;
    private OrderRepository fakeRepository;
    private EventPublisher fakePublisher;

    @BeforeEach
    void setUp() {
        fakeRepository = new InMemoryOrderRepository();
        fakePublisher = new FakeEventPublisher();
        sut = new CreateOrderService(fakeRepository, fakePublisher, new UuidIdGenerator());
    }

    @Test
    void shouldCreateAndConfirmOrder() {
        CreateOrderCommand command = new CreateOrderCommand(
            "customer-1",
            List.of(new OrderItemCommand("prod-1", "Keyboard", 50000, 2))
        );

        CreateOrderResult result = sut.execute(command);

        assertNotNull(result.orderId());
        Order saved = fakeRepository.findById(result.orderId()).orElseThrow();
        assertEquals(OrderStatus.CONFIRMED, saved.getStatus());
    }
}

// 테스트용 In-Memory Repository
class InMemoryOrderRepository implements OrderRepository {
    private final Map<String, Order> store = new HashMap<>();

    @Override
    public Optional<Order> findById(String id) {
        return Optional.ofNullable(store.get(id));
    }

    @Override
    public Order save(Order order) {
        store.put(order.getId(), order);
        return order;
    }
}

class ArchitectureTest {

    private final JavaClasses classes = new ClassFileImporter()
        .importPackages("com.example.shop");

    @Test
    void domainShouldNotDependOnInfrastructure() {
        noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAPackage("..infrastructure..")
            .check(classes);
    }

    @Test
    void domainShouldNotDependOnApplication() {
        noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAPackage("..application..")
            .check(classes);
    }

    @Test
    void domainShouldNotUseSpringAnnotations() {
        noClasses()
            .that().resideInAPackage("..domain..")
            .should().beAnnotatedWith("org.springframework.stereotype.Service")
            .orShould().beAnnotatedWith("org.springframework.stereotype.Component")
            .check(classes);
    }

    @Test
    void useCasesShouldOnlyBeAccessedByAdapters() {
        classes()
            .that().resideInAPackage("..application.service..")
            .should().onlyBeAccessed().byClassesThat()
            .resideInAnyPackage("..adapter..", "..config..", "..application..")
            .check(classes);
    }
}

          /  E2E Tests  \          ← 적게, 느림, 비쌈
         / (Cypress, etc) \
        /─────────────────\
       / Integration Tests \       ← 중간
      /  (Adapter Tests)    \
     /───────────────────────\
    /     Unit Tests          \    ← 많이, 빠름, 저렴
   /  (Domain + Use Case)     \
  /────────────────────────────\

// BAD: User의 이름을 바꾸는데 7개 파일이 필요?
// Command -> CommandHandler -> UseCase -> DomainService
// -> Repository -> Adapter -> Mapper
// 단순 업데이트에는 과도함!

// GOOD: 복잡도에 맞는 아키텍처 선택
// 간단한 CRUD = 레이어드 + 서비스 패턴으로 충분

// BAD: Anemic Domain Model
class Order {
    private String status;
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
}

class OrderService {
    void cancelOrder(Order order) {
        // 비즈니스 로직이 서비스에 존재
        if (order.getStatus().equals("SHIPPED")) {
            throw new Exception("Cannot cancel");
        }
        order.setStatus("CANCELLED");
    }
}

// GOOD: Rich Domain Model
class Order {
    private OrderStatus status;

    public void cancel() {
        // 비즈니스 로직이 엔티티 안에 존재
        if (this.status == OrderStatus.SHIPPED) {
            throw new OrderDomainException("Cannot cancel shipped order");
        }
        this.status = OrderStatus.CANCELLED;
    }
}

// BAD: 하나의 서비스가 모든 것을 처리
class OrderGodService {
    void createOrder() { /* ... */ }
    void cancelOrder() { /* ... */ }
    void processPayment() { /* ... */ }
    void sendNotification() { /* ... */ }
    void generateInvoice() { /* ... */ }
    void updateInventory() { /* ... */ }
    void calculateShipping() { /* ... */ }
    // ... 수천 줄의 메서드
}

// GOOD: 책임별 분리
class CreateOrderUseCase { /* 주문 생성만 */ }
class CancelOrderUseCase { /* 주문 취소만 */ }
class PaymentService { /* 결제만 */ }
class NotificationService { /* 알림만 */ }