Spring Integration ile Sipariş İşleme Akışını Kolayca Kurun

Günümüzde mikro hizmet mimarilerinde siparişleri işlerken karşılaşılan en büyük zorluklardan biri, farklı giriş noktalarından gelen verileri tutarlı bir şekilde yönetmektir. Spring Boot REST API'leriyle çalışmış olabilirsiniz, ancak Spring Integration'ın mesaj odaklı akış tasarımını gerçek bir projede nasıl uygulayabileceğinizi hiç merak ettiniz mi?

Bu örnek projede, hem HTTP üzerinden gönderilen hem de dosya sistemi üzerinden okunan siparişlerin aynı iş mantığıyla nasıl işlendiğini adım adım göreceksiniz. Proje, Java 21 ve Spring Boot 4.1 kullanılarak geliştirilmiş olup, Spring Integration 7'in Java DSL'ine dayanıyor. Veritabanı olarak geliştirme sürecinde H2, üretim ortamında ise PostgreSQL kullanılıyor.

Siparişlerin Akışını Anlamak

Proje, her siparişin aşağıdaki adımlardan geçtiği bir akış sunuyor:

• Giriş verisi Order nesnesine dönüştürülür.
• Alan doğrulaması (id, müşteri, toplam gibi kritik alanlar kontrol edilir).
• Toplam tutarına göre rotalama yapılır: toplam <= 100 için EXPRESS, toplam > 100 için REVIEW olarak işaretlenir.
• Veritabanına kalıcı olarak kaydedilir (Spring Data JPA).
• Son olarak, arşivleme, özet toplama ve HTTP yanıtı gibi farklı hedeflere dağıtılır.

Bu akışın tamamı, Spring Integration'ın sunduğu mesajlaşma altyapısı sayesinde oldukça temiz ve yönetilebilir bir şekilde kodlanmış durumda.

Kullanılan Teknolojiler ve Versiyonlar

Proje, modern Java ekosisteminin en son araçlarını kullanıyor:

• Java 21 – En yeni LTS sürümüyle geliştirildi.
• Spring Boot 4.1 – Uygulama çatısını oluşturuyor.
• Spring Integration 7 (Java DSL) – Mesaj odaklı akışları kolayca tasarlamak için kullanılıyor.
• Spring Data JPA – Veritabanı işlemleri için.
• PostgreSQL – Üretim ortamında verilerin saklanması için.
• H2 – Geliştirme ve test aşamasında yerel veritabanı olarak tercih edildi.
• Maven – Proje bağımlılıklarının yönetimi için.

Akışın Temel Parçaları

HTTP Akışı: REST API Üzerinden Sipariş Alımı

HTTP üzerinden gelen siparişler, aşağıdaki adımları izliyor:

POST /api/orders
Content-Type: application/json

{
  "id": "ORD-001",
  "customer": "Alice",
  "description": "Book",
  "total": 25.00
}

• Mesajlaşma geçidi (Messaging Gateway) aracılığıyla JSON verisi bir mesaja dönüştürülür.
• JsonToOrderTransformer kullanılarak Order nesnesine çevrilir.
• OrderValidationService tarafından doğrulanır.
• İçerik tabanlı bir rotalayıcı (content-based router) aracılığıyla EXPRESS veya REVIEW olarak sınıflandırılır.
• OrderStore.put(...) metodu ile veritabanına kaydedilir.
• Son olarak, arşivleme, özet toplama ve HTTP yanıtı gibi farklı hedeflere dağıtılır.

Dosya Akışı: CSV Dosyalarından Sipariş Okuma

Dosya sistemi üzerinden gelen siparişler için, sistem /input/ dizinine bırakılan CSV dosyalarını tarayan bir polimer (poller) kullanıyor:

• FileToStringTransformer ile dosya içeriği metne dönüştürülür.
• CsvToOrderTransformer ile CSV verisi Order nesnesine çevrilir.
• Doğrulama, rotalama ve kalıcı kayıt adımları HTTP akışıyla aynı şekilde ilerler.
• Son olarak, arşivleme ve özet toplama işlemlerine tabi tutulur.

