アプリケーション Use Cases の定義

Use Cases の概要

Use Case は、アプリケーションの完全な操作を表します。入力モデルを受け取り、データを検証し、依存関係を調整し、必要に応じてドメインの振る舞いを呼び出し、データを永続化または照会し、標準化された結果を返します。これは、不変条件をドメインモデルの外へ移動させずに、アプリケーションがビジネスフローをオーケストレーションする場所です。

Lino によって生成されたソリューションでは、use cases は予測可能な構造を使ってアプリケーションプロジェクト内にグループ化されます。

src/Services/<ServiceName>/<ModuleName>/Application/UseCases/<EntityName>/
├── Commands/
│   └── <CommandName>/
└── Queries/
    └── <QueryName>/

この整理により、各 feature がどのサービス、モジュール、エンティティに属するかが明確になります。また、書き込みモデルと読み取りモデルを独立させておけるため、画面、API、統合、または background process が振る舞いの片側だけを必要とする場合に役立ちます。

Command か Query か

アプリケーション use case に属するもの

• 入力契約: 操作に必要なデータだけを持つ command または query の record。
• 検証: handler がフローを実行する前に、リクエスト形式、必須フィールド、範囲、識別子、フィルター、その他の入力制約を確認するルール。
• handler のオーケストレーション: 依存関係の呼び出し、リポジトリへのアクセス、コンテキストへの問い合わせ、Unit of Work の使用、結果の組み立て、logging、tracing。
• 結果契約: caller が続行するために必要なものを正確に渡す、小さな応答オブジェクトまたは内容のない結果。

use case の外に置くべきもの

• ドメイン不変条件 は、エンティティ、Value Objects、domain services、ドメインメソッドに残すべきです。
• インフラストラクチャの詳細 は、抽象化、リポジトリ、データベースコンテキスト、ファイルサービス、メッセージング統合、外部 clients の背後に置くべきです。
• プレゼンテーションの関心事、たとえば UI 状態、labels、layouts、コンポーネントの振る舞いは、web app 層に残すべきです。

良い use case は明示的で、理解できるだけ十分に小さく、境界に厳密です。作業を調整しますが、システムのすべてのルールが混ざる場所にはなりません。

Commands

Command は、システムの状態を変更するアクションを実行するために必要なデータだけを運ぶ不変のメッセージです。一般的な例には CreateCustomer、UpdateVehicle、DeleteMaintenance、ConfirmOrder、SavePermissionsByRoleId があります。Commands は、アプリケーションに何かを実行させるものなので、アクションとして命名する必要があります。

Lino で生成される Commands は、command 抽象化を実装し、標準化された結果を返す records です。作成用 Commands は通常、生成された識別子または caller が必要とする最小限の情報を含む結果オブジェクトを返します。一方、更新用および削除用 commands は、操作が正常に完了した場合、通常 no-content を返します。

Command の特徴

• 不変性: record、または get のみを持ち変更可能な public setter を持たないクラスとして実装します。
• 命令形の名前: CreateOrder、UpdateCustomerAddress、ChangeProductPrice のように、ビジネス上のアクションを反映します。
• 最小限のデータ: エンティティ全体や大量のデータを運ばず、操作の実行に必要なフィールドだけを含みます。
• 分離された検証: 各 Command は、handler に到達する前にリクエストの整合性を保証するための独自のルールを持ちます。
• UI からの独立: Command は、操作を起動したボタン、フォーム、コンポーネントではなく、アプリケーションの意図を表します。

Command を作成するタイミング

• データを作成、変更、削除、関連付け、インポート、承認、キャンセル、または何らかの形で変更する場合は Command を使用します。
• payload は操作に集中させます。少数のフィールドで十分な場合に、エンティティ全体を渡さないでください。
• 開始元の視覚的なイベントではなく、ビジネスアクションを説明する名前を優先します。
• そのアクションが現在のモジュールに属するのか、別モジュールの統合、イベント、または shadow entity として表現すべきなのかを見直します。

Command Validators

Command Validators は、Command が handler に送信される前に、正しく形成され、入力要件を満たしていることを保証します。Lino では、これらの検証は FluentValidation で実装されます。FluentValidation は、ルール作成のための流暢で読みやすい API を提供するため、.NET プロジェクトでよく使われるライブラリです。

