Développement de API

API minimes sur Lino

Lino adopte le noyau ASP.NET API minimes comme standard pour générer des endpoints, car ils gardent le code direct, explicite et performant sans briser les limites de Clean Architecture.

Dans les projets Lino actuels, les endpoints générés sont des classes minimales API qui implémentent IEndpoint. Chaque endpoint expose une méthode statique MapEndpoint(IEndpointRouteBuilder app) et une méthode de gestionnaire qui utilise ISender pour distribuer la commande ou la requête générée à la couche Application.

Pièces principales générées

• *Endpoint.cs: méthode de cartes HTTP, itinéraire, métadonnées, autorisation, exigences du tenant, limitation de débit et version.
• *Request.cs: représente une entrée provenant du corps, de la chaîne de requête, des paramètres de route ou des données de formulaire.
• *Extensions.cs: convertit la requête en commande/requête et convertit le résultat de l'application en réponse HTTP.
• *Response.cs: définit le contrat fortement typé renvoyé par le endpoint et les typed clients.

Fonctionnalités intégrées

Lino utilise TypedResults et Results<...> afin que les réponses de réussite et d'erreur soient explicites dans le code et apparaissent correctement dans OpenAPI. Les défauts provenant de la couche Application sont convertis en ProblemDetails mettre result.MapToProblemDetails().

• WithTags: regroupe les endpoints par module, entité ou fonctionnalité dans OpenAPI et Scalar.
• WithName: définit un identifiant d'opération cohérent, le cas échéant.
• WithSummary: décrit clairement l'objectif du endpoint.
• Produces(statusCode, schema): spécifie les codes d'état et les contrats de réponse.
• MapToApiVersion(1, 0): associe le endpoint à la version API.
• RequirePermission, RequireAuthorization, AllowAnonymous et RequireTenant: appliquer la sécurité selon les options du projet.
• Limitation du débit au niveau du groupe ou du endpoint, à l'aide de politiques authentifiées ou anonymes selon la configuration.

Demandes et réponses

Par défaut, Lino utilise enregistrements pour les demandes et les réponses. Ils sont concis, immuables par défaut et fonctionnent bien en tant que contrats explicites entre API, les typed clients et les consommateurs externes.

• Les requêtes reçues via le endpoint sont transformées en commandes ou requêtes.
• Les résultats des commandes ou des requêtes sont convertis en réponses.
• Les entités de domaine ne doivent pas être directement exposées en tant que contrat HTTP.

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

Création de nouveaux API

Créez des API par CLI lorsque le modèle de domaine et le cas d'utilisation sont déjà suffisamment clairs pour être exposés par HTTP. Les API connectent les commandes et les requêtes à la couche de présentation via des Minimal APIs, des contrats, des réponses saisies et des métadonnées de documentation.

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

L'assistant interactif vous demandera :

• Service: service dans lequel API sera créé.
• Module: module de service, le cas échéant.
• Entité ou énumération: élément de domaine associé au endpoint.
• Nom de API: normalement aligné avec le verbe de l'opération, tel que CreatePerson.
• Type d'opération: GET, POST, PUT, PATCH, DELETE, options de chargement, de téléchargement ou de endpoint.
• Itinéraire:modèle d'itinéraire, comme /people/{id:guid}.
• Propriétés: champs de requête et de réponse qui doivent effectivement traverser la frontière HTTP.

Ce que l'assistant peut configurer

• OBTENIR: résultat unique, liste, liste paginée et options/sélectionner des scénarios.
• POSTE: création et actions commerciales, y compris le type de commande et les propriétés sélectionnées.
• METTRE et CORRECTIF: mise à jour complète ou partielle.
• SUPPRIMER: suppression mappée pour supprimer les commandes.
• Télécharger: endpoints avec IFormFile et DisableAntiforgery() lorsque cela est nécessaire.
• Télécharger:retour des endpoints FileStreamHttpResult; Les projets authentifiés peuvent générer un endpoint de jeton pour un accès sécurisé aux fichiers.
• Énumérations: endpoints qui exposent des options valides par requête et réponse générées.

Débit recommandé

1. Créez ou examinez l'entité, les commandes et les requêtes qui représentent le cas d'utilisation.
2. Courir lino api new et sélectionnez le service, le module et l'entité corrects.
3. Choisissez le type d'opération par cas d'utilisation, pas seulement par le verbe HTTP souhaité.
4. Définir un itinéraire stable, en utilisant des contraintes telles que {id:int} ou {id:guid} le cas échéant.
5. Sélectionnez uniquement les propriétés qui doivent traverser la limite HTTP.
6. Définissez l’autorisation, la permission, les exigences du tenant, la limitation du débit et les codes d’état attendus.
7. Exécutez build et inspectez Scalar/OpenAPI pour confirmer l'itinéraire, le résumé, la version, la sécurité et les réponses produites.

