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.