Hata Yönetimi: Düzgün ve İzlenebilir Hatalar

Hatalar, kullanıcıya ve sistem yöneticisine mümkün olan en iyi şekilde iletilir:

• HTTP hataları, JSON yanıtlarıyla birlikte doğrudan istemciye iletilir.
• Dosya işleme hataları, /output/failed/ dizinine hata kayıtları olarak kaydedilir ve hatalı dosyalar /input/failed/ dizinine taşınır.

Spring Integration'ın Avantajları

Spring Integration, bu tür akışların geliştirilmesini oldukça kolaylaştırıyor:

• Rotalama kuralları deklaratif olarak tanımlanabiliyor.
• Yayın-abone (publish-subscribe) kanalları sayesinde bir mesajın birden fazla hedefe dağıtılması basit hale geliyor.
• Dosya akışı için yeniden deneme (retry) tavsiyeleri kolayca eklenebiliyor.
• Entegre grafik arayüzü (/api/integration/graph) sayesinde akışın çalışma zamanındaki yapısı görselleştirilebiliyor.

Örnek Komutlar: Projeyi Test Etmek

Projeyi yerel ortamınızda çalıştırmak ve test etmek için aşağıdaki adımları izleyebilirsiniz:

Bir EXPRESS Siparişi Göndermek

curl -X POST  \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-001","customer":"Alice","description":"Book","total":25.00}'

Bir REVIEW Siparişi Göndermek

curl -X POST  \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-002","customer":"Bob","description":"Laptop","total":1500.00}'

Belirli Bir Siparişi Getirmek

curl 

Tüm Siparişleri Listelemek

curl 

Projeyi Yerel Ortamda Çalıştırma

Projeyi çalıştırmak için aşağıdaki adımları takip edebilirsiniz:

git clone 
cd spring-integration-sample

docker compose up -d
mvn clean package
mvn spring-boot:run

Ardından, HTTP uç noktalarını test edebilir veya /input/ dizinine bir CSV dosyası bırakabilirsiniz.

Test Süreci ve Kapsam

Proje, 38 adet test içeriyor ve bu testler aşağıdaki senaryoları kapsıyor:

• Dönüşüm ve doğrulama işlemleri.
• HTTP başarılı ve başarısız yollar.
• Çift siparişlerin engellenmesi (409 Conflict).
• Dosya polimerinin işlenmesi ve yeniden denemeler.
• Özet toplama davranışı.
• Entegre grafik uç noktası.

Testleri doğrudan proje dizininden çalıştırabilirsiniz.

Uygulama Detaylarından Öne Çıkanlar

Bu projenin geliştirilmesi sırasında edinilen bazı önemli ipuçları:

• Korelasyon ID'leri kullanarak logların akış boyunca takip edilebilirliğini artırmak.
• Konfigürasyonu, HttpIntegrationConfig, FileIntegrationConfig ve paylaşılan config olarak ayrı dosyalarda tutmak.
• Özet toplama işlemlerini durumlu mantık olarak ele almak (toplu iş boyutu ve zaman aşımı kuralları, kararlı anahtarlar).
• GET /api/orders/{id} gibi web yollarında değişkenli aramaları dolaylı yollardan ziyade doğrudan kullanmak.

Kimler İçin Uygun?

Bu proje, özellikle aşağıdaki konulara ilgi duyan geliştiriciler için mükemmel bir başlangıç noktası:

• Spring Integration temel kavramları.
• Spring ekosisteminde olay ve mesaj odaklı hizmet tasarımı.
• HTTP ve dosya tabanlı girişlerin birleştirildiği hibrit veri alma örüntüleri.
• Kafka veya RabbitMQ gibi dağıtık sistemlere geçiş için sağlam bir temel oluşturma.

Projeyi inceleyerek, Spring Integration'ın sunduğu esnekliği ve gücü kendi projelerinizde nasıl kullanabileceğinizi görebilirsiniz.