Intégrations internes et externes

Créer des intégrations

Les intégrations représentent une communication explicite avec un autre contexte, un service interne ou un système externe. Elles doivent avoir un nom, un contrat, une authentification, un timeout, une stratégie d’erreur et une responsabilité claire.

lino integration new --name <ServiceName>
lino integration list

Utilisez integration list pour vérifier les intégrations existantes avant d’en créer une autre. Évitez les intégrations génériques, comme CommonIntegration, car elles tendent à accumuler des responsabilités sans limite claire.

Avant de créer une intégration, définissez le problème qu’elle résout : consulter un registre externe, envoyer une facturation, valider un abonnement, synchroniser un utilisateur, consommer un module interne ou publier des données vers un autre système. Si l’intégration n’a pas d’intention spécifique, elle n’est probablement pas encore prête à devenir un contrat généré.

• Nommez par le contexte intégré : préférez Billing, Identity, Catalog ou Shipping aux noms génériques.
• Séparez contrat et implémentation : le domaine et l’application ne doivent pas dépendre directement des détails de transport.
• Supposez les défaillances externes : toute intégration distante peut devenir lente, indisponible, retourner une erreur partielle ou changer son contrat.

Resources d’intégration

Les resources représentent des objets exposés ou consommés par une intégration, comme customers, invoices, tenants, subscriptions, users ou documents.

lino integration resource new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration resource list --service <ServiceName> --module <ModuleName> --entity <EntityName>

Un resource d’intégration n’a pas besoin d’être identique à l’entité de domaine. Il s’agit souvent d’un contrat d’échange de données, d’une vue externe ou d’une représentation minimale nécessaire à la communication entre contextes. Copier toute l’entité dans le contrat externe expose souvent des détails internes et augmente le coût d’évolution.

• Modélisez le resource avec le vocabulaire du système intégré.
• N’exposez pas les entités internes comme contrat externe.
• Définissez quels champs sont des identifiants, des filtres et des données retournées.
• Documentez la pagination, l’authentification et les limites d’appel lorsqu’elles existent.

Lorsque le resource représente des données d’un autre module, incluez seulement ce qui est nécessaire au consommateur. Le même principe apparaît dans les shadow entities : le module consommateur conserve une petite copie locale, alignée sur son propre cas d’utilisation, au lieu de dépendre du modèle complet du module producteur.

Opérations d’intégration

Les opérations décrivent les actions disponibles sur un resource d’intégration : créer, consulter, mettre à jour, annuler, envoyer, synchroniser ou valider.

lino integration operation new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration operation list --service <ServiceName> --module <ModuleName> --entity <EntityName>

Chaque opération doit définir son intention, son entrée, sa sortie, sa méthode d’appel, son comportement d’erreur et si elle peut être réexécutée en sécurité.

• Les requêtes doivent avoir un timeout et une gestion de l’indisponibilité.
• Les commandes distantes doivent être idempotentes lorsque c’est possible.
• Les défaillances externes ne doivent pas casser la transaction principale si le métier accepte un traitement asynchrone.
• Utilisez des logs et un correlation id pour tracer les appels entre systèmes.

L’idempotence est particulièrement importante dans les opérations d’écriture. Si une tentative échoue après que le système externe a exécuté l’action, une nouvelle tentative peut dupliquer une facturation, créer un enregistrement répété ou envoyer un message deux fois. Lorsque c’est possible, utilisez des clés d’idempotence, des identifiants externes ou des règles de réexécution documentées.

Consommer des intégrations

Après avoir modélisé une intégration, un resource et une opération, utilisez la consommation pour connecter l’application au contrat généré. L’objectif est de faire dépendre le cas d’utilisation d’une abstraction nommée, avec une entrée et une sortie prévisibles, au lieu de disperser les appels HTTP, l’assemblage d’URL, les headers, le parsing de réponse et la gestion d’erreur dans plusieurs handlers.

lino integration consume

Les Use Cases doivent dépendre d’abstractions, pas de détails HTTP dispersés dans le code. Cela facilite les tests, le remplacement d’implémentation et la gestion uniforme des défaillances. Cela évite aussi que chaque endpoint de l’application réinvente différemment timeout, authentification, correlation id, sérialisation et mapping d’erreur.

• Validez les données avant d’appeler un service externe.
• Utilisez cancellation token et timeout.
• Mappez les réponses externes vers des erreurs internes prévisibles.
• N’enregistrez pas un payload externe brut comme règle de domaine sans transformation.

HTTP vs. in-process

L’intégration in-process est simple et rapide lorsque les modules s’exécutent ensemble. HTTP crée un contrat plus explicite entre processus, mais ajoute de la latence, des défaillances réseau et un besoin de résilience.

L’intégration in-process ne doit pas signifier un accès libre à tout. Même dans le même runtime, le consommateur doit communiquer par contrat, et non par entité interne, DbContext ou repository d’un autre module. Le coût réseau est plus faible, mais le risque de couplage existe toujours.

HTTP est plus adapté lorsque le producteur et le consommateur ont des runtimes séparés ou lorsque vous voulez rendre la frontière opérationnellement explicite. In-process est adapté lorsque la même application héberge les contextes et que la réponse doit être immédiate, à condition que la dépendance reste déclarée par contrat.

Événements vs. intégrations synchrones

Utilisez une intégration synchrone lorsque la réponse est nécessaire pour terminer l’opération en cours. Utilisez un événement lorsque le consommateur peut réagir plus tard et que la consistance éventuelle est acceptable.

Ce choix est une décision métier avant d’être une décision technique. Si une commande ne peut être créée qu’après confirmation d’autorisation par le service de paiement, l’appel synchrone peut être une partie essentielle du cas d’utilisation. Si la création de la commande doit seulement déclencher une notification, une mise à jour de projection ou une synchronisation vers un autre module, un événement tend à être plus approprié.