Définir des cas d'utilisation d'applications

Présentation du cas d'utilisation

Un Cas d'utilisation représente une opération d'application complète : reçoit un modèle d'entrée, valide les données, coordonne les dépendances, invoque le comportement du domaine si nécessaire, conserve ou interroge les données et renvoie un résultat standardisé. C'est là que l'application orchestre un flux métier sans déplacer les invariants en dehors du modèle de domaine.

Dans les solutions générées par Lino, les cas d'utilisation sont regroupés dans le projet d'application selon une structure prévisible :

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

Cette organisation indique clairement à quel service, module et entité appartient chaque fonctionnalité. Il maintient également le modèle d'écriture et le modèle de lecture indépendants, ce qui est utile lorsqu'un écran, API, une intégration ou un processus en arrière-plan n'a besoin que d'un seul côté du comportement.

Command ou Query ?

Qu'est-ce qui appartient au cas d'utilisation de l'application

• Contrat d'entrée: le record de command ou query avec uniquement les données nécessaires à l'opération.
• Validation: règles qui vérifient le format de la demande, les champs obligatoires, les plages, les identifiants, les filtres et autres restrictions de saisie avant que handler exécute le flux.
• Orchestration handler: appels aux dépendances, accès aux référentiels, requêtes contextuelles, utilisation de Unit of Work, composition des résultats, journalisation et traçage.
• Résultat contrat: un petit objet de réponse ou un résultat sans contenu qui donne à caller exactement ce dont il a besoin pour continuer.

Ce qui doit être exclu du cas d'utilisation

• Invariants de domaine doit rester dans les entités, Value Objects, domain services et les méthodes de domaine.
• Détails des infrastructures ils doivent rester derrière les abstractions, les référentiels, les contextes de bases de données, les services de fichiers, les intégrations de messagerie et les clients externes.
• Problèmes de présentation, tels que l'état UI, les étiquettes, les mises en page et le comportement des composants, doivent rester dans la couche de l'application Web.

Un bon cas d'utilisation est explicite, suffisamment petit pour être compris et strict avec des limites : il coordonne le travail, mais ne devient pas un lieu où toutes les règles du système sont mélangées.

Commands

Un Command est un message immuable qui transporte uniquement les données nécessaires pour effectuer une action modifiant l'état du système. Des exemples courants sont CreateCustomer, UpdateVehicle, DeleteMaintenance, ConfirmOrder et SavePermissionsByRoleId. Commands doit être nommé actions car elles indiquent à l'application de faire quelque chose.

Dans Lino, les Commands générés sont des record qui implémentent l'abstraction de command et renvoient un résultat standardisé. La création Commands renvoie généralement un objet résultat avec l'identifiant ou les informations minimales requises par caller, tandis que la mise à jour et la suppression commands renvoient généralement no-content lorsque l'opération se termine avec succès.

Caractéristiques d'un Command

• Immutabilité: mis en œuvre comme record ou cours avec seulement get, sans setters publics mutables.
• Nom à l'impératif: reflète l'action de l'entreprise, telle que CreateOrder, UpdateCustomerAddress ou ChangeProductPrice.
• Données minimales: contient uniquement les champs nécessaires pour effectuer l'opération, sans transporter d'entités entières ni de gros volumes de données.
• Validation isolée: chaque Command a ses propres règles pour garantir que la requête est cohérente avant d'atteindre handler.
• Indépendance de UI: Command représente l'intention de l'application, et non le bouton, le formulaire ou le composant qui a déclenché l'opération.

Quand créer un Command

• Utilisez un Command lorsque les données seront créées, modifiées, supprimées, jointes, importées, approuvées, annulées ou mutées de quelque manière que ce soit.
• Gardez payload concentré sur l’opération ; ne transmettez pas une entité entière lorsque peu de champs suffisent.
• Choisissez des noms qui décrivent l'action commerciale, et non l'événement visuel qui l'a initiée.
• Vérifiez si l'action appartient au module actuel ou si elle doit être exprimée par une intégration, un événement ou une entité fantôme dans un autre module.

Command Validators

