Anwendungsfälle definieren

Anwendungsfallübersicht

Eins Anwendungsfall stellt einen vollständigen Anwendungsvorgang dar: empfängt ein Eingabemodell, validiert die Daten, koordiniert Abhängigkeiten, ruft bei Bedarf Domänenverhalten auf, behält Daten bei oder fragt sie ab und gibt ein standardisiertes Ergebnis zurück. Hier orchestriert die Anwendung einen Geschäftsablauf, ohne Invarianten aus dem Domänenmodell zu verschieben.

In von Lino generierten Lösungen werden Anwendungsfälle im Anwendungsprojekt anhand einer vorhersehbaren Struktur gruppiert:

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

Diese Organisation macht deutlich, zu welchem ​​Dienst, Modul und welcher Entität jedes Feature gehört. Außerdem bleibt das Schreibmodell und das Lesemodell unabhängig, was nützlich ist, wenn ein Bildschirm, API, eine Integration oder ein Hintergrundprozess nur eine Seite des Verhaltens benötigt.

Command oder Query?

Was zum Anwendungsfall gehört

• Eintrittsvertrag: der record von command oder query mit nur den für den Vorgang erforderlichen Daten.
• Validierung: Regeln, die das Anforderungsformat, erforderliche Felder, Bereiche, Bezeichner, Filter und andere Eingabebeschränkungen überprüfen, bevor handler den Flow ausführt.
• handler-Orchestrierung: Aufrufe von Abhängigkeiten, Zugriff auf Repositorys, Kontextabfragen, Verwendung von Unit of Work, Ergebniszusammensetzung, Protokollierung und Ablaufverfolgung.
• Ergebnisvertrag: ein kleines Antwortobjekt oder inhaltsloses Ergebnis, das caller genau das gibt, was es zum Fortfahren benötigt.

Was sollte im Anwendungsfall weggelassen werden?

• Domäneninvarianten muss in Entitäten, Value Objects, Domänendiensten und Domänenmethoden verbleiben.
• Details zur Infrastruktur Sie müssen hinter Abstraktionen, Repositorys, Datenbankkontexten, Dateidiensten, Messaging-Integrationen und externen Clients bleiben.
• Bedenken hinsichtlich der PräsentationB. UI-Status, Beschriftungen, Layouts und Komponentenverhalten, müssen in der Web-App-Ebene verbleiben.

Ein guter Anwendungsfall ist explizit, klein genug, um verstanden zu werden, und streng mit Grenzen: Er koordiniert die Arbeit, wird aber nicht zu einem Ort, an dem alle Systemregeln durcheinander geraten.

Commands

Eins Command ist eine unveränderliche Nachricht, die nur die Daten enthält, die zum Ausführen einer Aktion erforderlich sind, die den Zustand des Systems ändert. Gängige Beispiele sind CreateCustomer, UpdateVehicle, DeleteMaintenance, ConfirmOrder Und SavePermissionsByRoleId. Commands sollten benannte Aktionen sein, da sie der Anwendung mitteilen, etwas zu tun.

In Lino, Commands werden records generiert, die die Abstraktion von command implementieren und ein standardisiertes Ergebnis zurückgeben. Die Erstellung Commands gibt normalerweise ein Ergebnisobjekt mit dem Bezeichner oder den Mindestinformationen zurück, die für caller erforderlich sind, während das Aktualisieren und Löschen commands normalerweise no-content zurückgibt, wenn der Vorgang erfolgreich abgeschlossen wurde.

Merkmale eines Command

• Unveränderlichkeit: implementiert als record oder Klasse mit nur get, ohne veränderliche öffentliche Setter.
• Name im Imperativ: spiegelt geschäftliche Maßnahmen wider, wie z CreateOrder, UpdateCustomerAddress oder ChangeProductPrice.
• Mindestdaten: Enthält nur die Felder, die zum Ausführen des Vorgangs erforderlich sind, ohne dass ganze Entitäten oder große Datenmengen transportiert werden.
• Isolierte Validierung: Jeder Command hat seine eigenen Regeln, um sicherzustellen, dass die Anfrage konsistent ist, bevor sie handler erreicht.
• Unabhängigkeit von UI: Command stellt die Absicht der Anwendung dar, nicht die Schaltfläche, das Formular oder die Komponente, die den Vorgang ausgelöst hat.

