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.

Aller à l'installation

Dépôt: linnefromice/claude-code-workspace
Dernière activité de la source: 12 avril 2026 à 09:13
Langue détectée de SKILL.md: japonais
Étoiles: 0
Forks: 0

Options d'installation

Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.

Vérifiez les fichiers source

Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.

Retour à la recherche Retour à l’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);
};