8 dk okuma
Giriş
ERP entegrasyonlarında Transactional Outbox, bir iş kaydını veritabanına yazarken aynı anda başka bir sisteme mesaj göndermenin oluşturduğu dual-write riskini azaltmak için kullanılan güvenilir bir entegrasyon desenidir. ERP, e-ticaret, pazaryeri, lojistik veya finans sistemleri arasında veri aktarırken en zor problem çoğu zaman API çağrısını yapmak değil, iki farklı sistemin aynı iş olayı hakkında tutarlı kalmasını sağlamaktır. Veritabanı kaydı başarıyla commit olup mesaj gönderilemezse downstream sistem değişikliği bilmez; mesaj gidip veritabanı rollback olursa bu kez dış sistem gerçekte oluşmamış bir işlemi işlemiş olabilir.
Transactional Outbox bu problemi tek bir dağıtık transaction kurmaya çalışmadan çözer. İş verisi ile dış sisteme gönderilecek olay aynı yerel veritabanı transaction’ı içinde kaydedilir. Daha sonra ayrı bir relay worker yalnızca commit edilmiş outbox kayıtlarını okuyup mesajı broker, API veya başka bir entegrasyon kanalına yayınlar. Bu yaklaşım, belirli bir ERP ürününe veya özel endpoint bilgisine bağlı değildir; genel entegrasyon mimarisinde güvenilirlik katmanı olarak uygulanabilir.
İçindekiler
- Dual-write problemi neden oluşur?
- Transactional Outbox nasıl çalışır?
- Outbox kaydı nasıl tasarlanır?
- Relay worker ve retry stratejisi nasıl kurulur?
- Idempotent consumer neden zorunludur?
- Sıralama, temizlik ve büyüme nasıl yönetilir?
- Monitoring ve alarm metrikleri neler olmalı?
- Sonuç
- Kaynaklar
1. Dual-Write Problemi Neden Oluşur?
Klasik entegrasyon kodunda geliştirici çoğu zaman iki adım uygular: önce yerel veriyi kaydeder, sonra dış sisteme mesaj veya API çağrısı gönderir. Bu iki işlem farklı kaynaklarda gerçekleştiği için tek bir ACID transaction ile doğal olarak korunmaz. AWS Prescriptive Guidance, veritabanı güncellemesi ile event bildirimini ayrı iki yazma olarak ele alır ve bunlardan birinin başarısız olmasının veri tutarsızlığı üretebileceğini açıkça belirtir. ERP senaryosunda bu durum sipariş, stok, sevkiyat, fatura, iade veya cari hareket gibi iş olaylarında görülebilir.
Dağıtık transaction veya iki aşamalı commit teorik olarak seçenek olabilir; ancak harici SaaS servisleri, pazaryeri API’leri ve birçok ERP entegrasyon noktası aynı transaction coordinator’a katılamaz. Bu nedenle daha pratik yaklaşım, yerel transaction’ı güvenilir hale getirip dış yayınlamayı eventual consistency modeliyle ayrı bir dayanıklı akışa taşımaktır.
2. ERP Entegrasyonlarında Transactional Outbox Nasıl Çalışır?
Temel akışta uygulama önce kendi veritabanında business record ile outbox event kaydını aynı transaction içinde oluşturur. Transaction commit olursa iki kayıt da kalıcıdır; rollback olursa ikisi de kaybolur. Microsoft’un Azure Architecture Center açıklaması da iş nesnesi ile event’in aynı transaction içinde kaydedilmesini, ardından ayrı worker’ın işlenmemiş outbox kayıtlarını okuyup message bus’a göndermesini önerir. Bu sayede uygulama, broker’ın o an ayakta olup olmadığına bağlı olmadan iş transaction’ını tamamlayabilir.
ERP tarafında önemli sınır şudur: Outbox tablosuna ticari sistemin özel field mapping detaylarını veya hassas müşteri verisini gereksiz yere kopyalamayın. Event payload yalnızca downstream işlemi başlatmak için gereken minimum genel bilgiyi taşımalıdır. Hassas veriler gerekiyorsa event içinde referans kimliği tutup yetkili servisin kaynağı kontrollü biçimde yeniden okuması daha güvenli olabilir.
3. Outbox Kaydını Minimum ve İzlenebilir Tasarlayın
Tipik bir outbox kaydı EventId, EventType, AggregateId veya EntityId, OccurredAt, Payload, Status, RetryCount ve gerekirse Sequence gibi alanlardan oluşabilir. EventId benzersiz olmalı; downstream sistem bu kimliği duplicate kontrolünde kullanabilmelidir. EventType teknik sınıf adı yerine iş anlamı taşıyan, zaman içinde sürdürülebilir bir sözleşme adı olmalıdır.
Payload versiyonlaması da önemlidir. Bir entegrasyon şeması değiştiğinde eski outbox kayıtları hâlâ işlenmemiş olabilir. Bu nedenle event version veya schema version alanı tutmak, relay ve consumer tarafında geriye uyumluluğu yönetmeyi kolaylaştırır. Outbox tablosunu normal uygulama sorgularının arasında bırakmak yerine doğru index’lerle yalnızca bekleyen kayıtların hızlı okunmasını sağlayacak şekilde tasarlamak gerekir.
4. Relay Worker ve Retry Stratejisini Güvenli Kurun
Relay worker’ın görevi basittir: yayınlanmamış kayıtları küçük batch’ler halinde alır, hedef broker veya servise gönderir ve başarılı olanları işaretler. Ancak başarısızlık durumunda sınırsız hızlı retry yapmak dış sistemi daha da zorlayabilir. Exponential backoff, maksimum deneme sayısı, dead-letter veya manuel inceleme kuyruğu gibi mekanizmalar birlikte düşünülmelidir.
Worker aynı kayıt üzerinde birden fazla instance ile yarışabiliyorsa row locking, lease, claim token veya status geçişi gibi güvenli claim yaklaşımı gerekir. Mesajı gönderdikten sonra process çökerse kayıt ‘gönderildi’ olarak işaretlenmeden kalabilir ve yeniden yayınlanabilir. Transactional Outbox’ın doğal sonucu bu nedenle genellikle at-least-once teslimattır; duplicate olasılığı sistem tasarımının parçası kabul edilmelidir.
5. Idempotent Consumer Neden Zorunludur?
AWS dokümantasyonu, event processor’ın duplicate mesaj gönderebileceğini ve consumer’ın işlenen mesajları takip ederek idempotent tasarlanmasını özellikle önerir. Bir consumer aynı EventId’yi ikinci kez aldığında aynı faturayı, sevkiyat kaydını veya stok hareketini yeniden üretmemelidir. Bunun için processed-message tablosu, unique constraint, doğal business key veya hedef sistemin sunduğu idempotency key mekanizması kullanılabilir.
Idempotency özellikle entegrasyonlarda yalnızca teknik bir detay değil, finansal doğruluk konusudur. Aynı ticari olayın iki kez işlenmesi yanlış bakiye, mükerrer sipariş veya tekrarlanan e-posta/lojistik aksiyonu doğurabilir. Bu nedenle outbox ile güvenilir yayınlama kurarken consumer tarafı deduplication tasarımını aynı mimari kararın diğer yarısı olarak ele alın.
6. Sıralama, Temizlik ve Büyümeyi Baştan Planlayın
Bazı iş akışlarında event sırası önemlidir. Örneğin ‘OrderCreated’ olayından önce ‘OrderCancelled’ yayınlanması downstream sistemi anlamsız bir duruma sokabilir. Bu yüzden aggregate bazlı sequence, oluşma zamanı ve partition key stratejisi gerekebilir. AWS kılavuzu da event’lerin kaynak güncelleme sırasına uygun gönderilmesini önemli bir tasarım konusu olarak vurgular.
Outbox tablosu sürekli büyür; başarılı kayıtları sonsuza kadar tutmak doğru değildir. Saklama süresi, audit ihtiyacı ve mevzuata göre belirlenmeli; başarılı kayıtlar düzenli batch’lerle arşivlenmeli veya silinmelidir. Temizlik job’ı ana transaction performansını etkilemeyecek şekilde küçük batch ve uygun index kullanmalıdır. Hatalı kayıtlar ise otomatik silinmek yerine inceleme için ayrı statüde tutulabilir.
7. Monitoring ve Alarm Metrikleri Neler Olmalı?
Outbox çalışan ama izlenmeyen bir sistem değildir. En kritik metrik, en eski bekleyen outbox kaydının yaşıdır. Queue depth tek başına yeterli değildir; yoğun saatlerde kayıt sayısı artabilir fakat worker aynı hızla eritiyorsa sorun olmayabilir. Buna karşılık yalnızca on kayıt bile saatlerdir bekliyorsa entegrasyon durmuş olabilir.
İzlenmesi faydalı diğer sinyaller: pending count, publish success/error rate, retry count dağılımı, relay latency, event başına ortalama işlem süresi, dead-letter sayısı ve consumer duplicate oranıdır. ERP veya dış servis bakımda olduğunda alert gürültüsü üretmemek için planned maintenance durumlarıyla monitoring’i ilişkilendirmek de operasyon kalitesini artırır.
Sonuç
ERP entegrasyonlarında Transactional Outbox, veritabanı ile dış sistem arasında doğrudan senkron iki yazma yapmanın oluşturduğu güvenilirlik açığını azaltır. İş kaydı ve event aynı local transaction içinde tutulur; yayınlama ayrı bir relay worker’a bırakılır; duplicate ihtimali idempotent consumer ile yönetilir. Bu mimari özellikle ERP, e-ticaret, pazaryeri, EDI ve benzeri çok sistemli süreçlerde servislerin geçici olarak erişilemez olduğu anlarda veri kaybı yerine kontrollü gecikme üretir.
Bu yaklaşımı gerçek bir entegrasyon bağlamında düşünmek için sitedeki Pazaryeri İade Entegrasyonu ve Nebim V3 Otomasyon Platformu ile Erkurt Holding EDI / ASN Operasyon Entegrasyonu projeleri, farklı dış sistemlerle güvenilir veri akışının iş açısından neden kritik olduğunu gösteren ilgili case study örnekleridir.
Kaynaklar
Kaynaklar: Microsoft Learn – Transactional Outbox;
AWS Prescriptive Guidance – Transactional Outbox;
Mehmet Özdemir – Pazaryeri İade Entegrasyonu case study;
Mehmet Özdemir – Nebim V3 OpenCart Entegrasyon Programı.