Wann muss ein Command erstellt werden?

• Verwenden Sie einen Command, wenn Daten erstellt, geändert, entfernt, verbunden, importiert, genehmigt, storniert oder auf irgendeine Weise verändert werden.
• Konzentrieren Sie payload auf den Vorgang. Übergeben Sie nicht eine ganze Entität, wenn nur wenige Felder ausreichen.
• Wählen Sie Namen, die die Geschäftsaktion beschreiben, nicht das visuelle Ereignis, das sie ausgelöst hat.
• Überprüfen Sie, ob die Aktion zum aktuellen Modul gehört oder ob sie durch Integration, Ereignis oder Schattenentität in einem anderen Modul ausgedrückt werden soll.

Command Validators

Du Command Validators Stellen Sie sicher, dass Command wohlgeformt ist und die Einreisebestimmungen erfüllt, bevor es an handler gesendet wird. In Lino werden diese Validierungen mit implementiert FluentValidation, eine gemeinsame Bibliothek in .NET-Projekten, da sie ein flüssiges und lesbares API zum Erstellen von Regeln bietet.

Gemeinsame Validierungsregeln

• NotEmpty Und NotNull für Pflichtfelder.
• InclusiveBetween für Zahlenbereiche, Geldwerte, Prozentsätze, Mindest- und Höchstmengen.
• MaximumLength, MinimumLength Und Length für die Saitengröße.
• RuleForEach zur Validierung von Sammlungsgegenständen, wie z List<T>.
• Must für benutzerdefinierte Regeln wie Dokumentformat, Datumskonsistenz und ungültige Feldkombinationen.

validator schützt die Vorderkante. Tatsächliche Domäneninvarianten wie Zustandsgrenzen, zulässige Übergänge und Regeln, die unabhängig von caller gelten müssen, gehören weiterhin zum aggregate, zur Entität, zum Value Object oder zum Domänendienst.

Command Handlers

DER Command Handler führt die mit Command verknüpfte Anwendungslogik aus. Es orchestriert Repositories, Kontexte, IUnitOfWork, Hilfsdienste, Protokollierung, Ablaufverfolgung, Integrationsaufrufe und Domänenereignisse bei Bedarf.

Implementierungsmuster für einen handler

• Empfangen Sie Abhängigkeiten über die Abhängigkeitsinjektion, z. B. Repositorys, externe Dienste, Kontexte und Unit of Work.
• Überprüfen Sie die Existenz und Verfügbarkeit der für den Vorgang erforderlichen Daten.
• Laden Sie den richtigen aggregate oder die richtige Entität, wenn der Vorgang vom vorhandenen Status abhängt.
• Rufen Sie Domänenmethoden auf, anstatt Invarianten in handler zu duplizieren.
• Behalten Sie Änderungen bei IUnitOfWork oder Projektpersistenzabstraktionen.
• Protokollieren Sie Domänen-, Outbox- oder Integrationsereignisse, wenn der Vorgang mit anderen Teilen des Systems kommunizieren muss.
• Zurückkehren Result oder Result<T> Erfolg, bekannter Fehler oder minimale Antwortdaten.

Command Results und Result Pattern

DER Command Result sollte ein einfacher DTO mit nur den Daten sein, die für den Fortgang von caller erforderlich sind. In der Schöpfung umfasst es normalerweise die Id generiert. Beim Aktualisieren oder Löschen ist möglicherweise kein payload vorhanden. Wenn der Vorgang aufgrund einer erwarteten Bedingung fehlschlägt, muss die Rückgabe standardisierte Fehlerinformationen enthalten.

