API の開発

Lino 上のMinimal APIs

LinoはASP.NETコアを採用 Minimal APIs Clean Architecture の境界を壊すことなく、コードを直接的、明示的、かつパフォーマンスに保つため、endpointを生成するための標準として使用されます。

現在の Lino プロジェクトでは、生成されるendpointは、実装するMinimal APIs クラスです。 IEndpoint。各endpointは静的メソッドを公開します MapEndpoint(IEndpointRouteBuilder app) および使用するハンドラー メソッド ISender 生成されたコマンドまたはクエリをアプリケーション層にディスパッチします。

生成された主要な部分

• *Endpoint.cs: メソッド HTTP、ルート、メタデータ、認可、テナント要件、レート制限、およびバージョンをマップします。
• *Request.cs: 本文、クエリ文字列、ルート パラメーター、またはフォーム データからの入力を表します。
• *Extensions.cs: リクエストをコマンド/クエリに変換し、アプリケーションの結果をレスポンス HTTP に変換します。
• *Response.cs: endpointおよびtyped clientsによって返される、厳密に型指定されたコントラクトを定義します。

内蔵機能

Lino が使用する TypedResults そして Results<...> これにより、成功とエラーの応答がコード内で明示され、OpenAPI に正しく表示されます。アプリケーション層からの障害は次のように変換されます。 ProblemDetails 置く result.MapToProblemDetails()。

• WithTags: OpenAPI および Scalar のモジュール、エンティティ、または機能ごとにendpointをグループ化します。
• WithName: 該当する場合、一貫したoperationIdを設定します。
• WithSummary: endpointの目的を明確に説明しています。
• Produces(statusCode, schema): ステータス コードと応答コントラクトを指定します。
• MapToApiVersion(1, 0): endpointを API バージョンに関連付けます。
• RequirePermission、 RequireAuthorization、 AllowAnonymous そして RequireTenant: プロジェクトのオプションに従ってセキュリティを適用します。
• 構成に応じて認証ポリシーまたは匿名ポリシーを使用して、グループまたはendpoint レベルでレート制限を行います。

リクエストとレスポンス

デフォルトでは、Lino は 記録 リクエストとレスポンス用。これらは簡潔で、デフォルトで不変であり、API、typed clients、および外部コンシューマー間の明示的なコントラクトとして適切に機能します。

• endpoint経由で受信したリクエストはコマンドまたはクエリに変換されます。
• コマンドまたはクエリの結果は応答に変換されます。
• ドメイン エンティティは、コントラクト HTTP として直接公開しないでください。

public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

新しい API の作成

ドメイン モデルとユースケースが HTTP によって公開できるほど十分に明確になっている場合は、CLI によって API を作成します。 API は、Minimal APIs、コントラクト、型付きレスポンス、およびドキュメントのメタデータを介して、コマンドとクエリをプレゼンテーション層に接続します。

lino api new
lino api new --name <ApiName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino api list --service <ServiceName> --module <ModuleName> --entity <EntityName>

対話型ウィザードでは次のプロンプトが表示されます。

• サービス: API が作成されるサービス。
• モジュール: サービス モジュール (該当する場合)。
• エンティティまたは列挙: endpointに関連付けられたドメイン要素。
• APIの名前: 通常、次のような操作の動詞と一致します。 CreatePerson。
• 操作の種類: GET、 POST、 PUT、 PATCH、 DELETE、アップロード、ダウンロード、またはendpointのオプション。
• ルート:ルート パターン、ような /people/{id:guid}。
• プロパティ: 実際に HTTP 境界を越える必要があるリクエスト フィールドとレスポンス フィールド。

ウィザードで設定できる内容

• 得る: 単一の結果、リスト、ページ付きリスト、およびオプション/選択シナリオ。
• 役職: コマンド タイプと選択したプロパティを含む、作成およびビジネス アクション。
• 置く そして パッチ: 完全または部分的な更新。
• 消去: 削除コマンドにマップされた削除。
• アップロード: endpoint IFormFile そして DisableAntiforgery() 必要に応じて。
• ダウンロード:endpointを返す FileStreamHttpResult;認証されたプロジェクトは、安全なファイル アクセスのためのトークン endpointを生成できます。
• 列挙: 生成されたクエリと応答ごとに有効なオプションを公開するendpoint。

推奨フロー

1. ユースケースを表すエンティティ、コマンド、クエリを作成または確認します。
2. 走る lino api new 正しいサービス、モジュール、エンティティを選択します。
3. 目的の HTTP 動詞だけでなく、ユースケースに基づいて操作のタイプを選択します。
4. 次のような制約を使用して、安定したルートを定義します。 {id:int} または {id:guid} 適切な場合。
5. HTTP 境界を越える必要があるプロパティのみを選択します。
6. 認可、許可、テナント要件、レート制限、および予期されるステータス コードを定義します。
7. ビルドを実行し、Scalar/OpenAPI を検査して、ルート、概要、バージョン、セキュリティ、生成された応答を確認します。

