Split View: Clean Architecture & Hexagonal 아키텍처 완전 가이드 2025: 의존성 역전, Ports & Adapters

Big Ball of Mud → Layered → Hexagonal → Onion → Clean → Modular
    (혼돈)       (계층화)    (포트/어댑터) (양파)   (깨끗)   (모듈화)
    1990s         2000s       2005        2008    2012     2020s

┌─────────────────────────┐
│   Presentation Layer    │ ← UI, Controllers
├─────────────────────────┤
│   Business Logic Layer  │ ← Services, Rules
├─────────────────────────┤
│   Data Access Layer     │ ← Repositories, ORM
├─────────────────────────┤
│      Database           │
└─────────────────────────┘
     위에서 아래로 의존

          ┌─────────────────────────────────┐
          │        Driving Side             │
          │   (Primary/Input Adapters)      │
          │                                 │
          │  ┌─────┐  ┌──────┐  ┌───────┐  │
          │  │ REST │  │ gRPC │  │  CLI  │  │
          │  │ API  │  │      │  │       │  │
          │  └──┬───┘  └──┬───┘  └──┬────┘  │
          │     │         │         │       │
          │     ▼         ▼         ▼       │
          │  ┌─────────────────────────┐    │
          │  │     Input Ports         │    │
          │  │    (Use Cases)          │    │
          │  ├─────────────────────────┤    │
          │  │                         │    │
          │  │    Application Core     │    │
          │  │    (Domain Logic)       │    │
          │  │                         │    │
          │  ├─────────────────────────┤    │
          │  │    Output Ports         │    │
          │  │   (Interfaces)          │    │
          │  └─────────────────────────┘    │
          │     │         │         │       │
          │     ▼         ▼         ▼       │
          │  ┌──────┐ ┌───────┐ ┌───────┐  │
          │  │ DB   │ │ Email │ │ Queue │  │
          │  │Adapter│ │Adapter│ │Adapter│  │
          │  └──────┘ └───────┘ └───────┘  │
          │                                 │
          │       Driven Side               │
          │   (Secondary/Output Adapters)   │
          └─────────────────────────────────┘

// Input Port: Use Case 인터페이스
interface PlaceOrderUseCase {
  execute(command: PlaceOrderCommand): Promise<OrderId>;
}

interface GetOrderUseCase {
  execute(query: GetOrderQuery): Promise<OrderDTO>;
}

interface CancelOrderUseCase {
  execute(command: CancelOrderCommand): Promise<void>;
}

// Output Port: Repository 인터페이스
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
  nextId(): OrderId;
}

// Output Port: 알림 서비스 인터페이스
interface NotificationPort {
  sendOrderConfirmation(
    customerId: CustomerId,
    orderId: OrderId
  ): Promise<void>;
}

// Output Port: 결제 서비스 인터페이스
interface PaymentPort {
  processPayment(
    orderId: OrderId,
    amount: Money
  ): Promise<PaymentResult>;
}

// Primary Adapter: REST Controller
class OrderController {
  constructor(
    private placeOrder: PlaceOrderUseCase,
    private getOrder: GetOrderUseCase,
    private cancelOrder: CancelOrderUseCase
  ) {}

  async handlePlaceOrder(req: Request, res: Response): Promise<void> {
    const command = new PlaceOrderCommand(
      req.body.customerId,
      req.body.items.map((item: any) => ({
        productId: item.productId,
        productName: item.productName,
        price: item.price,
        quantity: item.quantity,
      })),
      new Address(
        req.body.address.street,
        req.body.address.city,
        req.body.address.state,
        req.body.address.zipCode
      )
    );

    const orderId = await this.placeOrder.execute(command);
    res.status(201).json({ orderId: orderId.value });
  }

  async handleGetOrder(req: Request, res: Response): Promise<void> {
    const query = new GetOrderQuery(req.params.orderId);
    const order = await this.getOrder.execute(query);
    res.json(order);
  }

  async handleCancelOrder(req: Request, res: Response): Promise<void> {
    const command = new CancelOrderCommand(
      req.params.orderId,
      req.body.reason
    );
    await this.cancelOrder.execute(command);
    res.status(204).send();
  }
}