DER Result Pattern kapselt das Ergebnis einer Operation als Erfolg oder Misserfolg. Anstatt Ausnahmen für vorhersehbare Szenarien wie nicht gefundene Entität, ungültigen Status oder Geschäftsvalidierung auszulösen, gibt handler einen Typ wie „ Result<T> mit Wert, Fehler und Metadaten, sofern erforderlich.

• Bei Erfolg kann das Ergebnis Folgendes anzeigen: Value, wie etwa ein kleiner DTO oder ein manipulierter Bezeichner.
• Bei einem Fehler werden im Ergebnis standardisierte Codes oder Meldungen gespeichert, die häufig in wiederverwendbaren Fehlerdefinitionen definiert sind.
• Der Fehlerbehandlungsablauf ist zwischen Application, API, typed clients und UI konsistent.

Erstellen eines Command mit CLI

Lino vereinfacht die Generierung der notwendigen Artefakte für ein neues Command durch den Befehl:

lino command new

CLI unterstützt auch Optionen zur Reduzierung von Fragen im Assistenten:

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 oder --service: Zieldienst.
• -m oder --module: Zielmodul in modularisierten Diensten.
• -e oder --entity: Entität, die mit Command verknüpft ist.
• -n, --name, -c oder --command: Name von Command.

Während des interaktiven Ablaufs bestätigt Lino Dienst, Modul, Entität, Command-Name, Command-Typ und bei Erstellungs- oder Aktualisierungsvorgängen die Eigenschaften, die Teil der Anforderung sein werden. Die von CLI bereitgestellten Typen sind Erstellen, Aktualisieren Und Löschen.

Nach der Bestätigung erstellt Lino Dateien wie:

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

Beispiel einer generierten Struktur

Betrachten Sie Command CreatePerson. Die generierte Struktur sieht folgendermaßen aus:

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

Für eine angepasste Flotte Command folgt die Struktur demselben Muster:

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

Verantwortlichkeiten von Command-Dateien

• Command: unveränderlicher Anforderungsvertrag mit der Eingabe der Operation.
• Validator: Eingabevalidierung, typischerweise mit verbindlichen Regeln, Größe, Bereich, Bezeichnern und Sammlungen.
• Handler: Orchestrierung von Repositorys, Unit of Work, Kontexten, Domänenmethoden, Protokollierung, Ablaufverfolgung und Ergebniserstellung.
• Result: Mindestantwortvertrag für erfolgreiche Vorgänge, die Daten zurückgeben müssen.

Checkliste für die Umsetzung

1. Laufen lino command new und wählen Sie den richtigen Dienst, das richtige Modul, die richtige Entität, den richtigen Typ und die richtigen Eigenschaften aus.
2. Öffnen Sie den generierten Command und entfernen Sie alle Felder, die nicht Teil des Betriebsvertrags sind.
3. Stärken Sie validator mit Geschäftseintrittsregeln, die nicht automatisch abgeleitet werden können.
4. Überprüfen Sie handler und stellen Sie sicher, dass es Domänenverhalten hervorruft, anstatt Invarianten auf der Anwendungsebene zu duplizieren.
5. Verwenden IUnitOfWork für Persistenz und bevorzugen transaktionales Speichern, wenn der Vorgang auch Ereignisse oder zuverlässige Outbox erfordert.
6. Rückgabefehler aufgrund von Fehlern Result, nicht durch Ausnahmen von den erwarteten Geschäftsergebnissen.
7. Erstellen und testen Sie den Endpunkt, die Seite oder die Integration, die Command aufruft.

Queries

Eins Query stellt die Absicht dar, Daten abzurufen, ohne den Status der Domäne zu ändern. Queries sind für effizientes Lesen konzipiert und geben genau die von caller benötigten Felder zurück, ohne ganze Entitäten zu laden, wenn dies nicht erforderlich ist.

Gängige Beispiele sind GetCustomerById, ListCustomers, ListPhoneTypes, ListOrdersByDateRange und ein benutzerdefiniertes query-Gefällt mir GetVehicleAvailability. Ein Query muss eine anwendungsspezifische Frage beantworten.

