Entwickeln von APIs

Minimal APIs auf Lino

Lino übernimmt ASP.NET Core Minimal APIs als Standard für die Generierung von Endpoints, da sie den Code direkt, explizit und performant halten, ohne die Grenzen von Clean Architecture zu überschreiten.

In aktuellen Lino-Projekten sind generierte Endpoints Minimal API-Klassen, die implementieren IEndpoint. Jeder Endpoint stellt eine statische Methode bereit MapEndpoint(IEndpointRouteBuilder app) und eine Handler-Methode, die verwendet ISender um den generierten Befehl oder die generierte Abfrage an die Anwendungsschicht zu senden.

Hauptteile generiert

• *Endpoint.cs: Ordnet Methode HTTP, Route, Metadaten, Autorisierung, Tenantsanforderung, Ratenbegrenzung und Version zu.
• *Request.cs: Stellt Eingaben dar, die aus dem Textkörper, der Abfragezeichenfolge, Routenparametern oder Formulardaten stammen.
• *Extensions.cs: Konvertiert die Anfrage in einen Befehl/eine Abfrage und konvertiert das Anwendungsergebnis in eine Antwort HTTP.
• *Response.cs: Definiert den stark typisierten Vertrag, der vom Endpoint und den typisierten Clients zurückgegeben wird.

Integrierte Funktionen

Lino verwendet TypedResults Und Results<...> sodass Erfolgs- und Fehlerantworten im Code explizit sind und in OpenAPI korrekt angezeigt werden. Von der Anwendungsschicht kommende Fehler werden konvertiert ProblemDetails setzen result.MapToProblemDetails().

• WithTags: Gruppiert Endpoints nach Modul, Entität oder Feature in OpenAPI und Scalar.
• WithName: Legt gegebenenfalls eine konsistente operationId fest.
• WithSummary: Beschreibt klar den Zweck des Endpoints.
• Produces(statusCode, schema): Gibt Statuscodes und Antwortverträge an.
• MapToApiVersion(1, 0): Ordnet den Endpoint der API-Version zu.
• RequirePermission, RequireAuthorization, AllowAnonymous Und RequireTenant: Sicherheit entsprechend den Projektoptionen anwenden.
• Ratenbegrenzung auf Gruppen- oder Endpointsbene unter Verwendung authentifizierter oder anonymer Richtlinien je nach Konfiguration.

Anfragen und Antworten

Standardmäßig verwendet Lino Aufzeichnungen für Anfragen und Antworten. Sie sind prägnant, standardmäßig unveränderlich und funktionieren gut als explizite Verträge zwischen API, typisierten Kunden und externen Verbrauchern.

• Über den Endpoint empfangene Anfragen werden in Befehle oder Abfragen umgewandelt.
• Ergebnisse von Befehlen oder Abfragen werden in Antworten umgewandelt.
• Domänenentitäten sollten nicht direkt als Vertrag HTTP verfügbar gemacht werden.

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

Erstellen neuer APIs

Erstellen Sie APIs durch CLI, wenn das Domänenmodell und der Anwendungsfall bereits klar genug sind, um durch HTTP verfügbar gemacht zu werden. APIs verbinden Commands und Queries über Minimal APIs, Verträge, typisierte Antworten und Dokumentationsmetadaten mit der Präsentationsschicht.

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

Der interaktive Assistent fordert Sie auf:

• Service: Dienst, in dem API erstellt wird.
• Modul: Servicemodul, falls zutreffend.
• Entität oder Aufzählung: Domänenelement, das dem Endpoint zugeordnet ist.
• Name von API: Normalerweise ausgerichtet auf das Verb der Operation, z. B CreatePerson.
• Art der Operation: GET, POST, PUT, PATCH, DELETE, Upload, Download oder Endpointoptionen.
• Route:Routenmuster, wie /people/{id:guid}.
• Eigenschaften: Anforderungs- und Antwortfelder, die tatsächlich die HTTP-Grenze überschreiten müssen.

Was der Assistent konfigurieren kann

• ERHALTEN: Einzelergebnis, Liste, Seitenliste und Optionen/Szenarien auswählen.
• POST: Erstellungs- und Geschäftsaktionen, einschließlich Befehlstyp und ausgewählte Eigenschaften.
• SETZEN Und PATCH: vollständige oder teilweise Aktualisierung.
• LÖSCHEN: Entfernung zugeordnet, um Befehle zu löschen.
• Hochladen: Endpoints mit IFormFile Und DisableAntiforgery() wenn nötig.
• Herunterladen:Endpoints zurückgeben FileStreamHttpResult; Authentifizierte Projekte können einen Token-Endpoint für sicheren Dateizugriff generieren.
• Aufzählungen: Endpoints, die gültige Optionen pro generierter Abfrage und Antwort bereitstellen.

Empfohlener Durchfluss

1. Erstellen oder überprüfen Sie die Entität, Commands und Queries, die den Anwendungsfall darstellen.
2. Laufen lino api new und wählen Sie den richtigen Dienst, das richtige Modul und die richtige Entität aus.
3. Wählen Sie den Operationstyp nach Anwendungsfall und nicht nur nach dem gewünschten HTTP-Verb.
4. Definieren Sie eine stabile Route unter Verwendung von Einschränkungen wie {id:int} oder {id:guid} wenn es angebracht ist.
5. Wählen Sie nur Eigenschaften aus, die die HTTP-Grenze überschreiten müssen.
6. Definieren Sie Autorisierung, Erlaubnis, Mieteranforderungen, Ratenbegrenzung und erwartete Statuscodes.
7. Führen Sie Build aus und überprüfen Sie Scalar/OpenAPI, um Route, Zusammenfassung, Version, Sicherheit und erzeugte Antworten zu bestätigen.