一般的な検証ルール

• NotEmpty と NotNull は必須フィールドに使用します。
• InclusiveBetween は数値範囲、金額、割合、最小数量、最大数量に使用します。
• MaximumLength、MinimumLength、Length は文字列の長さに使用します。
• RuleForEach は List<T> など、コレクション内の項目を検証するために使用します。
• Must は、文書形式、日付の整合性、無効なフィールドの組み合わせなど、カスタムルールに使用します。

validator は入力境界を保護します。状態の制限、許可される遷移、caller に関係なく成立すべきルールなど、実際のドメイン不変条件は、引き続き aggregate、エンティティ、Value Object、または domain service に属します。

Command Handlers

Command Handler は、Command に関連付けられたアプリケーションロジックを実行します。必要に応じて、リポジトリ、コンテキスト、IUnitOfWork、補助サービス、logging、tracing、統合呼び出し、ドメインイベントをオーケストレーションします。

handler の実装パターン

• リポジトリ、外部サービス、コンテキスト、Unit of Work などの依存関係を依存性注入で受け取ります。
• 操作に必要なデータの存在と利用可能性を検証します。
• 操作が既存の状態に依存する場合は、正しい aggregate またはエンティティを読み込みます。
• handler 内で不変条件を重複させるのではなく、ドメインメソッドを呼び出します。
• IUnitOfWork またはプロジェクトの永続化抽象化を通じて変更を保存します。
• 操作がシステムの他の部分へ通知する必要がある場合は、ドメインイベント、Outbox、または統合を登録します。
• 成功、既知の失敗、または最小限の応答データを含む Result または Result<T> を返します。

Command Results と Result Pattern

Command Result は、caller が続行するために必要なデータだけを持つ単純な DTO であるべきです。作成では、生成された Id を含むことが一般的です。更新または削除では、payload がない場合もあります。操作が想定される条件によって失敗した場合、戻り値は標準化されたエラー情報を保持する必要があります。

Result Pattern は、操作の結果を成功または失敗としてカプセル化します。エンティティが見つからない、状態が無効である、ビジネス検証に失敗するなどの予測可能なシナリオで例外を投げる代わりに、handler は必要に応じて値、エラー、メタデータを持つ Result<T> のような型を返します。

• 成功時、結果は小さな DTO や作成された識別子などの Value を公開できます。
• 失敗時、結果は標準化されたコードまたはメッセージを保持します。多くの場合、それらは再利用可能な error definitions で定義されます。
• エラー処理の流れは、Application、API、typed clients、UI の間で一貫します。

CLI で Command を作成する

Lino は、次のコマンドを通じて新しい Command に必要なアーティファクトの生成を簡単にします。

lino command new

CLI は、アシスタントでの質問を減らすためのオプションも受け付けます。

lino command new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <CommandName>
lino command new --name <CommandName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino command list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s または --service: 対象サービス。
• -m または --module: モジュール化されたサービス内の対象モジュール。
• -e または --entity: Command に関連付けられたエンティティ。
• -n、--name、-c、または --command: Command の名前。

対話フロー中、Lino はサービス、モジュール、エンティティ、Command 名、Command の種類、そして作成または更新操作ではリクエストに含めるプロパティを確認します。CLI が公開する種類は Create、Update、Delete です。

確認後、Lino は次のようなファイルを作成します。

• CreateOrderCommand.cs
• CreateOrderCommandValidator.cs
• CreateOrderCommandHandler.cs
• CreateOrderCommandResult.cs

生成される構造の例

Command CreatePerson を考えます。生成される構造は次のようになります。

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── People/
                        ├── Commands/
                        │   └── CreatePerson/
                        │       ├── CreatePersonCommand.cs
                        │       ├── CreatePersonCommandValidator.cs
                        │       ├── CreatePersonCommandHandler.cs
                        │       └── CreatePersonCommandResult.cs
                        └── Queries/
                            └── ...

fleet のカスタム Command でも、構造は同じパターンに従います。

Application/UseCases/Vehicles/Commands/UpdateVehicle/
├── UpdateVehicleCommand.cs
├── UpdateVehicleCommandValidator.cs
├── UpdateVehicleCommandHandler.cs
└── UpdateVehicleCommandResult.cs

Command ファイルの責務

