Travailler avec les événements

Événements de Domaine

Les événements de domaine représentent des faits importants survenus dans le contexte de l'application. Ils sont générés et consommés en interne dans le système, permettant la propagation des changements d'état de manière découplée, c'est-à-dire sans que les objets aient besoin de se connaître directement.

Quand utiliser un Événement de Domaine ?

• Chaque fois qu'une opération génère un changement significatif dans le domaine et qu'il est nécessaire de notifier ou d'activer d'autres parties du système.
• Pour maintenir le modèle de domaine cohésif, permettant à différents processus d'être déclenchés sans créer de dépendances directes entre les modules ou services.

Dans Lino, créer un nouvel événement de domaine est simple. Vous pouvez exécuter :

lino event new

L'assistant CLI demandera :

• Service – Le service dans lequel l'événement sera créé.
• Module – Le module dans lequel l'événement sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle l'événement sera créé/associé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Nom de l'événement – Nom utilisé dans le domaine, associé à l'entité.

Exemple

En créant l'événement de domaine UserCreated associé à l'entité User, le système crée automatiquement un événement nommé UserCreatedDomainEvent. Ce nom indique clairement à toute partie du système consommant l'événement que l'action de création de l'utilisateur a déjà été effectuée.

Structure générée par Lino :

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Domain/
                ├── MyApp.MyService.Domain.csproj
                └── Aggregates/
                    └── Users/
                        ├── User.cs
                        ├── Errors/
                        ├── Events/
                        │   └── UserCreatedDomainEvent.cs
                        ├── Repositories/
                        └── Resources/

Gestionnaires d'Événements de Domaine

Un Domain Event Handler est une classe responsable de réagir à un Événement de Domaine, exécutant des actions liées à l'état interne de l'application, toujours dans le même contexte transactionnel.

L'objectif principal de ces gestionnaires est de maintenir le système cohésif et découplé, permettant l'application de règles supplémentaires sans surcharger la logique centrale de l'entité ou de l'agrégat.

Par exemple, après la création d'un User, il peut être nécessaire de mettre à jour les statistiques, générer un journal interne ou notifier un autre agrégat. Ces actions ont du sens dans le domaine et peuvent se produire de manière synchrone, garantissant une cohérence immédiate.

Cependant, les opérations qui dépendent de ressources externes — telles que l'envoi d'e-mails ou les appels à des API tierces — ne doivent pas être exécutées directement à partir des événements de domaine, car cela lierait la transaction à des tâches lentes ou instables. Dans ces cas, le domaine peut générer un événement d'intégration (enregistré dans l'Outbox), qui sera traité ultérieurement de manière asynchrone et résiliente.

Caractéristiques principales :

• Réagit à un événement mais ne le modifie jamais.
• Exécute uniquement des opérations in-process liées à la cohérence du domaine.
• Garantit que tout s'exécute dans la même transaction.

Pour créer un nouveau gestionnaire d'événements de domaine, il suffit d'exécuter la commande :

lino event-handler new

L'assistant CLI demandera :

• Service – Service dans lequel le gestionnaire d'événements sera créé.
• Module – Module dans lequel le gestionnaire d'événements sera créé (uniquement dans les services modulaires).
• Entité – Entité dans laquelle le gestionnaire d'événements sera créé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Événement – Événement qui sera consommé.
• Nom du gestionnaire d'événements – Nom utilisé qui sera associé à l'entité et à l'événement de domaine.

Exemple

En créant le gestionnaire d'événements de domaine UserCreated associé à l'entité User et à l'événement UserCreatedDomainEvent, le système crée automatiquement un gestionnaire d'événements nommé UserCreatedDomainEventHandler.

Structure générée par Lino :

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Domain/
                        │       └── UserCreatedDomainEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/

Événements d'Intégration

Les événements d'intégration sont des messages indiquant qu'un événement important s'est produit et doivent être partagés avec des systèmes externes ou d'autres microservices.

Contrairement aux événements de domaine, l'objectif ici est la communication entre systèmes et la synchronisation des états.

Quand créer un Événement d'Intégration :

• Lorsque un changement dans votre système doit être reflété dans un autre système.
• Lorsque votre microservice doit publier des changements afin que d'autres microservices puissent réagir.

Principales différences entre les Domain Events et les Integration Events :

Dans Lino, créer un nouvel événement d'intégration est simple. Vous pouvez exécuter :

lino event new

Le assistant CLI demandera :

• Service – Le service dans lequel l'événement sera créé.
• Module – Le module dans lequel l'événement sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle l'événement sera créé / associé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Nom de l'événement – Nom utilisé pour l'événement d'intégration, associé à l'entité.

Exemple

En créant l'événement d'intégration UserCreated associé à l'entité User, le système crée automatiquement un événement nommé UserCreatedIntegrationEvent. Ce nom indique clairement à toute partie du système consommant l'événement que l'action de création de l'utilisateur a déjà été effectuée.

Structure générée par Lino :

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── IntegrationEvents/
                ├── MyApp.MyService.IntegrationEvents.csproj
                └── Users/
                    └── UserCreatedIntegrationEvent.cs

Gestionnaires d'Événements d'Intégration

Un Integration Event Handler est une classe responsable de consommer un Événement d'Intégration, généralement publié par un autre service ou contexte, puis d'exécuter des actions spécifiques dans son propre domaine.

Ces handlers reçoivent les événements via des mécanismes de messagerie (comme RabbitMQ, Kafka, Azure Service Bus, etc.), généralement en combinaison avec le pattern Outbox, qui garantit une livraison fiable et un traitement asynchrone.

Par exemple, lorsqu'un événement UserCreated est publié par un service d'Identité, le handler correspondant dans un autre contexte peut réagir en envoyant un e-mail de bienvenue ou en appelant des APIs externes. Ces opérations peuvent être plus lentes ou sujettes à des erreurs, mais comme elles sont traitées en dehors de la transaction principale, elles ne compromettent pas la cohérence interne de l'application.

Caractéristiques principales :

• Réagit aux événements représentant des faits métier pertinents pour d'autres contextes.
• Exécute des opérations pouvant être lentes ou externes (ex. : envoi d'e-mails, appels à des APIs).
• Est traité de manière asynchrone et résiliente, souvent avec des tentatives de reprise et de la surveillance.
• Garantit que les échecs externes n'affectent pas la transaction d'origine du domaine.
• Facilite l'intégration entre les bounded contexts et les systèmes distribués.

Pour créer un nouveau gestionnaire d'événements d'intégration, il suffit d'exécuter la commande :

lino event-handler

L'assistant CLI demandera :

• Service – Le service dans lequel le gestionnaire d'événements sera créé.
• Module – Le module dans lequel le gestionnaire d'événements sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle le gestionnaire d'événements sera créé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Service – Le service dans lequel existe l'événement à consommer.
• Module – Le module dans lequel existe l'événement à consommer (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle existe l'événement à consommer.
• Événement – L'événement qui sera consommé.
• Nom du gestionnaire d'événement – Nom utilisé qui sera associé à l'entité et à l'événement d'intégration.

Exemple

En créant le gestionnaire d'événement d'intégration SendEmailOnUserCreated associé à l'entité User et à l'événement UserCreatedIntegrationEvent, le système crée automatiquement un gestionnaire d'événement nommé SendEmailOnUserCreatedIntegrationEventHandler.

Structure générée par Lino :

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Integration/
                        │       └── SendEmailOnUserCreatedIntegrationEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/