Beispiel: CreatePerson

Beim Erstellen eines API POST Anruf CreatePerson, mit der Entität verbunden Person, CLI generiert Endpoints, Anforderungs-/Antwortverträge, Zuordnungserweiterungen, OpenAPI-Metadaten und die Integration mit dem entsprechenden Befehl.

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

Verträge und typisierte Kunden

Wenn das Projekt über eine Web-App Blazor verfügt, generiert Lino auch Artefakte für die typisierte Nutzung von APIs: gemeinsame Verträge, Client-Schnittstelle und HTTP-Implementierung. Dadurch kann Blazor Endpoints auf einfache, konsistente und stark typisierte Weise nutzen.

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

Die Client-Schnittstelle ist für die Abhängigkeitsinjektion registriert und wird von der Implementierung verwendet HttpClientProvider mit den HTTP-Helfern von Tolitech, um das generierte API auf stark typisierte Weise aufzurufen.

Checkliste vor der Veröffentlichung

• Verwenden GET zum Lesen, POST für Schöpfung/Aktionen, PUT/PATCH für Veränderung und DELETE zum Entfernen, wenn es sinnvoll ist.
• Stellen Sie Domänenentitäten nicht direkt als externen Vertrag bereit.
• Fehler bei Dokumentvalidierung, Konflikt, nicht gefunden und Zugriff verweigert.
• Verwenden api list um doppelte Routen oder konkurrierende Endpoints für denselben Anwendungsfall zu vermeiden.

Endpointregistrierung mit Source Generators

Lino vermeidet die manuelle Zuordnung großer Dateien mithilfe von Source Generators. Anstatt die Endpoints einzeln aufzulisten Program.cs, das Protokoll wird während der Kompilierung erstellt.

Generierte Endpointklassen werden implementiert IEndpoint von Tolitech.MinimalApis.Generators.Abstractions. Die Endpointgruppenanrufe MapEndpointsGenerated(), produziert von Tolitech.MinimalApis.Generatorsund neue Endpoints werden durch generierten Code registriert.

Warum ist das wichtig?

• Weniger manuelle Verkabelung: Entwickler müssen nicht daran denken, jeden Endpoint manuell zuzuordnen.
• Konsistenz zur Kompilierungszeit: Endpoints folgen derselben Struktur und werden durch generierten Code erkannt.
• Saubererer Start: Program.cs Delegiert das Setup für die Konfiguration von Diensten, Middleware und Erweiterungsmethoden.
• AOT-Kompatibilität: Reduziert die Abhängigkeit von der Reflexion zur Laufzeit.
• OpenAPI konsistent: Tags, Zusammenfassungen, Statuscodes und Version werden am Endpoint generiert.
• Architektonische Ausrichtung: HTTP befindet sich in API, die Orchestrierung erfolgt über MediatR und Verträge können mit Kunden geteilt werden.

Fluss zur Laufzeit

1. Program.cs erstellt die Anwendung und ruft die Erweiterung von den Dienst- oder Modulendpunkten aus auf.
2. Die Erweiterung erstellt den API-Versionssatz und die Endpointgruppe, wendet Autorisierung/Ratenbegrenzung und Aufrufe an MapEndpointsGenerated().
3. Der generierte Mapper ruft die Methode auf MapEndpoint jedes Endpoints.
4. Jeder Endpoint ordnet Route, OpenAPI-Metadaten, Berechtigungen, Tenantsanforderungen und Handler zu.
5. Der Handler empfängt die Eingabe HTTP, wandelt sie in einen Befehl/eine Abfrage um, sendet sie an MediatR und gibt ein typisiertes Ergebnis zurück.

Fehlerdefinitionen

Fehlerdefinitionen standardisieren bekannte Domänen- und Anwendungsfehler. Sie helfen APIs, Handlern, Protokollen und Frontends, vorhersehbare Probleme zu bewältigen, ohne sich auf vereinzelte Nachrichten, doppelte Zeichenfolgen oder Ad-hoc-Entscheidungen an jedem Endpoint verlassen zu müssen.

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

In generierten APIs müssen erwartete Fehler, die von Befehlen und Abfragen zurückgegeben werden, konvertiert werden ProblemDetails mit Statuscode, Fehlercode und sicherer Nachricht. Der Server kann detaillierte technische Protokolle aufzeichnen, aber die HTTP-Antwort muss konsistent, sicher und lokalisierbar bleiben.

Gute Praktiken

• Erstellen Sie Fehlerdefinitionen für erwartete und wiederverwendbare Fehler.
• Vermeiden Sie die Rückgabe technischer Ausnahmen oder Infrastrukturdetails an den Kunden.
• Sorgen Sie für stabile Fehlercodes, damit Frontend, typed clients und Tests sicher reagieren können.
• Dokumentieren Sie in OpenAPI die Statuscodes, die der Endpoint erzeugen kann.
• Verwenden Sie serverseitige Protokolle für Diagnosedetails und sichere Nachrichten in öffentlichen Antworten.