이벤트 다루기

도메인 이벤트

도메인 이벤트는 애플리케이션 컨텍스트 내에서 발생한 중요한 사실을 나타냅니다. 이 이벤트는 시스템 내부에서 생성 및 소비되며, 상태 변경을 느슨하게 결합된 방식으로 전파할 수 있습니다. 즉, 객체들이 서로를 직접 알 필요가 없습니다.

도메인 이벤트를 언제 사용해야 하나요?

• 어떤 작업이 도메인에 중요한 변화를 일으키고, 시스템의 다른 부분에 알림 또는 트리거가 필요할 때.
• 도메인 모델의 응집력을 유지하고, 서로 직접 의존하지 않고도 다양한 프로세스를 트리거할 수 있도록 할 때.

Lino에서는 새로운 도메인 이벤트를 쉽게 생성할 수 있습니다. 다음 명령을 실행하세요:

lino event new
lino event new --name <EventName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event edit --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event list --service <ServiceName> --module <ModuleName> --entity <EntityName>

CLI 마법사가 다음을 요청합니다:

• 서비스 – 이벤트가 생성될 서비스.
• 모듈 – 이벤트가 생성될 모듈(모듈형 서비스만 해당).
• 엔티티 – 이벤트가 생성/연결될 엔티티.
• 이벤트 유형 – 도메인 이벤트 또는 통합 이벤트.
• 이벤트 이름 – 도메인에서 사용되며 엔티티와 연결되는 이름.

예시

User 엔티티와 연결된 도메인 이벤트 UserCreated를 생성하면, 시스템은 자동으로 UserCreatedDomainEvent라는 이름의 이벤트를 생성합니다. 이 이름은 이벤트를 소비하는 시스템의 어느 부분에서도 사용자 생성 작업이 이미 완료되었음을 명확히 보여줍니다.

Lino가 생성한 구조:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Domain/
                ├── <ProjectName>.<ServiceName>.Domain.csproj
                └── Aggregates/
                    └── Users/
                        ├── User.cs
                        ├── Errors/
                        ├── Events/
                        │   └── UserCreatedDomainEvent.cs
                        ├── Repositories/
                        └── Resources/

Technical flow in Lino

1. The aggregate registers an IDomainEvent with RegisterDomainEvent.
2. The command handler saves through IUnitOfWork, preferably SaveChangesInTransactionAsync when events are involved.
3. The Unit of Work persists changes and publishes events through MediatR.
4. A domain handler can register an integration event in IOutbox.

Events are not commands; use past-tense names such as UserCreatedDomainEvent.

도메인 이벤트 핸들러

Domain Event Handler는 도메인 이벤트에 반응하고 애플리케이션 내부 상태와 관련된 작업을 수행하는 클래스이며, 항상 동일한 트랜잭션 컨텍스트 내에서 실행됩니다.

이러한 핸들러의 주요 목적은 시스템을 응집력 있고 느슨하게 결합된 상태로 유지하여 엔티티나 애그리게이트의 핵심 로직을 과부하하지 않고 추가 규칙을 적용할 수 있도록 하는 것입니다.

예를 들어 User를 생성한 후 통계를 업데이트하거나 내부 로그를 생성하거나 다른 애그리게이트에 알림을 보내야 할 수 있습니다. 이러한 작업은 도메인 내에서 의미가 있으며 동기적으로 수행될 수 있어 즉각적인 일관성을 보장합니다.

그러나 외부 리소스에 의존하는 작업 — 이메일 전송 또는 서드파티 API 호출 등 — 은 도메인 이벤트에서 직접 수행해서는 안 됩니다. 이렇게 하면 트랜잭션이 느리거나 불안정한 작업에 묶이게 되기 때문입니다. 이 경우 도메인은 통합 이벤트(Outbox에 기록)를 생성하고 나중에 비동기적이고 회복력 있게 처리됩니다.

주요 특징:

• 이벤트에 반응하지만 절대 수정하지 않습니다.
• 도메인 일관성과 관련된 인프로세스 작업만 수행합니다.
• 모든 작업이 동일한 트랜잭션 내에서 실행되도록 보장합니다.

새로운 도메인 이벤트 핸들러를 생성하려면 다음 명령어를 실행하세요:

lino event-handler new

CLI 마법사가 다음을 요청합니다:

• 서비스 – 이벤트 핸들러가 생성될 서비스.
• 모듈 – 이벤트 핸들러가 생성될 모듈(모듈형 서비스에서만 해당).
• 엔티티 – 이벤트 핸들러가 생성될 엔티티.
• 이벤트 유형 – 도메인 이벤트 또는 통합 이벤트.
• 이벤트 – 소비될 이벤트.
• 이벤트 핸들러 이름 – 엔티티 및 도메인 이벤트에 연결될 이름.

예시

User 엔티티와 UserCreatedDomainEvent 이벤트에 연결된 도메인 이벤트 핸들러 UserCreated를 생성하면, 시스템은 자동으로 UserCreatedDomainEventHandler라는 이름의 이벤트 핸들러를 생성합니다.