// Primary Adapter: gRPC Handler
class OrderGrpcHandler {
  constructor(private placeOrder: PlaceOrderUseCase) {}

  async placeOrder(
    call: grpc.ServerUnaryCall<PlaceOrderRequest, PlaceOrderResponse>,
    callback: grpc.sendUnaryData<PlaceOrderResponse>
  ): Promise<void> {
    const command = this.toCommand(call.request);
    const orderId = await this.placeOrder.execute(command);
    callback(null, { orderId: orderId.value });
  }
}

// Primary Adapter: CLI Command
class PlaceOrderCLI {
  constructor(private placeOrder: PlaceOrderUseCase) {}

  async run(args: string[]): Promise<void> {
    const command = this.parseArgs(args);
    const orderId = await this.placeOrder.execute(command);
    console.log(`Order created: ${orderId.value}`);
  }
}

// Secondary Adapter: PostgreSQL Repository
class PostgresOrderRepository implements OrderRepository {
  constructor(private pool: Pool) {}

  async findById(id: OrderId): Promise<Order | null> {
    const result = await this.pool.query(
      'SELECT * FROM orders WHERE id = $1',
      [id.value]
    );
    if (result.rows.length === 0) return null;
    return this.toDomain(result.rows[0]);
  }

  async save(order: Order): Promise<void> {
    await this.pool.query(
      `INSERT INTO orders (id, customer_id, status, total_amount)
       VALUES ($1, $2, $3, $4)
       ON CONFLICT (id) DO UPDATE
       SET status = $3, total_amount = $4`,
      [order.id.value, order.customerId.value,
       order.status.value, order.totalAmount.value]
    );
  }

  nextId(): OrderId {
    return OrderId.generate();
  }
}

// Secondary Adapter: MongoDB Repository (같은 Port, 다른 구현)
class MongoOrderRepository implements OrderRepository {
  constructor(private collection: Collection) {}

  async findById(id: OrderId): Promise<Order | null> {
    const doc = await this.collection.findOne({ _id: id.value });
    if (!doc) return null;
    return this.toDomain(doc);
  }

  async save(order: Order): Promise<void> {
    await this.collection.updateOne(
      { _id: order.id.value },
      { $set: this.toDocument(order) },
      { upsert: true }
    );
  }

  nextId(): OrderId {
    return OrderId.generate();
  }
}

// Secondary Adapter: Email Notification
class EmailNotificationAdapter implements NotificationPort {
  constructor(private mailer: Mailer) {}

  async sendOrderConfirmation(
    customerId: CustomerId,
    orderId: OrderId
  ): Promise<void> {
    const customer = await this.getCustomerEmail(customerId);
    await this.mailer.send({
      to: customer.email,
      subject: `Order ${orderId.value} Confirmed`,
      template: 'order-confirmation',
      data: { orderId: orderId.value },
    });
  }
}

// Secondary Adapter: SMS Notification (같은 Port, 다른 구현)
class SmsNotificationAdapter implements NotificationPort {
  constructor(private smsClient: SmsClient) {}

  async sendOrderConfirmation(
    customerId: CustomerId,
    orderId: OrderId
  ): Promise<void> {
    const customer = await this.getCustomerPhone(customerId);
    await this.smsClient.send({
      to: customer.phone,
      message: `Your order ${orderId.value} has been confirmed.`,
    });
  }
}

┌───────────────────────────────────────────────┐
│              Frameworks & Drivers              │
│  ┌───────────────────────────────────────┐    │
│  │          Interface Adapters           │    │
│  │  ┌───────────────────────────────┐    │    │
│  │  │       Application Business    │    │    │
│  │  │           Rules               │    │    │
│  │  │  ┌───────────────────────┐    │    │    │
│  │  │  │   Enterprise Business │    │    │    │
│  │  │  │       Rules           │    │    │    │
│  │  │  │     (Entities)        │    │    │    │
│  │  │  └───────────────────────┘    │    │    │
│  │  │       (Use Cases)             │    │    │
│  │  └───────────────────────────────┘    │    │
│  │    (Controllers, Gateways, Presenters)│    │
│  └───────────────────────────────────────┘    │
│   (Web, DB, UI, Devices, External Interfaces) │
└───────────────────────────────────────────────┘

