hexagonal-architecture

Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services.

Zur Installation springen

Repository: linnefromice/claude-code-workspace
Letzte Quellaktivität: 12. April 2026 um 09:13
Erkannte Sprache von SKILL.md: Japanisch
Sterne: 0
Forks: 0

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur Installation

name	hexagonal-architecture
description	Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services.
origin	ECC

Hexagonal Architecture

ヘキサゴナルアーキテクチャ（Ports and Adapters）は、ビジネスロジックをフレームワーク、トランスポート、永続化の詳細から独立させます。コアアプリケーションは抽象的なポートに依存し、アダプターがエッジ部分でそれらのポートを実装します。

使用タイミング

長期的な保守性とテスタビリティが重要な新機能を構築する場合。
ドメインロジックが I/O 関連の処理と混在しているレイヤード構造やフレームワーク依存の強いコードをリファクタリングする場合。
同一のユースケースに対して複数のインターフェースをサポートする場合（HTTP、CLI、キューワーカー、cronジョブ）。
ビジネスルールを書き換えずにインフラ（データベース、外部API、メッセージバス）を置き換える場合。

リクエストが境界、ドメイン中心の設計、密結合サービスのリファクタリング、または特定のライブラリからのアプリケーションロジックの分離に関わる場合にこのスキルを使用してください。

コアコンセプト

ドメインモデル: ビジネスルールとエンティティ/値オブジェクト。フレームワークのインポートなし。
ユースケース（アプリケーション層）: ドメインの振る舞いとワークフローステップをオーケストレーションします。
インバウンドポート: アプリケーションが何を行えるかを記述するコントラクト（コマンド/クエリ/ユースケースインターフェース）。
アウトバウンドポート: アプリケーションが必要とする依存関係のコントラクト（リポジトリ、ゲートウェイ、イベントパブリッシャー、クロック、UUID など）。
アダプター: ポートのインフラおよびデリバリー実装（HTTPコントローラー、DBリポジトリ、キューコンシューマー、SDKラッパー）。
コンポジションルート: 具体的なアダプターをユースケースにバインドする単一の配線場所。

アウトバウンドポートインターフェースは通常アプリケーション層に配置されます（抽象化が真にドメインレベルの場合のみドメイン層に配置）。一方、インフラアダプターがそれらを実装します。

依存関係の方向は常に内向きです:

アダプター -> アプリケーション/ドメイン
アプリケーション -> ポートインターフェース（インバウンド/アウトバウンドコントラクト）
ドメイン -> ドメインのみの抽象化（フレームワークやインフラの依存関係なし）
ドメイン -> 外部への依存なし

仕組み

ステップ 1: ユースケース境界をモデル化する

flowchart LR
  Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
  InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
  UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
  OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
  OutboundAdapter --> ExternalSystem["DB/API/Queue"]
  UseCase --> DomainModel["DomainModel"]

src/
  features/
    orders/
      domain/
        Order.ts
        OrderPolicy.ts
      application/
        ports/
          inbound/
            CreateOrder.ts
          outbound/
            OrderRepositoryPort.ts
            PaymentGatewayPort.ts
        use-cases/
          CreateOrderUseCase.ts
      adapters/
        inbound/
          http/
            createOrderRoute.ts
        outbound/
          postgres/
            PostgresOrderRepository.ts
          stripe/
            StripePaymentGateway.ts
      composition/
        ordersContainer.ts

export interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(orderId: string): Promise<Order | null>;
}

export interface PaymentGatewayPort {
  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
}

type CreateOrderInput = {
  orderId: string;
  amountCents: number;
};

type CreateOrderOutput = {
  orderId: string;
  authorizationId: string;
};

export class CreateOrderUseCase {
  constructor(
    private readonly orderRepository: OrderRepositoryPort,
    private readonly paymentGateway: PaymentGatewayPort
  ) {}

  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });

    const auth = await this.paymentGateway.authorize({
      orderId: order.id,
      amountCents: order.amountCents,
    });

    // markAuthorized は新しい Order インスタンスを返します。その場での変更はしません。
    const authorizedOrder = order.markAuthorized(auth.authorizationId);
    await this.orderRepository.save(authorizedOrder);

    return {
      orderId: order.id,
      authorizationId: auth.authorizationId,
    };
  }
}

export class PostgresOrderRepository implements OrderRepositoryPort {
  constructor(private readonly db: SqlClient) {}

  async save(order: Order): Promise<void> {
    await this.db.query(
      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
      [order.id, order.amountCents, order.status, order.authorizationId]
    );
  }

  async findById(orderId: string): Promise<Order | null> {
    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
    return row ? Order.rehydrate(row) : null;
  }
}

export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
  const orderRepository = new PostgresOrderRepository(deps.db);
  const paymentGateway = new StripePaymentGateway(deps.stripe);

  return new CreateOrderUseCase(orderRepository, paymentGateway);
};