• Command: 操作の入力を持つ不変のリクエスト契約。
• Validator: 入力検証。通常は必須、長さ、範囲、識別子、コレクションに関するルールを含みます。
• Handler: リポジトリ、Unit of Work、コンテキスト、ドメインメソッド、logging、tracing、結果作成のオーケストレーション。
• Result: データを返す必要がある成功操作のための最小限の応答契約。

実装チェックリスト

1. lino command new を実行し、正しいサービス、モジュール、エンティティ、種類、プロパティを選択します。
2. 生成された Command を開き、操作契約の一部ではないフィールドをすべて削除します。
3. 自動的に推論できないビジネス入力ルールで validator を強化します。
4. handler を見直し、アプリケーション層で不変条件を重複させるのではなく、ドメインの振る舞いを呼び出していることを確認します。
5. 永続化には IUnitOfWork を使用し、操作がイベントまたは信頼性の高い Outbox も必要とする場合は、トランザクション保存を優先します。
6. 想定されるビジネス結果については、例外ではなく Result のエラーとして失敗を返します。
7. Command を呼び出す endpoint、ページ、または統合をビルドしてテストします。

Queries

Query は、ドメインの状態を変更せずにデータを取得する意図を表します。Queries は効率的な読み取りのために設計され、不要な場合にエンティティ全体を読み込まず、caller に必要なフィールドだけを返します。

一般的な例には GetCustomerById、ListCustomers、ListPhoneTypes、ListOrdersByDateRange、そして GetVehicleAvailability のようなカスタム query があります。Query は、アプリケーションの具体的な問いに答えるべきです。

Query の特徴

• 不変: Commands と同様に、Query は作成後の変更を許可すべきではありません。
• 説明的な名前: GetCustomerById や ListOrdersByDateRange のように、取得する情報を反映します。
• フィルターとページング: 日付、ステータス、ページ、ページサイズ、検索テキスト、並び順、その他の読み取りパラメーターを持つことができます。
• プロジェクション: 必要なフィールドだけを持つ DTO または view model を返し、ドメインエンティティの直接公開を避けるべきです。
• 副作用なし: 状態を変更するメソッドを呼び出したり、データベースに変更を保存したりすべきではありません。

Query を作成するタイミング

• 操作がデータを読み取り、状態を変更すべきでない場合は Query を使用します。
• 詳細画面、識別子による検索、可用性チェック、または単一オブジェクトの応答には、単一結果の Query を使用します。
• grids、選択肢リスト、子コレクション、選択コントロールには、リスト Query を使用します。
• grids や潜在的に大きなデータセットにはページングを使用します。
• 小さな参照データ、列挙、オプション endpoints には単純なリストを使用します。

Query Validators

Query Validators は、フィルター、ページング値、日付範囲、識別子、可視性ルールなどの入力パラメーターを検証します。これらも FluentValidation で実装されます。

Queries で一般的な検証ルール

• GreaterThanOrEqualTo と LessThanOrEqualTo は、開始日と終了日などの範囲フィルターに使用します。
• Length、MaximumLength、MinimumLength は、名前、メール、検索語などのテキストフィルターに使用します。
• InclusiveBetween はページングに使用し、page と pageSize を制限します。
• NotEmpty は詳細照会で必須となる識別子に使用します。
• Must は、終了日が開始日より前である場合など、無効なフィルターの組み合わせに使用します。

Query Handlers

Query Handler は、リポジトリまたはデータベースコンテキストを照会し、最適化されたプロジェクションを返します。Lino では、Select によるプロジェクション、明示的なフィルター、予測可能な並び順、適切な場合の tracking なしの読み取りを使うことを推奨します。

Query の handler は read-only でなければなりません。状態を変更するドメインメソッドを呼び出さず、永続的な変更を発生させず、SaveChanges を実行しません。読み取りが監査記録、統合の開始、または状態の再計算を必要とする場合、それは通常、別の use case または分離されたプロセスを示します。

Query Results

Lino では、Queries の結果は QueryResult サフィックスを持つ records で表されます。この規約は、単一応答、単純なリスト、ページングされたリスト、または画面、API、統合、background process 向けの特定 DTO に適用されます。

Query results は安定した読み取り契約であるべきです。ドメインエンティティを直接公開する近道としてではなく、コンシューマー向けに設計された DTOs として扱います。