의존성 방향: 바깥 → 안쪽 (항상)

// Entity Layer
class Order {
  private readonly id: OrderId;
  private status: OrderStatus;
  private items: OrderLineItem[];

  place(): void {
    if (this.items.length === 0) {
      throw new EmptyOrderError();
    }
    if (this.status !== OrderStatus.DRAFT) {
      throw new InvalidOrderStateError(this.status);
    }
    this.status = OrderStatus.PLACED;
  }

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

  canCancel(): boolean {
    return this.status !== OrderStatus.SHIPPED
      && this.status !== OrderStatus.DELIVERED;
  }
}

// Value Object (Entity Layer)
class Money {
  constructor(
    readonly value: number,
    readonly currency: Currency
  ) {
    if (value < 0) throw new NegativeMoneyError();
  }

  add(other: Money): Money {
    this.assertSameCurrency(other);
    return new Money(this.value + other.value, this.currency);
  }
}

// Use Case Layer
class PlaceOrderUseCase {
  constructor(
    private orderRepo: OrderRepository,     // Output Port
    private paymentPort: PaymentPort,       // Output Port
    private notificationPort: NotificationPort // Output Port
  ) {}

  async execute(command: PlaceOrderCommand): Promise<OrderId> {
    // 1. Aggregate 생성
    const orderId = this.orderRepo.nextId();
    const order = new Order(
      orderId,
      new CustomerId(command.customerId)
    );

    // 2. 아이템 추가
    for (const item of command.items) {
      order.addItem(
        new ProductId(item.productId),
        item.productName,
        Money.of(item.price, 'KRW'),
        new Quantity(item.quantity)
      );
    }

    // 3. 주문 실행
    order.place();

    // 4. 결제 처리
    const paymentResult = await this.paymentPort.processPayment(
      orderId,
      order.totalAmount
    );

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

    // 5. 저장
    await this.orderRepo.save(order);

    // 6. 알림
    await this.notificationPort.sendOrderConfirmation(
      order.customerId,
      orderId
    );

    return orderId;
  }
}

// Use Case: Input/Output DTO
class PlaceOrderCommand {
  constructor(
    readonly customerId: string,
    readonly items: OrderItemDTO[],
    readonly shippingAddress: AddressDTO
  ) {}
}

class OrderItemDTO {
  constructor(
    readonly productId: string,
    readonly productName: string,
    readonly price: number,
    readonly quantity: number
  ) {}
}

// Interface Adapter: Controller
class OrderRestController {
  constructor(
    private placeOrderUseCase: PlaceOrderUseCase,
    private getOrderUseCase: GetOrderUseCase
  ) {}

  async placeOrder(req: Request, res: Response): Promise<void> {
    try {
      const command = new PlaceOrderCommand(
        req.body.customerId,
        req.body.items,
        req.body.address
      );

      const orderId = await this.placeOrderUseCase.execute(command);
      res.status(201).json(
        OrderPresenter.toCreatedResponse(orderId)
      );
    } catch (error) {
      if (error instanceof EmptyOrderError) {
        res.status(400).json({ error: 'Order must have items' });
      } else if (error instanceof PaymentFailedError) {
        res.status(402).json({ error: 'Payment failed' });
      } else {
        res.status(500).json({ error: 'Internal server error' });
      }
    }
  }
}

// Interface Adapter: Presenter
class OrderPresenter {
  static toCreatedResponse(orderId: OrderId): object {
    return {
      orderId: orderId.value,
      message: 'Order placed successfully',
      links: {
        self: `/orders/${orderId.value}`,
        cancel: `/orders/${orderId.value}/cancel`,
      },
    };
  }

  static toDetailResponse(order: OrderDTO): object {
    return {
      id: order.id,
      status: order.status,
      items: order.items.map(item => ({
        product: item.productName,
        price: item.price,
        quantity: item.quantity,
        subtotal: item.subtotal,
      })),
      total: order.totalAmount,
      placedAt: order.placedAt.toISOString(),
    };
  }
}

