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  |  |      |  |       |   |
          |  +--+---+  +--+---+  +--+----+   |
          |     |         |         |         |
          |     v         v         v         |
          |  +---------------------------+    |
          |  |     Input Ports           |    |
          |  |    (Use Cases)            |    |
          |  +---------------------------+    |
          |  |                           |    |
          |  |    Application Core       |    |
          |  |    (Domain Logic)         |    |
          |  |                           |    |
          |  +---------------------------+    |
          |  |    Output Ports           |    |
          |  |   (Interfaces)            |    |
          |  +---------------------------+    |
          |     |         |         |         |
          |     v         v         v         |
          |  +------+ +-------+ +-------+    |
          |  | DB   | | Email | | Queue |    |
          |  |Adapt.| |Adapt. | |Adapt. |    |
          |  +------+ +-------+ +-------+    |
          |                                   |
          |       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コマンド
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通知
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通知（同じ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;
  }
}

// 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(),
    };
  }
}

// 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)     |    |    |  |
|  |  |  +-----------------------+    |    |  |
|  |  +-------------------------------+    |  |
|  +---------------------------------------+  |
+---------------------------------------------+

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呼び出し
        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実装
│   │   ├── 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

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);
  });
});

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;
  }
}

// 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>;
}