Lino가 생성한 구조:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Domain/
                        │       └── UserCreatedDomainEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/

Technical responsibilities

• Implements IDomainEventHandler and reacts inside the application boundary.
• Runs internal consistency, logging, tracing, or integration registration work.
• Uses IOutbox.RegisterIntegrationEvent for reliable messages.
• Keeps the business change and OutboxMessage in the same transaction.

통합 이벤트

통합 이벤트는 중요한 일이 발생했음을 알리는 메시지이며, 외부 시스템이나 다른 마이크로서비스와 공유해야 합니다.

도메인 이벤트와 달리, 여기서의 목적은 시스템 간 통신 및 상태 동기화입니다.

통합 이벤트를 생성할 때:

• 시스템의 변경 사항을 다른 시스템에 반영해야 할 때.
• 마이크로서비스가 변경 사항을 게시하여 다른 마이크로서비스가 반응해야 할 때.

도메인 이벤트와 통합 이벤트의 주요 차이점:

Lino에서는 새 통합 이벤트를 쉽게 생성할 수 있습니다. 다음 명령어를 실행하세요:

lino event new
lino event new --name <EventName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event list --service <ServiceName> --module <ModuleName> --entity <EntityName>

CLI 마법사가 요청하는 항목:

• 서비스 – 이벤트를 생성할 서비스.
• 모듈 – 이벤트를 생성할 모듈 (모듈형 서비스에서만).
• 엔티티 – 이벤트를 생성/연결할 엔티티.
• 이벤트 유형 – 도메인 이벤트 또는 통합 이벤트.
• 이벤트 이름 – 엔티티와 연결된 통합 이벤트 이름.

예시

User 엔티티와 연결된 통합 이벤트 UserCreated를 생성하면, 시스템은 자동으로 UserCreatedIntegrationEvent라는 이름의 이벤트를 생성합니다. 이 이름은 이벤트를 소비하는 시스템의 모든 부분에서 사용자 생성 작업이 이미 완료되었음을 명확하게 나타냅니다.

Lino가 생성한 구조:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Integration.Events/
                ├── <ProjectName>.<ServiceName>.Integration.Events.csproj
                └── Users/
                    └── UserCreatedIntegrationEvent.cs

Reliable publication

An integration event implements IIntegrationEvent and crosses boundaries between modules, services, or systems. The application registers the event in IOutbox, the Unit of Work persists an OutboxMessage, and a Hangfire worker later publishes it through MassTransit/RabbitMQ.

통합 이벤트 핸들러

Integration Event Handler 는 일반적으로 다른 서비스나 컨텍스트에서 발행된 Integration Event 를 소비하고, 자신의 도메인 내에서 특정 작업을 수행하는 클래스입니다.

이러한 핸들러는 RabbitMQ, Kafka, Azure Service Bus 등과 같은 메시징 메커니즘을 통해 이벤트를 수신하며, 일반적으로 Outbox 패턴과 함께 사용되어 안정적인 전달과 비동기 처리를 보장합니다.

예를 들어, Identity 서비스에서 UserCreated 이벤트를 발행하면, 다른 컨텍스트의 해당 핸들러는 환영 이메일을 보내거나 외부 API를 호출하는 등의 반응을 수행할 수 있습니다. 이러한 작업은 느리거나 실패할 수 있지만, 메인 트랜잭션 외부에서 처리되므로 애플리케이션의 내부 일관성에는 영향을 주지 않습니다.

주요 특징:

• 다른 컨텍스트와 관련된 비즈니스 사실을 나타내는 이벤트에 반응합니다.
• 느리거나 외부 작업(예: 이메일 발송, API 호출)을 수행합니다.
• 비동기적이고 복원력 있게 처리되며, 종종 재시도 및 모니터링이 포함됩니다.
• 외부 실패가 원래 도메인 트랜잭션에 영향을 주지 않도록 보장합니다.
• 바운디드 컨텍스트 및 분산 시스템 간의 통합을 용이하게 합니다.

새 통합 이벤트 핸들러를 생성하려면 다음 명령을 실행하세요:

lino event-handler new
lino event-handler new --name <EventHandlerName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event-handler list --service <ServiceName> --module <ModuleName> --entity <EntityName>

CLI 마법사가 요청하는 항목:

• 서비스 – 이벤트 핸들러가 생성될 서비스.
• 모듈 – 이벤트 핸들러가 생성될 모듈(모듈형 서비스만 해당).
• 엔티티 – 이벤트 핸들러가 생성될 엔티티.
• 이벤트 유형 – 도메인 이벤트 또는 통합 이벤트.
• 서비스 – 소비할 이벤트가 존재하는 서비스.
• 모듈 – 소비할 이벤트가 존재하는 모듈(모듈형 서비스만 해당).
• 엔티티 – 소비할 이벤트가 존재하는 엔티티.
• 이벤트 – 소비할 이벤트.
• 이벤트 핸들러 이름 – 엔티티 및 통합 이벤트와 연결될 이름.