Merkmale eines Query

• Unveränderlich: Genau wie Commands darf ein Query nach seiner Erstellung keine Änderungen zulassen.
• Beschreibender Name: spiegelt die gesuchten Informationen wider, z GetCustomerById oder ListOrdersByDateRange.
• Filter und Paginierung: kann Daten, Status, Seite, Seitengröße, Suchtext, Reihenfolge und andere Leseparameter laden.
• Vorsprung: muss DTO zurückgeben oder das Modell nur mit den erforderlichen Feldern anzeigen, um eine direkte Offenlegung von Domänenentitäten zu vermeiden.
• Keine Nebenwirkungen: Sie dürfen keine Methoden aufrufen, die den Status ändern oder Änderungen in der Datenbank speichern.

Wann muss ein Query erstellt werden?

• Verwenden Sie einen Query, wenn der Vorgang Daten liest und den Status nicht ändern soll.
• Verwenden Sie einen Einzelergebnis-Query für Detailbildschirme, Bezeichnersuchen, Verfügbarkeitsprüfungen oder Objektantworten.
• Verwenden Sie eine Liste Query für Raster, Auswahllisten, untergeordnete Sammlungen und Auswahlsteuerelemente.
• Verwenden Sie Paginierung für Raster und potenziell große Datensätze.
• Verwenden Sie einfache Listen für kleine Referenzdaten, Aufzählungen und Optionsendpunkte.

Query Validators

Du Query Validators Validieren Sie Eingabeparameter wie Filter, Paginierungswerte, Datumsbereiche, Bezeichner und Sichtbarkeitsregeln. Sie werden auch mit implementiert FluentValidation.

Allgemeine Validierungsregeln in Queries

• GreaterThanOrEqualTo Und LessThanOrEqualTo für Bereichsfilter wie Start- und Enddatum.
• Length, MaximumLength Und MinimumLength für Textfilter wie Name, E-Mail oder Suchbegriff.
• InclusiveBetween für Paging, Begrenzung page Und pageSize.
• NotEmpty für obligatorische Identifikatoren in Detailabfragen.
• Must für ungültige Filterkombinationen, z. B. Enddatum vor dem Startdatum.

Query Handlers

DER Query Handler Fragt Repositorys oder Datenbankkontext ab und gibt optimierte Projektionen zurück. In Lino wird empfohlen, Projektionen mit zu verwenden Select, explizite Filter, vorhersehbare Reihenfolge und gegebenenfalls nicht verfolgte Messwerte.

Der handler von Query muss read-only sein: Er ruft keine zustandsverändernden Domänenmethoden auf, löst keine dauerhaften Änderungen aus und wird nicht ausgeführt SaveChanges. Wenn bei einem Lesevorgang ein Audit protokolliert, eine Integration initiiert oder der Status neu berechnet werden muss, weist dies normalerweise auf einen anderen Anwendungsfall oder einen separaten Prozess hin.

Query Results

In Lino werden Ergebnisse von Queries durch records dargestellt, die mit dem Suffix benannt sind QueryResult. Diese Konvention gilt für Einzelantworten, einfache Listen, Seitenlisten oder bildschirmspezifische DTO, API, Integrations- oder Hintergrundprozesse.

ResultAbfragedaten müssen lesestabile Verträge sein. Behandeln Sie sie als DTOs, die für den Verbraucher entwickelt wurden, und nicht als Abkürzung für die direkte Offenlegung von Domänenentitäten.

Erstellen eines Query mit CLI

Ähnlich wie Commands stellt Lino den Befehl bereit:

lino query new

CLI akzeptiert auch Optionen wie:

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 oder --service: Zieldienst.
• -m oder --module: Zielmodul.
• -e oder --entity: Entität, die mit Query verknüpft ist.
• -n, --name, -q oder --query: Name von Query.