Toi Command Validators assurez-vous que Command est bien formé et répond aux conditions d’entrée avant d’être envoyé à handler. Dans Lino, ces validations sont implémentées avec FluentValidation, une bibliothèque commune dans les projets .NET car elle offre un API fluide et lisible pour créer des règles.

Règles de validation communes

• NotEmpty et NotNull pour les champs obligatoires.
• InclusiveBetween pour les plages numériques, les valeurs monétaires, les pourcentages, les quantités minimales et maximales.
• MaximumLength, MinimumLength et Length pour la taille de la chaîne.
• RuleForEach pour valider les éléments de collection, tels que List<T>.
• Must pour les règles personnalisées telles que le format du document, la cohérence des dates et les combinaisons de champs non valides.

validator protège le bord d'attaque. Les invariants de domaine réels, tels que les frontières d'état, les transitions autorisées et les règles qui doivent être valables indépendamment de caller, continuent d'appartenir à aggregate, à l'entité, à Value Object ou à domain service.

Command Handlers

LE Command Handler exécute la logique d'application associée à Command. Il orchestre les référentiels, les contextes, IUnitOfWork, services auxiliaires, journalisation, traçage, appels d'intégration et événements de domaine si nécessaire.

Modèle d'implémentation pour un handler

• Recevez des dépendances via l'injection de dépendances, telles que des référentiels, des services externes, des contextes et Unit of Work.
• Valider l'existence et la disponibilité des données nécessaires à l'opération.
• Chargez le aggregate ou l'entité correcte lorsque l'opération dépend de l'état existant.
• Appelez les méthodes de domaine au lieu de dupliquer les invariants dans handler.
• Persister les changements à travers IUnitOfWork ou des abstractions de persistance de projet.
• Enregistrez le domaine, Outbox ou les événements d'intégration lorsque l'opération doit communiquer avec d'autres parties du système.
• Retour Result ou Result<T> succès, échec connu ou données de réponse minimales.

Command Results et Result Pattern

LE Command Result devrait être un simple DTO avec juste les données nécessaires pour que caller continue. Dans la création, cela inclut généralement le Id généré. Lors de la mise à jour ou de la suppression, il se peut qu'il n'y ait pas de payload. Lorsque l'opération échoue en raison d'une condition attendue, le retour doit contenir des informations d'erreur standardisées.

LE Result Pattern encapsule le résultat d’une opération comme succès ou échec. Au lieu de lever des exceptions pour des scénarios prévisibles comme une entité introuvable, un état invalide ou une validation métier, handler renvoie un type comme Result<T> avec valeur, erreur et métadonnées si nécessaire.

• En cas de succès, le résultat peut révéler un Value, comme un petit DTO ou un identifiant spécialement conçu.
• En cas d'échec, le résultat stocke des codes ou des messages standardisés, souvent définis dans des définitions d'erreur réutilisables.
• Le flux de gestion des erreurs est cohérent entre Application, API, typed clients et UI.

Créer un Command avec CLI

Lino simplifie la génération des artefacts nécessaires pour un nouveau Command via la commande :

lino command new

CLI prend également en charge les options permettant de réduire les questions dans l'assistant :

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 ou --service: service cible.
• -m ou --module: module cible dans les services modularisés.
• -e ou --entity: entité associée à Command.
• -n, --name, -c ou --command: nom de Command.

Lors du flux interactif, Lino confirme le service, le module, l'entité, le nom Command, le type Command et, pour les opérations de création ou de mise à jour, les propriétés qui feront partie de la requête. Les types exposés par CLI sont Créer, Mise à jour et Supprimer.

Après confirmation, Lino crée des fichiers comme :

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

Exemple de structure générée

Considérez Command CreatePerson. La structure générée ressemblera à :

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

Pour une flotte personnalisée Command, la structure suit le même modèle :

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

Responsabilités des fichiers Command

• Command: contrat de demande immuable à l'entrée de l'opération.
• Validator: validation des entrées, généralement avec des règles obligatoires, taille, plage, identifiants et collections.
• Handler: orchestration des référentiels, Unit of Work, contextes, méthodes de domaine, journalisation, traçage et création de résultats.
• Result: Contrat de réponse minimum pour les opérations réussies qui doivent renvoyer des données.