// Interface Adapter: Gateway (Output Port 구현)
class PostgresOrderGateway implements OrderRepository {
  constructor(private dataSource: DataSource) {}

  async findById(id: OrderId): Promise<Order | null> {
    const entity = await this.dataSource
      .getRepository(OrderEntity)
      .findOne({ where: { id: id.value }, relations: ['items'] });

    if (!entity) return null;
    return OrderMapper.toDomain(entity);
  }

  async save(order: Order): Promise<void> {
    const entity = OrderMapper.toPersistence(order);
    await this.dataSource.getRepository(OrderEntity).save(entity);
  }

  nextId(): OrderId {
    return OrderId.generate();
  }
}

// Framework Layer: Express Setup
import express from 'express';

const app = express();
app.use(express.json());

// Dependency Injection (Composition Root)
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const orderRepo = new PostgresOrderGateway(pool);
const paymentAdapter = new StripePaymentAdapter(process.env.STRIPE_KEY);
const notificationAdapter = new EmailNotificationAdapter(mailer);

const placeOrderUseCase = new PlaceOrderUseCase(
  orderRepo,
  paymentAdapter,
  notificationAdapter
);

const getOrderUseCase = new GetOrderUseCase(orderRepo);
const controller = new OrderRestController(
  placeOrderUseCase,
  getOrderUseCase
);

// Routes
app.post('/orders', (req, res) => controller.placeOrder(req, res));
app.get('/orders/:id', (req, res) => controller.getOrder(req, res));

app.listen(3000);

┌─────────────────────────────────────────────┐
│              Infrastructure                  │
│  ┌───────────────────────────────────────┐  │
│  │        Application Services           │  │
│  │  ┌───────────────────────────────┐    │  │
│  │  │      Domain Services          │    │  │
│  │  │  ┌───────────────────────┐    │    │  │
│  │  │  │    Domain Model       │    │    │  │
│  │  │  │  (Entities + VOs)     │    │    │  │
│  │  │  └───────────────────────┘    │    │  │
│  │  └───────────────────────────────┘    │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

전통적 (Layered):
Controller → Service → Repository(PostgreSQL)
           ↓                    ↓
       비즈니스 로직이        DB 기술에
       DB에 의존             직접 결합

역전된 (Clean/Hexagonal):
Controller → UseCase → Repository(Interface)
                              ↑
                    PostgresRepository(구현)

  UseCase는 Interface만 알고, 구현체는 모른다

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


# === Domain Layer (가장 안쪽) ===