CLI で Query を作成する

Commands と同様に、Lino は次のコマンドを提供します。

lino query new

CLI は次のようなオプションも受け付けます。

lino query new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <QueryName>
lino query new --name <QueryName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino query list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s または --service: 対象サービス。
• -m または --module: 対象モジュール。
• -e または --entity: Query に関連付けられたエンティティ。
• -n、--name、-q、または --query: Query の名前。

対話フロー中、Lino は Query が単一結果を返すのかリストを返すのかを尋ねます。答えがリストの場合、ページングすべきかどうかも尋ねます。最後に、返すべき、または生成されたプロジェクションで使用すべきプロパティを選択できます。

Lino は自動的に次を生成します。

• GetOrderByIdQuery.cs
• GetOrderByIdQueryValidator.cs
• GetOrderByIdQueryHandler.cs
• GetOrderByIdQueryResult.cs

Queries の生成構造の例

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Orders/
                        ├── Commands/
                        |   └── ...
                        └── Queries/
                            └── GetOrderById/
                                ├── GetOrderByIdQuery.cs
                                ├── GetOrderByIdQueryValidator.cs
                                ├── GetOrderByIdQueryHandler.cs
                                └── GetOrderByIdQueryResult.cs

車両可用性のカスタム Query でも、構造は同じパターンに従います。

Application/UseCases/Vehicles/Queries/GetVehicleAvailability/
├── GetVehicleAvailabilityQuery.cs
├── GetVehicleAvailabilityQueryValidator.cs
├── GetVehicleAvailabilityQueryHandler.cs
└── GetVehicleAvailabilityQueryResult.cs

Query ファイルの責務

• Query: 識別子、フィルター、並び順、ページング、または日付範囲を持つ不変のリクエスト契約。
• Validator: 識別子、ページング、必須フィルター、日付範囲、検索条件の検証。
• Handler: アプリケーションコンテキスト、プロジェクション、フィルター、並び順、ページング、logging、tracing、結果作成を使った読み取りのオーケストレーション。
• Result: caller 向けにモデリングされた応答 DTO。多くの場合、リスト項目用の内部 records を持ちます。

実装チェックリスト

1. lino query new を実行し、サービス、モジュール、エンティティ、Query 名、戻り値の種類、ページングモード、プロパティを選択します。
2. リクエスト契約を見直し、caller に本当に必要なフィルターだけを残します。
3. 特に必須識別子、日付範囲、page size の制限、無効なフィルターの組み合わせについて、validator を強化します。
4. handler のプロジェクションを調整し、UI、API、統合、または background process が要求するフィールドだけを返します。
5. Query を read-only に保ちます。状態を変更するドメインメソッドを呼び出さず、handler で変更を保存しません。
6. 想定される失敗は Result で伝播し、適切な場合は既存の標準化されたエラーを使用します。
7. API endpoint、Blazor ページ、in-process 統合、typed client など、Query を呼び出すコンシューマーをビルドしてテストします。

カスタム Query の例

SaaS のモジュール間統合フローでは、車両可用性のカスタム Query を lino query new で作成できます。生成される構造は Query、Handler、Result、Validator を提供します。その後、開発者は車両識別子、開始日、終了日などの必要な入力を追加し、範囲が正しいことを検証し、handler のロジックを実装します。これが期待される流れです。まず一貫した構造を生成し、その後、明示的なコードでドメイン固有の振る舞いを完成させます。

まとめ

Lino で use cases を定義することは、ドメインモデルを明確なアプリケーション操作に変換することです。Commands は状態変更を扱い、Queries は読み取りを扱い、validators は入力境界を保護し、handlers はフローをオーケストレーションし、結果オブジェクトは出力を標準化します。

最も速い流れは通常、ドメインをモデリングし、必要な Commands と Queries を生成し、生成されたファイルを見直し、ビジネスの振る舞いを完成させ、必要に応じて API またはページで use case を公開し、build と tests ですべてを検証することです。これにより、アーキテクチャ上の制御を失わずに開発速度を保てます。

プロジェクトが成長するにつれて、各 use case を 1 つのビジネス意図に集中させ、サービスとモジュールの境界を尊重し、別のモジュールがプロセスに参加する必要がある場合はイベント、統合、または shadow entities を使用します。