vertical-slice-architecture

垂直スライスアーキテクチャ

クイックリファレンス：5 つのルール

1. 1 つの機能 = 1 つのディレクトリ。ハンドラー、リクエスト／レスポンス型、バリデーション、テストを含めます
2. 機能ごとに 1 つのエントリーポイント — ルーターと依存関係を受け取るセットアップ／登録関数です。名前は規約によって異なります（Setup、RegisterRoute、Map）。重要なのは名前ではなく、その役割です。
3. スライス間の結合を最小限にし、スライス内の結合を最大限にします
4. 早まった抽象化を避ける — 複数のスライスにわたって実際の重複が発生するまでは、共有リポジトリ／サービスレイヤーを作成しません
5. 各機能は主にエントリーポイントを通じてテストし、結果（DB の状態、API 呼び出し、レスポンス）を検証します。プラットフォーム／アダプターのテストも推奨します。

プロジェクト構成

{project}/
  features/              # or internal/features/ (Go), Features/ (.NET)
    {domain}/            # orders/, users/, kvs/
      {operation}/       # create/, list/, delete/
        handler          # Single entry point + orchestration
        request/response # DTOs
        validator        # Input validation (optional)
        test             # Co-located integration test
        internal/        # Feature-private helpers (optional)
  platform/              # or Infrastructure/ — shared cross-cutting concerns
    middleware/           # Auth, error handling, idempotency
    database/            # Connection pooling, circuit breakers
    observability/       # Metrics, tracing, structured logging
    opqueue/             # Operation queues, outbox patterns (if needed)
  main                   # Composition root wires features + infrastructure

ワークフロー：新しい機能の追加

1. ディレクトリを作成します：features/{domain}/{operation}/
2. エクスポートするセットアップ関数を 1 つだけ持つハンドラーを定義します
3. リクエスト／レスポンス型を定義します（単純なケースではインラインで定義します）
4. バリデーションロジックを追加します
5. コンポジションルート（main）に登録します
6. セットアップ関数を呼び出し、リクエストを送信して結果を検証する統合テストを作成します

ワークフロー：横断的関心事の追加

機能内ではなく、platform/ に配置します。例：

• 認証ミドルウェア、エラー処理、リクエストのログ記録
• データベースのコネクションプーリング、サーキットブレーカー
• 冪等性ミドルウェア、操作キュー、イベント通知
• オブザーバビリティ（メトリクス、トレーシング、構造化ログ）

ワークフロー：共有ロジックの抽出

複数のスライスにわたって実際の重複が発生した場合にのみ抽出します（判断が必要です。「3 つ以上のスライス」という経験則は指針であり、厳密なルールではありません）。

• ビジネスルールの重複：ドメインエンティティ／値オブジェクトに抽出します
• データアクセスパターンの重複：共有リポジトリに抽出します（その特定のパターンに限ります）
• HTTP ヘルパーの重複：platform/httpx/ に抽出します

言語別の重要な判断事項

プロジェクトの言語／フレームワークを特定し、該当するリファレンスを参照してください。

• 言語別のパターン：Go、.NET、Java、TypeScript、Python については references/patterns-by-language.md を参照してください
• 言語別のテスト：testcontainers、モック検証、統合テストのパターンについては references/testing.md を参照してください
• コア原則：詳細なルール、アンチパターン、共有ドメインモデルの指針については references/principles.md を参照してください

単一エントリーポイントの契約

各機能は、主要なセットアップ／登録関数を 1 つ公開します。内部型は非公開のままにします。エントリーポイントの名前は規約によります。変わらない原則は、各機能につき、スライスをフレームワークに接続する公開関数が 1 つであることです。

• Go — 規約は Setup または RegisterRoute、シグネチャは func Setup(r gin.IRoutes, repo Repository)。DI は明示的なパラメーターで行います。
• .NET — 規約は Map（静的）、シグネチャは static void Map(IEndpointRouteBuilder app)。依存関係はハンドラー内で DI コンテナーが解決します。
• Java/Kotlin — コンポーネントスキャンで検出される @RestController クラスを使用します。Spring DI（コンストラクターインジェクション）を使用します。
• TypeScript — 規約は setup、シグネチャは function setup(router: Router, db: Database): void。DI は明示的なパラメーターで行います。
• Python — 規約は setup、シグネチャは def setup(router: APIRouter, db: Database) -> None。DI は明示的なパラメーターまたは Depends() で行います。

例外：バージョン管理された API では、内部のハンドラー接続を共有する SetupV1／SetupV2 ラッパーを使用する場合があります。自動検出機能（Spring、NestJS）を備えたフレームワークでは、コントローラー／モジュールクラス自体をエントリーポイントとして使用します。

テスト

機能の統合テスト、プラットフォーム／アダプターのテスト、モック検証のパターン、テストの命名規則を含む、言語別のテスト戦略全体については references/testing.md を参照してください。