@dataclass(frozen=True)
class Money:
    amount: int
    currency: str = "KRW"

    def add(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("Currency mismatch")
        return Money(self.amount + other.amount, self.currency)


@dataclass(frozen=True)
class OrderId:
    value: str


class Order:
    def __init__(self, order_id: OrderId, customer_id: str) -> None:
        self.id = order_id
        self.customer_id = customer_id
        self.items: list[dict] = []
        self.status = "DRAFT"

    @property
    def total_amount(self) -> Money:
        total = Money(0)
        for item in self.items:
            subtotal = Money(item["price"] * item["quantity"])
            total = total.add(subtotal)
        return total

    def add_item(self, product_id: str, name: str,
                 price: int, quantity: int) -> None:
        if self.status != "DRAFT":
            raise ValueError("Can only add items to draft orders")
        self.items.append({
            "product_id": product_id,
            "name": name,
            "price": price,
            "quantity": quantity,
        })

    def place(self) -> None:
        if not self.items:
            raise ValueError("Cannot place empty order")
        if self.status != "DRAFT":
            raise ValueError("Can only place draft orders")
        self.status = "PLACED"


# === Port (도메인이 정의하는 인터페이스) ===

class OrderRepository(ABC):
    @abstractmethod
    async def find_by_id(self, order_id: OrderId) -> Optional[Order]:
        ...

    @abstractmethod
    async def save(self, order: Order) -> None:
        ...

    @abstractmethod
    def next_id(self) -> OrderId:
        ...


class PaymentPort(ABC):
    @abstractmethod
    async def process_payment(
        self, order_id: OrderId, amount: Money
    ) -> bool:
        ...


class NotificationPort(ABC):
    @abstractmethod
    async def send_order_confirmation(
        self, customer_id: str, order_id: OrderId
    ) -> None:
        ...


# === Use Case Layer ===

@dataclass
class PlaceOrderCommand:
    customer_id: str
    items: list[dict]


class PlaceOrderUseCase:
    def __init__(
        self,
        order_repo: OrderRepository,
        payment_port: PaymentPort,
        notification_port: NotificationPort,
    ) -> None:
        self._order_repo = order_repo
        self._payment_port = payment_port
        self._notification_port = notification_port

    async def execute(self, command: PlaceOrderCommand) -> str:
        order_id = self._order_repo.next_id()
        order = Order(order_id, command.customer_id)

        for item in command.items:
            order.add_item(
                product_id=item["product_id"],
                name=item["name"],
                price=item["price"],
                quantity=item["quantity"],
            )

        order.place()

        success = await self._payment_port.process_payment(
            order_id, order.total_amount
        )
        if not success:
            raise ValueError("Payment failed")

        await self._order_repo.save(order)

        await self._notification_port.send_order_confirmation(
            command.customer_id, order_id
        )

        return order_id.value


# === Adapter Layer (가장 바깥) ===

from uuid import uuid4


class InMemoryOrderRepository(OrderRepository):
    def __init__(self) -> None:
        self._store: dict[str, Order] = {}

    async def find_by_id(self, order_id: OrderId) -> Optional[Order]:
        return self._store.get(order_id.value)

    async def save(self, order: Order) -> None:
        self._store[order.id.value] = order

    def next_id(self) -> OrderId:
        return OrderId(str(uuid4()))


class StripePaymentAdapter(PaymentPort):
    def __init__(self, api_key: str) -> None:
        self._api_key = api_key

    async def process_payment(
        self, order_id: OrderId, amount: Money
    ) -> bool:
        # Stripe API 호출
        # stripe.Charge.create(...)
        return True


class ConsoleNotificationAdapter(NotificationPort):
    async def send_order_confirmation(
        self, customer_id: str, order_id: OrderId
    ) -> None:
        print(
            f"Order {order_id.value} confirmed "
            f"for customer {customer_id}"
        )


# === Composition Root ===

async def main():
    # 의존성 조립
    order_repo = InMemoryOrderRepository()
    payment = StripePaymentAdapter("sk_test_xxx")
    notification = ConsoleNotificationAdapter()

    use_case = PlaceOrderUseCase(order_repo, payment, notification)

    # 실행
    result = await use_case.execute(
        PlaceOrderCommand(
            customer_id="cust-1",
            items=[
                {
                    "product_id": "prod-1",
                    "name": "Widget",
                    "price": 10000,
                    "quantity": 2,
                }
            ],
        )
    )
    print(f"Order created: {result}")

src/
├── domain/                          # Entity Layer
│   ├── model/
│   │   ├── Order.ts                 # Aggregate Root
│   │   ├── OrderLineItem.ts         # Entity
│   │   ├── Money.ts                 # Value Object
│   │   ├── OrderId.ts               # Value Object
│   │   └── OrderStatus.ts           # Enum
│   ├── event/
│   │   ├── OrderPlaced.ts
│   │   └── OrderCancelled.ts
│   ├── service/
│   │   └── OrderPricingService.ts   # Domain Service
│   └── port/
│       ├── OrderRepository.ts       # Output Port (Interface)
│       ├── PaymentPort.ts           # Output Port (Interface)
│       └── NotificationPort.ts      # Output Port (Interface)
│
├── application/                     # Use Case Layer
│   ├── command/
│   │   ├── PlaceOrderCommand.ts
│   │   ├── PlaceOrderHandler.ts     # Use Case Implementation
│   │   ├── CancelOrderCommand.ts
│   │   └── CancelOrderHandler.ts
│   ├── query/
│   │   ├── GetOrderQuery.ts
│   │   └── GetOrderHandler.ts
│   └── dto/
│       ├── OrderDTO.ts
│       └── OrderItemDTO.ts
│
├── adapter/                         # Interface Adapter Layer
│   ├── in/                          # Primary (Driving) Adapters
│   │   ├── rest/
│   │   │   ├── OrderController.ts
│   │   │   └── OrderPresenter.ts
│   │   ├── grpc/
│   │   │   └── OrderGrpcHandler.ts
│   │   └── cli/
│   │       └── PlaceOrderCLI.ts
│   └── out/                         # Secondary (Driven) Adapters
│       ├── persistence/
│       │   ├── PostgresOrderRepository.ts
│       │   ├── MongoOrderRepository.ts
│       │   └── entity/
│       │       └── OrderEntity.ts   # ORM Entity
│       ├── payment/
│       │   ├── StripePaymentAdapter.ts
│       │   └── TossPaymentAdapter.ts
│       ├── notification/
│       │   ├── EmailNotificationAdapter.ts
│       │   └── SmsNotificationAdapter.ts
│       └── messaging/
│           └── KafkaEventPublisher.ts
│
├── config/                          # Framework Layer
│   ├── container.ts                 # DI Container
│   ├── database.ts
│   └── server.ts
│
└── main.ts                          # Composition Root

src/
├── domain/
│   ├── __init__.py
│   ├── model/
│   │   ├── order.py
│   │   ├── order_line_item.py
│   │   └── value_objects.py
│   ├── events/
│   │   └── order_events.py
│   ├── services/
│   │   └── pricing_service.py
│   └── ports/
│       ├── order_repository.py      # ABC
│       ├── payment_port.py          # ABC
│       └── notification_port.py     # ABC
│
├── application/
│   ├── __init__.py
│   ├── commands/
│   │   ├── place_order.py
│   │   └── cancel_order.py
│   ├── queries/
│   │   └── get_order.py
│   └── dto/
│       └── order_dto.py
│
├── adapters/
│   ├── __init__.py
│   ├── inbound/
│   │   ├── fastapi_routes.py
│   │   └── cli.py
│   └── outbound/
│       ├── sqlalchemy_order_repo.py
│       ├── stripe_payment.py
│       └── email_notification.py
│
├── config/
│   ├── container.py                 # DI
│   └── settings.py
│
└── main.py

// Input Port (인터페이스)
interface PlaceOrderInputPort {
  execute(command: PlaceOrderCommand): Promise<PlaceOrderResult>;
}

// Output Port (인터페이스)
interface PlaceOrderOutputPort {
  orderCreated(orderId: OrderId, totalAmount: Money): void;
  paymentFailed(reason: string): void;
  validationFailed(errors: ValidationError[]): void;
}

// Interactor (Use Case 구현체)
class PlaceOrderInteractor implements PlaceOrderInputPort {
  constructor(
    private orderRepo: OrderRepository,
    private paymentPort: PaymentPort,
    private presenter: PlaceOrderOutputPort
  ) {}

  async execute(
    command: PlaceOrderCommand
  ): Promise<PlaceOrderResult> {
    // Validation
    const errors = this.validate(command);
    if (errors.length > 0) {
      this.presenter.validationFailed(errors);
      return PlaceOrderResult.failure('VALIDATION_ERROR');
    }

    // Domain logic
    const orderId = this.orderRepo.nextId();
    const order = new Order(
      orderId,
      new CustomerId(command.customerId)
    );

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

    order.place();

    // Payment
    const paymentResult = await this.paymentPort.processPayment(
      orderId,
      order.totalAmount
    );

    if (!paymentResult.isSuccess) {
      this.presenter.paymentFailed(paymentResult.reason);
      return PlaceOrderResult.failure('PAYMENT_FAILED');
    }

    await this.orderRepo.save(order);

    this.presenter.orderCreated(orderId, order.totalAmount);
    return PlaceOrderResult.success(orderId);
  }

  private validate(command: PlaceOrderCommand): ValidationError[] {
    const errors: ValidationError[] = [];
    if (!command.customerId) {
      errors.push(new ValidationError('customerId', 'Required'));
    }
    if (!command.items || command.items.length === 0) {
      errors.push(new ValidationError('items', 'At least one item'));
    }
    return errors;
  }
}

describe('Order', () => {
  it('should place order with items', () => {
    const order = new Order(
      OrderId.generate(),
      new CustomerId('cust-1')
    );

    order.addItem(
      new ProductId('prod-1'),
      'Widget',
      Money.of(10000, 'KRW'),
      new Quantity(2)
    );

    order.place();

    expect(order.status).toBe(OrderStatus.PLACED);
    expect(order.totalAmount).toEqual(Money.of(20000, 'KRW'));
  });

  it('should not place empty order', () => {
    const order = new Order(
      OrderId.generate(),
      new CustomerId('cust-1')
    );

    expect(() => order.place()).toThrow(EmptyOrderError);
  });

  it('should not add items to placed order', () => {
    const order = createPlacedOrder();

    expect(() =>
      order.addItem(
        new ProductId('prod-2'),
        'Gadget',
        Money.of(5000, 'KRW'),
        new Quantity(1)
      )
    ).toThrow(InvalidOrderStateError);
  });
});

describe('Money', () => {
  it('should add same currency', () => {
    const a = Money.of(10000, 'KRW');
    const b = Money.of(5000, 'KRW');
    expect(a.add(b)).toEqual(Money.of(15000, 'KRW'));
  });

  it('should reject negative amount', () => {
    expect(() => Money.of(-100, 'KRW')).toThrow(NegativeMoneyError);
  });

  it('should reject currency mismatch', () => {
    const krw = Money.of(10000, 'KRW');
    const usd = Money.of(10, 'USD');
    expect(() => krw.add(usd)).toThrow(CurrencyMismatchError);
  });
});

describe('PlaceOrderUseCase', () => {
  let useCase: PlaceOrderUseCase;
  let orderRepo: InMemoryOrderRepository;
  let paymentPort: FakePaymentAdapter;
  let notificationPort: SpyNotificationAdapter;

  beforeEach(() => {
    orderRepo = new InMemoryOrderRepository();
    paymentPort = new FakePaymentAdapter();
    notificationPort = new SpyNotificationAdapter();
    useCase = new PlaceOrderUseCase(
      orderRepo, paymentPort, notificationPort
    );
  });

  it('should place order successfully', async () => {
    paymentPort.willSucceed();

    const command = new PlaceOrderCommand(
      'cust-1',
      [{ productId: 'prod-1', productName: 'Widget',
         price: 10000, quantity: 2 }],
      new AddressDTO('Street', 'City', 'State', '12345')
    );

    const orderId = await useCase.execute(command);

    expect(orderId).toBeDefined();
    const saved = await orderRepo.findById(orderId);
    expect(saved).not.toBeNull();
    expect(saved!.status).toBe(OrderStatus.PLACED);
    expect(notificationPort.wasCalled).toBe(true);
  });

  it('should fail when payment fails', async () => {
    paymentPort.willFail('Insufficient funds');

    const command = new PlaceOrderCommand(
      'cust-1',
      [{ productId: 'prod-1', productName: 'Widget',
         price: 10000, quantity: 1 }],
      new AddressDTO('Street', 'City', 'State', '12345')
    );

    await expect(useCase.execute(command))
      .rejects.toThrow(PaymentFailedError);
  });
});

// Test Doubles
class InMemoryOrderRepository implements OrderRepository {
  private store = new Map<string, Order>();

  async findById(id: OrderId): Promise<Order | null> {
    return this.store.get(id.value) || null;
  }

  async save(order: Order): Promise<void> {
    this.store.set(order.id.value, order);
  }

  nextId(): OrderId { return OrderId.generate(); }
}

class FakePaymentAdapter implements PaymentPort {
  private shouldSucceed = true;

  willSucceed(): void { this.shouldSucceed = true; }
  willFail(reason: string): void { this.shouldSucceed = false; }

  async processPayment(): Promise<PaymentResult> {
    return this.shouldSucceed
      ? PaymentResult.success()
      : PaymentResult.failure('Declined');
  }
}

class SpyNotificationAdapter implements NotificationPort {
  wasCalled = false;

  async sendOrderConfirmation(): Promise<void> {
    this.wasCalled = true;
  }
}

describe('PostgresOrderRepository', () => {
  let repo: PostgresOrderRepository;
  let pool: Pool;

  beforeAll(async () => {
    pool = new Pool({
      connectionString: process.env.TEST_DATABASE_URL,
    });
    repo = new PostgresOrderRepository(pool);
  });

  afterAll(async () => {
    await pool.end();
  });

  it('should save and retrieve order', async () => {
    const order = createSampleOrder();
    await repo.save(order);

    const retrieved = await repo.findById(order.id);

    expect(retrieved).not.toBeNull();
    expect(retrieved!.id).toEqual(order.id);
    expect(retrieved!.status).toBe(OrderStatus.PLACED);
    expect(retrieved!.totalAmount).toEqual(order.totalAmount);
  });
});

// Before: Express
import express from 'express';
const app = express();
app.post('/orders', (req, res) =>
  controller.placeOrder(req, res)
);

// After: Fastify (도메인/유스케이스 코드 변경 없음!)
import Fastify from 'fastify';
const fastify = Fastify();

// 새로운 Primary Adapter만 작성
class OrderFastifyAdapter {
  constructor(private useCase: PlaceOrderUseCase) {}

  async placeOrder(
    request: FastifyRequest,
    reply: FastifyReply
  ): Promise<void> {
    const command = new PlaceOrderCommand(
      request.body.customerId,
      request.body.items,
      request.body.address
    );

    const orderId = await this.useCase.execute(command);
    reply.code(201).send({ orderId: orderId.value });
  }
}

const adapter = new OrderFastifyAdapter(placeOrderUseCase);
fastify.post('/orders', (req, reply) =>
  adapter.placeOrder(req, reply)
);

// 도메인 코드: 변경 없음
// Use Case 코드: 변경 없음
// Output Port (Interface): 변경 없음

// 새로운 Secondary Adapter만 작성
class MongoOrderRepository implements OrderRepository {
  constructor(private db: Db) {}

  async findById(id: OrderId): Promise<Order | null> {
    const doc = await this.db
      .collection('orders')
      .findOne({ _id: id.value });
    return doc ? this.toDomain(doc) : null;
  }

  async save(order: Order): Promise<void> {
    await this.db.collection('orders').updateOne(
      { _id: order.id.value },
      { $set: this.toDocument(order) },
      { upsert: true }
    );
  }

  nextId(): OrderId { return OrderId.generate(); }
}

// Composition Root만 변경
// Before:
// const orderRepo = new PostgresOrderRepository(pool);
// After:
const mongoClient = new MongoClient(process.env.MONGO_URL);
const orderRepo = new MongoOrderRepository(mongoClient.db('shop'));

단순 CRUD 앱에 Clean Architecture를 적용하면:

Entity → Use Case → Input Port → Controller
                     Output Port → Repository
                     Output Port → Notification
                     Output Port → Payment

파일 수: 20+

그냥 이렇게 하면 됩니다:
Controller → Service → Repository

파일 수: 3

// 나쁜 예: 도메인에 인프라 의존성
class Order {
  async save(): Promise<void> {
    // 도메인이 DB를 직접 알면 안 됨!
    await db.query('INSERT INTO orders ...');
  }
}

// 나쁜 예: Use Case에 프레임워크 의존성
class PlaceOrderUseCase {
  async execute(req: express.Request): Promise<void> {
    // Use Case가 Express를 직접 알면 안 됨!
    const body = req.body;
  }
}

// 좋은 예: 각 레이어가 자기 역할만
class Order {
  place(): void { /* 순수 도메인 로직 */ }
}

class PlaceOrderUseCase {
  execute(command: PlaceOrderCommand): Promise<OrderId> {
    /* DTO만 받고, Port를 통해 외부와 통신 */
  }
}

// 나쁜 예: Port가 특정 기술에 종속
interface OrderRepository {
  // SQL을 직접 노출 - PostgreSQL에 종속!
  findByQuery(sql: string): Promise<Order[]>;
  // Mongoose Document를 노출 - MongoDB에 종속!
  findByMongoQuery(filter: FilterQuery<OrderDoc>): Promise<Order[]>;
}

// 좋은 예: 기술 중립적 Port
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  findByCustomer(customerId: CustomerId): Promise<Order[]>;
  findByStatus(status: OrderStatus): Promise<Order[]>;
  save(order: Order): Promise<void>;
}