Liste de contrôle de mise en œuvre

1. Courir lino command new et choisissez le service, le module, l'entité, le type et les propriétés appropriés.
2. Ouvrez le Command généré et supprimez tout champ qui ne fait pas partie du contrat d'exploitation.
3. Renforcez validator avec des règles d’entrée commerciale qui ne peuvent pas être automatiquement déduites.
4. Examinez handler et assurez-vous qu'il invoque le comportement du domaine plutôt que de dupliquer les invariants au niveau de la couche application.
5. Utiliser IUnitOfWork pour la persistance et préférez la sauvegarde transactionnelle lorsque l'opération nécessite également des événements ou un Outbox fiable.
6. Échecs de retour dus à des erreurs Result, et non par des exceptions aux résultats commerciaux attendus.
7. Créez et testez le point de terminaison, la page ou l'intégration qui appellera Command.

Queries

Un Query représente l’intention d’obtenir des données sans changer l’état du domaine. Queries sont conçus pour une lecture efficace, renvoyant exactement les champs nécessaires à caller, sans charger des entités entières lorsque cela n'est pas nécessaire.

Des exemples courants sont GetCustomerById, ListCustomers, ListPhoneTypes, ListOrdersByDateRange et un query personnalisé comme GetVehicleAvailability. Un Query doit répondre à une question spécifique à l’application.

Caractéristiques d'un Query

• Immuable: Tout comme Commands, un Query ne doit pas autoriser les modifications une fois créé.
• Nom descriptif: reflète les informations recherchées, telles que GetCustomerById ou ListOrdersByDateRange.
• Filtres et pagination: peut charger les dates, le statut, la page, la taille de la page, le texte de recherche, l'ordre et d'autres paramètres de lecture.
• Projection: doit renvoyer DTO ou afficher le modèle avec uniquement les champs nécessaires, en évitant l'exposition directe des entités de domaine.
• Aucun effet secondaire: vous ne devez pas appeler de méthodes qui changent d'état ou enregistrer les modifications dans la base de données.

Quand créer un Query

• Utilisez un Query lorsque l'opération lit des données et ne doit pas modifier l'état.
• Utilisez un Query à résultat unique pour les écrans de détails, les recherches d'identifiants, les contrôles de disponibilité ou les réponses d'objets.
• Utilisez une liste Query pour les grilles, les listes de sélection, les collections enfants et les contrôles de sélection.
• Utilisez la pagination pour les grilles et les ensembles de données potentiellement volumineux.
• Utilisez des listes simples pour les petites données de référence, les énumérations et les points de terminaison des options.

Query Validators

Toi Query Validators validez les paramètres d'entrée tels que les filtres, les valeurs de pagination, les plages de dates, les identifiants et les règles de visibilité. Ils sont également mis en œuvre avec FluentValidation.

Règles de validation courantes dans Queries

• GreaterThanOrEqualTo et LessThanOrEqualTo pour les filtres de plage tels que les dates de début et de fin.
• Length, MaximumLength et MinimumLength pour les filtres de texte, tels que le nom, l'e-mail ou le terme de recherche.
• InclusiveBetween pour la pagination, la limitation page et pageSize.
• NotEmpty pour les identifiants obligatoires dans les requêtes détaillées.
• Must pour les combinaisons de filtres non valides, telles que la date de fin inférieure à la date de début.

Query Handlers

LE Query Handler interroge les référentiels ou le contexte de la base de données et renvoie des projections optimisées. Dans Lino, il est recommandé d'utiliser des projections avec Select, des filtres explicites, un ordre prévisible et des lectures non suivies le cas échéant.

Le handler de Query doit être read-only : il n'appelle pas de méthodes de domaine changeant d'état, ne déclenche pas de modifications persistantes et ne s'exécute pas. SaveChanges. Si une lecture doit enregistrer un audit, lancer une intégration ou recalculer l'état, cela indique généralement un autre cas d'utilisation ou un processus distinct.