예제

User 엔티티 및 UserCreatedIntegrationEvent 이벤트와 연결된 통합 이벤트 핸들러 SendEmailOnUserCreated 를 생성하면, 시스템은 자동으로 SendEmailOnUserCreatedIntegrationEventHandler 라는 이름의 핸들러를 생성합니다.

Lino가 생성한 구조:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Integration/
                        │       └── SendEmailOnUserCreatedIntegrationEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/

Operational guidance

• Implements IIntegrationEventHandler and consumes messages with MassTransit.
• Does not read the producer database directly.
• Updates local state, projections, or shadow entities.
• Should be idempotent because retries and duplicate messages can happen.

Shadow Entities

shadow entity는 소유자가 다른 모듈이나 서비스에 있는 데이터를 로컬에 최소한으로, 통제된 방식으로 복사한 것입니다. consumer가 producer 데이터베이스에 직접 접근하지 않고 참조 데이터를 조회, 검증 또는 표시해야 할 때 결합도를 낮추기 위해 사용합니다.

Shadow Entities는 eventual consistency를 허용할 수 있을 때 유용합니다. producer가 integration event를 게시하고, 메시지는 Outbox에 저장되며, worker가 bus에 게시하고, consumer는 integration event handler를 통해 로컬 복사본을 갱신합니다.

lino shadow-entity new
lino event new
lino event-handler new

이 명령은 lino shadow new alias로도 사용할 수 있습니다. 대화형 흐름에서 Lino는 대상 서비스 또는 모듈, 원본 entity, 복사할 properties를 묻습니다. 이를 통해 identifier type, 필수 여부, string 길이, 기본 references를 수동으로 다시 만들 필요가 줄어들고 source와 consumer 사이의 불일치를 줄일 수 있습니다.

shadow entity는 전체 복제본이 아닙니다. Catalog 모듈이 Tenancy와 Security의 데이터를 소비하는 예에서 catalog는 Tenant.Id, Tenant.Slug, User.Id, User.Email, User.TenantId만 유지할 수 있습니다. 원래 user entity에는 hash, confirmation, tokens, dates 및 catalog context에 속하지 않는 다른 내부 필드가 계속 포함됩니다.

사용할 때

• consumer가 다른 context에 속한 entity의 일부 필드만 필요로 할 때.
• 규칙이 producer 변경과 consumer 업데이트 사이의 작은 지연을 허용할 때.
• producer 데이터베이스를 직접 읽는 것이 모듈이나 서비스 간의 부적절한 결합을 만들 때.
• grids, filters, local validations 또는 projections가 외부 참조 데이터를 필요로 할 때.

피해야 할 때

• 규칙이 즉시 갱신된 데이터를 요구하고 eventual consistency를 허용하지 않을 때.
• 로컬 복사본이 원래 aggregate의 전체 복제본이 될 때.
• consumer가 producer에 속한 invariants에 의존하기 시작할 때.

권장 흐름

1. consumer에 필요한 필드만 포함하도록 shadow entity를 모델링합니다.
2. producer가 게시하는 integration event를 만들거나 선택합니다.
3. consumer에 integration event handler를 만듭니다.
4. producer key 또는 natural identifier를 사용해 idempotent upsert를 구현합니다.
5. retries, 중복 메시지, 영구 실패를 진단할 수 있을 만큼 충분한 logs를 기록합니다.

이벤트 기반 동기화

전체 흐름은 domain, application, Unit of Work, Outbox, worker, bus, consumer를 결합합니다. 목표는 모듈이나 서비스 간의 취약한 직접 호출을 피하고, 게시 또는 소비가 실패했을 때 retry, audit, reprocessing을 가능하게 하는 것입니다.

1. aggregate가 변경되고 domain event를 등록합니다.
2. Unit of Work가 transaction 안에서 변경을 저장합니다.
3. domain handler가 그 사실에 반응하여 integration event를 IOutbox에 등록합니다.
4. Unit of Work가 business data와 OutboxMessage를 같은 transaction에 저장합니다.
5. Hangfire worker가 Outbox를 읽고 MassTransit/RabbitMQ를 통해 bus에 게시합니다.
6. consumer가 IIntegrationEventHandler를 통해 메시지를 받습니다.
7. consumer는 local model, shadow entity, projection, email, external integration 또는 다른 asynchronous flow를 갱신합니다.

Domain change -> Domain Event -> Domain Handler -> Integration Event -> Outbox -> Worker -> Event Bus -> Consumer -> Local model

설계 규칙

• invariants는 domain에 둡니다. events는 필수 규칙을 숨기기 위해서가 아니라 reactions를 위해 사용합니다.
• integration events는 business change와 같은 transaction 안에서 등록합니다.
• integration contracts는 작고, versionable하며, 안정적으로 유지합니다.
• retries와 중복 메시지가 발생할 수 있으므로 idempotent consumers를 구현합니다.
• worker failures와 Outbox에 멈춘 messages를 모니터링합니다.