Während des interaktiven Ablaufs fragt Lino, ob Query ein einzelnes Ergebnis oder eine Liste zurückgibt. Wenn es sich bei der Antwort um eine Liste handelt, wird auch gefragt, ob sie paginiert werden soll. Schließlich können Sie die Eigenschaften auswählen, die von der generierten Projektion zurückgegeben oder verwendet werden sollen.

Lino generiert automatisch:

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

Beispiel einer generierten Struktur für Queries

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

Für eine maßgeschneiderte Fahrzeugverfügbarkeit Query folgt die Struktur demselben Muster:

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

Verantwortlichkeiten von Query-Dateien

• Query: unveränderlicher Anforderungsvertrag mit Kennungen, Filtern, Reihenfolge, Paginierung oder Datumsbereichen.
• Validator: Validierung von Bezeichnern, Paginierung, obligatorischen Filtern, Datumsbereichen und Suchkriterien.
• Handler: Lesen der Orchestrierung mithilfe von Anwendungskontext, Projektionen, Filtern, Reihenfolge, Paginierung, Protokollierung, Ablaufverfolgung und Ergebniserstellung.
• Result: Antwort DTO nach dem Vorbild von caller, häufig mit internen records für Listenelemente.

Checkliste für die Umsetzung

1. Laufen lino query new und wählen Sie Dienst, Modul, Entität, Query-Namen, Rückgabetyp, Paging-Modus und Eigenschaften.
2. Überprüfen Sie den Anfragevertrag und behalten Sie nur Filter bei, die für caller wirklich notwendig sind.
3. Stärken Sie validator, insbesondere für erforderliche Kennungen, Datumsbereiche, Seitengrößenbeschränkungen und ungültige Filterkombinationen.
4. Passen Sie die handler-Projektion an, um nur die Felder zurückzugeben, die für UI, API, Integration oder Hintergrundprozess erforderlich sind.
5. Behalten Sie Query read-only bei: Rufen Sie keine Domänenmethoden auf, die den Status ändern, und speichern Sie keine Änderungen in handler.
6. Erwartete Fehler überall verbreiten Result, wobei gegebenenfalls vorhandene standardisierte Fehler verwendet werden.
7. Erstellen und testen Sie den Verbraucher, der Query aufruft, z. B. API Endpunkt, Blazor-Seite, In-Process-Integration oder typed client.

Beispiel für benutzerdefiniertes Query

Im Integrationsfluss zwischen SaaS-Modulen kann eine individuelle Fahrzeugverfügbarkeit Query erstellt werden lino query new. Die generierte Struktur stellt Query, Handler, Result und Validator bereit. Anschließend fügt der Entwickler die erforderlichen Eingaben wie Fahrzeugkennung, Startdatum und Enddatum hinzu, überprüft, ob der Bereich korrekt ist, und implementiert die handler-Logik. Dies ist der erwartete Ablauf: Generieren Sie zuerst die konsistente Struktur und vervollständigen Sie dann das domänenspezifische Verhalten mit explizitem Code.

Abschluss

Durch die Definition von Anwendungsfällen in Lino wird das Domänenmodell in klare Anwendungsoperationen umgewandelt. Commands verarbeitet Zustandsänderungen, Queries verarbeitet Lesevorgänge, validators schützt die Eingabekante, handlers orchestriert den Fluss und Ergebnisobjekte standardisieren die Ausgabe.

Der schnellste Ablauf ist in der Regel: Modellieren Sie die Domäne, generieren Sie die erforderlichen Commands und Queries, überprüfen Sie die generierten Dateien, vervollständigen Sie das Geschäftsverhalten, legen Sie den Anwendungsfall bei Bedarf über einen API oder eine Seite offen und validieren Sie alles mit Build und Tests. Dadurch bleibt die Entwicklung schnell, ohne dass die Kontrolle über die Architektur verloren geht.

Wenn das Projekt wächst, konzentrieren Sie sich bei jedem Anwendungsfall auf eine Geschäftsabsicht, respektieren Sie Service- und Modulgrenzen und nutzen Sie Ereignisse, Integrationen oder Schattenentitäten, wenn ein anderes Modul am Prozess teilnehmen muss.