C# / .NET Kompendium PLEN
.NET / C# / Architektura rozproszona

Outbox Pattern - gwarancja spójności między bazą danych i publikacją zdarzeń

Problem, który Outbox rozwiązuje - "dual write problem"

To jest bezpośrednie nawiązanie do Sagi (Choreography), o której właśnie mówiliśmy - żeby Saga działała, serwisy muszą publikować zdarzenia po zapisaniu zmian w swojej bazie danych. Ale co, jeśli zapis do bazy się powiedzie, a publikacja zdarzenia zawiedzie (np. broker wiadomości jest chwilowo niedostępny)?

// ❌ NIEBEZPIECZNE - dwa niezależne systemy, dwa niezależne punkty awarii
public async Task PlaceOrderAsync(Order order)
{
    _context.Orders.Add(order);
    await _context.SaveChangesAsync(); // ✅ zapisano do bazy danych

    // Co jeśli SERWER PADNIE właśnie TUTAJ, między tymi dwoma liniami?
    await _eventBus.PublishAsync(new OrderPlacedEvent(order.Id)); // ❌ zdarzenie NIGDY nie zostanie opublikowane!
}

To jest dual write problem - zapisujesz do dwóch różnych systemów (baza danych + broker wiadomości), które nie mają wspólnej transakcji. Nie da się tego owinąć w BeginTransactionAsync(), bo broker wiadomości (Kafka, RabbitMQ) nie uczestniczy w transakcjach SQL Server/PostgreSQL.

Konsekwencja w kontekście Sagi: jeśli OrderPlacedEvent nigdy nie zostanie opublikowany, cała Saga się zatrzymuje - InventoryService nigdy nie zarezerwuje towaru, mimo że zamówienie istnieje w bazie OrderService. To jest niespójność między stanem faktycznym a tym, co "wie" resztę systemu.

Rozwiązanie - zapisz zdarzenie DO TEJ SAMEJ bazy danych, w tej samej transakcji

Outbox Pattern polega na: zamiast publikować zdarzenie bezpośrednio do brokera, zapisz je jako wiersz w tabeli "outbox" w TEJ SAMEJ bazie danych, w tej samej transakcji co Twoje właściwe dane biznesowe.

public class OutboxMessage
{
    public Guid Id { get; set; }
    public string EventType { get; set; }
    public string Payload { get; set; } // JSON zawierający dane zdarzenia
    public DateTime CreatedAt { get; set; }
    public DateTime? ProcessedAt { get; set; } // null = jeszcze nieopublikowane
}
// ✅ BEZPIECZNE - JEDNA transakcja SQL obejmuje OBA zapisy
public async Task PlaceOrderAsync(Order order)
{
    _context.Orders.Add(order);

    _context.OutboxMessages.Add(new OutboxMessage
    {
        Id = Guid.NewGuid(),
        EventType = nameof(OrderPlacedEvent),
        Payload = JsonSerializer.Serialize(new OrderPlacedEvent(order.Id, order.Items)),
        CreatedAt = DateTime.UtcNow
    });

    await _context.SaveChangesAsync(); // JEDNA transakcja - ALBO obie zmiany się zapiszą, ALBO żadna
}

Teraz SaveChangesAsync() (jak omawialiśmy przy transakcjach EF Core) automatycznie owija oba zapisy (Order + OutboxMessage) w jedną transakcję SQL - niemożliwe jest zapisanie zamówienia bez zapisania odpowiadającego mu wiersza w outboxie (i vice versa).

Krok 2 - osobny proces publikujący zdarzenia z outboxa

To jest druga część wzorca - background worker (dokładnie BackgroundService, o którym mówiliśmy przy IServiceScopeFactory), który regularnie sprawdza tabelę outbox i publikuje niewysłane jeszcze wiadomości:

public class OutboxPublisherService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly IEventBus _eventBus;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = _scopeFactory.CreateScope(); // Scoped DbContext, jak omawialiśmy wcześniej
            var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();

            var pendingMessages = await context.OutboxMessages
                .Where(m => m.ProcessedAt == null)
                .OrderBy(m => m.CreatedAt)
                .Take(20)
                .ToListAsync(stoppingToken);

            foreach (var message in pendingMessages)
            {
                try
                {
                    await _eventBus.PublishAsync(message.EventType, message.Payload);
                    message.ProcessedAt = DateTime.UtcNow; // oznacz jako wysłane
                }
                catch (Exception)
                {
                    // NIE oznaczaj jako przetworzone - kolejna iteracja pętli spróbuje PONOWNIE
                    break;
                }
            }

            await context.SaveChangesAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromSeconds(2), stoppingToken);
        }
    }
}

Kluczowa gwarancja: jeśli publikacja do brokera zawiedzie, wiersz zostaje w tabeli outbox z ProcessedAt = null - następna iteracja worker'a spróbuje ponownie. Nic nie zostaje "zgubione", nawet jeśli cały proces aplikacji padnie w międzyczasie - po restarcie worker po prostu kontynuuje od miejsca, gdzie tabela outbox wskazuje niewysłane wiadomości.

"At-least-once delivery" - konsekwencja, którą trzeba obsłużyć

Outbox gwarantuje, że zdarzenie zostanie opublikowane przynajmniej raz - ale może zostać opublikowane więcej niż raz (np. worker opublikował zdarzenie, ale padł zanim zapisał ProcessedAt, więc następna iteracja publikuje je ponownie).

To jest bezpośrednie nawiązanie do idempotencji, o której mówiłem przy Sadze - konsument zdarzenia (np. InventoryService z poprzedniego przykładu) musi być odporny na duplikaty:

public async Task Handle(OrderPlacedEvent orderPlaced)
{
    // Idempotencja - sprawdź, czy TO KONKRETNE zdarzenie już przetworzono
    var alreadyProcessed = await _context.ProcessedEvents.AnyAsync(e => e.EventId == orderPlaced.EventId);
    if (alreadyProcessed) return;

    // ... właściwa logika ...

    _context.ProcessedEvents.Add(new ProcessedEvent { EventId = orderPlaced.EventId });
    await _context.SaveChangesAsync();
}

Alternatywa - Change Data Capture (CDC), bardziej zaawansowana wersja

W niektórych architekturach, zamiast dedykowanego workera odpytującego tabelę outbox (polling), używa się CDC (np. Debezium z Kafka Connect) - narzędzia, które nasłuchuje bezpośrednio na logu transakcyjnym bazy danych i automatycznie publikuje zmiany do Kafki, bez potrzeby pisania własnego BackgroundService. To rozwiązuje ten sam problem (dual write), ale przenosi odpowiedzialność za "publikowanie" do infrastruktury, nie do kodu aplikacji.

Podsumowanie - relacja Outbox ↔ Saga

Outbox Pattern rozwiązuje fundamentalny problem inżynierski leżący pod każdą implementacją Sagi w stylu Choreography: jak atomowo zapisać zmianę stanu i opublikować odpowiadające jej zdarzenie, gdy te dwie operacje dotyczą różnych systemów (baza danych vs broker wiadomości). Rozwiązanie: zapisz zdarzenie jako wiersz w tabeli tej samej bazy danych, w tej samej transakcji co dane biznesowe (SaveChangesAsync() gwarantuje atomowość), a osobny proces w tle (BackgroundService) asynchronicznie publikuje te zdarzenia do brokera, z retry w przypadku niepowodzenia. To jest jeden z fundamentalnych "cegiełek" niezbędnych, żeby Saga Choreography działała bezpiecznie w praktyce.

Postaw mi kawę