API 開発

Minimal APIs

Lino はエンドポイント生成のデフォルトとして Minimal API スタイルを採用しており、次を優先します：

• 明確さ – 簡潔で直接的、かつ表現力のあるコード。
• パフォーマンス – 不要なオーバーヘッドのない最適化されたレスポンス。

統合機能

TypedResults：型が強制されたレスポンスを保証し、可読性と OpenAPI 生成に役立ちます。

API バージョン管理：エンドポイントは互換性を壊さずに進化可能です。

充実したドキュメント：設定可能なメタデータが OpenAPI に直接組み込まれ、以下を含みます：

• WithTags → OpenAPI 内でエンドポイントを論理的にグループ化。
• WithName → operationId を一貫して定義。
• WithSummary → エンドポイントの目的を明確に記述。
• Produces(statusCode, schema) → ステータスコードとレスポンス契約を指定。
• MapToApiVersion → 同一エンドポイントの異なるバージョンを公開可能。

Requests と Responses

Record classes はデフォルトで Requests と Responses に使用されます：

• 不変（副作用やバグを減らす）
• 簡潔で読みやすい

CQRS との統合：

• エンドポイント経由で受け取ったリクエストは Commands または Queries に変換されます。
• Commands/Queries の結果は Responses に変換され、アーキテクチャの一貫性を促進します。

簡単な例：
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

新しい API を作成する

Lino の CLI を使ってエンドポイントを作成するのはとても簡単です：

lino new api

対話型ウィザードでは次の内容が求められます：

• サービス – API を作成するサービス。
• モジュール – サービスのモジュール（該当する場合）。
• エンティティ – エンドポイントに関連付けられるエンティティ。
• API 名 – 通常、操作の動詞に合わせます（例: CreatePerson）。
• 操作タイプ – POST、PUT、PATCH、DELETE、または GET。
• ルート – ルートパターン（例: /people/{id}）。

例：

エンティティ Person に関連付けられた CreatePerson という名前の POST API を作成すると、CLI は自動的に次を生成します：

• HTTP マッピングを持つエンドポイント。
• リクエスト/レスポンス DTO。
• OpenAPI との統合およびバージョン管理のための拡張。
• 他のサービスが内部的に利用できる型付き HttpClient。

生成される構造：

MyApp/
└── src/
    ├── Services/
    │   └── MyService/
    │       └── Presentation.API/
    │           ├── MyApp.MyService.Presentation.API.csproj
    │           └── Endpoints/
    │               └── People/
    │                   └── CreatePerson/
    │                       ├── CreatePersonEndpoint.cs
    │                       ├── CreatePersonExtensions.cs
    │                       ├── CreatePersonRequest.cs
    │                       └── CreatePersonResponse.cs
    └── Integrations/
        └── MyService/
            └── Http/
                ├── Contracts/
                │   └── Apis/
                │       └── People/
                │           ├── IPersonHttpClient.cs
                │           └── CreatePerson/
                │               ├── CreatePersonRequest.cs
                │               └── CreatePersonResponse.cs
                └── Clients/
                    └── Apis/
                        └── PersonHttpClient.cs

Source Generators を使用したエンドポイントの登録

Lino はエンドポイントの手動マッピングや実行時の大量の Reflection の使用を不要にします。
代わりに、Source Generators を使用してコンパイル時に自動で登録コードを生成します。

仕組み

作成された各エンドポイントについて、ジェネレーターは MapGet、MapPost、MapPut、MapDelete などを呼び出すクラス/部分クラスを生成します。

これにより、Program.cs にすべてのマッピングを手動で追加する必要がなくなります。

利点：

• コンパイル時登録 → 実行時エラーを防止。
• 簡潔な Program.cs → 手動設定の範囲を最小化。
• AOT 対応 → Reflection への依存を排除。
• 統合ドキュメント → メタデータ(tags、summary、produces) がマッピングと一緒に生成されます。

このモデルにより、Lino で作成された API は以下を保証します：

• 自動ドキュメント化
• 高パフォーマンス
• フレームワークの CQRS アーキテクチャと整合