例: CreatePersonal

API を作成する場合 POST 電話 CreatePerson、エンティティに関連付けられている Person、CLI は、endpoint、request/response contracts、マッピング拡張機能、OpenAPI メタデータ、および対応するコマンドとの統合を生成します。

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Api/
                └── Endpoints/
                    └── People/
                        └── CreatePerson/
                            ├── CreatePersonEndpoint.cs
                            ├── CreatePersonExtensions.cs
                            ├── CreatePersonRequest.cs
                            └── CreatePersonResponse.cs

契約とtyped clients

プロジェクトに Web アプリ Blazor がある場合、Lino は、API の型付き消費のためのアーティファクト (共有コントラクト、クライアント インターフェイス、および HTTP 実装) も生成します。これにより、Blazor は、シンプルで一貫性があり、厳密に型指定された方法でendpointを使用できるようになります。

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            ├── Api.Contracts/
            │   └── Features/
            │       └── People/
            │           ├── CreatePerson/
            │           │   ├── CreatePersonRequest.cs
            │           │   └── CreatePersonResponse.cs
            │           └── IPersonApiClient.cs
            └── Api.Client/
                └── Features/
                    └── PersonApiClient.cs

クライアント インターフェイスは依存関係注入用に登録されており、実装では次を使用します。 HttpClientProvider Tolitech の HTTP ヘルパーを使用して、生成された API を厳密に型指定された方法で呼び出します。

公開前のチェックリスト

• 使用 GET 読書のために、 POST 創作/行動に関しては、 PUT/PATCH 変化と DELETE 意味がある場合は削除します。
• ドメイン エンティティを外部コントラクトとして直接公開しないでください。
• ドキュメントの検証、競合、見つからない、およびアクセス拒否のエラー。
• 使用 api list 同じユースケースでルートの重複や競合するendpointを避けるため。

Source Generator によるendpointの登録

Lino は、Source Generatorsを使用して大きなファイルを手動でマッピングすることを回避します。endpointを 1 つずつリストする代わりに、 Program.cs、ログはコンパイル中に生成されます。

生成されたendpoint クラスの実装 IEndpoint の Tolitech.MinimalApis.Generators.Abstractions。endpointグループの呼び出し MapEndpointsGenerated()によって制作されました。 Tolitech.MinimalApis.Generators、生成されたコードによって新しいendpointが登録されます。

なぜこれが重要なのか

• 手動配線の削減: 開発者は各endpointを手動でマッピングすることを忘れる必要はありません。
• コンパイル時の一貫性: endpointは同じ構造に従い、生成されたコードによって検出されます。
• よりクリーンな起動: Program.cs サービス、ミドルウェア、拡張メソッドを構成するためのセットアップを委任します。
• AOTの互換性: 実行時のリフレクションへの依存を減らします。
• OpenAPI の一貫性: タグ、概要、ステータス コード、およびバージョンはendpointで生成されます。
• 建築の調整: HTTP は API にあり、オーケストレーションは MediatR を経由し、コントラクトはクライアントと共有できます。

実行時の流れ

1. Program.cs アプリケーションを構築し、サービスまたはモジュールのendpointから拡張機能を呼び出します。
2. 拡張機能は、API バージョン セットとendpoint グループを作成し、認可/レート制限を適用して呼び出します。 MapEndpointsGenerated()。
3. 生成されたマッパーはメソッドを呼び出します MapEndpoint 各endpointの。
4. 各endpointは、ルート、OpenAPI メタデータ、権限、テナント要件、およびハンドラーをマップします。
5. ハンドラーは入力 HTTP を受け取り、それをコマンド/クエリに変換し、MediatR に送信して、型指定された結果を返します。

エラーの定義

エラー定義は、既知のドメインおよびアプリケーションの障害を標準化します。これらは、API、ハンドラー、ログ、フロントエンドが、各endpointでの迷走メッセージ、重複文字列、またはアドホックな決定に依存することなく、予測可能な問題を処理するのに役立ちます。

lino error-definition new --name <ErrorDefinitionName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino error-definition list --service <ServiceName> --module <ModuleName> --entity <EntityName>

生成された API では、コマンドおよびクエリによって返される予期されるエラーは次のように変換される必要があります。 ProblemDetails ステータスコード、エラーコード、安全なメッセージが含まれます。サーバーは詳細な技術ログを記録する場合がありますが、HTTP 応答は一貫性があり、安全で、ローカライズ可能である必要があります。

良い習慣

• 予期される再利用可能なエラーのエラー定義を作成します。
• 技術的な例外やインフラストラクチャの詳細をクライアントに返さないようにします。
• フロントエンド、typed clients、テストが安全に反応できるように、安定したエラー コードを維持します。
• endpointが生成できるステータス コードを OpenAPI に文書化します。
• サーバー側のログを使用して、診断の詳細と公開応答の安全なメッセージを取得します。