Exemple : Créer une personne

Lors de la création d'un API POST appel CreatePerson, associé à l'entité Person, CLI génère un endpoint, des contrats de demande/réponse, des extensions de mappage, des métadonnées OpenAPI et une intégration avec la commande correspondante.

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

Contrats et typed clients

Lorsque le projet dispose d'une Web App Blazor, Lino génère également des artefacts pour la consommation typée des API: contrats partagés, interface client et implémentation de HTTP. Cela permet à Blazor de consommer les endpoints d'une manière simple, cohérente et fortement typée.

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

L'interface client est enregistrée pour l'injection de dépendances et l'implémentation utilise HttpClientProvider avec les assistants HTTP de Tolitech pour appeler le API généré d'une manière fortement typée.

Liste de contrôle avant de publier

• Utiliser GET pour la lecture, POST pour la création/actions, PUT/PATCH pour le changement et DELETE pour le retrait lorsque cela a du sens.
• N'exposez pas les entités de domaine directement en tant que contrat externe.
• Erreurs de validation de document, de conflit, d'introuvable et d'accès refusé.
• Utiliser api list pour éviter les routes en double ou les endpoints concurrents pour le même cas d'utilisation.

Enregistrement des endpoints avec les source generators

Lino évite de mapper manuellement des fichiers volumineux à l'aide de source generators. Au lieu de lister les endpoints un par un dans Program.cs, l'enregistrement est produit lors de la compilation.

Implémentation des classes de endpoints générées IEndpoint de Tolitech.MinimalApis.Generators.Abstractions. Le groupe de endpoints appelle MapEndpointsGenerated(), produit par Tolitech.MinimalApis.Generators, et les nouveaux endpoints sont enregistrés par le code généré.

Pourquoi est-ce important

• Moins de câblage manuel: Les développeurs n'ont pas besoin de penser à mapper chaque endpoint manuellement.
• Cohérence au moment de la compilation: les endpoints suivent la même structure et sont découverts par le code généré.
• Démarrage plus propre: Program.cs délègue l'installation pour la configuration des services, des middlewares et des méthodes d'extension.
• Compatibilité AOT: réduit la dépendance à la réflexion au moment de l'exécution.
• OpenAPI cohérent: les balises, les résumés, les codes d'état et la version sont générés au niveau du point final.
• Alignement architectural: HTTP est dans API, l'orchestration passe par MediatR, et les contrats peuvent être partagés avec les clients.

Flux au moment de l'exécution

1. Program.cs construit l'application et appelle l'extension à partir des endpoints du service ou du module.
2. L'extension crée l'ensemble de versions API et le groupe de endpoints, applique l'autorisation/limitation de débit et appelle MapEndpointsGenerated().
3. Le mappeur généré appelle la méthode MapEndpoint de chaque point final.
4. Chaque endpoint mappe l'itinéraire, les métadonnées OpenAPI, l'autorisation, les exigences du tenant et le gestionnaire.
5. Le gestionnaire reçoit l'entrée HTTP, la convertit en commande/requête, l'envoie à MediatR et renvoie un résultat typé.

Définitions des erreurs

Les définitions d'erreurs normalisent les erreurs connues du domaine et de l'application. Ils aident les API, les gestionnaires, les journaux et les interfaces à gérer des problèmes prévisibles sans compter sur des messages parasites, des chaînes en double ou des décisions ad hoc à chaque endpoint.

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

Dans les API générés, les échecs attendus renvoyés par les commandes et les requêtes doivent être convertis en ProblemDetails avec code d'état, code d'erreur et message sécurisé. Le serveur peut enregistrer des journaux techniques détaillés, mais la réponse HTTP doit rester cohérente, sécurisée et localisable.

Bonnes pratiques

• Créez des définitions d'erreur pour les échecs attendus et réutilisables.
• Évitez de renvoyer des exceptions techniques ou des détails d’infrastructure au client.
• Maintenez des codes d'erreur stables afin que le frontend, les clients saisis et les tests puissent réagir en toute sécurité.
• Documentez dans OpenAPI les codes d'état que le endpoint peut produire.
• Utilisez les journaux côté serveur pour les détails de diagnostic et les messages sécurisés dans la réponse publique.