Query Results

Dans Lino, les résultats de Queries sont représentés par des record nommés avec le suffixe QueryResult. Cette convention s'applique aux réponses uniques, aux listes simples, aux listes paginées ou aux processus DTO, API spécifiques à l'écran, aux processus d'intégration ou d'arrière-plan.

Les données de requête Result doivent être des contrats stables en lecture. Traitez-les comme DTOs conçu pour le consommateur, et non comme un raccourci pour exposer directement les entités de domaine.

Créer un Query avec CLI

Semblable à Commands, Lino fournit la commande :

lino query new

CLI accepte également des options telles que :

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 ou --service: service cible.
• -m ou --module: module cible.
• -e ou --entity: entité associée à Query.
• -n, --name, -q ou --query: nom de Query.

Pendant le flux interactif, Lino demande si Query renvoie un résultat unique ou une liste. Lorsque la réponse est une liste, il demande également si elle doit être paginée. Enfin, il permet de sélectionner les propriétés qui doivent être renvoyées ou utilisées par la projection générée.

Lino générera automatiquement :

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

Exemple de structure générée pour Queries

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

Pour une disponibilité de véhicule personnalisée Query, la structure suit le même schéma :

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

Responsabilités des fichiers Query

• Query: contrat de requête immuable avec identifiants, filtres, ordre, pagination ou plages de dates.
• Validator: validation des identifiants, pagination, filtres obligatoires, plages de dates et critères de recherche.
• Handler: lecture de l'orchestration utilisant le contexte d'application, les projections, les filtres, l'ordre, la pagination, la journalisation, le traçage et la création de résultats.
• Result: réponse DTO calquée sur caller, souvent avec des record internes pour les éléments de la liste.

Liste de contrôle de mise en œuvre

1. Courir lino query new et choisissez le service, le module, l'entité, le nom Query, le type de retour, le mode de pagination et les propriétés.
2. Relisez le contrat de demande et ne conservez que les filtres réellement nécessaires pour caller.
3. Renforcez validator, en particulier pour les identifiants requis, les plages de dates, les limites de taille de page et les combinaisons de filtres non valides.
4. Ajustez la projection handler pour renvoyer uniquement les champs requis par UI, API, l'intégration ou le processus en arrière-plan.
5. Conservez Query read-only : n'appelez pas les méthodes de domaine qui modifient l'état et n'enregistrez pas les modifications dans handler.
6. Propager les échecs attendus à travers Result, en utilisant les erreurs standardisées existantes, le cas échéant.
7. Créez et testez le consommateur qui appelle Query, tel que le point de terminaison API, la page Blazor, l'intégration en cours ou typed client.

Exemple de Query personnalisé

Dans le flux d'intégration entre les modules SaaS, une disponibilité personnalisée du véhicule Query peut être créée avec lino query new. La structure générée fournit Query, Handler, Result et Validator. Ensuite, le développeur ajoute les entrées nécessaires, telles que l'identifiant du véhicule, la date de début et la date de fin, valide que la plage est correcte et implémente la logique handler. C'est le flux attendu : générez d'abord la structure cohérente, puis complétez le comportement spécifique au domaine avec du code explicite.

Conclusion

Définir des cas d'utilisation dans Lino transforme le modèle de domaine en opérations d'application claires. Commands gère les changements d'état, Queries gère les lectures, validators protège le front d'entrée, handlers orchestre le flux et les objets de résultat standardisent la sortie.

Le flux le plus rapide a tendance à être : modéliser le domaine, générer les Commands et Queries nécessaires, examiner les fichiers générés, compléter le comportement commercial, exposer le cas d'utilisation via un API ou une page si nécessaire et valider le tout avec la construction et les tests. Cela permet un développement rapide sans perdre le contrôle architectural.

Au fur et à mesure que le projet se développe, concentrez chaque cas d'utilisation sur une intention commerciale, respectez les limites des services et des modules et utilisez des événements, des intégrations ou des entités fantômes lorsqu'un autre module doit participer au processus.