Berk Selvi | Software Developer

IEnumerable'dan IAsyncEnumerable'a: .NET'te Belleği Öldürmeden Büyük Veri Setlerini Streaming ile İşlemek

Sun, 02 Aug 2026 00:00:00 +0300

Birkaç ay önce, gece çalışan export job’larımızdan biri OutOfMemoryException fırlatmaya başladı. Kodda hiçbir şey değişmemişti. Değişen tek şey, okuduğu tablonun boyutuydu—sessizce 200 bin satırdan 4 milyon satıra çıkmıştı. Job tam olarak söylediğimiz şeyi yapıyordu: tüm tabloyu .ToListAsync() ile çekip üzerinde döngü kuruyordu. Sadece önce tüm veritabanı tablosunu RAM’e alıyordu ve RAM kaybediyordu.

Bu, neredeyse her .NET geliştiricisinin er ya da geç düştüğü bir tuzak: aslında ihtiyacınız olan şey kayıt kayıt streaming yapan IAsyncEnumerable<T> iken IEnumerable<T>‘ye (ya da onun async kuzeni Task<List<T>>‘ye) yönelmek. IEnumerable<T> ve IAsyncEnumerable<T> yüzeysel olarak birbirine benzer ama çok farklı problemleri çözerler, ve yanlışını seçmek sizi gece 2’de 4 milyon satırlık bir tabloyu bellekte sayfalamaya götüren tam olarak budur.

Bir Bakışta IEnumerable vs IAsyncEnumerable

Özellik	`IEnumerable<T>` / `List<T>`	`IAsyncEnumerable<T>`
Materialization	Iterasyon başlamadan önce tamamen gerçekleştirilir	Talep üzerine, tek tek çekilir
Bellek ayak izi	Sonuç kümesinin boyutuyla birlikte büyür	Boyuttan bağımsız olarak kabaca sabit
İlk öğeye kadar geçen süre	Tüm sorgu/koleksiyonu bekler	İlk öğe hazır olur olmaz kullanılabilir
Cancellation	Sadece döngünüzü durdurur; zaten yapılmış iş yapılmış kalır	Altta yatan sorguyu akış ortasında durdurabilir
Iterasyon	Tekrarlanabilir, indekslenebilir	Sadece ileri yönlü, tek geçişli
Tipik kullanım	Küçük, sınırlı koleksiyonlar	Export’lar, ETL, sayfalanmış API’ler, log işleme

Eski Yöntem: Önce Her Şeyi Yükle, Sonra Iterasyon Yap

İşte bizi belaya sokan pattern buydu. Order’ları export etmek için okuyan tipik bir .NET servisi:


public async Task<List<Order>> GetAllOrdersAsync()
{
 return await _dbContext.Orders
 .AsNoTracking()
 .ToListAsync();
}

public async Task ExportOrdersAsync()
{
 var orders = await GetAllOrdersAsync();

 foreach (var order in orders)
 {
 await _exportWriter.WriteLineAsync(order.ToCsvRow());
 }
}

Bu tamamen makul görünüyor, ve küçük tablolar için de öyle. Ama ToListAsync()‘in aslında ne yaptığına yakından bakın: sorgunun döndürdüğü her bir satırı, kodunuz ilk öğeye dokunmadan önce bellekte duran bir List<Order> içinde materialize eder. Sorgu 4 milyon satır döndürüyorsa, foreach döngüsünde her seferinde sadece bir satır işlese bile, aynı anda 4 milyon Order nesnesini tutacak kadar belleğe ihtiyacınız var.

Belirtiler yavaşça ortaya çıkar:

Bellek sıçramaları: GC baskısı artar, process’in working set’i şişer, ve Kubernetes’te container bellek limitlerine takılınır.
İlk sonuçtan önce gecikme: Caller, tek bir satır görmeden önce tüm sorgunun tamamlanmasını bekler, sadece sonuçları bir client’a stream etmek istese bile.
Cancellation’da boşa giden iş: Caller yarı yolda işlemi iptal ederse, her şeyi yükleme maliyetinin tamamını zaten ödemişsinizdir.
Backpressure yok: “Yavaşla, son batch’i hâlâ işliyorum” demenin bir yolu yoktur—veritabanı, driver’ın buffer’layabildiği hızda satır üretmeye devam eder.

Export yapan bir background job, bir CSV stream eden API endpoint’i, ya da bir veri migration script’i için bu pattern ölçeklenmez. Local development’ta 50 satırlık seed veri setinizle çalışır, ve sessizce production’da bozulur.

Neden IAsyncEnumerable?

.NET Core 3.0, tam olarak bu tür problemi çözmek için await foreach syntax’ıyla birlikte IAsyncEnumerable<T>‘yi tanıttı. Tamamen gerçekleştirilmiş bir koleksiyon döndüren bir method yerine, consumer bir sonraki elemanı her istediğinde asenkron olarak tek tek çekilen bir sequence döndürür.

Mental model değişimi önemli:

Task<List<T>> şu anlama gelir: “her şey hazır olana kadar bekle, sonra bana tüm şeyi ver.”
IAsyncEnumerable<T> şu anlama gelir: “bir sonrakini istediğimde bana bir öğe ver, hazır değilse await etmeme izin ver.”

Bu şunları mümkün kılar:

Sabit bellek kullanımı: Kaynağın 10 satırı ya da 10 milyon satırı olması fark etmeksizin, herhangi bir anda bellekte sadece bir öğenin (ya da küçük bir buffer’ın) olması yeterlidir.
Time-to-first-byte iyileştirmeleri: Bir consumer, tüm sonuç kümesini beklemek yerine ilk satır hazır olur olmaz işlemeye (ya da bir HTTP client veri almaya) başlayabilir.
Doğal cancellation desteği: IAsyncEnumerable<T>, WithCancellation üzerinden CancellationToken ile compose olur, böylece bir stream’i iptal etmek, sadece zaten yüklenmiş bir listeyi atmak yerine gerçekten altta yatan sorguyu durdurur.
LINQ ile composability: System.Linq.Async paketiyle, async stream’ler üzerinde Select, Where ve benzerlerini kullanabilirsiniz, böylece IEnumerable<T> ile alışık olduğunuz ifade gücünü kaybetmezsiniz.

Trade-off ise, random access’ten ve ayrı bir sorgu yapmadan sayıyı önceden bilme yeteneğinden vazgeçmenizdir—IAsyncEnumerable<T> tasarım gereği sadece ileri yönlü, tek geçişlidir. Streaming senaryoları için bu tam olarak doğru kısıtlamadır.

yield return ile IAsyncEnumerable Üretmek

Bir IAsyncEnumerable<T> üretmenin en basit yolu, async bir method içinde yield return kullanmaktır. İşte simüle edilmiş bir I/O gecikmesiyle sayıları stream eden, EF Core’u işin içine katmadan önce mekaniği anlamak için kullanışlı, el yazımı bir örnek:


public async IAsyncEnumerable<int> GenerateNumbersAsync(
 int count,
 [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
 for (int i = 0; i < count; i++)
 {
 cancellationToken.ThrowIfCancellationRequested();

 // Simulate an async I/O operation, e.g. a network call per item
 await Task.Delay(10, cancellationToken);

 yield return i;
 }
}

[EnumeratorCancellation] attribute’u gözden kaçması kolay ama önemli bir detay: bu olmadan, WithCancellation‘a geçirilen bir CancellationToken aslında method body’sine akmaz, ve ThrowIfCancellationRequested caller’ın token’ına karşı no-op haline gelir.

Bunu tüketmek şöyle görünür:


await foreach (var number in GenerateNumbersAsync(1000, cts.Token))
{
 Console.WriteLine(number);
}

Burada olmayan şeye dikkat edin: 1000 sayının tamamını tutan ara bir List<int> yok. Her number üretilir, tüketilir, ve bir sonraki üretilmeden önce garbage collect edilebilir.

Gerçek Hayat Örneği: EF Core Sorgu Sonuçlarını Streaming Yapmak

Gece 2’de 4 milyon Order satırını belleğe sayfalayan export job’a geri dönelim ve doğru şekilde düzeltelim. Entity Framework Core, AsAsyncEnumerable() üzerinden DbSet<T> ve IQueryable<T> üzerinde doğrudan IAsyncEnumerable<T> sunar, bu yüzden veritabanı sorguları için kendi yield return wrapper’ınızı yazmanıza gerek yoktur:


public IAsyncEnumerable<Order> StreamOrdersAsync(CancellationToken cancellationToken)
{
 return _dbContext.Orders
 .AsNoTracking()
 .OrderBy(o => o.Id)
 .AsAsyncEnumerable();
}

public async Task ExportOrdersAsync(CancellationToken cancellationToken)
{
 await foreach (var order in StreamOrdersAsync(cancellationToken).WithCancellation(cancellationToken))
 {
 await _exportWriter.WriteLineAsync(order.ToCsvRow());
 }
}

Fark kodda ince ama runtime’da devasa. Sorgu tamamen çalışıp 4 milyon Order satırını bir List<Order>‘a buffer’lamak yerine, EF Core altta yatan DbDataReader‘ı açık tutar ve await foreach döngüsü istedikçe veritabanı bağlantısından satırları stream eder. Sorgunun kendisi için bellek kullanımı, tablo boyutundan bağımsız olarak kabaca sabit kalır—tüm sonuç kümesi için değil, her seferinde bir satır (artı küçük bir internal buffer) için ödeme yaparsınız.

Burada gözden kaçması kolay iki detay önemli. Birincisi, .AsNoTracking() dekoratif değildir—olmadan, EF Core’un change tracker’ı, DbContext‘in ömrü boyunca size verdiği her entity’nin bir snapshot’ını tutar, bu da sorgu kendisi stream ediyor olsa bile, ortadan kaldırmaya çalıştığınız tam bellek büyümesini sessizce geri getirir. İkincisi, yukarıdaki el yazımı yield return örneğinin aksine, AsAsyncEnumerable() kendi kodunuzda herhangi bir yerde [EnumeratorCancellation] eklemenizi gerektirmez—EF Core, WithCancellation‘a geçirdiğiniz CancellationToken‘ı internal olarak kendi sorgu pipeline’ına bağlar. Attribute sadece async IAsyncEnumerable<T> method’unu kendiniz yazdığınızda önem kazanır.

Bu ayrıca ASP.NET Core ile de temiz bir şekilde compose olur. Bunu minimal bir API endpoint’i olarak sunarsanız, framework, tüm JSON array’ini önce server-side’da buffer’lamak yerine, öğeler hazır oldukça stream’i doğrudan response body’sine serialize eder:


app.MapGet("/orders/stream", (AppDbContext dbContext, CancellationToken cancellationToken) =>
{
 return dbContext.Orders
 .AsNoTracking()
 .OrderBy(o => o.Id)
 .AsAsyncEnumerable();
});

.NET 6’dan beri, ASP.NET Core’un minimal API’leri IAsyncEnumerable<T> dönüş tipini algılar ve altta yatan enumerable öğeleri ürettikçe JSON array’ini, tam listeyi return etmeden önce materialize etmenizi gerektirmek yerine, chunk chunk stream eder. Bilinmeye değer bir tuzak: eğer response compression middleware’i endpoint’in önünde duruyorsa, etkili bir şekilde sıkıştırmak için response’u internal olarak buffer’layabilir, bu da az önce kurduğunuz streaming davranışını sessizce boşa çıkarır—uçtan uca çalıştığını varsaymadan önce gerçek bir client ve Transfer-Encoding: chunked ile kontrol etmeye değer.

Batching Üzerine Bir Not

EF Core’dan bir seferde bir satır stream etmek bellek dostudur, ama her satırı harici bir sisteme yazıyorsanız (bir HTTP call, bir message queue, ikinci bir veritabanı), bunu satır bazında yapmak, öğe başına overhead nedeniyle yavaş olabilir. Yaygın bir orta yol, stream’i chunk’lara batch’lemektir:


public static async IAsyncEnumerable<List<T>> ChunkAsync<T>(
 this IAsyncEnumerable<T> source,
 int chunkSize,
 [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
 var buffer = new List<T>(chunkSize);

 await foreach (var item in source.WithCancellation(cancellationToken))
 {
 buffer.Add(item);

 if (buffer.Count == chunkSize)
 {
 yield return buffer;
 buffer = new List<T>(chunkSize);
 }
 }

 if (buffer.Count > 0)
 {
 yield return buffer;
 }
}

Şöyle kullanılır:


await foreach (var batch in StreamOrdersAsync(cancellationToken).ChunkAsync(500, cancellationToken))
{
 await _messageBus.PublishBatchAsync(batch);
}

Yine de belleği sınırlı tutarsınız—4 milyon yerine aynı anda uçuşta sadece 500 order—aynı zamanda downstream sistemin çağrı başına overhead’ini bir batch üzerinden amortize edersiniz.

IAsyncEnumerable Doğru Araç Olmadığında

IAsyncEnumerable<T>, List<T> ya da IEnumerable<T> için evrensel bir replacement değildir. Şu durumlarda yanlış seçimdir:

Sayıya ihtiyacınız varsa, yükledikten sonra sort etmeniz gerekiyorsa, ya da random access’e ihtiyacınız varsa (örn. orders[42])—bunlar zaten veriyi materialize etmeyi gerektirir.
Veri seti gerçekten küçük ve sınırlıysa (20 kategoriden oluşan bir dropdown listesi streaming semantiğine ihtiyaç duymaz).
Aynı sequence’ı birden fazla kez iterate etmeniz gerekiyorsa—IAsyncEnumerable<T> convention gereği tek geçişlidir; yeniden enumerate etmek genellikle altta yatan sorguyu yeniden çalıştırır.
Zaten tüm koleksiyona ihtiyaç duyan in-memory dönüşümler yapıyorsanız (örn. median hesaplamak), bu durumda streaming, bellek kullanımını azaltmadan sadece await overhead’i ekler.

Problemin şekli “potansiyel olarak büyük bir sequence’ı, hepsini bir anda tutmaya ihtiyaç duymadan, tek tek (ya da küçük batch’ler halinde) işlemek” olduğunda özellikle kullanın. Export’lar, ETL pipeline’ları, sayfalanmış API sonuçları, log işleme, ve büyük rapor üretimi klasik durumlardır.

Özet

Bu araştırmayı başlatan OutOfMemoryException, geleneksel anlamda bir bug değildi—kod, ToListAsync()‘in vaat ettiği şeyi tam olarak yapıyordu. Gerçek çözüm daha akıllı bir allocation stratejisi ya da daha büyük bir container bellek limiti değildi; job’un aslında hiçbir zaman bellekte duran bir List<Order>‘a ihtiyaç duymadığını fark etmekti. İhtiyacı olan bir stream’di. O export job’ında ToListAsync()‘i AsAsyncEnumerable() ile değiştirdiğimizde, aynı 4 milyon satırlık tablo düz, öngörülebilir bir bellek kullanımıyla işlendi, ve OutOfMemoryException bir daha geri gelmedi.

Büyük veri setlerini IAsyncEnumerable<T> ile stream etmek her sorguyu daha hızlı yapmaz, ve karmaşıklık ekler—cancellation token’ları, [EnumeratorCancellation], ve random access ile tekrarlanabilir iterasyonun kaybı bedava değildir. Ama probleminiz gerçekten “çok fazla veri okuyup sıralı olarak işlemek” olduğunda, IAsyncEnumerable<T>, sınırsız bir bellek problemini sabit bir probleme dönüştürür. Bir dahaki sefere, beklediğinizden daha fazla satır döndürebilecek bir sorguda alışkanlıktan .ToListAsync() yazdığınızda, gerçekten listeye mi ihtiyacınız var, yoksa sadece bir sonraki öğeye mi ihtiyacınız var diye durup sormaya değer.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

.NET'te Idempotency Key Pattern: Ödeme API'niz İki Kere Çağrılırsa Ne Olur?

Wed, 22 Jul 2026 00:00:00 +0300

Müşteri “Öde” butonuna basıyor. İstek API’nize düşüyor, ödeme sağlayıcınız kartı çekiyor ve sonra… response timeout’a düşüyor. Mobil uygulama ödemenin başarılı olup olmadığını bilmiyor, bu yüzden bildiği tek şeyi yapıyor: retry atıyor. Şimdi tek bir sipariş için iki başarılı çekim, sinirli bir müşteri ve “iki kere para çekildi” diye başlayan bir destek talebiniz var.

Parayla, kuyruklarla veya üçüncü parti API’lerle ilgilenen herhangi bir şey geliştirdiyseniz, bu senaryonun hipotetik olmadığını zaten biliyorsunuzdur. Ağ kesintileri, client timeout’ları ve load balancer retry’ları distributed system’lerin gerçeği. Idempotency key pattern, retry sayısı ne olursa olsun aynı mantıksal isteğin yalnızca bir kez uygulanmasını garanti eden, production seviyesindeki ödeme API’lerinin kullandığı yöntem. Bu yazıda bunun neden önemli olduğunu, önlem alınmazsa genelde nelerin ters gittiğini ve .NET API’de nasıl doğru şekilde uygulanacağını anlatacağım.

Problem: “At least once delivery” Varsayılan Davranıştır

Rahatsız edici bir gerçek var: güvenilir olmayan bir ağ üzerinden bir isteğin “tam olarak bir kez” teslim edildiğini garanti edemezsiniz. TCP bağlantıları response ortasında kopabilir, HTTP client’lar timeout’a düşebilir, load balancer’lar veya mobil uygulamalar 5xx hatalarında ve timeout’larda retry atabilir. Gerçekçi olarak inşa edebileceğiniz en iyi şey en az bir kez teslimat (at-least-once delivery), yani endpoint’iniz tamamen aynı mantıksal isteği iki, üç, hatta on kez alabilir.

GET /orders/123 isteği için bu zararsız. Veriyi iki kez okumak hiçbir şeyi değiştirmez. Ama POST /payments/charge için, bu retry’ların her biri yepyeni bir çekim tetikleyebilir, çünkü server açısından bu, yeni ve alakasız bir istek gibi görünür.

Eski Yöntem: Mükerrer İsteklere Karşı Hiçbir Koruma Yok

Çoğu ekip hiçbir koruma olmadan başlar. Tipik, naif bir ödeme endpoint’i şöyle görünür:


[HttpPost("charge")]
public async Task<IActionResult> ChargeCard([FromBody] ChargeRequest request)
{
 var result = await _paymentGateway.ChargeAsync(request.CardToken, request.Amount);

 await _orderRepository.MarkAsPaidAsync(request.OrderId, result.TransactionId);

 return Ok(result);
}

Bu, happy path’te gayet iyi çalışır. Ama client, aslında başarılı olmak üzere olan bir response’u beklerken timeout’a düşerse neler olduğuna bakalım:

Client, #4711 numaralı sipariş için POST /payments/charge isteği gönderir.
Server payment gateway’i çağırır, kart başarıyla çekilir.
Server response dönmeden önce, client’ın HTTP timeout’u devreye girer.
Client, standart retry mantığını izleyerek aynı isteği tekrar gönderir.
Server ilk denemeyi hiç hatırlamadığı için kartı ikinci kez çeker.

Bunu “timeout olmasın yeter” diyerek çözemezsiniz, çünkü timeout’lar, kopan bağlantılar ve process crash’leri microservices ve diğer distributed system’lerde ağ üzerinden çalışan bir servisi işletmenin normal bir parçası. Çözüm retry’ları önlemek değil, doğru tasarlanmış bir idempotent API ile retry’ları güvenli hale getirmek.

Neden Idempotency Key?

Idempotency key, genellikle client tarafında üretilen bir UUID olan, çağıranın isteğe eklediği benzersiz bir tanımlayıcıdır. API’nize şunu söyler: “bu belirli deneme, kaç kere görürsen gör, tek bir mantıksal işlemi temsil ediyor.” Server’ın görevi şudur:

İlk başarılı isteğin sonucunu bu key’e karşılık saklamak.
Aynı key’i taşıyan herhangi bir mükerrer istekte, işlemi yeniden çalıştırmak yerine saklanan sonucu döndürmek.
Aynı key’i farklı bir payload ile yeniden kullanan istekleri reddetmek (client’ın key’i yanlış kullandığının bir işareti).

Bir API’yi Gerçekten Idempotent Yapan Nedir

Sıradan bir endpoint’i idempotent bir API’ye dönüştürmek, client kaç kere aynı key ile çağırırsa çağırsın, endpoint’in şu üç özelliği sağlaması demektir:

Side effect’lerin tek seferde çalışması: payment gateway, envanter sistemi veya veritabanı yazma işlemi yalnızca bir kez gerçekleşir.
Tutarlı response: her retry, orijinal denemeyle tamamen aynı response body ve status code’u geri alır.
Sınırlı yaşam süresi: key belirli bir süre sonra expire olur, böylece store sonsuza kadar büyümez ve bir client’ın yanlışlıkla yeniden kullandığı bir key yüzünden meşru yeni istekler engellenmez.

Gezegendeki en çok retry atılan API’lerden biri olan Stripe, tam olarak bu pattern’i dokümante ediyor ve durum değiştiren tüm isteklerde bir Idempotency-Key header’ı zorunlu kılıyor. Bu bir “olsa iyi olur” özelliği değil; retry ağırlıklı SDK’larını bir ödeme API’sine karşı güvenle kullanılabilir kılan temel yapı.

Idempotency Store’u Tasarlamak

Herhangi bir middleware yazmadan önce, idempotency kayıtlarını saklayacak bir yere ihtiyacınız var. Basit bir relational tablo gayet iyi iş görür:


CREATE TABLE IdempotencyKeys (
 Key VARCHAR(64) NOT NULL PRIMARY KEY,
 RequestHash VARCHAR(64) NOT NULL,
 ResponseStatus INT NULL,
 ResponseBody TEXT NULL,
 Status VARCHAR(20) NOT NULL, -- 'Processing' | 'Completed'
 CreatedAt TIMESTAMP NOT NULL,
 ExpiresAt TIMESTAMP NOT NULL
);

Burada önemli olan birkaç tasarım kararı var:

RequestHash: request body’nin hash’i, böylece bir client’ın aynı key’i farklı bir payload için yeniden kullanıp kullanmadığını tespit edebilirsiniz (bu bir client bug’ı ve saklanan yanlış response’u sessizce döndürmek yerine 422 dönmelisiniz).
Status: sadece “Completed” değil, bir “Processing” state’ine de ihtiyacınız var, böylece ikinci, eşzamanlı bir istek ilkinin hâlâ devam ettiğini anlayabilir. Mükerrer çekime karşı asıl garanti, veritabanının Key üzerindeki unique constraint’inin ikinci insert’i reddetmesinden gelir, sadece Status kolonundan değil — bunu aşağıdaki store implementasyonunda göreceksiniz.
ExpiresAt: idempotency key’ler sonsuza kadar yaşamamalı. Stripe bunları 24 saat sonra expire ediyor; client’larınızın gerçekçi olarak ne kadar süre retry attığına uyan bir pencere seçin ve ExpiresAt‘i geçmiş satırları silen bir background cleanup job’ı çalıştırın, böylece tablo sınırsızca büyümesin.

Bu şemanın Postgres tarzı SQL (ON CONFLICT) kullandığını unutmayın. SQL Server kullanıyorsanız, karşılığı MERGE veya Key üzerinde unique index ile birleştirilmiş bir IF NOT EXISTS guard’ıdır — concurrency güvenliği prensibi aynı, sadece syntax farklı.

.NET’te Uygulamak

Bunu bir ActionFilter olarak inşa edelim, böylece business logic’i kirletmeden idempotency korumasına ihtiyaç duyan herhangi bir endpoint’e deklaratif olarak uygulanabilir.

1. Idempotency Store

Bu örnek raw SQL erişimi için Dapper kullanıyor, önce onu ekleyin:


dotnet add package Dapper


public interface IIdempotencyStore
{
 Task<IdempotencyRecord?> GetAsync(string key, CancellationToken ct);
 Task<bool> TryStartProcessingAsync(string key, string requestHash, CancellationToken ct);
 Task CompleteAsync(string key, int statusCode, string responseBody, CancellationToken ct);
}

public record IdempotencyRecord(string RequestHash, string Status, int? ResponseStatus, string? ResponseBody);

TryStartProcessingAsync metodu kritik parça. Bu, atomik bir “yoksa insert et” işlemi olmalı, aksi halde aynı key’e sahip iki eşzamanlı istek de kontrolü geçip ikisi de kartı çekmeye devam edebilir:


public class SqlIdempotencyStore : IIdempotencyStore
{
 private readonly IDbConnection _db;

 public SqlIdempotencyStore(IDbConnection db) => _db = db;

 public async Task<bool> TryStartProcessingAsync(string key, string requestHash, CancellationToken ct)
 {
 // Relies on the PRIMARY KEY constraint on `Key` to fail on duplicates
 const string sql = @"
 INSERT INTO IdempotencyKeys (Key, RequestHash, Status, CreatedAt, ExpiresAt)
 VALUES (@Key, @RequestHash, 'Processing', @Now, @Expires)
 ON CONFLICT (Key) DO NOTHING
 RETURNING Key;";

 var inserted = await _db.QueryFirstOrDefaultAsync<string>(sql, new
 {
 Key = key,
 RequestHash = requestHash,
 Now = DateTime.UtcNow,
 Expires = DateTime.UtcNow.AddHours(24)
 });

 return inserted != null;
 }

 public async Task<IdempotencyRecord?> GetAsync(string key, CancellationToken ct)
 {
 const string sql = "SELECT RequestHash, Status, ResponseStatus, ResponseBody FROM IdempotencyKeys WHERE Key = @Key";
 return await _db.QueryFirstOrDefaultAsync<IdempotencyRecord>(sql, new { Key = key });
 }

 public async Task CompleteAsync(string key, int statusCode, string responseBody, CancellationToken ct)
 {
 const string sql = @"
 UPDATE IdempotencyKeys
 SET Status = 'Completed', ResponseStatus = @Status, ResponseBody = @Body
 WHERE Key = @Key";

 await _db.ExecuteAsync(sql, new { Key = key, Status = statusCode, Body = responseBody });
 }
}

ON CONFLICT (Key) DO NOTHING ... RETURNING Key numarası, veritabanının unique constraint’inin concurrency kontrolünü sizin yerinize yapmasını sağlar, böylece application seviyesinde lock’lara ihtiyacınız kalmaz.

2. Action Filter


public class IdempotentAttribute : Attribute, IAsyncActionFilter
{
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 var httpContext = context.HttpContext;

 // Let model validation fail first - an invalid request should never consume a key.
 if (!context.ModelState.IsValid)
 {
 await next();
 return;
 }

 if (!httpContext.Request.Headers.TryGetValue("Idempotency-Key", out var keyHeader) ||
 string.IsNullOrWhiteSpace(keyHeader) || keyHeader.ToString().Length > 64)
 {
 context.Result = new BadRequestObjectResult("A valid Idempotency-Key header (max 64 chars) is required.");
 return;
 }

 var store = httpContext.RequestServices.GetRequiredService<IIdempotencyStore>();
 var key = keyHeader.ToString();
 var requestHash = await ComputeRequestHashAsync(httpContext.Request);

 var existing = await store.GetAsync(key, httpContext.RequestAborted);

 if (existing is not null)
 {
 if (existing.RequestHash != requestHash)
 {
 context.Result = new UnprocessableEntityObjectResult(
 "Idempotency-Key was reused with a different request payload.");
 return;
 }

 if (existing.Status == "Completed")
 {
 context.Result = new ContentResult
 {
 StatusCode = existing.ResponseStatus,
 Content = existing.ResponseBody,
 ContentType = "application/json"
 };
 return;
 }

 // Still processing - a concurrent duplicate arrived while the first one is in flight.
 context.Result = new ConflictObjectResult("Request with this Idempotency-Key is already being processed.");
 return;
 }

 var acquired = await store.TryStartProcessingAsync(key, requestHash, httpContext.RequestAborted);
 if (!acquired)
 {
 // Lost the race to a concurrent request that inserted first.
 context.Result = new ConflictObjectResult("Request with this Idempotency-Key is already being processed.");
 return;
 }

 var executedContext = await next();

 // Persist whatever the action produced so retries get an identical replay.
 // Anything other than ObjectResult (exceptions, StatusCodeResult, etc.) should
 // still release the key - otherwise it stays stuck in "Processing" until it expires.
 if (executedContext.Result is ObjectResult objectResult)
 {
 var statusCode = objectResult.StatusCode ?? 200;
 var body = JsonSerializer.Serialize(objectResult.Value, httpContext.RequestServices
 .GetRequiredService<IOptions<JsonOptions>>().Value.JsonSerializerOptions);
 await store.CompleteAsync(key, statusCode, body, httpContext.RequestAborted);
 }
 else
 {
 var statusCode = executedContext.Exception is not null ? 500 : (httpContext.Response.StatusCode);
 await store.CompleteAsync(key, statusCode, string.Empty, httpContext.RequestAborted);
 }
 }

 private static async Task<string> ComputeRequestHashAsync(HttpRequest request)
 {
 request.EnableBuffering();
 using var reader = new StreamReader(request.Body, leaveOpen: true);
 var body = await reader.ReadToEndAsync();
 request.Body.Position = 0;

 var bytes = Encoding.UTF8.GetBytes(body);
 var hash = SHA256.HashData(bytes);
 return Convert.ToHexString(hash);
 }
}

Değinilmesi gereken iki detay var: JsonSerializerOptions, uygulamanın gerçek AddJsonOptions konfigürasyonundan IOptions<JsonOptions> üzerinden alınıyor, böylece replay edilen body, client’ın zaten beklediği casing ve converter’larla eşleşiyor — burada default serializer’ı kullanmak sessizce orijinal response’tan farklı bir payload üretirdi. Ve hatalar dahil her code path artık CompleteAsync‘i çağırıyor, böylece bir key hiçbir zaman kalıcı olarak "Processing"‘de takılı kalmıyor; bunu, bir şekilde yine de takılı kalan herhangi bir kaydın otomatik olarak geri alınması için ExpiresAt cleanup job’ı ile birleştirin.

3. Idempotent API’yi Endpoint’e Uygulamak


[HttpPost("charge")]
[Idempotent]
public async Task<IActionResult> ChargeCard([FromBody] ChargeRequest request)
{
 var result = await _paymentGateway.ChargeAsync(request.CardToken, request.Amount);
 await _orderRepository.MarkAsPaidAsync(request.OrderId, result.TransactionId);

 return Ok(result);
}

Artık client, her mantıksal ödeme denemesi için bir UUID üretmekten ve aynı denemenin her retry’ında bunu Idempotency-Key header’ı olarak göndermekten sorumlu:


$ curl -X POST https://api.example.com/payments/charge \
 -H "Idempotency-Key: 8f14e45f-ceea-467e-bb9d-8f7c1a1c1b1a" \
 -H "Content-Type: application/json" \
 -d '{"orderId":"4711","cardToken":"tok_visa","amount":4999}'

Response gelmeden ağ koparsa ve client aynı header ile retry atarsa, ikinci istek payment gateway’e bir daha hiç dokunmadan ilk denemede saklanan sonucu döndürür.

Bunun Çözmediği Şeyler

Idempotency key’ler sihirli bir değnek değil, sınırlarını açıkça belirtmekte fayda var:

Outbox pattern’inin yerini tutmaz. Charge handler’ınız aynı zamanda bir OrderPaidEvent yayınlaması gerekiyorsa, klasik dual-write problemini önlemek için o event için hâlâ transactional garantilere ihtiyacınız var.
Client işbirliği gerektirir. Mobil client’ınız aynı UUID’yi yeniden kullanmak yerine her retry’da yeni bir UUID üretirse, tüm pattern boşa çıkar. Bunu API kontratınızda açıkça dokümante edin ve key’i her HTTP denemesinde değil, kullanıcı “Öde"ye bastığı anda client tarafında üretmeyi düşünün.
Her istekte bir yazma işlemi ekler. Aşırı yüksek throughput’lu, düşük değerli endpoint’ler için ekstra veritabanı round-trip’i buna değmeyebilir. Bu pattern’i, mükerrerliğin gerçekten pahalıya mal olduğu işlemler için saklayın: ödemeler, sipariş oluşturma ve para veya envanter hareket ettiren her şey.
Expiration bir trade-off. Çok kısa olursa, meşru ama yavaş retry’lar pencerenin dışında kalır ve yine de mükerrer çekim olur. Çok uzun olursa, sürekli büyüyen bir ölü kayıt tablosu biriktirirsiniz. Expire olmuş key’leri temizleyen bir background cleanup job’ı ilk günden inşa edilmeye değer.

Özet

Retry’lar distributed system’lerde bir edge case değil; payment gateway’lerle, webhook’larla ve birbiriyle konuşan microservices’lerin normal işleyiş koşuludur. Idempotency key pattern retry’ları önlemeye çalışmaz, “bu ödeme çekildi mi?” sorusunu bir tahmin yerine bir lookup’a çevirerek onları zararsız hale getirir. Yazının başındaki, iki kere ücretlendirilip ücretlendirilmediğini merak eden o müşteriyi hatırlayın? Idempotent bir API yerinde olsaydı, o retry sessizce tamamen aynı başarı response’unu döndürürdü ve müşteri bir ağ sorunu yaşandığından haberdar bile olmazdı. Bir ödeme API’si, bir webhook receiver’ı veya mükerrer çalışmanın gerçek bir maliyeti olan başka bir şey inşa ediyorsanız, idempotency key’leri sonradan eklenen bir yama değil, birinci sınıf bir gereksinim olarak ele alın.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Yazılım Mimarisinde Events vs Commands: Kapsamlı Bir .NET Rehberi

Mon, 22 Jun 2026 14:55:00 +0300

Modern yazılım mühendisliği dünyasında, monolitik sistemlerden dağıtık microservices mimarilerine geçiş yaygın bir evrimsel yoldur. Sistemler karmaşıklaştıkça, farklı bileşenlerin, modüllerin ve servislerin iletişim kurma şekli; sistemin dayanıklılığını, ölçeklenebilirliğini ve sürdürülebilirliğini belirleyen kritik faktör haline gelir. Eğer sağlam, cloud-native uygulamalar geliştiriyorsanız, bileşenlerinizi birbirinden ayırma (decouple) ihtiyacıyla kaçınılmaz olarak karşılaşırsınız.

Bu iletişim ve decoupling stratejisinin merkezinde iki temel mesajlaşma deseni (pattern) yatar: Commands ve Events.

İlk bakışta birbirlerine benzeseler de —her ikisi de özünde sistemin bir parçasından diğerine gönderilen ve veri içeren mesajlardır— amaçları, işlenme şekilleri (handling) ve mimari etkileri birbirinden çok farklıdır. Software architecture içinde events vs commands ayrımını yanlış anlamak, bir Event-Driven Architecture (EDA) tasarlarken veya Command Query Responsibility Segregation (CQRS) uygularken düşülen en yaygın tuzaklardan biridir.

Bu kapsamlı rehberde, events ve commands arasındaki teorik farkları keşfedecek, hangisinin ne zaman kullanılacağını analiz edecek ve .NET ve C# kullanarak hikaye tadında pratik bir uygulamayı adım adım inceleyeceğiz.

Dağıtık Sistemlerde Temel İletişim Problemi

Tanımlara dalmadan önce, çözmeye çalıştığımız problemi anlayalım.

Bir e-ticaret uygulaması hayal edin. Kullanıcı “Ödeme Yap” (Checkout) butonuna tıklar. Geleneksel, sıkı sıkıya bağlı (tightly coupled) monolitik bir mimaride, sistem aşağıdaki adımları tek bir senkron akış içinde sırayla yürütebilir:

Sepeti doğrula.
Stoğu düş.
Ödemeyi işle.
Fatura oluştur.
Onay e-postası gönder.

Eğer e-posta sunucusu çökerse, tüm ödeme süreci başarısız olabilir, ödeme işlemi geri alınabilir ve kullanıcı hüsrana uğrayabilir. Bu sıkı bağ (tight coupling), kırılgan sistemler yaratır.

Bunu çözmek için mimarlar asynchronous messaging kavramını devreye sokarlar. Servisler metotları doğrudan çağırmak yerine, bir mediator veya bir message broker (RabbitMQ, Apache Kafka veya AWS ve Google Cloud üzerindeki cloud-native çözümler gibi) aracılığıyla birbirlerine mesaj gönderirler. Peki bu mesajlar nasıl yapılandırılmalıdır? Ödeme servisi, e-posta servisine bir e-posta göndermesini mi söylemeli, yoksa sadece bir siparişin verildiğini mi belirtmeli?

İşte Commands ve Events arasındaki ayrım bu noktada kritik bir hal alır.

Command Nedir?

Bir Command, bir niyetin (intent) ifadesidir. Sistemin belirli bir eylemi gerçekleştirmesi veya durumunu (state) değiştirmesi için yapılan bir istektir.

Bir command’i emir kipiyle verilmiş bir talimat olarak düşünün. Sisteme tam olarak ne yapmasını istediğinizi söylüyorsunuz. Bir istek olduğu için, bir command reddedilebilir. Sistem command’i doğrulayabilir ve iş kuralları, izinler veya geçersiz veriler nedeniyle çalıştırılamayacağına karar verebilir.

Bir Command’in Temel Özellikleri:

Imperative Naming (Emir Kipiyle İsimlendirme): Command’ler emir kipindeki fiillerle isimlendirilir (örneğin, PlaceOrderCommand, CreateUserCommand, ProcessPaymentCommand).
Targeted (Hedefe Yönelik): Bir command tam olarak bir handler’a yönlendirilir (routed). Bir command’i tüm sisteme yayınlamazsınız (broadcast); onu o eylemden sorumlu olan belirli bileşene gönderirsiniz.
Can Fail (Başarısız Olabilir): Durumu (state change) değiştirmeye yönelik bir istek olduğundan, alıcı handler doğrulama başarısız olursa bu isteği reddedebilir (ve genellikle reddeder) ve gönderene bir hata veya exception döndürür.
High Coupling (Behavioral): Command’i gönderen taraf ne yapılması gerektiğini bilmek zorundadır. Fiziksel bağ bir mesaj veriyolu ile soyutlanmış olsa da, bu durum events’e kıyasla daha sıkı bir davranışsal bağ anlamına gelir.

Event Nedir?

Öte yandan bir Event, bir gerçeğin (fact) ifadesidir. Geçmişte bir şeyin zaten gerçekleşmiş olduğunun duyurusudur.

Bir event’i reddedemezsiniz çünkü geçmişi değiştiremezsiniz. Eğer bir event yayınlanmışsa (published), state change çoktan gerçekleşmiştir. Sistemdeki bileşenler, bu olaylara tepki vermek ve kendi ardışık süreçlerini tetiklemek için events’i dinlerler.

Bir Event’in Temel Özellikleri:

Past-Tense Naming (Geçmiş Zamanla İsimlendirme): Events, geçmiş zamanlı fiiller kullanılarak isimlendirilir (örneğin, OrderPlacedEvent, UserCreatedEvent, PaymentProcessedEvent).
Broadcasted (Yayınlanan - Publish/Subscribe): Bir event, bir event bus veya message broker’a yayınlanır. Sıfır, bir veya birden fazla handler’ı olabilir. Yayınlayan taraf (publisher), kimin dinlediğini bilmez ve umursamaz.
Cannot Be Rejected (Reddedilemez): Olay zaten gerçekleşmiştir. Abone olanlar (subscribers) bunu işlemek zorundadır. Eğer bir subscriber bir event’i işlemekte başarısız olursa, kendi retry (yeniden deneme) mantığını yürütmelidir; publisher’a bu gerçeği “geri almasını” söyleyemez.
Loose Coupling (Gevşek Bağ): Gönderici (publisher), alıcılardan (subscribers) tamamen izole edilmiştir (decoupled). Publisher sadece bir durum değişikliğini duyurur, bu da mevcut koda hiç dokunmadan sisteme yeni işlevsellikler eklemeyi inanılmaz derecede kolaylaştırır.

Temel Farklar: Events vs Commands

Kavramları pekiştirmek için yan yana bir karşılaştırma yapalım.

Özellik	Command	Event
Tanım	Bir eylemi gerçekleştirmek için yapılan istek.	Bir şeyin gerçekleştiğine dair bildirim.
İsimlendirme Standardı	Emir Kipi (örn. `ShipOrder`)	Geçmiş Zaman (örn. `OrderShipped`)
Yönlendirme / Handlers	Tam olarak bir handler (1:1).	Sıfırdan çoka kadar handlers (1:N).
Yön	Noktadan noktaya (Point-to-point). Gönderen bir alıcıyı hedefler.	Publish/Subscribe. Gönderen yayınlar.
Hata Yönetimi	Reddedilebilir (doğrulama hatası).	Reddedilemez. Geçmiş olaylar değiştirilemez (immutable).
Gönderenin Bilgisi	Ne yapılması gerektiğini bilir.	Event ile kimin ilgilendiğini bilmez.

.NET Uygulama Hikayesi: Hayata Geçirmek

Bu kavramların gerçek dünya uygulamalarında nasıl bir araya geldiğini göstermek için .NET kullanarak bir hikaye anlatalım. .NET ekosisteminde in-memory (bellek içi) mesajlaşma ve CQRS pattern’leri için standart uygulama olan, oldukça popüler MediatR kütüphanesini kullanacağız.

Bir Sipariş Yönetimi microservice’i inşa ettiğimizi hayal edelim.

Adım 1: Command’i Tanımlamak

Yolculuk, bir kullanıcının sepetini onaylamasıyla başlar. API controller HTTP isteğini alır ve bir command oluşturur. Emir kipiyle isimlendirmeye dikkat edin. Mesajlar değiştirilemez (immutable) olması gerektiği için C# record’larını kullanıyoruz.

using MediatR;

namespace ECommerce.Domain.Commands;

// The Command: A request that returns a strongly typed result
public record PlaceOrderCommand(
 Guid CustomerId,
 List<CartItem> Items,
 string ShippingAddress
) : IRequest<OrderResult>;

public record CartItem(Guid ProductId, int Quantity, decimal Price);

public record OrderResult(bool IsSuccess, string Message, Guid? OrderId = null);

Adım 2: Command’i İşlemek (Handling)

Command tam olarak bir handler’a yönlendirilir. Bu handler temel iş mantığını içerir. İsteği doğrular, veritabanı durumunu günceller ve eğer başarılı olursa bir Event üretir.

using MediatR;

namespace ECommerce.Application.Handlers.Commands;

public class PlaceOrderCommandHandler : IRequestHandler<PlaceOrderCommand, OrderResult>
{
 private readonly IOrderRepository _repository;
 private readonly IMediator _mediator;

 public PlaceOrderCommandHandler(IOrderRepository repository, IMediator mediator)
 {
 _repository = repository;
 _mediator = mediator;
 }

 public async Task<OrderResult> Handle(PlaceOrderCommand request, CancellationToken cancellationToken)
 {
 // 1. Validation (The command can be rejected!)
 if (request.Items == null || !request.Items.Any())
 {
 return new OrderResult(false, "Cart cannot be empty.");
 }

 // 2. State Change
 var totalAmount = request.Items.Sum(i => i.Price * i.Quantity);
 var order = new Order(Guid.NewGuid(), request.CustomerId, totalAmount, request.ShippingAddress);

 await _repository.SaveAsync(order);

 // 3. Announcing the Fact (The Event)
 var orderPlacedEvent = new OrderPlacedEvent(order.Id, request.CustomerId, totalAmount);

 // Notice we are Publishing the event, not Sending a command.
 await _mediator.Publish(orderPlacedEvent, cancellationToken);

 return new OrderResult(true, "Order successfully placed.", order.Id);
 }
}

Adım 3: Event’i Tanımlamak

Durum (state) değişti. Sipariş güvenli bir şekilde veritabanına kaydedildi. Artık sistem sadece bu gerçeği uygulamanın geri kalanına duyurur. Geçmiş zamanlı isimlendirmeye dikkat edin.

using MediatR;

namespace ECommerce.Domain.Events;

// The Event: A notification that something happened. Does not return a response.
public record OrderPlacedEvent(
 Guid OrderId,
 Guid CustomerId,
 decimal TotalAmount
) : INotification;

Adım 4: Event’e Tepki Vermek (Multiple Handlers)

İşte Event-Driven Architecture‘ın büyüsünün parladığı yer burasıdır. Bir event yayınladığımız için, çekirdek PlaceOrderCommandHandler sınıfımızı değiştirmeden, birbirinden bağımsız birden fazla handler’ın bu olaya tepki vermesini sağlayabiliriz.

Diyelim ki pazarlama ekibi bir “Teşekkürler” e-postası göndermek istiyor ve lojistik ekibinin stoğu ayırması gerekiyor. Basitçe iki ayrı event handler oluşturuyoruz.

Handler A: E-posta Servisi

using MediatR;

namespace ECommerce.Application.Handlers.Events;

public class SendOrderConfirmationEmailHandler : INotificationHandler<OrderPlacedEvent>
{
 private readonly IEmailService _emailService;

 public SendOrderConfirmationEmailHandler(IEmailService emailService)
 {
 _emailService = emailService;
 }

 public async Task Handle(OrderPlacedEvent notification, CancellationToken cancellationToken)
 {
 // React to the fact
 await _emailService.SendEmailAsync(
 notification.CustomerId,
 $"Thank you for your order! Your total is ${notification.TotalAmount}."
 );
 }
}

Handler B: Envanter Servisi

using MediatR;

namespace ECommerce.Application.Handlers.Events;

public class ReserveInventoryHandler : INotificationHandler<OrderPlacedEvent>
{
 private readonly IInventoryService _inventoryService;

 public ReserveInventoryHandler(IInventoryService inventoryService)
 {
 _inventoryService = inventoryService;
 }

 public async Task Handle(OrderPlacedEvent notification, CancellationToken cancellationToken)
 {
 // React to the same fact independently
 await _inventoryService.ReserveItemsForOrderAsync(notification.OrderId);
 }
}

.NET kodumuzu bu şekilde yapılandırarak harika bir loosely coupled (gevşek bağlı) sistem elde ettik. Yarın analiz ekibi satışları takip etmek isterse, PlaceOrderCommandHandler‘a dokunmayız. Sadece OrderPlacedEvent‘i dinleyen bir TrackSalesAnalyticsHandler ekleriz.

İleri Düzey Mimari Değerlendirmeler

MediatR örneği in-memory kavramları mükemmel bir şekilde gösterse de, bu pattern’leri bellekten çıkarıp dağıtık (distributed) bir bulut ortamına taşımak karmaşık zorlukları beraberinde getirir. Microservices’leri çalıştırmak için Google Cloud, AWS veya Azure gibi cloud platformları kullanıldığında, mesajlaşma yapısı da dağıtık hale gelir.

İşte Events vs Commands yapılarını ölçeklendirirken göz önünde bulundurmanız gereken üç ileri düzey pattern:

1. The Outbox Pattern (Garantili Teslimat)

C# örneğimizde siparişi veritabanına kaydettik ve ardından event’i MediatR’a yayınladık. Peki ya veritabanı kaydı başarılı olur ancak uygulama tam olarak await _mediator.Publish() satırı çalıştırılmadan bir milisaniye önce çökerse?

Durum değişti, ancak event hiçbir zaman fırlatılmadı. Müşterinin kartından para çekildi, ancak deponun haberi olmadı. Bu, dağıtık sistemlerde “Dual Write Problem” (Çift Yazma Problemi) olarak bilinen yıkıcı bir hatadır.

Bunu çözmek için mimarlar Outbox Pattern (veya Transactional Outbox Pattern) kullanırlar. Command handler, event’i doğrudan yayınlamak yerine, siparişin kendisiyle aynı veritabanı transaction’ı içinde OrderPlacedEvent‘i bir “Outbox” tablosuna yazar. Ayrı bir arka plan süreci (bir .NET BackgroundService gibi) sürekli olarak bu Outbox tablosunu okur ve mesajları harici broker’ınıza (örn. RabbitMQ veya Google Cloud Pub/Sub) yayınlar. Bu, event’lerinizin en az bir kere teslim edilmesini garanti eder.

2. Idempotency (Yinelenen Event’leri İşlemek)

Dağıtık mesajlaşma sistemleri genellikle “en az bir kere” teslimat garantisi sunduğundan, event handler’larınız aynı OrderPlacedEvent‘i iki kez alabilir.

Eğer SendOrderConfirmationEmailHandler dikkatlice tasarlanmazsa, müşteri iki e-posta alabilir. Daha da kötüsü, bir event ödeme alımını tetikliyorsa, müşteriden iki kez ücret alınabilir.

Event handler’lar idempotent olmalıdır. Bu, aynı event’i birden fazla kez uygulamanın, bir kez uygulamakla aynı etkiye sahip olması anlamına gelir. .NET’te bu genellikle işlenmiş EventId‘lerin tutulduğu bir tablo aracılığıyla uygulanır. Bir handler bir event’i işlemeden önce kontrol eder: “Bu Event ID’yi daha önce gördüm mü?” Eğer evetse, onu güvenli bir şekilde yoksayar ve başarılı bir yanıt döner.

3. Event Sourcing vs Event-Driven Architecture

Bir Event-Driven Architecture‘ı (EDA), Event Sourcing ile karıştırmamak önemlidir.

EDA, servisler arasında iletişim kurmak için events kullanır (yukarıdaki örneğimizde olduğu gibi). Durum (state) hala geleneksel bir veritabanı tablosunda (örneğin, bir Status sütunu olan Orders tablosunda) saklanır.
Event Sourcing ise events’in veritabanının ta kendisi olduğu çok daha karmaşık bir paradigmadır. Bir siparişin mevcut durumunu kaydetmek yerine, sadece ekleme yapılabilen (append-only) bir olaylar günlüğü (log) kaydedersiniz: OrderCreated, AddressUpdated, ItemAdded, OrderCheckedOut. Sistemin mevcut durumu bulabilmesi için events başlangıç zamanından itibaren yeniden oynatılır. Denetim izleri için güçlü olsa da, devasa bir karmaşıklık getirir ve finansal defterler gibi katı tarihsel doğruluk gerektiren özel alanlara saklanmalıdır.

Hangisini Ne Zaman Kullanmalı?

Yazılım tasarımının güzelliği, iş için doğru aracı seçmektir. İşte .NET uygulamalarınızda Commands vs Events tercihini ne zaman yapacağınıza dair kısa bir kopya kağıdı:

Şu durumlarda Command kullanın:

Sistemin belirli bir eylemi gerçekleştirmesine ihtiyacınız varsa ve bunu hangi bileşenin işlemesi (handle) gerektiğini tam olarak biliyorsanız.
Kullanıcı girdisini doğrulamanız ve potansiyel olarak isteği reddetmeniz gerekiyorsa.
Geriye bir sonuç bekliyorsanız (başarı, başarısızlık veya yeni oluşturulan bir entity’nin ID’si).

Şu durumlarda Event kullanın:

Önemli bir durum değişikliği (state change) gerçekleştiyse ve sistemin diğer parçalarını bilgilendirmek istiyorsanız.
Farklı, bağımsız modüllerin sıkı bir bağ (tight coupling) yaratmadan tek bir eyleme tepki vermesine izin vermek istiyorsanız.
Microservice sınırları arasında entegrasyon yapıyorsanız ve servislerin otonom kalmasını sağlamak istiyorsanız.

Özet

Software architecture içinde events vs commands arasındaki farkta uzmanlaşmak, bir geliştiricinin system design mükemmelliğine giden yolculuğunda önemli bir kilometre taşıdır. Commands uygulamanızın niyetini yönlendirir ve iş kurallarını korur, durum değişikliklerinin sadece geçerli olduğunda gerçekleşmesini sağlar. Events ise sistemin sinir ağı gibi davranır, gerçekleri yayınlar ve yüksek ölçeklenebilir, loosely coupled (gevşek bağlı) bir microservices ekosistemini mümkün kılar.

.NET’teki MediatR gibi güçlü kütüphanelerden yararlanarak ve asynchronous messaging inceliklerini anlayarak, sadece günümüz iş mantığının karmaşıklığıyla başa çıkabilen değil, aynı zamanda yarının gereksinimlerine uyum sağlayacak kadar esnek ve dayanıklı sistemler inşa edebilirsiniz. Command’lerinizi emir kipiyle isimlendirmeyi, event’lerinizi geçmişin değiştirilemez gerçekleri olarak ele almayı ve decouple mimarinin gücünü kucaklamayı unutmayın.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme konusundaki araştırmalarımı kaçırmamak için beni @berkslv adresinden takip edebilirsiniz.

.NET'te Anemic'ten Rich Domain Model'e Refactoring

Tue, 16 Jun 2026 00:00:00 +0300

.NET’te kurumsal uygulamalar geliştirmek için önemli bir zaman harcadıysanız, Domain-Driven Design (DDD) kavramıyla karşılaşmış olmanız muhtemeldir. DDD, kodunuzu temsil ettiği gerçek dünya iş domain’iyle hizalayarak yazılım karmaşıklığıyla başa çıkmanın bir yolunu vaat eder. Ancak, geliştiricilerin DDD’yi—veya sadece temel Object-Oriented Programming’i (OOP)—benimserken düştükleri en yaygın tuzaklardan biri Anemic Domain Model yaratmaktır.

Birçok .NET mimarisinde tanıdık bir pattern görürsünüz: yalnızca public getter ve setter’lardan oluşan torbalar olan “entity"ler ve bunlara eşlik eden, tüm iş kurallarını (business rules), validation ve state manipulation mantığını içeren devasa “service” sınıfları. Bu yapı, özellikle veritabanı odaklı bir geçmişten gelenler için rahat hissettirse de, object-oriented design ve encapsulation prensiplerine aktif olarak ters düşer.

Bu kapsamlı rehberde, Anemic Domain Model’in tam olarak ne olduğunu, endüstri uzmanlarının bunu neden bir anti-pattern olarak gördüğünü ve C# uygulamalarınızı nasıl Rich Domain Model’e refactor edebileceğinizi inceleyeceğiz. Pratik kod örneklerine bakacak, Entity Framework Core (EF Core) ile persistence işlemlerini nasıl halledeceğimizi tartışacak ve mantığı entity’lerinizin içine taşımanın unit testing’i nasıl çocuk oyuncağı haline getirdiğini göreceğiz.

1. Anemic Domain Model Tuzağı

Anemic Domain Model Nedir?

“Anemic Domain Model” terimi ilk olarak 2003 yılında Martin Fowler tarafından meşhur edilmiştir. O, bu durumu nesnelerin gerçek domain entity’leri gibi göründüğü (genellikle iş alanındaki Customer, Order veya Invoice gibi isimlerle adlandırıldığı) ancak neredeyse hiçbir davranışa (behavior) sahip olmadığı bir anti-pattern olarak tanımlamıştır. Bunun yerine, onlar sadece birer veri konteyneridir (data containers)—public property’lerle dolu C# sınıflarıdır.

C#’ta anemic bir entity’nin klasik bir örneğine bakalım:

public class Order
{
 public Guid Id { get; set; }
 public Guid CustomerId { get; set; }
 public DateTime OrderDate { get; set; }
 public OrderStatus Status { get; set; }
 public decimal TotalAmount { get; set; }
 public List<OrderItem> Items { get; set; } = new List<OrderItem>();
 public string ShippingAddress { get; set; }
}

public enum OrderStatus
{
 Pending,
 Paid,
 Shipped,
 Cancelled
}

İlk bakışta bu tamamen normal görünebilir. Entity Framework eğitimlerinin büyük çoğunluğu sınıfları bu şekilde oluşturmanızı öğretir. Ancak bu sınıf davranıştan (behavior) tamamen yoksundur. Bu “aptal” (dumb) bir nesnedir.

Order kendi state’ini koruyamadığı için, uygulamanın herhangi bir kısmı onu doğrudan değiştirebilir:

var order = new Order();
// Bekle, müşterisi olmayan, ürün içermeyen ve çoktan kargolandı olarak işaretlenmiş bir sipariş mi?
order.Status = OrderStatus.Shipped;
order.TotalAmount = -500m; // Negatif tutar mı? Tabii, neden olmasın!

“Service” Katmanı Şişkinliği

Entity hiçbir mantığa sahip olmadığı için, iş kuralları (business rules) başka bir yerde yaşamalıdır. Bu durum genellikle Transaction Scripts olarak adlandırılan “God class"ların veya devasa service katmanlarının oluşmasına yol açar.

İşte anemic bir modelle uğraşırken bir OrderService‘in nasıl göründüğü:

public class OrderService
{
 public void AddItemToOrder(Guid orderId, OrderItem item)
 {
 var order = _repository.Get(orderId);

 if (order == null) throw new Exception("Order not found");

 if (order.Status == OrderStatus.Shipped || order.Status == OrderStatus.Cancelled)
 {
 throw new InvalidOperationException("Cannot modify a shipped or cancelled order.");
 }

 order.Items.Add(item);

 // Recalculate total
 order.TotalAmount = order.Items.Sum(i => i.Price * i.Quantity);

 _repository.Save(order);
 }
}

Bu kod çalışmasına rağmen, object-oriented programming kılığına girmiş prosedürel programlamayı (procedural programming) temsil eder. Bir Order‘ı neyin geçerli (valid) kıldığıyla ilgili mantık Order‘dan çıkarılıp OrderService içine atılmıştır.

Anemi’nin Maliyetleri

Domain modeliniz anemic olduğunda, birkaç önemli mimari maliyetle karşılaşırsınız:

Eksik Encapsulation: Herhangi bir yerdeki herhangi bir kod bir entity’nin state’ini değiştirebilir. Bir Order‘ın geçerli (valid) bir state’te olduğunu garanti etmek imkansızdır.
Tekrarlanan Logic: Farklı bir use case’te bir siparişin toplam tutarını yeniden hesaplamanız gerekirse (örneğin indirim uygularken), muhtemelen bu hesaplama mantığını başka bir service içinde kopyalayacaksınız.
Düşük Cohesion: Veri (Order) ve o veri üzerinde işlem yapan davranış (OrderService) birbirinden ayrılmıştır. Bir siparişin yaşam döngüsünü anlamak için birden fazla katman arasında gezinmeniz gerekir.
Kırılganlık (Fragility): Uygulama büyüdükçe, karmaşık iş mantığı onlarca service’e dağılır ve bu da bug’ların izini sürmeyi veya sistemi refactor etmeyi inanılmaz derecede zorlaştırır.

2. Çözüm: Rich Domain Model’e Giriş

Bir Rich Domain Model bu paradigmayı tam tersine çevirir. Rich bir modelde entity’ler zeki nesnelerdir. Hem kendi verilerini (state) hem de o verilerin nasıl mutate edilebileceğini yöneten iş kurallarını (behavior) encapsulate ederler.

Rich bir domain model üç temel sütun üzerine inşa edilir:

Her Zaman Geçerli State (Invariants): Bir entity asla geçersiz bir state’te bulunmamalıdır. Yaratılması ve mutate edilmesi sıkı bir şekilde kontrol edilir.
Encapsulation: Property’ler dışarıdan keyfi olarak değiştirilemez. State mutation’ları sadece açıkça isimlendirilmiş methodlar aracılığıyla gerçekleşir.
Behavior-Driven (Davranış Odaklı): Bir nesneden verilerini isteyip onun adına kararlar vermek yerine, nesneye ne yapacağını söylersiniz (Tell, Don’t Ask prensibi).

Anemic Order entity’mizi C#’ta behavior-driven, rich bir domain entity’sine refactor etme sürecine başlayalım.

3. C#’ta Adım Adım Rich Domain Model’e Refactoring

Adım 1: State’i Kilitleyin (Private Setter’lar)

Anemic bir modeli iyileştirmenin ilk adımı kanamayı durdurmaktır. Dışarıdaki kodun property’leri keyfi olarak değiştirmesini engellemeliyiz. Bunu tüm property setter’larını private veya protected yaparak başarıyoruz.

public class Order
{
 public Guid Id { get; private set; }
 public Guid CustomerId { get; private set; }
 public DateTime OrderDate { get; private set; }
 public OrderStatus Status { get; private set; }
 public decimal TotalAmount { get; private set; }
 public string ShippingAddress { get; private set; }

 // We don't want external code adding to the list directly
 private readonly List<OrderItem> _items = new List<OrderItem>();
 public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
}

Burada ne olduğuna dikkat edin:

set accessor’ları artık private. Siparişin state’ini okuyabilirsiniz, ancak doğrudan değiştiremezsiniz.
Items koleksiyonu artık IReadOnlyCollection<OrderItem> olarak dışarı sunuluyor. Gerçek liste, private readonly bir backing field’ın arkasına gizlenmiştir. Bu, birisinin dışarıdan order.Items.Add(...) çağırmasını engeller.

Adım 2: Anlamlı Constructor’lar

Setter’lar private ise, bir nesneyi nasıl oluştururuz? Başından itibaren geçerli (valid) bir entity oluşturmak için gerekli tüm bilgileri talep eden parametreli bir constructor kullanırız.

public class Order
{
 // ... properties ...

 public Order(Guid id, Guid customerId, string shippingAddress)
 {
 if (id == Guid.Empty) throw new ArgumentException("Order ID cannot be empty.");
 if (customerId == Guid.Empty) throw new ArgumentException("Customer ID cannot be empty.");
 if (string.IsNullOrWhiteSpace(shippingAddress)) throw new ArgumentException("Shipping address is required.");

 Id = id;
 CustomerId = customerId;
 ShippingAddress = shippingAddress;

 // Initial defaults
 OrderDate = DateTime.UtcNow;
 Status = OrderStatus.Pending;
 TotalAmount = 0m;
 }
}

Artık bir Customer ID veya Shipping Address olmadan bir Order oluşturmak tam anlamıyla imkansızdır. Derleyici (compiler) sizin iş kurallarınızı zorunlu kılar.

Adım 3: Domain Method’ları Ekleyin (Behavior)

State korunduğuna göre, state mutation’larına izin vermek için açık ve amacını belli eden methodlar eklememiz gerekiyor. Mantığı OrderService‘ten çıkarıp Order entity’sinin içine taşıdığımız yer burasıdır.

Bir öğe ekleme ve siparişi kargolandı olarak işaretleme mantığını implement edelim.

public class Order
{
 // ... constructor and properties ...

 public void AddItem(Product product, int quantity)
 {
 if (Status != OrderStatus.Pending)
 {
 throw new InvalidOperationException("Can only add items to a pending order.");
 }

 if (quantity <= 0)
 {
 throw new ArgumentException("Quantity must be greater than zero.");
 }

 var existingItem = _items.SingleOrDefault(i => i.ProductId == product.Id);
 if (existingItem != null)
 {
 existingItem.IncreaseQuantity(quantity);
 }
 else
 {
 _items.Add(new OrderItem(product.Id, product.Price, quantity));
 }

 RecalculateTotal();
 }

 public void Ship()
 {
 if (Status != OrderStatus.Paid)
 {
 throw new InvalidOperationException("Cannot ship an order that has not been paid.");
 }

 if (!_items.Any())
 {
 throw new InvalidOperationException("Cannot ship an empty order.");
 }

 Status = OrderStatus.Shipped;
 }

 private void RecalculateTotal()
 {
 TotalAmount = _items.Sum(item => item.Price * item.Quantity);
 }
}

Sonuçta Ortaya Çıkan Application Layer

Bu refactoring’den sonra OrderService‘imizin (Clean Architecture’da genellikle Command Handler veya Application Service olarak adlandırılır) nasıl göründüğüne bakalım:

public class OrderService
{
 public void AddItemToOrder(Guid orderId, Product product, int quantity)
 {
 var order = _repository.Get(orderId);
 if (order == null) throw new Exception("Order not found");

 // The logic is no longer here! We simply delegate to the domain.
 order.AddItem(product, quantity);

 _repository.Save(order);
 }
}

Application Service artık incedir ve tamamen bir orkestratör (orchestrator) görevi görür. Veritabanından entity’yi çeker, entity üzerindeki davranışı (behavior) çağırır ve yeni state’i tekrar veritabanına kaydeder. Tüm o ağır işler, business rule’lar ve invariant’lar Order sınıfının içine düzgün bir şekilde encapsulate edilmiştir. Bu, Domain-Driven Design prensipleriyle mükemmel bir şekilde uyum sağlar.

4. Entity Framework Core: Rich Model’leri Veritabanına Map Etmek

Geliştiricilerin Anemic Domain Model’lere bağlı kalmalarının tarihi ve büyük bir nedeni, Object-Relational Mapper’ların (ORM) bunları zorunlu kılmasıydı. Entity Framework’ün erken sürümleri, tabloları nesnelere map etmek için public setter’lar, parametresiz public constructor’lar ve public collection’lar talep ediyordu.

Neyse ki, modern Entity Framework Core (EF Core) inanılmaz derecede güçlüdür ve Domain-Driven Design pattern’lerini aktif olarak destekler. Persistence endişelerini domain’inize sızdırmadan tamamen encapsulate edilmiş bir Rich Domain Model’i koruyabilirsiniz.

İşte Rich Domain Model’leri veritabanına kaydetmek (persist) için ihtiyacınız olan temel EF Core özellikleri:

1. EF Core için Parametresiz Constructor’lar

EF Core veritabanından veri okuduğunda, property’lerini ayarlamadan önce nesnelerinizi instance haline getirmek için bir yola ihtiyaç duyar. Public bir parametresiz constructor istemezsiniz çünkü bu encapsulation’ı bozar. Bunun yerine, özellikle EF Core için private bir parametresiz constructor sağlayabilirsiniz.

public class Order
{
 // Public constructor for your application code
 public Order(Guid id, Guid customerId, string shippingAddress) { ... }

 // Private constructor for EF Core
 private Order() { }
}

EF Core nesneyi oluşturmak için reflection kullanır, bu yüzden private bir constructor mükemmel çalışırken API’nizi diğer geliştiricilerden de korur.

2. Private Backing Field’ları Map Etmek

EF Core, private backing field’ları otomatik olarak bulacak ve onlara bağlanacak (bind) kadar akıllıdır. Eğer bir IReadOnlyCollection<OrderItem> Items property’niz ve bir _items backing field’ınız varsa, veritabanından veri materialize ederken EF Core ilişkileri doğrudan _items alanına map edecektir.

Eğer isimlendirme kuralınız farklıysa, bunu OnModelCreating methodunda veya IEntityTypeConfiguration sınıfınızda açıkça yapılandırabilirsiniz:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
 public void Configure(EntityTypeBuilder<Order> builder)
 {
 builder.HasKey(o => o.Id);

 // Tell EF Core to use the private backing field for the collection
 builder.Metadata.FindNavigation(nameof(Order.Items))
 .SetPropertyAccessMode(PropertyAccessMode.Field);
 }
}

3. Owned Entity’ler Aracılığıyla Value Object’ler

Bir Rich Domain Model’de genellikle birbiriyle ilişkili property’leri Value Object’ler halinde gruplamak istersiniz. Örneğin, Currency ve Amount değerlerini bir entity üzerinde ayrı ayrı tutmak yerine, bir Money value object’i oluşturabilirsiniz.

EF Core bunu Owned Types (OwnsOne) aracılığıyla destekler:

// The Value Object
public class Money
{
 public string Currency { get; private set; }
 public decimal Amount { get; private set; }

 public Money(string currency, decimal amount)
 {
 Currency = currency;
 Amount = amount;
 }

 private Money() { } // For EF Core
}

// Inside your Entity Configuration:
builder.OwnsOne(o => o.Price, priceBuilder =>
{
 priceBuilder.Property(p => p.Currency).HasColumnName("PriceCurrency");
 priceBuilder.Property(p => p.Amount).HasColumnName("PriceAmount");
});

Bu, son derece anlamlı, object-oriented bir domain modeli korumanıza olanak tanırken, verileri tek bir SQL tablosuna düzgün bir şekilde düzleştirmenizi (flatten) sağlar.

5. Rich Domain Model’leri Unit Test Etmenin Büyüsü

Mantığı entity’lerinizin içine taşımanın en derin faydalarından biri de unit testing süreçlerinizin ne kadar kolaylaştığıdır.

Mantığınız devasa bir OrderService içinde yaşadığında, unit test yazmak acı vericidir. IOrderRepository‘yi mock’lamanız, IProductRepository‘yi mock’lamanız, loglama servisini mock’lamanız, veritabanı state’ini hazırlamanız (arrange) ve son olarak mantığı test etmeniz gerekir. Test kurulumu genellikle testin kendisinden daha büyüktür.

Ancak bir Rich Domain Model kullandığınızda, business logic tamamen entity’nin state’ine dayanır. Order sınıfınızın içinde harici bağımlılıklar, veritabanları veya API’ler yoktur. Bu saf (pure) bir C# kodudur.

Domain mantığını test etmek inanılmaz derecede basit ve ışık hızında hale gelir:

public class OrderTests
{
 [Fact]
 public void AddItem_Should_ThrowException_When_OrderIsNotPending()
 {
 // Arrange
 var order = new Order(Guid.NewGuid(), Guid.NewGuid(), "123 Main St");

 // Use reflection or a test-specific setup to transition state to Shipped 
 // (Assuming we have a Pay() then Ship() method)
 order.Pay();
 order.Ship();

 var product = new Product(Guid.NewGuid(), "Laptop", 1000m);

 // Act & Assert
 var exception = Assert.Throws<InvalidOperationException>(() =>
 order.AddItem(product, 1));

 Assert.Equal("Can only add items to a pending order.", exception.Message);
 }

 [Fact]
 public void AddItem_Should_IncreaseTotalAmount()
 {
 // Arrange
 var order = new Order(Guid.NewGuid(), Guid.NewGuid(), "123 Main St");
 var product = new Product(Guid.NewGuid(), "Laptop", 1000m);

 // Act
 order.AddItem(product, 2);

 // Assert
 Assert.Equal(2000m, order.TotalAmount);
 Assert.Single(order.Items);
 }
}

Bu testte sıfır mock olduğuna dikkat ettiniz mi? Rich Domain Model, iş mantığını altyapı (infrastructure) endişelerinden izole ettiği için domain katmanınız yüksek test edilebilirliğe (testability) ulaşır. Sadece in-memory C# sınıflarını çalıştırdığınız için binlerce karmaşık business varyasyonunu milisaniyeler içinde kapsayabilirsiniz.

Özet

Anemic Domain Model’den Rich Domain Model’e refactoring yapmak zihniyette bir değişim gerektirir. Entity’lerinizi sadece veritabanı tablolarının (veri yapıları / data structures) birer yansıması olarak görmekten uzaklaşmalı ve onları açık davranışları (behavior) olan yaşayan business konseptleri olarak görmeye başlamalısınız.

Private setter’lar, anlamlı constructor’lar, açık domain method’ları gibi prensipleri uygulayarak ve Tell, Don’t Ask kuralına bağlı kalarak, iş mantığınızı (business logic) tam olarak ait olduğu yerde, yani entity’nin içinde merkezileştirebilirsiniz.

Bu geçiş bir öğrenme eğrisi gerektirse de, EF Core’un private backing field’lar ve owned entity’ler gibi gelişmiş mapping yeteneklerinin entegrasyonu, artık veritabanınız uğruna object-oriented design’dan ödün vermek zorunda olmadığınız anlamına gelir. Uzun vadeli ödüller inkar edilemez: bug’lara ve technical debt’e aktif olarak direnen, yüksek düzeyde cohesive, derinlemesine encapsulate edilmiş ve kolayca test edilebilir bir kod tabanı.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için beni @berkslv adresinden takip edebilirsiniz.

Legacy WCF/SOAP'tan Modern .NET'e: Taviz Vermeden Migration

Fri, 12 Dec 2025 00:00:00 +0300

Legacy WCF/SOAP’tan Modern .NET’e: Taviz Vermeden Migration

Mükemmel migration planını hazırladınız. Yol haritası harika görünüyor: O yaşlanmış, bitik monolitik .NET Framework 4.8 WCF uygulamasını alıp dönüştüreceksiniz. Arayüzü .NET 10 üzerinde şık, state tutmayan bir REST API olarak yeniden yazacak ve sonunda o eski IIS sunucusunu kapatacaksınız.

Planı paydaşlara sunuyorsunuz. İç ekipler alkışlarla tezahürat yapıyor. DevOps ekibi çoktan Dockerfile’ları yazmaya başladı bile. Herkes çok heyecanlı.

Ve sonra o e-posta geliyor.

Büyük bir iş ortağının “Eski Entegrasyonlar” ekibinden veya belki de 2014’ten beri yazılım güncellemesi almamış bir donanım cihazını yöneten bir tedarikçiden geliyor. Mesajları kibar ama net:

“Bir REST API tüketemeyiz. Sistemlerimiz bir SOAP gerektiriyor. WSDL’in olduğu gibi kalmasına ihtiyacımız var. Eğer kontratı değiştirirseniz, size entegre olamayız.”

Aniden, migration planınız bir tuğla duvara çarpıyor. İki kötü seçenekle karşı karşıyasınız:

migrationü iptal etmek: Sadece tek bir arayüzü memnun etmek için tüm projeyi .NET Framework üzerinde tutmak.
“Sidecar” Kabusu: Yeni sistemi .NET Core’da kurmak, ancak sadece SOAP isteklerini yeni API’ye proxy etmek için çalışan bir zombi .NET Framework sunucusunu ayakta tutmak.

Ancak üçüncü bir seçenek daha var. Bir köprü.

CoreWCF.

CoreWCF, barındırma modelini, Dependency Injection ve performans özelliklerini modern .NET kullanarak tamamen yeniden yazarken, dış kontratı (SOAP) eski sistemle aynı tutmamıza olanak tanır.

Bu yazıda, bir InvoiceService‘i adım adım taşıyacağız. Ham bir uç noktayla (endpoint) başlayacak, onu modern yetkilendirme ile güvenli hale getirecek ve son olarak RESTful ProblemDetails ile SOAP Hataları (Faults) arasındaki boşluğu dolduran sofistike bir hata yönetimi uygulayacağız.

Adım 1: migrationün “Merhaba Dünya"sı

İlk hedefimiz sadece ışıkları yakmak. IInvoiceService kontratını IIS yerine Kestrel web sunucusu kullanarak sunabileceğimizi kanıtlamak istiyoruz.

Henüz güvenlik veya hata yönetimi hakkında endişelenmiyoruz. Sadece XML’in aktığını görmek istiyoruz.

Kontrat ve Servis

Servis Kontratımızı eski sistemdekiyle neredeyse tamamen aynı tutuyoruz. Tek fark, eski WCF uygulamasına kıyasla büyük bir performans kazancı sağlayan gerçek asenkron işlemeyi yani Task<T> yapısını benimsiyor olmamız. Ayrıca, Mediator desenine daha iyi uyması için mevcut istek ve yanıt modellerini birazcık yeniden adlandırdık.

// Sample.API.WCF/IInvoiceService.cs
using CoreWCF;
using Sample.Business.Features.Invoices.CreateInvoice;

namespace Sample.API.WCF;

[ServiceContract]
public interface IInvoiceService
{
 [OperationContract]
 Task<CreateInvoiceCommandResponse> CreateInvoice(CreateInvoiceCommand command);
}

// Dikkat: Henüz burada hiçbir attribute yok, sadece saf mantık.
public class InvoiceService(ISender mediator) : IInvoiceService
{
 public async Task<CreateInvoiceCommandResponse> CreateInvoice(CreateInvoiceCommand command)
 {
 return await mediator.Send(command);
 }
}

Konfigürasyon (1. Adım)

İşte en temel kurulum için Program.cs. Gereksiz her şeyi çıkarıyoruz.

// Program.cs - Adım 1: Temel WCF Barındırma
using CoreWCF;
using CoreWCF.Configuration;
using CoreWCF.Description;
using Sample.API.WCF;
using CoreWCF.Description;

var builder = WebApplication.CreateBuilder(args);

// 1. CoreWCF temellerini DI container'a ekle
builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();

// 2. MediatR ve Servisimizi Kaydet
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var app = builder.Build();

// 3. CoreWCF Middleware'ini Yapılandır
app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc" // Uç nokta URL'si
 );

 // İnatçı istemcinin referansını güncellemesi gerekirse diye WSDL üretimini etkinleştir
 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

Bu noktada, taşıma katmanında zafer kazandık. Entegratör /Services/InvoiceService.svc adresine gelebilir, bir XML/SOAP zarfı gönderebilir ve modern MediatR işleyicilerimiz iş kurallarını işler.

Adım 2: Yetkilendirme (Authorization) Ekleme

“Sade” servis çalışıyor ama tehlikeli. Eski WCF günlerinde, geliştiriciler çoğu zaman uç noktalara herhangi bir yetkilendirme desteği eklemezdi, güvenliği yapılandırmak güvenlik sertifikalarıyla uğraşmak demekti.

CoreWCF’de, güvenlik sadece ASP.NET Core güvenliğidir.

Eğer REST API’niz JWT Bearer tokenları veya Cookie Auth kullanıyorsa, CoreWCF uç noktalarınız da bunları kullanabilir. Tekerleği yeniden icat etmemize gerek yok. Servisimizi basitçe [Authorize] ile süslüyoruz.

Güncellenmiş Servis

[Authorize] ekliyoruz ve kullanıcı bağlamına erişebildiğimizi kanıtlamak için IHttpContextAccessor enjekte ediyoruz.

using CoreWCF;
using MediatR;
using Microsoft.AspNetCore.Authorization;
using Sample.Shared.Services.Interfaces;

namespace Sample.API.WCF;

[Authorize] // <--- Sihirli kelime. Bu standart ASP.NET Core yetkilendirmesidir.
public class InvoiceService(ISender mediator, IHttpContextAccessor httpContextAccessor) : IInvoiceService
{
 public async Task<Response> CreateInvoice(CreateInvoiceCommand command)
 {
 var context = httpContextAccessor.HttpContext;
 Console.WriteLine(context?.User.Identity?.Name);

 return await mediator.Send(command);
 }
}

Konfigürasyon (2. Adım)

ASP.NET Core Auth ara yazılımını (middleware), CoreWCF ara yazılımından önce katmanlamamız gerekiyor.

// Program.cs - Adım 2: Yetkilendirme Ekleme
using CoreWCF.Configuration;
using CoreWCF.Description;
using Sample.API.WCF;
using Microsoft.AspNetCore.Authentication.JwtBearer; // JWT varsayıyoruz

var builder = WebApplication.CreateBuilder(args);

// 1. Standart ASP.NET Core Kimlik Doğrulama Kurulumu
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
 {
 options.MapInboundClaims = false;
 options.TokenValidationParameters = new TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = true,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = configuration["Jwt:Issuer"],
 ValidAudience = configuration["Jwt:Audience"],
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]!))
 };
 });

builder.Services.AddAuthorization(options =>
{
 options.DefaultPolicy = new AuthorizationPolicyBuilder(JwtBearerDefaults.AuthenticationScheme)
 .RequireAuthenticatedUser()
 .Build();
});

builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();

builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var app = builder.Build();

// 2. ÖNEMLİ: Auth middleware WCF middleware'den önce çalışmalıdır
app.UseAuthentication();

app.UseAuthorization();

app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc"
 );

 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

Şimdi, eğer entegratör geçerli bir standart HTTP Authorization: Bearer header’ı olmadan bir istek gönderirse, CoreWCF bunu kodumuza daha ulaşmadan 401 ile reddedecektir. Elbette müşterimizin istek yapmadan önce ek bir adım uygulaması gerekir ancak authn & authz olmadan herhangi bir uygulama saldırılara açık olacaktır.

Adım 3: Evrensel Çevirmen (Birleşik Hata Yönetimi)

Hikayenin en zor kısmı burası.

Modern bir REST API’de, bir şeyler ters gittiğinde (örneğin “Fatura bulunamadı”), özel bir BadRequestException fırlatırız ve bir JSON ProblemDetails (RFC 7807) yanıtı döndürürüz.

WCF’de ise, XML içine sarılmış bir FaultException döndürmemiz beklenir.

Eğer bunu yönetmezsek, güzelim ValidationException‘ımız servisi çökertecek ve istemciye genel, çirkin bir “Internal Server Error” dönecektir. Modern Exception’larımızı yakalayan ve onları hala tüm zengin verileri (doğrulama hata alanları gibi) içeren SOAP Hatalarına (Faults) çeviren bir tercümana ihtiyacımız var.

using System.Diagnostics;
using System.Xml.Linq;
using CoreWCF;
using CoreWCF.Channels;
using CoreWCF.Dispatcher;
using Sample.Domain.Constants;
using Sample.Domain.Exceptions;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace Sample.API.Filters;

/// <summary>
/// Exception'ları yakalayan ve ProblemDetails'i SOAP Fault olarak döndüren CoreWCF Hata İşleyicisi.
/// Bu, modern Exception tanımları ile eski SOAP hataları arasında bir köprü görevi görür.
/// </summary>
public class ExceptionHandlerErrorHandler : IErrorHandler
{
 private const string HttpRfcBadRequest = "https://tools.ietf.org/html/rfc7231#section-6.5.1";
 private const string ProblemDetailsNamespace = "urn:ietf:rfc:7807";

 private readonly ILogger<ExceptionHandlerErrorHandler> _logger;
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IStringLocalizer<ExceptionHandleMiddleware> _localizer;
 private readonly Dictionary<Type, Func<Exception, ProblemDetails>> _exceptionHandlers;

 public ExceptionHandlerErrorHandler(
 ILogger<ExceptionHandlerErrorHandler> logger,
 IHttpContextAccessor httpContextAccessor,
 IStringLocalizer<ExceptionHandleMiddleware> localizer)
 {
 _logger = logger;
 _httpContextAccessor = httpContextAccessor;
 _localizer = localizer;

 // Domain exception'larını belirli ProblemDetails işleyicilerine eşle
 _exceptionHandlers = new()
 {
 { typeof(BadRequestException), HandleBadRequestException },
 // İstediğiniz kadar ekleyin
 };
 }

 public bool HandleError(Exception error)
 {
 // Hatayı işlediğimizi ve oturumun hatalı olmadığını belirtmek için true döndür
 return true;
 }

 public void ProvideFault(Exception error, MessageVersion version, ref Message fault)
 {
 // 1. Exception'ı ProblemDetails'e dönüştür
 var problemDetails = CreateProblemDetails(error);

 // 2. ProblemDetails'i SOAP Body için XML Elementine dönüştür
 var problemDetailsElement = TransformToXml(problemDetails);

 // 3. Problem detaylarını içeren bir FaultException oluştur
 var faultException = new FaultException<XElement>(
 problemDetailsElement,
 new FaultReason(problemDetails.Title ?? "An error occurred"),
 new FaultCode(GetFaultCodeFromStatus(problemDetails.Status ?? 500)),
 "ProblemDetails");

 var messageFault = faultException.CreateMessageFault();
 fault = Message.CreateMessage(version, messageFault, faultException.Action);

 // 4. Temel HTTP durum kodunu ayarla (izleme/gözlemlenebilirlik için önemli)
 SetHttpStatusCode(problemDetails.Status ?? StatusCodes.Status500InternalServerError);
 }

 private ProblemDetails CreateProblemDetails(Exception exception)
 {
 var exceptionType = exception.GetType();

 if (_exceptionHandlers.TryGetValue(exceptionType, out var handler))
 {
 _logger.LogWarning("Handled Exception {ExceptionMessage}: Time {Time}", exception.Message, DateTime.UtcNow);
 var pd = handler(exception);
 EnrichProblemDetails(pd);
 return pd;
 }

 _logger.LogError(exception, "Unhandled Exception: Time {Time}", DateTime.UtcNow);
 var unknownPd = HandleUnknownException(exception);
 EnrichProblemDetails(unknownPd);
 return unknownPd;
 }

 // --- Özel Exception İşleyicileri ---
 private ProblemDetails HandleBadRequestException(Exception ex)
 {
 var exception = (BadRequestException)ex;
 return new ProblemDetails
 {
 Status = StatusCodes.Status400BadRequest,
 Type = HttpRfcBadRequest,
 Title = _localizer[Localized.BadRequestExceptionTitle],
 Detail = _localizer[exception.LocalizedMessage, exception.Arguments]
 };
 }

 private ProblemDetails HandleValidationException(Exception ex)
 {
 var exception = (ValidationException)ex;
 return new ValidationProblemDetails(exception.Errors)
 {
 Status = StatusCodes.Status400BadRequest,
 Type = HttpRfcBadRequest,
 Title = _localizer[Localized.ValidationExceptionTitle]
 };
 }

 private static ProblemDetails HandleUnknownException(Exception ex)
 {
 return new ProblemDetails
 {
 Status = StatusCodes.Status500InternalServerError,
 Type = HttpRfcInternalError,
 Title = "Beklenmeyen bir hata oluştu",
 Detail = ex.Message
 };
 }

 // --- Yardımcılar ---

 private static void EnrichProblemDetails(ProblemDetails result)
 {
 // Hata raporlaması için dağıtık izleme (distributed tracing) ID'lerini ekle
 var correlation = AsyncStorage<Correlation>.Retrieve();
 if (correlation is not null)
 {
 result.Extensions.Add("correlationId", correlation.Id);
 }

 var traceId = Activity.Current?.Id;
 if (traceId is not null)
 {
 result.Extensions.Add(nameof(traceId), traceId);
 }
 }

 private static XElement TransformToXml(ProblemDetails problemDetails)
 {
 var ns = XNamespace.Get(ProblemDetailsNamespace);

 var element = new XElement(ns + "problem",
 new XElement(ns + "type", problemDetails.Type),
 new XElement(ns + "title", problemDetails.Title),
 new XElement(ns + "status", problemDetails.Status),
 new XElement(ns + "detail", problemDetails.Detail ?? string.Empty));

 foreach (var extension in problemDetails.Extensions)
 {
 element.Add(new XElement(ns + extension.Key, extension.Value?.ToString() ?? string.Empty));
 }

 if (problemDetails is ValidationProblemDetails validationProblemDetails &&
 validationProblemDetails.Errors.Count > 0)
 {
 var errorsElement = new XElement(ns + "errors");
 foreach (var error in validationProblemDetails.Errors)
 {
 var errorElement = new XElement(ns + "error", new XAttribute("field", error.Key));
 foreach (var message in error.Value)
 {
 errorElement.Add(new XElement(ns + "message", message));
 }
 errorsElement.Add(errorElement);
 }
 element.Add(errorsElement);
 }

 return element;
 }

 private static string GetFaultCodeFromStatus(int status)
 {
 return status switch
 {
 400 => "BadRequest",
 401 => "Unauthorized",
 403 => "Forbidden",
 404 => "NotFound",
 _ => "InternalServerError"
 };
 }

 private void SetHttpStatusCode(int statusCode)
 {
 var httpContext = _httpContextAccessor.HttpContext;
 if (httpContext is not null)
 {
 httpContext.Response.StatusCode = statusCode;
 }
 }
}

Konfigürasyon (3. Adım)

Bu hata işleyicisini bir IServiceBehavior olarak bağlamamız gerekiyor. Bu, servise yapılan her bir çağrı için geçerli olmasını sağlar.

// Program.cs - Adım 3: Hata Yönetimi ile Üretime Hazır
using CoreWCF;
using CoreWCF.Channels;
using CoreWCF.Configuration;
using CoreWCF.Description;
using CoreWCF.Dispatcher;
using Sample.API.Filters; // ErrorHandler'ımızın olduğu yer
using Sample.API.WCF;
using Microsoft.Extensions.DependencyInjection.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
 {
 options.MapInboundClaims = false;
 options.TokenValidationParameters = new TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = true,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = configuration["Jwt:Issuer"],
 ValidAudience = configuration["Jwt:Audience"],
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]!))
 };
 });

builder.Services.AddAuthorization(options =>
{
 options.DefaultPolicy = new AuthorizationPolicyBuilder(JwtBearerDefaults.AuthenticationScheme)
 .RequireAuthenticatedUser()
 .Build();
});

builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
builder.Services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();
builder.Services.AddSingleton<IErrorHandler, ExceptionHandlerErrorHandler>(); // Bu satırların
builder.Services.AddSingleton<IServiceBehavior, ExceptionHandlerServiceBehaviour>(); // eklenmesi gerek.

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc"
 );

 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

Mutlu Son

Adım itibarıyla dikkate değer bir şey başardık:
Entegratör mutlu çünkü hala /Services/InvoiceService.svc adresine SOAP istekleri gönderiyorlar. Entegrasyon desenlerini değiştirmek zorunda kalmadılar.
Geliştirici mutlu çünkü InvoiceService tertemiz. MediatR kullanıyor. İş mantığını kirleten try/catch blokları yok. Güvenlik için [Authorize] kullanıyor.
Operasyon Ekibi mutlu çünkü loglar, istek bir REST istemcisinden de gelse SOAP istemcisinden de gelse tutarlı ProblemDetails yapılarını gösteriyor.

Sadece kodu “port” etmedik; etrafındaki ekosistemi modernize ettik ve WCF arayüzünü bir pranga yerine bir uyumluluk katmanı olarak bıraktık.

.NET Mikroservislerinde gRPC: REST ile Karşılaştırma

Wed, 08 Oct 2025 00:00:00 +0300

.NET mikroservislerinin birbirleriyle senkron iletişim kurması gerektiğinde, genellikle iki ana seçenek önümüze çıkar: REST API ve gRPC API.

REST, HTTP/1.1 protokolü üzerinde JSON ile çalışır; kolay okunur, tüm tarayıcılarda desteklenir ve debug işlemi basittir. Ancak REST API’lerde veri paketleri gRPC’ye kıyasla daha büyüktür ve her istek kendi TCP bağlantısını açar. gRPC ise veri iletimini Protocol Buffers ile sıkıştırır ve tüm trafiği tek bir HTTP/2 bağlantısı üzerinden aktararak gecikmeyi minimuma indirir. Bu yazımda hem REST hem gRPC teknolojilerinin çalışma mantığını, .NET 9 üzerinde örneklerle karşılaştırmasını ve hangi senaryolarda hangi çözümün daha avantajlı olduğunu inceleyeceğiz. Haydi başlayalım.

Nedir bu RPC?

Uzun süredir .NET ekosisteminde uygulama geliştiriyorsanız RPC kavramıyla büyük ihtimal ilk kez karşılaşmıyorsunuz. SOAP tabanlı, IIS üzerinden WCF servisleri kullanarak servisler arası iletişim .NET Framework zamanlarındada yapılıyordu, ancak bu framework ile XML tipinkedi mesajlarla boğuşup, .NET ekosisteminde sıkışıp kalabiliyorduk.

Bunun yerine HTTP/2 üzerinden çok daha performanslı, cross-platform ve cross-language çalışabilen gRPC, yeni projelerde seçebileceğimiz en mantıklı RPC framework’ü haline geliyor.

REST ile gRPC arasındaki farklar

Mikroservis mimarisinde, servisler arası iletişim için kullanabileceğimiz tek seçenek RPC değildir. REST API yaklaşımı da, servislerin birbirleriyle kolayca ve yaygın şekilde iletişim kurmasını sağlar. Ancak, REST ve gRPC arasında hem mimari tasarım hem de teknik uygulama açısından önemli farklar bulunmaktadır. Bu farklılıkları tasarım felsefesi ve teknik farklar altında inceleyelim.

1. Tasarım Felsefesi

REST ve gRPC, API tasarımında farklı bakış açılarına sahiptir. REST’te temel yaklaşım, her şeyi bir “kaynak” (resource) olarak görmek ve bu kaynaklar üzerinde işlem yapmaktır. HTTP metodları (GET, POST, PUT, DELETE) yapılan işlemi temsil eder, URL ise üzerinde çalışılan kaynağı belirtir. Örneğin /api/books adresi bir kitaplar kaynağıdır, bu şekilde bir endpointe sahipseniz onun üzerinde yapabileceğiniz işlemleri az çok tahmin edebilirsiniz;

GET /api/books isteği kitap listesini döndürür,
POST /api/books ile yeni bir kitap eklersiniz,

gRPC’de ise bakış açısı daha çok “eylem” (action) veya “metot” (method) odaklıdır. Yani her bir işlem, bir fonksiyon çağrısı gibi tanımlanır. gRPC’de doğrudan hangi işlemi yapmak istediğinizi belirtirsiniz ve URL tasarımına veya HTTP metodlarına bağlı kalmazsınız.

Örneğin,

BookService.GetBooks() ile kitapları listelersiniz,
BookService.CreateBook() ile yeni bir kitap eklersiniz.

REST’te de işlemsel endpoint’ler tanımlamak teknik olarak mümkün olsa da, bu genellikle best practice’lere ve standart REST felsefesine uygun değildir.

2. Teknik Farklılıklar

REST ve gRPC arasında, iletişimden veri formatına, bağlantı yönetiminden hata kontrolüne kadar birçok teknik fark bulunur. Aşağıda en önemli başlıklar ve farklar özetlenmiştir:

Transport Layer

REST HTTP/1.1 kullanır. Her bir REST API isteği için ayrı bir TCP/TLS bağlantısı kurulur. Bu, özellikle yüksek istek hacminde head-of-line blocking (bir isteğin yavaşlaması diğerlerini de etkiler) gibi performans darboğazlarına neden olabilir. Ayrıca, REST’te çift yönlü sürekli iletişim (örneğin canlı veri akışı veya anlık bildirimler) gerektiren durumlarda WebSocket veya Server-Sent Events gibi ek protokoller kullanmak gerekir. Yani REST, temelinde request-response modeline dayanır ve streaming (akış) desteği doğal değildir.

gRPC ise modern iletişim protokolü olan HTTP/2 ile çalışır. HTTP/2’nin multiplexing özelliği sayesinde tek bir TCP bağlantısı üzerinden eşzamanlı birçok istek ve yanıt taşınabilir. Bu, yüksek performans ve düşük gecikme (latency) sağlar. gRPC, HTTP/2’nin sunduğu native stream ve header compression gibi özelliklerle, gerçek zamanlı ve çift yönlü iletişimi çok daha kolay ve verimli şekilde gerçekleştirir.

gRPC, hizmetlerin arayüzlerini ve mesaj yapısını genellikle Protocol Buffers (Protobuf) ile tanımlar. Servis tanımı, uzaktan çağrılabilecek metodları ve mesaj şemalarını açıkça belirtir.

Aşağıda bir örnek görebilirsin

service HelloService {
 rpc SayHello (HelloRequest) returns (HelloResponse);
}

message HelloRequest {
 string greeting = 1;
}

message HelloResponse {
 string reply = 1;
}

gRPC ile 4 farklı iletişim (RPC) yöntemi mümkündür:

Unary

En klasik yöntemdir: istemci bir istek gönderir, sunucu bir yanıt döner. REST’teki request-response modeline benzer. Aşağıdaki şekilde tanımlanabilir.

rpc SayHello(HelloRequest) returns (HelloResponse);

Server Streaming

İstemci tek bir istek gönderir, sunucu ise birden fazla yanıt mesajı akışı (stream) dönebilir. İstemci, sunucudan gelen veri akışını tek tek okur.

rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);

Client Streaming

İstemci, sunucuya birden fazla mesaj gönderir (stream). Tüm mesajları gönderdikten sonra sunucudan tek bir yanıt alır. Büyük veri yükleme işlemleri, toplu güncellemeler gibi alanlarda kullanılabilir.

rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);

Bidirectional Streaming RPC

Hem istemci hem sunucu, aynı anda birbirlerine bağımsız şekilde veri akışı gönderebilirler. Akışlar birbirinden bağımsız çalışır; sıralama her bir akış için korunur. Gerçek zamanlı sohbet uygulamaları, canlı veri transferlerinde tercih edilebilir.

rpc BidiHello(stream HelloRequest) returns (stream HelloResponse);

Veri

REST: Mesajlar genellikle insan tarafından okunabilir JSON formatında taşınır. JSON, okunabilir ve esnek ama büyük veri boyutuna ve yüksek ayrıştırma maliyetine sahiptir. Ayrıca kesin bir şema zorunlu değildir. Genellikle OpenAPI/Swagger ile dokümantasyon eklenir, ancak uygulama sırasında tip uyuşmazlıkları yaşanabilir.
gRPC: Protocol Buffers (Protobuf) adı verilen ikili (binary) ve sıkıştırılmış bir format kullanır. Protobuf mesajları küçük ve hızlıdır, ağ ve CPU maliyeti düşüktür. Tüm veri tipleri ve metodlar .proto dosyasında tanımlanır. Sunucu ve istemci kodları otomatik olarak üretilir, tip güvenliği yüksektir.

Performans ve Verimlilik

REST: JSON’un büyük boyutu ve HTTP/1.1’in sınırlamaları nedeniyle yüksek trafik altında gecikme ve kaynak tüketimi artar.
gRPC: Küçük paket boyutu ve HTTP/2 ile tek bağlantı üzerinden çoklu istek sayesinde daha düşük gecikme, daha fazla RPS (istek/saniye) ve daha verimli ağ kullanımı sağlar.

Tarayıcı ve Platform Uyumluluğu

REST: Doğrudan tarayıcıdan çağrılabilir, fetch/AJAX ile kolayca entegre edilir.
gRPC: Tarayıcıdan doğrudan kullanılamaz; gRPC-Web veya JSON Transcoding gibi ek katmanlara ihtiyaç duyacağı için tarayıcı içeren senaryolarda tercih edilmezler.

Hangi Senaryolarda REST veya gRPC Seçilmeli?

REST ve gRPC arasında seçim yaparken sadece teknik detaylara bakmak yeterli olmayabilir; iş ihtiyaçları, hedef kullanıcı kitlesi ve entegrasyon gereksinimleri de en az performans kadar önemlidir. İşte bazı tipik senaryolar ve öneriler:

Ne Zaman REST Kullanılmalı?

Tarayıcı veya üçüncü parti entegrasyonu: Eğer API’nız doğrudan web tarayıcıları veya harici uygulamalar tarafından tüketilecekse REST her zaman daha yaygın ve erişilebilir bir çözüm sunar.
public API’ler: JSON’un okunabilirliği ve HTTP/1.1’in yaygın desteği sayesinde REST tabanlı API’ler, geliştiriciler tarafından kolayca test edilebilir ve dökümante edilebilir.
Basit CRUD işlemleri: Kaynak odaklı (ör. ürünler, siparişler) ve klasik GET/POST/PUT/DELETE işlemleri için REST yalın ve anlaşılırdır.
Cache/Proxy ihtiyaçları: CDN veya reverse proxy üzerinden önbellekleme ve yönlendirme yapmak gerekiyorsa, HTTP standardı ile tam uyumlu olduğu için REST daha avantajlıdır.

Ne Zaman gRPC Kullanılmalı?

Mikroservisler arası iletişim: Aynı altyapı içinde, yüksek hacimli ve düşük gecikmeli servis-servis trafiği için gRPC ciddi avantaj sağlar.
Mobil ve IoT cihazları: Küçük paket boyutu ve ikili format sayesinde veri tüketimi azalır.
Gerçek zamanlı akış gereksinimi: Sunucudan istemciye ya da çift yönlü veri akışının gerektiği chat, canlı skor, bildirim gibi uygulamalarda gRPC doğal akış desteği sunar.
Dil bağımsızlığı: Birden çok farklı programlama dili arasında tip güvenli bir iletişim kurmak istiyorsanız, Protobuf sayesinde uyumluluk kolayca sağlanır.
Daha güçlü tip güvenliği: Derlenmiş sözleşmeler ve otomatik kod üretimi sayesinde API tüketiminde hata oranı düşer.

.NET ile Kapsamlı Uygulama Örneği: Books Servisi

Hem REST hem de gRPC ile kitap yönetim servisi oluşturalım. Bu örnekte, gRPC’nin sunduğu farklı streaming modlarını da göreceğiz.

Proje Kurulumu

İlk olarak gerekli paketleri ekleyelim:

dotnet new web -n BookService
cd BookService
dotnet add package Grpc.AspNetCore
dotnet add package Grpc.AspNetCore.Server.Reflection
dotnet add package Grpc.Tools

REST API İmplementasyonu

// Models/Book.cs
namespace BookService.Models;

public class Book
{
 public int Id { get; set; }
 public string Title { get; set; } = string.Empty;
 public string Author { get; set; } = string.Empty;
 public int Year { get; set; }
 public decimal Price { get; set; }
}

// Controllers/BooksController.cs
using Microsoft.AspNetCore.Mvc;
using BookService.Models;

namespace BookService.Controllers;

[ApiController]
[Route("api/books")]
public class BooksController : ControllerBase
{
 private static readonly List<Book> Books = Book.GenerateBooks();

 [HttpGet]
 public IActionResult GetBooks()
 {
 return Ok(Books);
 }

 [HttpGet("{id}")]
 public IActionResult GetBook(int id)
 {
 var book = Books.FirstOrDefault(b => b.Id == id);
 if (book == null)
 return NotFound();

 return Ok(book);
 }

 [HttpPost]
 public IActionResult CreateBook([FromBody] Book book)
 {
 book.Id = Books.Max(b => b.Id) + 1;
 Books.Add(book);
 return CreatedAtAction(nameof(GetBook), new { id = book.Id }, book);
 }
}

gRPC Servisi - Protobuf Tanımları

// Protos/books.proto
syntax = "proto3";

option csharp_namespace = "BookService.Grpc";

package books;

// Ana servis tanımı
service BookService {
 // Unary RPC - Tüm kitapları getir
 rpc GetBooks (GetBooksRequest) returns (BookList);

 // Server Streaming - Kitapları tek tek stream et
 rpc StreamBooks (StreamBooksRequest) returns (stream Book);

 // Client Streaming - Toplu kitap ekleme
 rpc AddBooksStream (stream Book) returns (AddBooksResponse);

 // Bidirectional Streaming - Gerçek zamanlı kitap arama
 rpc SearchBooksStream (stream SearchRequest) returns (stream Book);
}

message Book {
 int32 id = 1;
 string title = 2;
 string author = 3;
 int32 year = 4;
 double price = 5;
}

message GetBooksRequest {
 // Boş istek mesajı
}

message BookList {
 repeated Book books = 1;
}

message StreamBooksRequest {
 int32 delay_ms = 1; // Her kitap arasında gecikme (ms)
}

message AddBooksResponse {
 int32 count = 1;
 string message = 2;
}

message SearchRequest {
 string query = 1;
}

gRPC Servisi - İmplementasyon

// Services/GrpcBookService.cs
using Grpc.Core;
using BookService.Grpc;

namespace BookService.Services;

public class GrpcBookService : Grpc.BookService.BookServiceBase
{
 private static readonly List<BookService.Grpc.Book> Books = BookService.Models.Book.GenerateBooks()
 .Select(b => new BookService.Grpc.Book { Id = b.Id, Title = b.Title, Author = b.Author, Year = b.Year, Price = (double)b.Price })
 .ToList();

 // Unary RPC - Klasik request-response
 public override Task<BookList> GetBooks(GetBooksRequest request, ServerCallContext context)
 {
 var response = new BookList();
 response.Books.AddRange(Books);

 return Task.FromResult(response);
 }

 // Server Streaming - Sunucu kitapları tek tek stream eder
 public override async Task StreamBooks(StreamBooksRequest request,
 IServerStreamWriter<BookService.Grpc.Book> responseStream,
 ServerCallContext context)
 {
 foreach (var book in Books)
 {
 // İptal kontrolü
 if (context.CancellationToken.IsCancellationRequested)
 {
 break;
 }

 await responseStream.WriteAsync(book);

 // Belirtilen süre kadar bekle (streaming'i göstermek için)
 if (request.DelayMs > 0)
 {
 await Task.Delay(request.DelayMs);
 }
 }
 }

 // Client Streaming - İstemci birden fazla kitap gönderir
 public override async Task<AddBooksResponse> AddBooksStream(
 IAsyncStreamReader<BookService.Grpc.Book> requestStream,
 ServerCallContext context)
 {
 int count = 0;
 int maxId = Books.Any() ? Books.Max(b => b.Id) : 0;

 await foreach (var book in requestStream.ReadAllAsync())
 {
 book.Id = ++maxId;
 Books.Add(book);
 count++;
 }

 return new AddBooksResponse
 {
 Count = count,
 Message = $"Successfully added {count} books"
 };
 }

 // Bidirectional Streaming - İki yönlü gerçek zamanlı arama
 public override async Task SearchBooksStream(
 IAsyncStreamReader<SearchRequest> requestStream,
 IServerStreamWriter<BookService.Grpc.Book> responseStream,
 ServerCallContext context)
 {
 await foreach (var searchRequest in requestStream.ReadAllAsync())
 {
 var results = Books.Where(b =>
 b.Title.Contains(searchRequest.Query, StringComparison.OrdinalIgnoreCase) ||
 b.Author.Contains(searchRequest.Query, StringComparison.OrdinalIgnoreCase)
 ).ToList();

 foreach (var book in results)
 {
 await responseStream.WriteAsync(book);
 }
 }
 }
}

Program.cs Konfigürasyonu

// Program.cs
using BookService.Services;

var builder = WebApplication.CreateBuilder(args);

// REST API servisleri
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// gRPC servisleri
builder.Services.AddGrpc();

var app = builder.Build();

// Swagger (REST için)
if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();

 // gRPC reflection (development için)
 app.MapGrpcReflectionService();
}

// REST endpoints
app.MapControllers();

// gRPC endpoints
app.MapGrpcService<GrpcBookService>();

app.Run();

.csproj Dosyası

<Project Sdk="Microsoft.NET.Sdk.Web">

 <PropertyGroup>
 <TargetFramework>net9.0</TargetFramework>
 <Nullable>enable</Nullable>
 <ImplicitUsings>enable</ImplicitUsings>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="Grpc.AspNetCore" Version="2.60.0" />
 <PackageReference Include="Grpc.AspNetCore.Server.Reflection" Version="2.60.0" />
 <PackageReference Include="Grpc.Tools" Version="2.60.0">
 <PrivateAssets>all</PrivateAssets>
 <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 </PackageReference>
 <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
 </ItemGroup>

 <ItemGroup>
 <Protobuf Include="Protos\\books.proto" />
 </ItemGroup>

</Project>

Ayrıca lokalden çalışan uygulamanız https ile çalışmayacaksa HTTP/1 protundan ayrı HTTP/2 için ayrı bir port açmamız gerekiyor. Bunun için appsettings.json dosyasında aşağıdaki tanım eklenerek ilgili portlar açılır.

 "Kestrel": {
 "Endpoints": {
 "Http": {
 "Protocols": "Http1",
 "Url": "http://*:5000"
 },
 "gRPC": {
 "Protocols": "Http2",
 "Url": "http://*:5001"
 }
 }
 },

gRPC Client Örnekleri

Şimdi farklı streaming modlarını kullanan client örnekleri görelim:

// Client/GrpcClientExamples.cs
using Grpc.Net.Client;
using BookService.Grpc;

namespace BookService.Client;

public class GrpcClientExamples
{
 private readonly GrpcChannel _channel;
 private readonly Grpc.BookService.BookServiceClient _client;

 public GrpcClientExamples(string serverAddress = "http://localhost:5001")
 {
 _channel = GrpcChannel .ForAddress(serverAddress, new GrpcChannelOptions
 {
 // HTTPS tanımı disable ediliyor. Production ortamda dikkatlı kullanınız
 HttpHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
 }
 });
 _client = new Grpc.BookService.BookServiceClient(_channel);
 }

 // Unary RPC Örneği
 public async Task UnaryCallExample()
 {
 Console.WriteLine("=== Unary Call Example ===");
 var request = new GetBooksRequest();
 var response = await _client.GetBooksAsync(request);

 Console.WriteLine($"Received {response.Books.Count} books:");
 foreach (var book in response.Books)
 {
 Console.WriteLine($"- {book.Title} by {book.Author} ({book.Year})");
 }
 }

 // Server Streaming Örneği
 public async Task ServerStreamingExample()
 {
 Console.WriteLine("\\n=== Server Streaming Example ===");
 var request = new StreamBooksRequest { DelayMs = 500 };

 using var call = _client.StreamBooks(request);

 await foreach (var book in call.ResponseStream.ReadAllAsync())
 {
 Console.WriteLine($"Received: {book.Title} - ${book.Price}");
 }

 Console.WriteLine("Streaming completed");
 }

 // Client Streaming Örneği
 public async Task ClientStreamingExample()
 {
 Console.WriteLine("\\n=== Client Streaming Example ===");

 using var call = _client.AddBooksStream();

 var booksToAdd = new[]
 {
 new Book { Title = "Design Patterns", Author = "Gang of Four", Year = 1994, Price = 59.99 },
 new Book { Title = "Head First Design Patterns", Author = "Eric Freeman", Year = 2004, Price = 44.99 },
 new Book { Title = "Microservices Patterns", Author = "Chris Richardson", Year = 2018, Price = 49.99 }
 };

 foreach (var book in booksToAdd)
 {
 await call.RequestStream.WriteAsync(book);
 Console.WriteLine($"Sent: {book.Title}");
 await Task.Delay(300); // Simüle edilmiş gecikme
 }

 await call.RequestStream.CompleteAsync();
 var response = await call;

 Console.WriteLine($"Result: {response.Message}");
 }

 // Bidirectional Streaming Örneği
 public async Task BidirectionalStreamingExample()
 {
 Console.WriteLine("\\n=== Bidirectional Streaming Example ===");

 using var call = _client.SearchBooksStream();

 // Background'da sonuçları oku
 var readTask = Task.Run(async () =>
 {
 await foreach (var book in call.ResponseStream.ReadAllAsync())
 {
 Console.WriteLine($"Found: {book.Title} by {book.Author}");
 }
 });

 // Arama sorgularını gönder
 var queries = new[] { "Clean", "Design", "Refactoring", "Domain" };

 foreach (var query in queries)
 {
 Console.WriteLine($"Searching for: {query}");
 await call.RequestStream.WriteAsync(new SearchRequest { Query = query });
 await Task.Delay(1000); // Her aramadan sonra bekle
 }

 await call.RequestStream.CompleteAsync();
 await readTask;

 Console.WriteLine("Bidirectional streaming completed");
 }

 public async ValueTask DisposeAsync()
 {
 await _channel.ShutdownAsync();
 _channel.Dispose();
 }
}

// Kullanım örneği
public class Program
{
 public static async Task Main(string[] args)
 {
 await using var client = new GrpcClientExamples();

 await client.UnaryCallExample();
 await client.ServerStreamingExample();
 await client.ClientStreamingExample();
 await client.BidirectionalStreamingExample();
 }
}

grpcurl ile Test Etme

grpcurl, gRPC servisleri için curl benzeri bir komut satırı aracıdır. Servisimizi test edelim:

grpcurl Kurulumu

# macOS (Homebrew)
brew install grpcurl

# Linux
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Windows (Chocolatey)
choco install grpcurl

grpcurl Kullanım Örnekleri

# 1. Serviste hangi servisler var? (Reflection gerektirir)
grpcurl -plaintext localhost:5001 list

# Çıktı:
# books.BookService
# grpc.reflection.v1alpha.ServerReflection

# 2. BookService'in metodlarını listele
grpcurl -plaintext localhost:5001 list books.BookService

# Çıktı:
# books.BookService.AddBooksStream
# books.BookService.GetBooks
# books.BookService.SearchBooksStream
# books.BookService.StreamBooks

# 3. Unary RPC çağrısı - Tüm kitapları getir
grpcurl -plaintext localhost:5001 books.BookService/GetBooks

# Çıktı:
# {
# "books": [
# {
# "id": 1,
# "title": "Dune",
# "author": "Frank Herbert",
# "year": 1965,
# "price": 29.99
# },
# ...
# ]
# }

Performans Karşılaştırması: REST vs gRPC Benchmark

Teorik avantajları görmek güzel, ancak gerçek performans farkını ölçmek için kapsamlı bir benchmark yapalım. BenchmarkDotNet kullanarak REST ve gRPC’nin farklı senaryolardaki performansını karşılaştıracağız.

Benchmark Kurulumu

// BookService.Benchmark/BookServiceBenchmark.cs
using BenchmarkDotNet.Attributes;
using Grpc.Net.Client;
using BookService.Grpc;
using System.Net.Http.Json;

namespace BookService.Benchmark;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class BookServiceBenchmark
{
 private HttpClient? _httpClient;
 private GrpcChannel? _grpcChannel;
 private Grpc.BookService.BookServiceClient? _grpcClient;

 private const string RestUrl = "http://localhost:5000";
 private const string GrpcUrl = "http://localhost:5001";

 [GlobalSetup]
 public void Setup()
 {
 // REST client kurulumu
 _httpClient = new HttpClient { BaseAddress = new Uri(RestUrl) };

 // gRPC client kurulumu - HTTP/2 optimizasyonları ile
 _grpcChannel = GrpcChannel.ForAddress(GrpcUrl, new GrpcChannelOptions
 {
 MaxReceiveMessageSize = 4 * 1024 * 1024, // 4MB
 MaxSendMessageSize = 4 * 1024 * 1024, // 4MB
 });
 _grpcClient = new Grpc.BookService.BookServiceClient(_grpcChannel);
 }

 [Benchmark(Baseline = true)]
 public async Task<int> REST_GetAllBooks()
 {
 var books = await _httpClient!.GetFromJsonAsync<List<BookDto>>("/api/books");
 return books?.Count ?? 0;
 }

 [Benchmark]
 public async Task<int> gRPC_GetAllBooks()
 {
 var response = await _grpcClient!.GetBooksAsync(new GetBooksRequest());
 return response.Books.Count;
 }

 [Benchmark]
 public async Task<int> REST_GetAllBooks_10Times()
 {
 int totalCount = 0;
 for (int i = 0; i < 10; i++)
 {
 var books = await _httpClient!.GetFromJsonAsync<List<BookDto>>("/api/books");
 totalCount += books?.Count ?? 0;
 }
 return totalCount;
 }

 [Benchmark]
 public async Task<int> gRPC_GetAllBooks_10Times()
 {
 int totalCount = 0;
 for (int i = 0; i < 10; i++)
 {
 var response = await _grpcClient!.GetBooksAsync(new GetBooksRequest());
 totalCount += response.Books.Count;
 }
 return totalCount;
 }

 [GlobalCleanup]
 public async Task Cleanup()
 {
 _httpClient?.Dispose();
 if (_grpcChannel != null)
 {
 await _grpcChannel.ShutdownAsync();
 _grpcChannel.Dispose();
 }
 }
}

Benchmark Sonuçları

Optimizasyonlar sonrasında elde edilen gerçek performans sonuçları:

Method	Mean	Error	StdDev	Ratio	RatioSD	Allocated	Alloc Ratio
REST_GetAllBooks	332.3 μs	42.42 μs	28.06 μs	1.00	0.00	22.91 KB	1.00
gRPC_GetAllBooks	296.9 μs	18.10 μs	10.77 μs	0.90	0.06	25.66 KB	1.12
REST_GetAllBooks_10Times	3,257.1 μs	364.16 μs	240.87 μs	9.85	0.99	227.61 KB	9.94
gRPC_GetAllBooks_10Times	2,883.9 μs	338.63 μs	223.99 μs	8.74	1.05	255.17 KB	11.14

Sonuçların Analizi

Tek istek performansı incelendiğinde, gRPC’nin REST’e kıyasla %10 daha hızlı çalıştığı görülüyor (296.9 μs vs 332.3 μs). Bu fark, Protocol Buffers’ın binary serializasyon formatının JSON’a gösterdiği avantajdan kaynaklanmaktadır. Çoklu istek senaryolarında ise gRPC’nin performans üstünlüğü daha da belirginleşiyor ve %11.5’e çıkıyor (2,883.9 μs vs 3,257.1 μs). Bu artış, HTTP/2 protokolünün connection reuse özelliğinin devreye girmesiyle açıklanabilir.

Bellek kullanımı açısından bakıldığında, gRPC’nin REST’e göre %12 daha fazla bellek tükettiği görülmektedir (25.66 KB vs 22.91 KB). Bu ek bellek kullanımı, HTTP/2 bağlantı yönetimi için gerekli olan overhead’dan kaynaklanmaktadır. Ancak elde edilen performans iyileştirmeleri göz önüne alındığında, bu bellek artışı kabul edilebilir bir trade-off olarak değerlendirilebilir.

Özet

Bu yazı, .NET 9 ekosisteminde mikroservisler arası senkron iletişimde REST ve gRPC’yi mimari yaklaşım, teknik altyapı ve performans boyutlarıyla karşılaştırıyor. REST, HTTP/1.1 üzerinde JSON’la kolay erişilebilirlik, tarayıcı uyumluluğu ve cache/proxy avantajı sunarken; gRPC, HTTP/2’nin multiplexing ve doğal streaming yetenekleri ile Protobuf sayesinde daha düşük gecikme ve daha güçlü tip güvenliği sağlıyor. Yazıda, aynı “Books” alanında hem REST Controller hem de gRPC servis (unary, server/client/bidirectional streaming) örnekleri ve grpcurl ile test adımları bulunuyor. BenchmarkDotNet sonuçları, tekil çağrıda gRPC’nin REST’e kıyasla yaklaşık %10, art arda çağrılarda %11 civarı daha hızlı olduğunu; buna karşılık az miktarda ek bellek kullandığını gösteriyor.

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

https://github.com/berkslv/lecture-grpc

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

.NET’te Kod Kalitesini Zorunlu kılın: .editorconfig & Analyzers & Pre-Commit Hooks

Thu, 24 Jul 2025 00:00:00 +0300

Kod kalitesini korumak ve iyileştirmek yazdığımız her satırda hem kendimize hem de takım arkadaşlarımıza karşı bir sorumluluğumuz olarak düşünüyorum. Bu sorumluluğu uygularken kimi zaman acele yazılan kodlarla, yetişmesi gereken deadline’larla uygulanması gereken pratikleri göz ardı edebiliyoruz. Ayrıca, bu pratikleri takım arkadaşlarımıza yaygınlaştırırken de zorluklar yaşayabiliyoruz.

Bu tip sorunları aşıp, Kod kalitesini developer’ın inisiyatifine bırakmadan bir zorunluluk haline getirmenin birkaç adımdan oluşan ve 20+ developer’ın çalıştığı, 10+ servisten oluşan projeden çıkarılan deneyimlerle ispatlanan yöntemini paylaşmak istiyorum.

İlk olarak TreatWarningsAsErrors flag’i ile projenin 1000+ warning ile production’a çıkmasını engelleyeceğiz.

Devamında .editorconfig dosyaları ile .NET tarafından default olarak sağlanan kurallarla örneğin property isimlendirmeleri takıma yaygınlaştırılması gereken genel-geçer bir kural değil bir zorunluluk haline getireceğiz.

Bu kuralları SonarAnalyzer ve Roslynator gibi paketlerle geliştirip, sonar taramalarına daha girmeden ilgili sorunları çözüp, daha performanslı ve güvenli kodlar yazacağız.

Son olarakta pre-commit hook ile, build olmayan projenin ve fail eden testlerin CI/CD pipelinelarında hataya sebep olmadan önce, daha commit atmadan bu testleri görüp, düzelteceğiz. Haydi başlayalım.

TreatWarningsAsErrors ile warning içermeyen proje

.NET ile proje geliştirirken en çok warning “Possible null reference” ile ortaya çıkıyor. Bu warningle sınırlı olmadan projemizde birçok farklı warning ortaya çıkabilir ve bunlara saygı duymazsak runtime’da her yerde NullReferenceException almamız kadar doğal birşey olamaz.

Bu tip hatalar daha ortaya çıkmadan çözmek için Warning’lere Error olarak muamele edip, projenin build olmasını engelleyebiliriz. Bunun içinde .csproj dosyasına aşağıdaki flag’i eklememiz yeterlidir.

<PropertyGroup>
 <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
 <!-- Sadece gerçekten gerekli ise -->
 <WarningsNotAsErrors>CS0108;NU1901;NU1902;NU1903;NU1904;NU1701</WarningsNotAsErrors>
</PropertyGroup>

Ancak bu flag ile .NET platformu tarafından verilen tüm Warning’ler Error olarak görüleceği için örneğin Nuget paketleri tarafından verilen ve bizim tarafımızca çözülemeyecek warningler başımızı çokça ağrıtabilir. Bu tür sorunların üstesinden gelmek içinde WarningsNotAsErrors flag’ini kullanabiliyoruz. Ancak bunu sadece çözülemez hatalar için yapmak önemli.

.editorconfig ile projenin kurallarını belirleyelim

EditorConfig, aynı proje üzerinde çalışan birden fazla geliştiricinin farklı IDE’ler aracılığıyla tutarlı kodlama stilleri korumasına yardımcı olur. .NET projelerine özel bir pratik değildir, dil bağımsızdır ve ortak kuralları olduğu gibi dil özelinde kurallarıda mevcuttur.

Bu sayede sınıflar .NET tarafından standart sağlanan kurallar ile örneğin PascalCase, değişkenler camelCase, sabitler LOWER_CASE olmalı gibi kuralları proje seviyesinde tanımlayabiliriz.

Bu kurallara ek olarak SonarAnalyzer ile örneğin name == “” gibi facia bir kullanımı sonar taramasına girmeden yakalayıp string.IsNullOrEmpty(name) önerisini Visual Studio kullanıyorsanız Alt+Enter ile direk çözüm önerisini olarak alıp uygulayabilirsiniz. Bu sayede CI/CD adımında sonar taramasına giren kodunuz çok daha az hatayla taramaya başlayacaktır.

Harika bir diğer code analyzer kütüphanesi olan Roslynator sayesinde de çok daha spesifik kuralları projemizde uygulayabiliriz. Örneğin class property’leri arasında bir boşluk olmalı gibi kod okunaklığını arttıran kuralları bu sayede uygulayabiliriz.

Bu tür third party analyzer kütüphanelerini repo içerisindeki tüm projelere uygulamak için her projeye tek tek uygulamaktansa root dizinde Directory.Build.Props isminde bir dosya oluşturup içeriğini aşağıdaki şekilde oluşturursak build adımında bu paketler tüm projelere otomatik eklenecektir.

<Project>
 <ItemGroup>
 <PackageReference
 Include="Roslynator.Analyzers"
 Version="4.12.4"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 <PackageReference
 Include="Roslynator.Formatting.Analyzers"
 Version="4.12.4"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 <PackageReference
 Include="SonarAnalyzer.CSharp"
 Version="9.32.0.97167"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 </ItemGroup>
</Project>

Örnek olarak aşağıdaki .editorconfig dosyasına göz atabiliriz. Burada IDE ile tanımlanan kurallar .NET tarafından sağlanan standart kurallar, rcs ile başlayanlar roslynator ve S ile başlayanlar sonar kurallarıdır. Bu kurallar suggestion, warning ve error seviyesiyle tanımlanıp her bir proje için özelleştirilebilir.


# top-most EditorConfig file
root = true

# Don't use tabs for indentation.
[*]
indent_style = space
# (Please don't specify an indent_size here; that has too many unintended consequences.)
spelling_exclusion_path = SpellingExclusions.dic

# Code files
[*.{cs,csx,vb,vbx}]
indent_size = 4
insert_final_newline = true
charset = utf-8-bom

# XML project files
[*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
indent_size = 2

# XML config files
[*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
indent_size = 2

# JSON files
[*.json]
indent_size = 2

# Powershell files
[*.ps1]
indent_size = 2

# Shell script files
[*.sh]
end_of_line = lf
indent_size = 2

# Dotnet code style settings:
[*.{cs,vb}]

# Sort using and Import directives with System.* appearing first
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

# IDE0005: Remove unnecessary using directives
dotnet_diagnostic.IDE0005.severity = warning

# IDE0010: Add missing cases to switch statement 
dotnet_diagnostic.IDE0010.severity = warning

# Add blank line after using directive list
dotnet_diagnostic.rcs0003.severity = error

# Place new line after/before '?:' operator
dotnet_diagnostic.rcs0028.severity = error

# Track uses of "TODO" tags
dotnet_diagnostic.S1135.severity = suggestion

Son olarak bu pratiklerle aşağıdaki gibi bir öneri alarak kodumuzun daha tutarlı ve okunaklı olmasını sağlayabiliyoruz.

csharp_prefer_braces = true:suggestion

// Good:
if (isActive)
{
 DoSomething();
}

// Bad:
if (isActive)
 DoSomething();

Ayrıca GitHub’ın bol yıldızlı repolarında dotnet / roslyn ve christianhelle / refitter gibi .editorconfig referansları bulabilirsiniz.

pre-commit hook ile sorunları lokalde yakalayalım

Pre-commit hook’lar, Git’in her commit’ten önce çalıştırdığı scriptlerdir. Kod formatlama, linting veya testlerin çalıştırılması gibi kontroller için oldukça uygundur, sorunlu kodların commitlenmesini engellerler. Testlerde hata alan bir kodu commitlemeyi engellemek kısa vadede sinir bozucu olsa da uzun vadede testleri canlı tutmak adına çok önemli. Eğer CI/CD pipeline’ınızda test adımı varsa o adıma gelmeden önce lokalde sorunları görmemizi sağlar.

.NET projelerinde bu pre-commit hook’larını register etmek için ek paketlerden yardım alınabilir veya manuel süreçler ile her developer’ın git config core.hooksPath ./.git-hooks komudunu çalıştırması istenebilir. Biz burada projemizi ek bir pakete bağımlı hale getirmeden .NET platformunun bize sağladığı yeteneklerden faydalanacağız.

.csproj dosyanıza aşağıdaki gibi ekleyeceğiniz basit bir MSBuild target’ı ile, her dotnet restore adımında, dolayısıylada build adımında Git hook dizininizin kurulmasını sağlayabilirsiniz. Böylece, projenizde çalışan kim olursa olsun, projeyi build ettiği sürece, ekstra adımlara gerek kalmadan pre-commit hook otomatik olarak yüklenecektir. Ayrıca Production ortamında bu adımı atlıyoruz, böylece CI/CD pipeline’larında ya da prod ortamlarda gereksiz kurulumlar yapılmıyor.

<Target Name="register git hooks" BeforeTargets="Restore;CollectPackageReferences" Condition="'$(ASPNETCORE_ENVIRONMENT)' != 'Production'">
 <Exec Command="git config core.hooksPath ./.git-hooks" StandardOutputImportance="Low" StandardErrorImportance="High" />
</Target>

Projenizin root dizininde .git-hooks adlı bir klasör oluşturun. İçine pre-commit isminde bir dosya oluşturun:

./git-hooks/pre-commit

#!/bin/sh
echo Running tests...
dotnet format
dotnet test

Dosyanızı çalıştırılabilir yapmayı unutmayın:

chmod +x .git-hooks/pre-commit

Bu akış sayesinde testlerin hata aldığı durumda commit atamayacağız

$ git commit -m 'failed commit'
Running tests...
 Determining projects to restore...
 All projects are up-to-date for restore.
 Committer.API -> C:\Projects\Personal\lecture-net-pre-commit\src\Committer.API\bin\Debug\net9.0\Committer.API.dll
 Committer.Tests -> C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll
Test run for C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll (.NETCoreApp,Version=v9.0)
VSTest version 17.14.0 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
[xUnit.net 00:00:00.14] Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(a: 5, b: 3, expected: 7) [FAIL]
 Failed Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(a: 5, b: 3, expected: 7) [1 ms]
 Error Message:
 Assert.Equal() Failure: Values differ
Expected: 7
Actual: 8
 Stack Trace:
 at Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(Double a, Double b, Double expected) in C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\Services\CalculatorServiceTests.cs:line 25
 at InvokeStub_CalculatorServiceTests.Add_ShouldReturnCorrectSum(Object, Span`1)
 at System.Reflection.MethodBaseInvoker.InvokeWithFewArgs(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)

Failed! - Failed: 1, Passed: 18, Skipped: 0, Total: 19, Duration: 39 ms - Committer.Tests.dll (net9.0)

$ git log --oneline
9a89b16 (HEAD -> main, origin/main) test commit
10367df README.md added
0051724 Inital commit

Testler başarılı ise commit işlemi gerçekleşecektir:

$ git commit -m 'succeded commit'
Running tests...
 Determining projects to restore...
 All projects are up-to-date for restore.
 Committer.API -> C:\Projects\Personal\lecture-net-pre-commit\src\Committer.API\bin\Debug\net9.0\Committer.API.dll
 Committer.Tests -> C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll
Test run for C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll (.NETCoreApp,Version=v9.0)
VSTest version 17.14.0 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.

Passed! - Failed: 0, Passed: 19, Skipped: 0, Total: 19, Duration: 31 ms - Committer.Tests.dll (net9.0)
[main 0d9f3cf] succeded commit
 1 file changed, 1 insertion(+), 1 deletion(-)

$ git log --oneline
0d9f3cf (HEAD -> main) succeded commit
9a89b16 (origin/main) test commit
10367df README.md added
0051724 Inital commit

Özet

Özetle, .NET projelerinde kod kalitesini geliştirici insiyatifinden çıkarıp, takım genelinde zorunlu hale getirmek için uyguladığımız pratiklere göz attık. TreatWarningsAsErrors, .editorconfig kuralları ve gelişmiş analyzer paketleriyle kodun hem okunabilirliğini hem de güvenliğini arttırdık. Pre-commit hook’ları sayesinde ise hatalı veya testten geçmeyen kodun repoya girmesini baştan engelledik. Bu yaklaşımlarla, takımda sürdürülebilir ve yüksek kaliteli bir yazılım geliştirme kültürü oturtmak mümkün oldu.

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

github.com/berkslv/lecture-net-pre-commit

Kapanış

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden beni takip edebilirsiniz.

Feature Flagging in .NET with OpenFeature and flagd

Tue, 08 Jul 2025 00:00:00 +0300

Feature flagging (özellik bayrakları), modern yazılım geliştirme pratiklerinin vazgeçilmezlerinden biri haline geldi. Sık sık release alıyorsanız, belirli kullanıcılarla özellikleri test etmek istiyorsanız, daha güvenli sürümler arıyorsanız, feature flag’ler kesinlikle araç kutunuzda olmalı. Bu yazıda, vendor bağımsız bir feature flag standardı olan OpenFeature’ı anlatacağım ve .NET projelerinde flagd ile nasıl entegre edilebileceğini göstereceğim.

Feature Flagging Nedir?

Feature flag’ler (ya da diğer adıyla feature toggle’lar), yeni bir kod release almadan uygulamanızdaki özellikleri runtime sırasında anlık olarak açıp kapatmanızı sağlar. Hatta bir özelliği kullanıcı, ortam veya istediğiniz herhangi bir kritere göre segmente edebilirsiniz. Bu sayede:

Kademeli yaygınlaştırma (progressive delivery)
A/B testleri ve denemeler
Problemli özellikler için anında kill switch
Dağıtım sırasında daha düşük risk

Peki ya en önemli faydası nedir? Kontrol. Artık yayına aldığınız kod, sadece ekibinize ya da küçük bir beta grubuna görünür olabilir. Bir problem çıktığında ise, panikle rollback yapmak yerine, sadece flag’i kapatırsınız.

Eski Yöntem: Environment Variables

OpenFeature ve flagd’dan önce biraz gerçek dünyada yaşanan acılardan bahsetmek istiyorum. Pek çok ekip gibi, ben de başlangıçta feature flag yönetimini environment variable (veya appsettings.json) üzerinden yaptım. Şu yapı eminim size de tanıdık gelecektir:


{
 "EnableNewDashboard": true
}

Kodda da şöyle bir kontrol:


if (Configuration["EnableNewDashboard"] == "true")
{
 // Yeni dashboard’u göster
}

Tabiki ilk başta işe yarıyor… ama bir süre sonra sorunlar başlıyor:

Hedefleme yok: Ya hep ya hiç. Sadece iç kullanıcılar için mi açmak istiyorsunuz? Mümkün değil.
Anlık değişiklik yok: Değişiklik için çoğu zaman yeniden deploy veya restart gerekiyor.
Config karmaşası: Zamanla onlarca flag, diğer konfigürasyonlarla karışıyor.
Audit veya geçmiş yok: Kim ne zaman değiştirdi, iz yok.
Standart yok: Her ekip, her uygulama kendince yapıyor.

Ekipler büyüdükçe bu yaklaşım kırılganlaşıyor. Progressive delivery, canary deployment veya A/B testleri için dinamik kontrol şart. İşte bu noktada feature flag platformları ve OpenFeature gibi standartlar devreye giriyor.

Neden OpenFeature?

OpenFeature dışındaki çoğu feature flag çözümü (LaunchDarkly, Unleash, vs.) sizi kendi SDK’sına ve API’sine bağımlı kılar. OpenFeature burada devreye giriyor:

Vendor bağımsız: Sağlayıcı değiştirmek için kodunuzu yeniden yazmanız gerekmez.
Standart API: Farklı dil ve platformlarda aynı yaklaşımı kullanabilirsiniz.
Genişletilebilir: Loglama, telemetry gibi hook’lar ekleyebilirsiniz.
Cloud-native uyumlu: Modern mimariler için tasarlanmıştır.

OpenFeature ile uygulamanız sadece OpenFeature SDK’ya bağımlı olur; belli bir sağlayıcıya değil. Zamanla farklı bir sağlayıcıya geçmek isterseniz, provider’ı değiştirmeniz yeterli olacaktır.

Neden flagd?

flagd, açık kaynak ve hafif bir feature flag backend’idir. OpenFeature ile doğrudan çalışmak için tasarlanmıştır ve flag’leri JSON dosyalarından, HTTP endpoint veya gRPC üzerinden yönetilebilir. Fakat ne yazık ki şu anda flag’leri yönetmek için official bir kullanıcı arayüzü (UI) bulunmuyor, bunun yerine GitOps pratikleri ile yönetim sağlanıyor. flagd, hiçbir vendor-lockin yaşamadan, self host edebileceğiniz, bulut tabanlı bir feature flag backendi istiyorsanız idealdir.

Gerçek Hayattan Örnek: ENV’den Feature Flag’e

Gerçek hayattan bir örnekle, bir .NET web API’niz var diyelim. Yeni bir özelliği yayına alıyorsunuz; ama önce sadece iç kullanıcılarınıza açmak istiyorsunuz. Bir environment variable tanımlayıp, bunu isInternalUser gibi bir değişkene bağlayarak feature flag pratiklerini kısmen uygulayabilirsiniz. Ancak bu değişkende her değişiklikte kodu tekrar deploy etmeniz gerekiyor ve belirli bir kullanıcı grubu için değil, servisi kullanan tüm kullanıcılar için bu işlemi yapabiliyorsunuz.

Enviroment variable ile yönetilen bir feature flag ortamında Product Manager, bir özelliği kullanıcıların %10’u ile A/B test yapmak istiyorsa özel kod ve yeniden deploy gerekecektir.

Feature flag’ler bu tabloyu değiştiriyor:

Özelliği anında, spesifik kullanıcı/gruplar için açıp kapatın.
Herkese açmaya hazır olduğunuzda deploy gerekmeden canlıya çıkın.
Sorun çıkarsa, tek tuşla anında kapatın.

Modern ürün ekipleri bu sayede daha hızlı iterasyon yapabiliyor, riski azaltıyor ve sürekli değer sunabiliyor.

.NET’te OpenFeature ve flagd Entegrasyonu

Şimdi kurulumun nasıl yapılacağına bakalım.

1. NuGet Paketlerini Ekleyin


dotnet add package OpenFeature
dotnet add package OpenFeature.Contrib.Providers.Flagd

2. flagd’i docker-compose ile çalıştırın


services:
 flagd:
 image: ghcr.io/open-feature/flagd:latest
 volumes:
 - ./flags:/etc/flagd
 command: [
 'start',
 '--uri',
 'file:/etc/flagd/flags.json',
 '--debug'
 ]
 ports:
 - '8013:8013'

Örnek flags.json:


{
 "$schema": "https://flagd.dev/schema/v0/flags.json",
 "flags": {
 "new-greeting": {
 "state": "ENABLED",
 "variants": {
 "on": true,
 "off": false
 },
 "defaultVariant": "off",
 "targeting": {
 "if": [
 {
 "$ref": "userAgentIsFirefox"
 },
 "on",
 null
 ]
 }
 }
 },
 "$evaluators": {
 "userAgentIsFirefox": {
 "in": [
 "firefox",
 {
 "var": [
 "userAgent"
 ]
 }
 ]
 }
 }
}

3. .NET Uygulamanızda OpenFeature’ı Konfigüre Edin


using OpenFeature.Contrib.Providers.Flagd;
using OpenFeature.Model;

var builder = WebApplication.CreateBuilder(args);

await OpenFeature.Api.Instance.SetProviderAsync(new FlagdProvider(new Uri("http://localhost:8013")));

var app = builder.Build();

app.MapGet("/greet", async context =>
{
 var client = OpenFeature.Api.Instance.GetClient();
 // Get User-Agent header
 var userAgent = context.Request.Headers["User-Agent"].FirstOrDefault() ?? "";
 var evalContext = EvaluationContext.Builder().Set("userAgent", userAgent).Build();

 var useNewGreeting = await client.GetBooleanValueAsync("new-greeting", false, evalContext);

 string greeting = useNewGreeting
 ? "Hey there! Welcome to the new greeting experience! 🎉"
 : "Hello, World!";

 await context.Response.WriteAsync(greeting);
});

app.Run();

4. Test Edin

flags.json dosyanızdan flag’i değiştirin. .NET uygulamanız değişikliği anında yakalayacaktır. API ucunu test ettiğimizde aşağıdaki gibi bir sonuçla karşılaşırız.


$ curl http://localhost:5050/greet
Hello, World!

$ curl http://localhost:5050/greet -H 'User-Agent: firefox'
Hey there! Welcome to the new greeting experience! 🎉

Eğer flagd backendine direk olarak istek atıp flagin durumunu görmek istersek ise aşağıdaki şekilde sorgulama yapabiliriz


$ curl -X POST "http://localhost:8013/flagd.evaluation.v1.Service/ResolveBoolean" -d '{"flagKey":"new-greeting","context":{}}' -H "Content-Type: application/json"
{"value":false, "reason":"DEFAULT", "variant":"off", "metadata":{}}

$ curl -X POST "http://localhost:8013/flagd.evaluation.v1.Service/ResolveBoolean" -d '{"flagKey":"new-greeting","context":{"userAgent": "firefox"}}' -H "Content-Type: application/json"
{"value":true, "reason":"TARGETING_MATCH", "variant":"on", "metadata":{}}

Özet

Feature flag’ler riski azaltır, daha hızlı dağıtım sağlar ve kullanıcı hedeflemesini kolaylaştırır. OpenFeature, .NET’te feature flag yönetimi için size standart ve geleceğe dönük bir API sunar. flagd ise kendi kendinize barındırabileceğiniz, Kubernetes ile uyumlu açık kaynak bir backend’dir.

Hâlâ environment variable ya da config dosyaları ile özellik yönetimi yapıyorsanız, OpenFeature ve flagd’ye bir şans verin. Gelecekte kendinize teşekkür edeceksiniz, özellikle bir cuma akşamı bir özelliği acil kapatmanız gerekirse.

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

https://github.com/berkslv/lecture-net-pre-commit

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden beni takip edebilirsiniz.

SignalR ile Gerçek Zamanlı İletişim: Derinlemesine İnceleme

Fri, 29 Nov 2024 00:00:00 +0300

Günümüz dünyasında verilerin hızla hareket ettiği bir ortamda, modern uygulamaların kullanıcılarına sorunsuz deneyimler sunabilmesi için gerçek zamanlı iletişim bir zorunluluk haline gelmiştir. SignalR, .NET uygulamaları için gerçek zamanlı iletişim özelliklerini kolayca hayata geçirmenize yardımcı olan temel bir kütüphanedir. SignalR kullanırken tüm iletişim ve network gereksinimleri kütüphane tarafından soyutlanır; sadece bir RPC çağrısı yapar gibi yöntem çağrısında bulunmanız yeterlidir. SignalR sayesinde canlı panolar, sohbet uygulamaları veya web uygulamalarında sıkça ihtiyaç duyulan basit bildirim özelliklerini kolayca oluşturabilirsiniz. Haydi başlayalım.

Neden SignalR?

Geleneksel istemci-sunucu iletişim modelleri, yüksek etkileşim ihtiyaçları için daha az verimli ve sınırlı olan istek-cevap modeline dayanır ve veriye ihtiyaç duyulduğunda istemcinin bir istek göndermesini gerektirir. SignalR, istemci ile sunucu arasındaki aynı bağlantıyı sürekli açık tutarak bu zorlukları ortadan kaldırmak için tasarlanmıştır.

SignalR’ın Temel Avantajları:

Gerçek Zamanlı İletişim: İstemciler, yeni bir istek göndermeye gerek kalmadan anında güncellemeleri alır.
Çapraz Platform Desteği: SignalR, platform ve tarayıcıdan bağımsızdır.
Karmaşık Protokollerin Soyutlanması: SignalR, WebSocket, Server-Sent Events ve Long Polling protokollerini kullanma yeteneğine sahiptir. Bu, istemci ve sunucu arasında daha verimli bir ilişki sağlar ve en uygun protokolün seçilmesine olanak tanır. WebSocket protokolü istemci tarafından desteklenmiyorsa, SignalR kendi iç algoritmasına göre diğer yöntemleri seçerek kullanır.
.NET Uygulamaları ile Entegrasyon: .NET ile başarılı bir şekilde entegre olarak modern .NET uygulamalarında sorunsuz bir kullanım sağlar.

SignalR ile Başlangıç

.NET projenize SignalR’ı entegre etmek için aşağıdaki adımları takip edebilirsiniz:

1. SignalR NuGet Paketi

SignalR, .NET sistem kütüphaneleriyle birlikte gelir, bu nedenle ek bir paket yüklemenize gerek yoktur. Ancak Visual Studio saçmalamaya başlarsa Microsoft.AspNetCore.SignalR paketini yüklemeyi deneyebilirsiniz.

2. Hub Sınıfı Oluşturma

Hub, bağlantıları yöneten ve istemcilere mesaj gönderen merkezi bir bileşen görevi görür. Bu sınıfı, HTTP isteklerini kabul ettiğiniz Controller’lara benzetebilirsiniz, ancak burada istemciden gelen istekleri kabul edebilir veya istemciye doğrudan istek gönderebilirsiniz. Basit bir örnek:


using Microsoft.AspNetCore.SignalR;

public class NotificationsHub : Hub
{
 public async Task SendNotification(string content)
 {
 await Clients.All.SendAsync("ReceiveNotification", content);
 }
}

3. Program.cs Dosyasında Hub’ı Yapılandırma

SignalR servislerini kaydedin ve hub uç noktasını şu şekilde eşleyin:


var builder = WebApplication.CreateBuilder(args);

//...

builder.Services.AddSignalR();

var app = builder.Build();

//...

app.MapHub<NotificationsHub>("hubs/notification");

app.Run();

4. SignalR İstemcisi

SignalR, Javascript, .NET ve Java gibi çeşitli istemci platformlarını destekler. Eğer bu platformlarda SignalR kütüphanesini uygulamak istemiyorsanız, uç noktanızı test etmek için basitçe Postman kullanabilirsiniz. Ancak JSON sonuna 0x1E karakterini eklemeniz gerekir. SignalR’ın dahili protokol gerekliliği budur. Javascript kütüphanesi kullanıyorsanız bu detayla uğraşmanıza gerek yoktur.


{
 "protocol": "json",
 "version": 1
}

SignalR Hub’a mesaj göndermek ve almak için şu şekilde bir JSON kullanabilirsiniz:


{
 "arguments" : ["hello world"],
 "target" : "SendNotification",
 "type" : 1
}

Kısa bir Postman ve SignalR demosu:

SignalR ve Postman demo

Gelişmiş Özellikler

1. Tip Güvenli Hub’lar

Bakımı daha kolay hale getirmek için hub arayüzünü belirterek tip güvenli hub’lar kullanabilirsiniz:


public interface INotificationsClient
{
 Task ReceiveNotification(string content);
}

public class NotificationsHub : Hub<INotificationsClient>
{
 public async Task SendNotification(string content)
 {
 await Clients.All.ReceiveNotification(content);
 }
}

2. Belirli İstemcilere Mesaj Gönderme

SignalR, belirli kullanıcılar veya gruplara mesaj gönderme yeteneğine sahiptir. Kullanıcıyı bir grup adına ekledikten sonra yalnızca ilgili kullanıcıya bildirim gönderebilirsiniz:


await Clients.User(userId).ReceiveNotification("Hello, User!");
await Clients.Group(groupName).ReceiveNotification("Hello, Group!");

Kullanıcı kimliği (userId) ile hedefleme yapmak için IUserIdProvider uygulamanız gerekir:


public class UserIdProvider : IUserIdProvider
{
 public string GetUserId(HubConnectionContext connection)
 {
 return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
 }
}


// Program.cs
services.AddSingleton<IUserIdProvider, CustomUserIdProvider>();

3. Hub Dışından IHubContext Kullanımı

Hub dışında istemcilere mesaj göndermek için aşağıdaki şekilde bir yaklaşım izleyebilirsiniz. IHubContext türünü enjekte edin ve mesajınızı istemcilere gönderin.

Sisteminizde bir olay gerçekleştiğinde bu özelliği kullanarak hub’ı tetikleyebilirsiniz. Örneğin, uzun süren bir toplu işlem tamamlandığında kullanıcılarınıza sonuç hakkında bildirim gönderebilirsiniz.

Kısa bir not: Kodunuzu daha temiz hale getirmek için bu IHubContext arayüzünü, örneğin INotificationDispatcher gibi başka bir arayüzle soyutlamanız iyi bir fikir olabilir.


public class NotificationDispatcher(IHubContext<NotificationsHub> hubContext) : INotificationDispatcher
{
 public async Task SendNotification(string content)
 {
 await hubContext.Clients.All.SendAsync("ReceiveNotification", content);
 }

 public async Task SendNotificationToUser(string userId, string content)
 {
 await hubContext.Clients.User(userId).SendAsync("ReceiveNotification", content);
 }

 public async Task SendNotificationToGroup(string groupName, string content)
 {
 await hubContext.Clients.Group(groupName).SendAsync("ReceiveNotification", content);
 }
}

SignalR Güvenliğini Sağlama

SignalR hub’larını [Authorize] özniteliği ile güvence altına alabilirsiniz:


[Authorize]
public class NotificationsHub : Hub
{
 // Hub methods
}

Redis Backplane ile SignalR Ölçekleme

SignalR’ı birden fazla sunucuya ölçeklendirmek, birden çok instance üzerinde çalışan yüksek talep gören uygulamalar için güvenilir gerçek zamanlı iletişim sağlar. Redis backplane, SignalR sunucuları arasındaki mesajları senkronize ederek, farklı sunuculara bağlı istemcilerin sorunsuz bir şekilde mesaj almasını sağlar. İşte Microsoft belgelerinden bir alıntı:

SignalR Redis backplane, mesajları diğer sunuculara iletmek için pub/sub özelliğini kullanır. Bir istemci bağlantı kurduğunda, bağlantı bilgileri backplane’e iletilir. Bir sunucu tüm istemcilere mesaj göndermek istediğinde, bunu backplane’e iletir. Backplane, tüm bağlı istemcileri ve hangi sunucularda olduklarını bilir. Mesajı ilgili sunucular aracılığıyla tüm istemcilere gönderir.


dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis


// Program.cs

builder.Services.AddSignalR()
 .AddStackExchangeRedis("localhost:6379", options =>
 {
 options.Configuration.ChannelPrefix = "SignalR";
 });

Eğer bana inanmıyorsanız, SignalR uygulamanızı yerel test ortamında birden fazla instance ile çalıştırmayı Docker Compose kullanarak deneyebilirsiniz:


services:
 signalr:
 image: your-app
 ports:
 - "5000:5000"
 depends_on:
 - redis
 redis:
 image: redis:latest
 ports:
 - "6379:6379"


docker-compose up --scale signalr=3

SignalR İletişim Modelleri

SignalR, uyumluluk ve performansı sağlamak için birden fazla taşıma yöntemini soyutlar:

WebSocket (`webSockets`):

WebSockets, SignalR için en verimli ve tercih edilen gerçek zamanlı, çift yönlü iletişim yöntemidir. Tek bir TCP kanalı üzerinden kalıcı, tam çift yönlü bir bağlantı kurarak istemci ve sunucu arasında eşzamanlı mesaj alışverişine olanak tanır. Bu, canlı sohbetler, ortak düzenleme araçları, çevrimiçi oyunlar ve finansal veri akışları gibi düşük gecikme ve yüksek hız gerektiren uygulamalar için idealdir.

WebSockets, ilk HTTP el sıkışmasının ardından kendi hafif protokolüne (ws:// veya wss://) geçerek geleneksel HTTP tabanlı iletişimin getirdiği yükü azaltır. Ancak, WebSockets’in ölçeklendirilmesi, WebSocket uyumlu yük dengeleyiciler ve yapışkan oturumlar gibi özel altyapılar gerektirir. SignalR, bağlantı sürekliliğini, otomatik yeniden bağlantıları ve WebSockets kullanılamadığında alternatif protokollere geçişi yöneterek bu zorlukları basitleştirir.

Server-Sent Events (`serverSentEvents`):

SSE (Server-Sent Events), uzun ömürlü bir bağlantı üzerinden sunucudan istemciye gerçek zamanlı güncellemeler sağlayan hafif bir HTTP tabanlı mekanizmadır. Standartlaştırılmış EventSource API’sini kullanır ve verileri text/event-stream formatında iletir. Bu, canlı panolar, bildirimler ve haber akışları gibi yalnızca sunucudan istemciye veri aktarımı gerektiren durumlar için basit ve etkilidir.

SSE, standart HTTP üzerinde çalıştığı için mevcut HTTP altyapısı ile kolayca entegre olur ve WebSockets’e kıyasla daha kolay ölçeklenebilir. Ancak, SSE Internet Explorer tarafından desteklenmez ve istemciden sunucuya iletişim gerektiren durumlar için ayrı HTTP istekleri gerektirir. SignalR, WebSockets kullanılamadığında otomatik olarak SSE’yi tercih ederek kesintisiz bir deneyim sunar.

Long Polling (`longPolling`):

Long Polling, sürekli olarak HTTP bağlantıları açıp kapatarak gerçek zamanlı iletişimi taklit eder. İstemci, sunucuya bir istek gönderir ve sunucu veri gönderene kadar bağlantıyı açık tutar. Veriler iletildikten sonra istemci hemen yeni bir istek oluşturur. Bu yöntem, güncellemeler arasındaki gecikmeyi en aza indirir ve bir tür push tabanlı bağlantı hissi yaratır.

Long Polling, tüm tarayıcılarla çalışabilir ve uygulanması kolaydır. Ancak, sık HTTP istekleri ve yanıtları nedeniyle daha fazla yük oluşturur. Bu, özellikle yüksek frekanslı güncellemelerde, WebSockets veya SSE’ye kıyasla daha az verimlidir. SignalR, WebSockets veya SSE desteklenmediğinde Long Polling’i bir yedek çözüm olarak kullanır.

Forever Frame (`foreverFrame`):

Forever Frame, eski Internet Explorer sürümlerine özgü bir protokoldür ve gerçek zamanlı, tek yönlü iletişim sağlar. İstemci tarayıcısında gizli bir iframe oluşturur ve sunucu bu iframe’e sürekli olarak çalıştırılabilir komut dosyaları gönderir.

Forever Frame, çift yönlü iletişimi desteklememesi ve yüksek ek yük getirmesi gibi sınırlamalara sahiptir. İstemciden sunucuya iletişim, ayrı standart HTTP istekleri gerektirir ve bu da uygulamayı daha az verimli ve zahmetli hale getirir. SignalR, yalnızca eski Internet Explorer tarayıcılarına özgü ortamlar için bir son çare olarak Forever Frame’i kullanır.

WebSockets ve Server-Sent Events Karşılaştırması

WebSockets ve Server-Sent Events (SSE), farklı gerçek zamanlı iletişim ihtiyaçlarına hitap eder. WebSockets, düşük gecikmeli, çift yönlü iletişim sunarak sohbet, oyun ve ortak çalışma araçları için idealdir. SSE ise hafif, tek yönlü güncellemeler sağlayarak canlı panolar ve bildirimler gibi durumlar için mükemmeldir.

WebSockets, etkili iki yönlü mesajlaşma için özel bir protokol (ws:// veya wss://) kullanır ancak ölçeklendirme için WebSocket uyumlu altyapı gerektirir. SSE ise standart HTTP (text/event-stream) üzerinde çalışır ve geleneksel HTTP araçları ile daha kolay ölçeklenebilir. Ancak, yalnızca sunucudan istemciye iletişim sağlar ve Internet Explorer desteği bulunmaz.

SignalR, bu farklılıkları soyutlayarak performans için WebSockets’i önceliklendirir ve kesintisiz gerçek zamanlı işlevsellik sağlamak için SSE veya diğer yöntemlere otomatik olarak geçiş yapar.

Protokolü Belirleme

SignalR, gerçek zamanlı iletişim için kullanılacak taşıma protokolünü açıkça belirtmenize olanak tanır. Varsayılan olarak, SignalR dahili algoritmasıyla mevcut en iyi protokolü otomatik olarak seçer. Ancak, bu davranışı uygulamanızın ihtiyaçlarına göre özelleştirebilirsiniz.

WebSockets’in verimliliğinden yararlanmak ve WebSockets kullanılamadığında Long Polling’e geçiş yapmak için Program.cs dosyasına şu kodu ekleyebilirsiniz:


app.MapHub<NotificationsHub>("/hubs/notification", opt =>
{
 opt.Transports = HttpTransportType.WebSockets | HttpTransportType.LongPolling;
});

Veya istemci tarafında JavaScript ile şu şekilde yapılandırabilirsiniz:


let connection = new signalR.HubConnectionBuilder()
 .withUrl("/hubs/notification", {
 transport: signalR.HttpTransportType.WebSockets
 | signalR.HttpTransportType.LongPolling })
 .build();

Özet

SignalR, .NET uygulamalarına gerçek zamanlı özellikler eklemeyi kolay ve verimli hale getirir. Karmaşık ağ protokollerini soyutlayarak, alt yapı detaylarıyla uğraşmadan canlı panolar, sohbet uygulamaları veya bildirimler oluşturmanıza olanak tanır. WebSockets, Server-Sent Events (SSE) ve Long Polling gibi protokolleri destekleyen SignalR, ortamınıza en uygun protokolü otomatik olarak seçerek kesintisiz bir deneyim sunar.

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

GitHub - berkslv/lecture-signalr-deep-dive

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Event-Driven Architecture: Mikroservis mimarisinde başka servislerin verilerine mi ihtiyacınız var

Sat, 07 Sep 2024 00:00:00 +0300

Microservice mimarisinde geliştirilen uygulamalarda domainler genellikle birbirlerinden sıkı bir şekilde ayrılmaya çalışılıyor, inceleyeceğimiz örnekte ürün ile ilgili tüm logic ve data product servisinde yer alırken, bu ürün ile sipariş oluşturabilecek satış danışmanlarını yöneten organization serviside kendi logic ve datasını barındırıyor.

Ancak organization servisinde satış danışmanı oluşturmak için yapacağımız createUnit() isteği validasyon sebepleri için product servisinin verisine ihtiyaç duyacaktır. Var olmayan bir ürün için oluşturma izni unit’e verilmemeli değil mi? Bu durumda organization servisi kendi domain’inde yer almayan ve kendi sorumluluğunda olmayan product servisinin verisine ihtiyaç duyacak.

Bu veriye senkron veya asenkron olarak erişebiliriz. ilk olarak senkron olarak erişecek ve yaşayacağımız sorunları ele aldıktan sonra, asenkron methodu kullanıp yaşayabileceğimiz sorunları ele alacağız, hadi başlayalım.

Synchronous communication

Organization servisimize rest ile göndereceğimiz istek ile, createUnit() methodunu tetikletecek ve unit oluşturacağız, ancak bu servis product verisine validasyon sebebiyle için ihtiyaç duyacağı için bu veriyi senkron olarak, HTTP REST yardımıyla yapacağı getProduct() isteği ile getirmesi gerekecektir.

runtime sırasında, createUnit methodunun işlenebilmesi için organization servisine ek olarak product servisininde ayakta ve erişilebilir olması, aradaki network bağlantısında bir sorun olmaması gerekiyor. Eğer product servisi çalışmıyorsa, organization serviside çalışmayacaktır. Her iki serviste ayakta ve erişilebilir olduğu durumlarda ise product servisi yavaş çalışıyorsa, senkron yapacağımız istek akışı bloklayacağı için, organization serviside yavaş çalışacaktır. Bu sorunu aşmak için organization servisinin yoğun istek aldığı durumlarda scale edilecektir. Ancak runtime bağımlılığı bulunan product servisininde organizationdan gelecek bol miktarda isteği karşılayabilmek için aynı şekilde scale etmemiz gerekecektir. Bu pratiği tüm servislere uyguladığımız senaryoda, tüm servislerin beraber scale edilmesi gerekecektir. Bu sebeple Organization servisi, Product servisine son derece bağımlı olup, yaşamlarına kendi başlarına değil, beraber devam etmek zorunda kalacaklardır. Eğer microservice mimarimizdeki tüm servislerimiz birbirlerine bu şekilde bağımlı olursa tek bir servisin erişilemez olması diğer tüm servislerin erişilemez olmasına yol açabilir.

design time sırasında ise product servisinin getProduct API’ında yapılacak olan bir geliştirme sonrası Organization servisinin geliştirici takımıda aynı değişikliği kendi Product HTTP Client entegrasyonlarında yapmaları gerekecektir. Bu değişiklik büyük olasılıkla organization servisinin iş akışlarındada kod değişikliğe yol açacaktır.

Sonuç olarak hem runtime’da hemde design time’da coupling ortaya çıkacağı için iki servis birbirine göbekten bağlı olacaktır, Jonathan Tower’ın tabiriyle distributed monolith geliştirmiş olacağız. Bir servisimizde yapılacak olan değişiklik, diğer serviside direk olarak etkileyeceğinden ötürü, sürekli değişen iş gereksinimlerine hızlıca cevap veremeyeceğiz. Product servisinin getProduct() methodunda yapılan herhangi bir geliştirmeye istinaden, bu ucu kullanan diğer servislerinde aynı geliştirmeyi kendi servislerinde yapması gerekecektir. Geliştirmeyi bir şekilde tamamladıktan sonrada son kullanıcıların uygulamamızı kullanabilmesi için senkron olarak birbirlerine bağlı olan tüm servislerin erişilebilir olması gerekecektir.

Synchronous communication

Müşterimize bir SLA garantisi vermek istediğimiz senaryoda, iyimser olarak Product ve Organization servislerimiz için %99.5 uptime garantisi verecek olursak yıllık 43 saat downtime yaşanabileceğini kabul ediyoruz. product ve organization servislerinin runtime’da bağımlı olacağı senaryoda $0.995 * 0,995 = 0.990$ hesabıyla senkron iletişimle beraber çalışan servislerimiz ile yaşanan bağımlılık sonucunda, her bir servisimiz iki kat daha kötü uptime garanti ederek, yıllık 87 saat downtime yaşayabileceklerini görüyoruz.

	Product	Organization	Product & Organization
Uptime percentege	99.5	99.5	99.0
Month	716	716	712
Downtime in month	4	4	7
Year	8716	8716	8672
Downtime in year	43	43	87

Peki başımızı bu kadar ağrıtabileceğini ön gördüğümüz bu yöntemden nasıl kaçınacağız? Servisler arası iletişimdeki diğer çözüm önerimize bir bakalım.

Asynchronous communication

Senkron iletişim, servisler arası bağımlılığı mümkün olan her yönde arttırdığı için bu seçeneği tercih etmek istemezsek, diğer seçeneğimiz olan asenkron iletişimle devam edebiliriz. Asenkron yöntemle okları tersine çevirerek Product servisinin Product tablosunda bir güncelleme yaşanması durumunda ProductCreatedEvent isminde bir domain event publish ediyoruz. Bu eventi dinleyen tüm servisler, kendi veritabanlarında tuttukları products tablolarını güncelliyorlar.

Organization servisi product verisine ihtiyaç duyduğunda kendi veritabanında yer alan products tablosundan okuma yapacaktır. Bu tablo organization’ın iş akışlarından etkilenmeden, sadece okuma yapılacaktır. Bu şekilde createUnit() methodumuzda ihtiyacımız olacak ürün bilgisini sorgulamak için unit verisini kaydedeceğimiz aynı veritabanından okuma yaparak ilgili veriye ulaşmış oluruz.

Asynchronous communication

Bu yöntemle createUnit() akışımızda product verisine organization’ın kendi veritabanından erişerek, Product servisimize runtime sırasındaki bağımlılığımızı ortadan kaldırıyoruz.

Bu sayede, run time sırasındaki bağımlılık ortadan kalkıyor, çünkü product servisinin verdiği getProduct() ucunu senkron bir şekilde sorgulamayı bıraktık. design time sırasındada geliştirme yaparken yaşadığımız bağımlılıkta ortadan kalkmış oluyor. Çünkü Product servisinin getProduct() methodunda yaptığımız bir değişiklik sonrasında Organization servisine sahip olan takımın kendi servislerinde bir değişiklik yapması gerekmiyor.

Design time sırasındada asenkron bir bağımlılığımız var, sadece ihtiyacımız olduğu durumlarda ilgili değişiklikleri yapmamız gerekiyor. Eğer Product servisinin product domain modelinde bir değişiklik yapılarak yeni bir kolon eklenirse, bu kolon direk olarak event’e yeni bir field olarak eklenebilir. Eğer product tablosunda bir kolon silindiyse, bu kolon, event tipinde silinmeden default değerleri ile gönderilmeye başlanıp, obsolete olarakta işaretlenebilir. Bu eklenip çıkartılan kolonlara diğer servisler diledikleri gibi cevap verebilir veya hiç bir değişiklik yapmadan kendi hayatlarına devam edebilirler.

Publish edilen eventin, kimler tarafından işlendiği publish eden taraf olan Product servisini ilgilendirmez. Artık bu veriye ihtiyacı olan herkes bu eventi consume edip, kendi veritabanlarında product verisinin bir kopyasını tutarak, Product servisiyle senkron bir iletişime geçmeden kendi işlerini kendi başlarına halledebiliyorlar. Bu şekilde daha scale edilebilir ve daha erişilebilir uygulamalar ortaya çıkarmış oluyoruz, çünkü artık uygulamalarımızın farklı bir servise bağımlılığı bulunmadan kendi başlarına hareket edilebiliyorlar.

Eğer tablolarımızın domain bazında karışacağını düşünüyorsak farklı domainlerden gelecek olan tabloları aşağıdaki örnekteki gibi farklı bir veritabanı şemasında tutabiliriz.

Asynchronous communication 2

Eventual consistency

Bu yöntemin karşımıza çıkartacağı en büyük sorun, eventual consistency yaratacak olmasıdır. Product servisine eklenen bir ürünün, organization servisindeki ilgili tabloya yansıması aynı t anında değil, aradaki message broker’ın erişilebilirlik durumuna göre, birkaç milisaniye veya saniye gecikme ile yaşanacaktır.

Bu durumu CAP teorisiylede açıklayabiliriz. CAP teorisinin 3 bacağından biri olan Partition tolarence bacağını sabit tutarsak, Consistency ve Availability bacaklarından birisi artarken diğeri azalacaktır. Dolayısıyla bu üç seçeneği aynı anda sağlayamayacağız. Buradada çalıştığımız iş akışına göre karar vermemiz gerekiyor.

Örneğin bir eticaret sisteminde sepete ekleme özelliğinin highly avaliable olması gerekebilir, çünkü sepete ekleme özelliği çalışmıyorsa, lütfen daha sonra tekrar deneyin gibi bir hata alıyorsak, o sitede değil rakip sitede alışverişe devam etmemiz olasıdır. Ancak sepete devam ettiğimizde istediğimiz üründen 1 değil 2 adet görürsek ilgili düzeltmemizi yapıp ödemeye devam edebiliriz.

Fakat aynı durumu otel rezervasyonlarında uygulayamayabiliriz. Sepet örneğimizin tersine consistency muhtemelen daha önemli olacaktır. Aynı odayı birden çok kişiye kiralamak yerine, lütfen daha sonra tekrar deneyin gibi bir hata dönmek çok daha mantıklı olabilir.

Sonuç olarak senkron iletişimin uygun olduğu immediate consistency isteyen akışlar için senkron iletişim, high avalability ihtiyacı olan akışlar için ise asenkron iletişimden faydalanabiliriz. Burada küçük bir yorum olarak microservice mimarisindeki akışlarda genellikle high avalability tercih edilmesi gerekiyor, çünkü diğer senkron iletişim yöntemiyle tüm servislerimiz göbekten birbirlerine bağımlı olacaklardır.

High avalability vs Immidiate consistency

Edge cases in asynchronous communication

Eğer servisleriniz arasındaki iletişimde, event driven architecture ile ilerlemeye karar verdiyseniz sistemdeki veri tutarlılığını sağlamak içinde bir şeyler yapmanız gerekecektir. Bir servisimize create isteği gelir ve CreatedEvent publish edersek, ilk önce veritabanını güncelleyip, sornasında event publish ettiğimiz durumda, eğer veritabanında yürüttüğümüz transaction hatayla sonuçlanır, ve bunu takip etmeden eventi publish edersek, veya veritabanında yürüttüğümüz transaction başarıyla sonuçlanır, ancak sonrasında event bus’a erişilemezse, uygulamalarımızda dağıtık olarak duran veri, insonsistent state’e düşebilir. Bu durumun önüne geçmek için product servisi kendi veritabanındaki product verisini güncellerken aynı zamanda aynı veritabanında yer alan outbox tablosunada ilgili eventi ekledikten sonra, farklı bir thread bu tabloyu devamlı olarak tarayarak yeni gelen eventleri publish eder. Veritabanına yaptığımız kayıt atomic olarak işleneceği için product verisi oluşturulurken event verisininde outbox tablosunda oluşturulacağı garanti edilir. Fakat birden çok instance olarak çalışan bir uygulamada bir eventin aynı outbox tablosundan 2 defa okuyup, 2 defa publish etmesi gibi durumlarla karşılaşılabilir. Bu durumda zaten idempotency sorununa çıkıyor.

Bir metodun bir defa çağrıldığında alınan sonuç ile birden fazla kez çağrıldığında alınan sonuç aynı ise bu bir idempotent metottur. Bir eventin, farklı sebeplerden ötürü, birden çok kez işlenip sistemdeki veri tutarlılığını bozulmasını önlemek için, eventlerin benzersiz message id değerlerini consume edildikten sonra veritabanına kaydedip, yeni bir event consume edileceği zaman, message id değeri veritabanında yoksa işleme devam etmemiz gerekecektir. Chris Richardson (microservices.io) bu konuya Pattern: Idempotent Consumer isimli yazısındada değiniyor.

Without Outbox & Idempotency

Outbox & Idempotency

Sonuç olarak Computer Science alanındaki çoğu problemle sunulan çözüm önerilerinde olduğu gibi elimizde bir silver bullet bulunmuyor. Her iki yönteminde avantajları ve dezavantajlarını kapsamlı bir şekilde, çalıştığımız domain’inde aklımızda bulundurup değerlendirdikten sonra dilediğimiz yöntemle devam edebiliriz. Ancak benim önerim, servisler arasındaki bağımlılığı mümkün olduğu durumlarda asenkron iletişim kullanarak ortadan kaldırmak olacaktır.

Asenkron ve senkron veri iletişimiyle çalışırken yaşanbilecek durumları simule etmek için geliştirdiğim .NET projesine aşağıdaki github reposundan ulaşabilirsiniz. Örnekte outbox yapısı için MassTransit tarafından sağlanan altyapı kullanılarak bu özellik için özel bir geliştirme yapılmamıştır.

GitHub - berkslv/lecture-fetch-other-service-data-with-event-driven-architecture

Resources

Don’t Build a Distributed Monolith - Jonathan “J.” Tower - NDC London 2023

The Many Meanings of Event-Driven Architecture • Martin Fowler • GOTO 2017

Solving distributed data problems in a microservice architecture | Microservices.io

You Keep Using That Word • Sam Newman • GOTO 2023

Microservices Pattern: Pattern: Idempotent Consumer

The Reactive Manifesto

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

HTTP ve MassTransit ile .NET Mikroservislerinde CorrelationId Takibi

Sun, 14 Jul 2024 00:00:00 +0300

Microservice mimarisinde dağıtık olarak çalışan uygulamaların kendi aralarında yaptıkları iletişimler sırasında devam eden işlemin takip edilebilirliği ve eğer bir serviste performans sebepli veya akışsal bir sorun varsa hangi adımlardan sonra buraya geldiğini anlamlandırabilmek için Distributed tracing başlığı altında CorrelationId çok önemli bir yere sahiptir.

CorrelationId, bir isteğin tüm yaşam döngüsü boyunca taşınarak, farklı servisler arasındaki bağıntıyı sağlamalıdır. Bu yazıda, .NET tabanlı bir microservice mimarisinde HTTP ve RabbitMQ istekleri kullanarak CorrelationId değerinin nasıl gezdirilebileceğini inceleyeceğiz. Bu çözüm sorunumuza net bir şekilde cevap olmak için tasarlandı ancak her türlü yoruma ve geliştirmeye açıktır, eğer aklınızda daha iyi bir çözüm gelirse lütfen bana ulaşın.

Big picture

CorrelationId değerini HTTP ve MassTransit kullanarak servisler arasındaki iletişim sırasında Middleware ve Filter yapılarıyla gelen ve giden isteklerde araya girerek header değerleri üzerinde manipulasyonda bulunarak CorrelationId değerini servisler arasında gezdireceğiz. Bu gezdirme sırasındada gelen isteklerle başlatılan contextlerin, verilen CorrelationId değeri ile loglanması için Serilog tarafından sağlanan LogContext sınıfından faydalanacağız. Tüm örneklere aşağıdaki repodan ulaşabilirsiniz.

GitHub - berkslv/lecture-correlation-id-microservices

Serivisimize gelen isteklerde aldığımız CorrelationId değerini, giden isteklerde göndermek için Scoped olarak tanımlayabileceğimiz Correlation sınıfımızdan yararlanabiliriz. Ancak bu şekilde Dependency Injection yöntemleri ile sınıflar arasında gezdirdiğimiz state değerimiz async olarak ilerleyen isteğimizde özel bir durumda erişilemez oluyor: DelegatingHandler sınıfı kullanarak HttpClient ile yapacağımız isteklerde araya girecek olan CorrelationHeaderHandler sınıfımız uygulamamızdan ayrı bir DI scope içerisinde çalışacağı için Scoped olarak tanımlayabileceğimiz Correlation sınıfımızın değerine bu özel durumda erişemeyeceğiz. Bu konu microsoft’un kendi dökümantasyonundada şöyle aktarılıyor

When IHttpClientFactory creates a new delegating handler, it uses DI to fulfill the handler’s constructor parameters. IHttpClientFactory creates a separate DI scope for each handler, which can lead to surprising behavior when a handler consumes a scoped service.

Bu soruna çözüm olarak AsyncStorage isminde bir sınıf oluşturup Microsoft tarafından sağlanan AsyncLocal sınıfını kullanarak CorrelationId değerini async olarak ilerleyen isteğimizde aynı thread içerisinde dilediğimiz zaman erişebileceğimiz bir yapı oluşturacağız:


namespace Order.API.Filters.Correlation;

/// <summary>
/// Stores and retrieves values in an async context.
/// </summary>
/// <typeparam name="T">What should be stored</typeparam>
public static class AsyncStorage<T> where T : new()
{
 private static readonly AsyncLocal<T> _asyncLocal = new AsyncLocal<T>();

 public static T Store(T val)
 {
 _asyncLocal.Value = val;
 return _asyncLocal.Value;
 }

 public static T? Retrieve()
 {
 return _asyncLocal.Value;
 }
}

AsyncStorage sınıfına type olarak vereceğimiz Correlation sınıfını, aşağıdaki gibi tanımlayarak Id property’sinde CorrelationId değerini barındıracağız.


namespace Order.API.Filters.Correlation;

/// <summary>
/// It holds the CorrelationId value that comes with HTTP requests and events handled via MassTransit.
/// </summary>
public class Correlation
{
 public Guid Id { get; init; }
}

CorrelationId değerini yapılan istek boyunca erişebileceğimiz bir konumda sakladığımıza göre, şimdi gelen isteklerde araya girerek header’lardan CorrelationId değerini çekelim. Microservice mimarisinde geliştirilen uygulamalarda servisler arasında sadece HTTP değil, aynı zamanda event tabanlı yöntemlerle iletişim kurulabiliyor. Ancak bu şekilde başlatılan isteklerde, CorrelationId değerini HTTP header’larında değil, MassTransit tarafından sağlanan header değerlerinde taşıyacağız.

Filters for CorrelationId

CorrelationMiddleware

Gelen HTTP isteklerinde araya girecek ve CorrelationId HTTP header’ından değeri alacak olan CorrelationMiddleware sınıfımızı aşağıdaki gibi tanımlıyoruz. Eğer headerda değer varsa ilk önce Serilog tarafından sağlanan LogContext sınıfına bu değeri ayrı bir field olarak koyarak bir nevi enrich işlemi yapıyoruz. Daha sonra AsyncStorage sınıfımıza Correlation sınıfını vererek CorrelationId değerini saklıyoruz. Bu sayede gelen isteklerde CorrelationId değerini alıp, giden isteklerde bu değeri kullanabileceğiz.


namespace Order.API.Filters.Correlation;

/// <summary>
/// When the Http request is made, it takes the CorrelationId value from the HttpContext Header and sets the Correlation.Id value.
/// </summary>
public class CorrelationMiddleware
{
 private readonly RequestDelegate _next;

 public CorrelationMiddleware(RequestDelegate next)
 {
 _next = next;
 }

 public async Task InvokeAsync(HttpContext context, Correlation correlation)
 {
 var correlationIdHeader = context.Request.Headers["CorrelationId"];

 if (!string.IsNullOrWhiteSpace(correlationIdHeader))
 {
 var correlationId = Guid.Parse(correlationIdHeader.ToString());

 LogContext.PushProperty("CorrelationId", new ScalarValue(correlationId));

 AsyncStorage<Correlation>.Store(new Correlation
 {
 Id = correlationId
 });
 }

 await _next(context);
 }
}

Bu middleware’i uygulamamıza eklemek için Progam.cs içerisinde aşağıdaki gibi düzenliyoruz.


var builder = WebApplication.CreateBuilder(args);

//...

var app = builder.Build();

app.UseMiddleware<CorrelationMiddleware>();

//...

app.Run();

CorrelationConsumeFilter

Eğer servisimize gelen istek HTTP değil, event ile tetiklenen bir istek ise ortada bir HTTP headerı olmayacaktır. Bu sebeple MassTransit tarafından sağlanan header değerlerinden CorrelationId değerini almak için CorrelationConsumeFilter sınıfımızı aşağıdaki gibi tanımlıyoruz. Bu sınıfımızda IConsumer ile imzalanan sınıflarda consume işlemi gerçekleştirilmeden önce, gelen eventlerde araya girerek CorrelationId değerini alıp, LogContext ve AsyncStorage<Correlation> içerisine ekliyoruz.


namespace Order.API.Filters.Correlation;

/// <summary>
/// It is triggered when there is an event consumed by MassTransit and sets the CorrelationId value to the Correlation class.
/// </summary>
public class CorrelationConsumeFilter<T> : IFilter<ConsumeContext<T>> where T : class
{
 public Task Send(ConsumeContext<T> context, IPipe<ConsumeContext<T>> next)
 {
 var correlationIdHeader = context.CorrelationId;

 if (correlationIdHeader.HasValue)
 {
 var correlationId = correlationIdHeader.Value;

 LogContext.PushProperty("CorrelationId", new ScalarValue(correlationId));

 AsyncStorage<Correlation>.Store(new Correlation
 {
 Id = correlationId
 });
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

Bu şekilde gelen isteklerde AsyncStorage<Correlation> içerisinde tuttuğumuz Correlation değerimizi, yapılacak olan event isteklerinde ilgili header alanlarına eklemek için neler yapabileceğimizi inceleyelim.

CorrelationPublishFilter

MassTransit tarafından sağlanan IPublishEndpoint ile publish edilen eventlerde araya girecek olan CorrelationPublishFilter sınıfımızı aşağıdaki gibi tanımlıyoruz. Bu sınıfımız, publish edilen eventlerde araya girerek AsyncStorage<Correlation> içerisinden CorrelationId değerini alıp, MassTransit’in CorrelationId header değerine ekleyecektir.


namespace Order.API.Filters.Correlation;

/// <summary>
/// Sets the CorrelationId value of events published via MassTransit.
/// </summary>
public class CorrelationPublishFilter<T> : IFilter<PublishContext<T>> where T : class
{

 public Task Send(PublishContext<T> context, IPipe<PublishContext<T>> next)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 context.CorrelationId = Guid.Parse(correlation.Id.ToString()!);
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

CorrelationSendFilter

Eğer MassTransit’e gönderilen event publish edilmemiş ve request/response yapısı ile IRequestClient<T> kullanılarak gönderildiyse CorrelationPublishFilter değil CorrelationSendFilter sınıfımız araya girecek. Bu sınıfımızda send edilen eventlerde araya girerek AsyncStorage<Correlation> içersinden CorrelationId değerini alıp, MassTransit’in CorrelationId header değerininin içerisine ekliyoruz.


namespace Order.API.Filters.Correlation;

/// <summary>
/// Sets the CorrelationId value of events sent via MassTransit.
/// </summary>
public class CorrelationSendFilter<T> : IFilter<SendContext<T>> where T : class
{
 public Task Send(SendContext<T> context, IPipe<SendContext<T>> next)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 context.CorrelationId = Guid.Parse(correlation.Id.ToString());
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

CorrelationConsumeFilter, CorrelationPublishFilter ve CorrelationSendFilter sınıflarımızı uygulamamıza eklemek için aşağıdaki gibi ConfigureServices sınıfımızı tanımlayıp bu methodu Program.cs içerisinde kullanıyoruz.


public static class ConfigureServices
{
 public static WebApplicationBuilder AddMassTransit(this WebApplicationBuilder builder, IConfiguration configuration)
 {
 var messageBroker = builder.Configuration.GetSection("MessageBroker");
 builder.Services.AddMassTransit(cfg =>
 {
 cfg.SetKebabCaseEndpointNameFormatter();

 cfg.AddConsumers(Assembly.GetExecutingAssembly());

 cfg.UsingRabbitMq((context, config) =>
 {
 config.UseSendFilter(typeof(CorrelationSendFilter<>), context);
 config.UsePublishFilter(typeof(CorrelationPublishFilter<>), context);
 config.UseConsumeFilter(typeof(CorrelationConsumeFilter<>), context);

 config.Host(messageBroker["Host"], messageBroker["VirtualHost"], h =>
 {
 h.Username(messageBroker["Username"]!);
 h.Password(messageBroker["Password"]!);
 });

 config.ConfigureEndpoints(context);
 });
 });

 return builder;
 }
}


var builder = WebApplication.CreateBuilder(args);

builder.AddMassTransit(builder.Configuration);

// ...

var app = builder.Build();

// ...

app.Run();

CorrelationHeaderHandler

Eğer servisimizden yapılan istek event değil HTTP isteği ise IHttpClientFactory ile oluşturacağımız HttpClient sınıfımızdan yapacağımız isteklerde araya girecek olan CorrelationHeaderHandler sınıfımızı aşağıdaki gibi tanımlıyoruz. Bu sınıfımızda uygulamamızdan yapılan HTTP isteklerinde araya girerek AsyncStorage<Correlation> içersinden CorrelationId değerini alıp, HTTP header olarak ekliyoruz.


/// <summary>
/// Middleware to be used in requests made with HttpClient. Adds the CorrelationId header to the requests made.
/// </summary>
public class CorrelationHeaderHandler : DelegatingHandler
{
 protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 request.Headers.Add("CorrelationId", correlation.Id.ToString());
 }

 return await base.SendAsync(request, cancellationToken);
 }
}

Bu middleware’i uygulamamıza eklemek için Progam.cs içerisinde aşağıdaki gibi Named Http Client tanımlayıp AddHttpMessageHandler ile yapılacak isteklerde araya girecek olan middleware’i ekliyoruz.


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTransient<CorrelationHeaderHandler>();

builder.Services.AddHttpClient("Inventory", c =>
 {
 c.BaseAddress = new Uri("http://localhost:5053");
 })
 .AddHttpMessageHandler<CorrelationHeaderHandler>();;

// ...

var app = builder.Build();

// ...

app.Run();

Oluşturduğumuz Named Http Client için kullanımı aşağıdaki gibi yapıyoruz. Burada yapacağımız isteklerin async olmazsa middleware araya giremiyor.


public class InventoryService : IInventoryService
{
 private readonly IHttpClientFactory _httpClientFactory;

 public InventoryService(IHttpClientFactory httpClientFactory)
 {
 _httpClientFactory = httpClientFactory;
 }

 public async Task RemoveStockAsync(string productId, int quantity)
 {
 var httpClient = _httpClientFactory.CreateClient("Inventory");

 var response = await httpClient.PostAsync($"remove-stock/{productId}/{quantity}", null);

 response.EnsureSuccessStatusCode();
 }
}

Bu makalede, HTTP ve RabbitMQ kullanarak .NET microservice mimarisinde dağıtık izlenebilirliği artırmak için CorrelationId’yi nasıl etkili bir şekilde kullanabileceğimizi inceledik. Middleware ve Filter yapılarından yararlanarak, farklı servisler arasında CorrelationId’yi yayarak header değerlerini manipüle edebildik ve Serilog’un LogContext framework’ü ile kapsamlı loglama ve izleme sağladık.

CorrelationId’yi hem HTTP isteklerinde hem de MassTransit tarafından sağlanan event tabanlı iletişimde nasıl ele alacağımızı gösterdik. HTTP için CorrelationMiddleware ve CorrelationHeaderHandler sınıflarını; event tabanlı iletişim için ise CorrelationConsumeFilter, CorrelationPublishFilter ve CorrelationSendFilter sınıflarını uygulayarak, CorrelationId’nin bir isteğin tüm yaşam döngüsü boyunca tutarlı bir şekilde taşınmasını sağladık. Bu, işlem akışının net bir şekilde izlenmesini sağladı ve performans veya akış sorunlarını belirlemeye yardımcı oldu.

AsyncLocal sınıfıyla birlikte AsyncStorage<Correlation> kullanımı, CorrelationId değerini farklı kapsamlar arasında saklamak ve almak için güvenilir bir yol sağladı ve Dependency Injection ve asenkron işlemeyle ilgili zorlukları ele aldı.

Umarım bu rehber, kendi microservice mimarinizde sağlam bir dağıtık izleme çözümü uygulamanıza yardımcı olur. Daha detaylı örnekler için, GitHub reposunu inceleyebilirsiniz:

GitHub - berkslv/lecture-correlation-id-microservices

Kaynaklar

AsyncLocal sınıfnın doğru kullanımı için yararlandığım kaynak:

https://medium.com/@mbearz/how-to-log-everything-using-middleware-and-httpclient-handler-42b8f628fe84

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

.NET Geliştiricisi Perspektifinden API Gateway Alternatifleri: YARP, Ocelot, Kong, APISIX ve KrakenD

Mon, 20 May 2024 00:00:00 +0300

API Gateway servislerini microservice mimarisinde servislerimizi dış dünyaya açarken bir ara katman olarak kullanabiliyoruz. Bu yazımızda kısaca API Gateway nedirden bahsedip sonrasında kullanabileceğimiz .NET, OpenResty ve Go tabanlı API Gateway alternatiflerinden performans testleri ile beraber bahsedip sonlandıracağız.

GitHub - berkslv/lecture-api-gateway-comparison

API Gateway nedir?

API Gateway, sistemlerimize aşağıdaki gibi bir giriş noktası sağlarak dış dünyadan izole eder. İçerisinde her bir alt serviste tekrar tekrar implemente edilmesi gereken yetkilendirme, loglama, Rate limiting gibi ortak sorunları tek bir servis ile çözer.

İstekleri yönlendirirken url ve body bilgilerinde hatta protokollerinde dönüşümler uygulayabilirler, http bir isteği alt servislere daha performanslı olması için gRPC protokolü ile iletebilirler. Gelen istekleri yönlendirecekleri servislerin adresini bulmak için flat file veya veritabanlarından yararlanabilirler.

Seçenekler nelerdir

Sistemlerimizde kullanabileceğimiz API Gateway alternatiflerini değerlendirirken, gereken özelleştirme miktarı, performans, dağıtık mimariye uygunluk ve admin paneli üzerinden route bilgilerini güncelleme gibi ihtiyaçları değerlendirip uygun kararı vermemiz gerekir. Tüm bu özellikleri içerisinde barındıran, tüm ihtiyaçlarımızı tek seferde çözen bir gateway ürünü maalesef yok, bu değerlendirmeleri sistemimizin özel ihtiyaçlarına göre yapmamız gerekiyor.

İlk olarak .NET tabanlı, C# ile özelleştirilebilen YARP ve Ocelot API gateway ürünlerini inceleyip, OpenResty yani ngnix ve lua ikilisini beraber kullanan Kong ve Apache APISIX’den bahsettikten sonra son olarak cloud native ortamdada sıklıkla kullanılan Go ile geliştirilmiş KrakenD’yi inceleyeceğiz. Tüm bu seçenekler open source olarak ücretsiz bir şekilde kullanılabilir, ancak Kong, Apache APISIX ve KrakenD seçeneklerinde gerektiğinde enterprise desteğide alabiliriz.

Seçeneklerimizi değerlendirmeye geçmeden önce 1 saniye bekleyerek veritabanı sorgularını simule eden çok basit bir .NET API servisi geliştirdim, bu servisi API Gateway’in arkasına aldıktan sonra isteklerimizi yönlendirmeye çalışacak ve basit bir performans aracı olan Apache Benchmark kullanarak performans testlerimizi yapacağız. Kaynak tüketimini daha yakından inceleyebilmek için bu uygulamayı diğer gateway’lerle beraber docker compose ile çalıştırıp service:8080 adresinden isteklerimize cevap alacağız.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();
}

app.MapGet("/weather", () =>
{
 Task.Delay(1000).Wait();

 return "Weather is OK!";
})
.WithName("GetWeather")
.WithOpenApi();

app.Run();

.NET Based

.NET developerları olarak genellikle aklımıza ilk gelen çözüm yine .NET teknolojileri ile geliştirilebilen YARP ve Ocelot API Gateway’den bahsederek seçeneklerimizi incelemeye başlayabiliriz. Bu seçenekler performans olarak çok basit senaryolarda diğer rakipleriyle yarışabilirken, kaynak tüketimi ve admin dashboard gibi kompleks ihtiyaçlara cevap veremiyorlar.

YARP

Microsoft’un geliştirdiği YARP (Yet Another Reverse Proxy), bir reverse proxy ürünü olarak öne çıkıyor ve API Gateway olarak da kullanılabiliyor. Microsoft’un GitHub’da yayınladığı eShop örnek microservice projelerinde API Gateway olarak kullanıldığı için benim dikkatimi çekmişti. YARP, load balancing desteği sunuyor ve birden fazla servis olduğunda bu servislerin adreslerini service discovery yöntemleriyle alarak istekleri round robin gibi algoritmalarla bu servislere iletebiliyor. .NET tabanlı olması sebebiyle standart .NET API projelerinde kullanılabilen yetkilendirme, rate limiting, distributed tracing, loglama gibi işlemler de kolayca ve aşina olduğumuz yöntemlerle uygulanabiliyor. Ayrıca, middleware eklemesi ile özelleştirmeler yapılabiliyor, HTTP isteklerini gRPC isteklerine dönüştürebiliyor.

YARP projesi oluşturmak için bir .NET web api projesi oluşturulduktan sonra Yarp.ReverseProxy paketini uygulamaya dahil edip, gerekli konfigürasyonları yaptıktan sonra istekleri yönlendirmek için hazırız.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
 .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();
app.Run();

// appsettings.json
{
 "ReverseProxy": {
 "Routes": {
 "weaher_route": {
 "ClusterId": "weather_api",
 "Match": {
 "Path": "/weather"
 }
 }
 },
 "Clusters": {
 "weather_api": {
 "Destinations": {
 "destination1": {
 "Address": "http://service:8080"
 }
 }
 }
 }
 },
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*"
}

Ocelot

Ocelot, YARP ile birçok ortak özelliğe sahip bir API Gateway çözümüdür. .NET API projelerinde kullanılabilecek tüm özellikleri yine buradada kullanabiliriz, bağımsız bir open source projesi olarak geliştiriliyor. Ocelot, YARP’a kıyasla direk olarak API Gateway ürünü olarak kendisini konumlandırıyor. Farklı olarak, gRPC desteği bulunmamakla birlikte request aggregation gibi özellikler sunuyor. Bu özellik, backend for frontend yapılarında tercih edilebiliyor.

Ocelot uygulaması oluşturmak için benzer şekilde bir .NET API projesi oluşturulur ve Program.cs içerisindeki konfigurasyonlarla birlikte servis konfigürasyonları appsettings.json değil ayrı bir ocelot.json dosyasından okunacak şekilde ayarlanır. Ocelot ile route tanımlarını yaparken servis adreslerini tekrar tekrar vermemiz gerekiyor, YARP ile bunu tek bir yerden verip oluşturduğumuz servisin bilgisini router içerisinde belirtmemiz yeterliydi. Request aggregation işleminide route tanımlamalarından sonra aggregates kısmında yapabiliriz. Daha kompleks ihtiyaçlar için ise IDefinedAggregator interface’inden yararlanılarak özel aggregate’ler tanımlayabiliyoruz.

// Program.cs
using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();
await app.RunAsync();

// ocelot.json
{
 "Routes": [
 {
 "DownstreamPathTemplate": "/weather",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "service",
 "Port": 8080
 }
 ],
 "UpstreamPathTemplate": "/weather",
 "UpstreamHttpMethod": [ "Get" ]
 }
 ],
 "GlobalConfiguration": {
 "BaseUrl": "https://service:8080"
 }
 }

YARP vs Ocelot

Ocelot ve YARP teknolojilerinin karşılaştırılması için hazırladığım tabloda görebileceğiniz üzere çoğu özellikte ortaklar. Burada iki teknoloji arasında tercih sebebimiz destekledikleri özellikler, community desteği ve konfigurasyon dosyasının yapısı olabilir diye düşünüyorum.

Özellik	YARP	Ocelot
Routing & Request mapping	Var	Var
Authn & Authz	Var	Var
Rate limiting	Var	Var
Load balancing	Var	Var
gRPC	Var	Yok, Eski paketler mevcut
Request aggregation	Yok, Özel geliştirme gerekiyor	Var, Basit ise konfigurasyon ile yapılabilir
Distributed tracing
Var	Var

Mac M1 8GB özelliklere sahip makinede, docker üzerinde çalışan ortamda, sadece tek bir endpointin olduğu çok basit bir senaryoda performans testlerimiz için 10 bin adet isteği, 50 concurrent channel üzerinden Apache Benchmark aracı ile ilettim. Ocelot ortalama 1030 ms, YARP ortalama 1029 ms cevap süresi ile hemen hemen aynı sonucu verdiler. Tüketim için 20MB hafıza tüketimi ile başlarken, istekler gelmeye başlayınca maksimum 100MB tüketime kadar yükseldi, CPU için ise %10 - %20 arasında değişkenli gösteren bir tüketim oldu. Bu oranlar YARP ve Ocelot için hemen hemen aynı. Testleri yaptığım komutlarda şu şekilde:

# YARP
# 100 MB RAM | %10 - %20 CPU

ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.561 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1470000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.18 [#/sec] (mean)
Time per request: 1037.804 [ms] (mean)
Time per request: 20.756 [ms] (mean, across all concurrent requests)
Transfer rate: 6.92 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 2
Processing: 1002 1029 122.9 1015 2961
Waiting: 1002 1028 122.9 1015 2961
Total: 1002 1029 123.0 1016 2962

Percentage of the requests served within a certain time (ms)
 50% 1016
 66% 1019
 75% 1021
 80% 1023
 90% 1028
 95% 1033
 98% 1052
 99% 1517
 100% 2962 (longest request)

# Ocelot
# 100 MB RAM | %10 - %20 CPU

ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.739 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1470000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.14 [#/sec] (mean)
Time per request: 1038.695 [ms] (mean)
Time per request: 20.774 [ms] (mean, across all concurrent requests)
Transfer rate: 6.91 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 2
Processing: 1001 1030 120.0 1016 3347
Waiting: 1001 1030 119.9 1016 3347
Total: 1001 1030 120.0 1016 3349

Percentage of the requests served within a certain time (ms)
 50% 1016
 66% 1020
 75% 1023
 80% 1025
 90% 1032
 95% 1040
 98% 1061
 99% 1359
 100% 3349 (longest request)

OpenResty tabanlı

Temellerinden yüksek performansı ile adını duyuran ngnix ve onun üzerine LuaJIT ile script dili olarak esnek bir geliştirme ortamı sunan ve JIT desteği yeniden başlatmaya gerek kalmadan hot reload özelliğini destekleyen Lua kullanılabiliyor. Lua dili çoğu senaryoda içerdiği C API’ı sayesinde C kadar yüksek performans sunarken aynı zamanda script dili olduğu için daha yüksek seviyede bir programlama ile, daha geliştirici dostu yapısıyla daha esnek geliştirme yapmaya olanak sağlıyor. C kodundan Lua kodunu veya Lua kodundan C kodunu çağırmakta mümkün, bu sebeplerden ötürü, beraber kullanılabilen güzel bir ikili ortaya çıkmış oluyor. Hatta C ve Lua ikilisi Cloudflare’in kendi araçları içinde kullandığı bir stack, yani networking uygulamarındada sıklıkla kullanılıyor.

Bahsettiğim OpenResty temeline sahip gatewaylerdende sektörde çok sık tercih edilen ve ismini duyuran Kong, sonrasında tamamen open source olduğu için dikkat çeken ve kong’dan birkaç güzel özellikle sıyrılmayı başaran Apache APISIX’den bahsedip Go tabanlı gatewaylerle devam edeceğiz.

Kong

Kong, API gateway çözümleri arasında öne çıkan bir araçtır. Ocelot ve YARP gibi araçlarda bulunan tüm özellikleri içermesinin yanı sıra, 60’tan fazla plugin desteği ile ek özellikler sunar. Ayrıca, Lua veya diğer programlama dilleri ile kendi pluginlerinizi geliştirebilirsiniz. Enterprise versiyonu, GraphQL desteği, request validation, body güncelleme ve secret manager gibi ekstra özellikler sağlar.

Kong, bir API gateway’den beklenebilecek yetkilendirme, loglama, request transformation ve rate limiting gibi çoğu özelliği içerir. Ancak, request aggregation pattern (tek bir istekle birden fazla servisten dönen cevabı birleştirme) gibi bazı özellikler için ek geliştirme yapılması gerekir. Native olarak kullanılabilen ve diğer alternatiflerden daha iyi çalışacak olan Lua dışında Go, JavaScript veya Python ile IPC (Inter Process Communication) desteği sayesindede geliştirme yapabiliriz ancak daha düşük bir performansla karşılaşacağız. Bununla birlikte, WebAssembly desteği sayesinde Go ve Rust dilleri ile IPC yöntemlerine gerek kalmadan aşina olduğumuz dillerle yüksek performanslı pluginler oluşturabiliyoruz.

Ocelot ve YARP gibi .NET tabanlı gateway’lerden farklı olarak, Kong farklı deployment seçenekleri sunuyor. “DB-less” mod ile, konfigurasyon dosyaları üzerinden yönetim yapılabilir. Bu mod, CI/CD tabanlı deployment senaryolarında oldukça kullanışlıdır ve state farklılıklarından kaynaklanabilecek sorunları önler.

Kong, ayrıca traditional olarak adlandırılan yöntemle veritabanı kullanarak da yapılandırılabilir. Bu yöntemde, PostgreSQL, Cassandra, Redis, InfluxDB ve Kafka gibi veritabanları kullanılabilir. Admin API üzerinden route ve service bilgileri üzerinde değişiklikler yapılabilir. Ancak, bu senaryo veritabanına ek bir bağımlılık yaratır ve control plane ile data plane aynı instance üzerinde çalıştığı için saldırılara karşı daha korunaksız olabilir.

Konnect servisi sayesinde uygulayabildiğimiz deployment senaryosu ile data plane ve control plane kısımlarını birbirinden ayırarak daha güvenli bir yapıya sahip oluyoruz. Konnect, Kong tarafından software as a service olarak sunuluyor ve state yönetimi için ekstra bir veritabanı bağımlılığı gerektirmiyor.

Eğer Kong tarafından yönetilen bir ürünü kullanmak istemiyorsak, tüm sürecin kendi iç network ağımız üzerinde yapılmasını istiyorsak Hybrid mod olarak isimlendirilen yöntem ile control plane ve veritabanı, data plane’den ayrı olarak sistemimizin, birbiri ile iletişime geçebilecekleri farklı bir konumuna deploy edilerek, data plane’i kontrol etmek için kullanılabiliyor

Local olarak geliştirme yapmak için, Kong’un sunduğu Docker Compose dosyası sayesinde PostgreSQL ile beraber çalışabilirsiniz ve ilk çalıştırmada bu dosyadan okuma yapılır. Eğer Db-less modda çalışacaksak, tüm route’larınızı bir konfigurasyon dosyasında tanımlamanız gerekir. Aşağıdaki gibi konfigurasyon tanımını yaptıktan sonra Docker compose dosyamız ile gateway’imizi ayağa kaldırıyoruz.

# kong.yaml
# a very minimal declarative config file
_format_version: "2.1"
_transform: true

services:
 - name: weather-service
 url: http://host.docker.internal:8080
 routes:
 - name: get-weather
 paths:
 - /weather

# docker-compose.yml
 # ...
 kong:
 image: "${KONG_DOCKER_TAG:-kong:latest}"
 user: "${KONG_USER:-kong}"
 environment:
 <<: *kong-env
 KONG_ADMIN_ACCESS_LOG: /dev/stdout
 KONG_ADMIN_ERROR_LOG: /dev/stderr
 KONG_PROXY_LISTEN: "${KONG_PROXY_LISTEN:-0.0.0.0:8000}"
 KONG_ADMIN_LISTEN: "${KONG_ADMIN_LISTEN:-0.0.0.0:8001}"
 KONG_ADMIN_GUI_LISTEN: "${KONG_ADMIN_GUI_LISTEN:-0.0.0.0:8002}"
 KONG_PROXY_ACCESS_LOG: /dev/stdout
 KONG_PROXY_ERROR_LOG: /dev/stderr
 KONG_PREFIX: ${KONG_PREFIX:-/var/run/kong}
 KONG_DECLARATIVE_CONFIG: "/opt/kong/kong.yaml"
 secrets:
 - kong_postgres_password
 networks:
 - kong-net
 ports:
 # The following two environment variables default to an insecure value (0.0.0.0)
 # according to the CIS Security test.
 - "${KONG_INBOUND_PROXY_LISTEN:-0.0.0.0}:8000:8000/tcp"
 - "${KONG_INBOUND_SSL_PROXY_LISTEN:-0.0.0.0}:8443:8443/tcp"
 # Making them mandatory but undefined, like so would be backwards-breaking:
 # - "${KONG_INBOUND_PROXY_LISTEN?Missing inbound proxy host}:8000:8000/tcp"
 # - "${KONG_INBOUND_SSL_PROXY_LISTEN?Missing inbound proxy ssl host}:8443:8443/tcp"
 # Alternative is deactivating check 5.13 in the security bench, if we consider Kong's own config to be enough security here

 - "127.0.0.1:8001:8001/tcp"
 - "127.0.0.1:8444:8444/tcp"
 - "127.0.0.1:8002:8002/tcp"
 healthcheck:
 test: [ "CMD", "kong", "health" ]
 interval: 10s
 timeout: 10s
 retries: 10
 restart: on-failure:5
 read_only: true
 volumes:
 - kong_prefix_vol:${KONG_PREFIX:-/var/run/kong}
 - kong_tmp_vol:/tmp
 - ./config:/opt/kong
 security_opt:
 - no-new-privileges
 # ...


KONG_DATABASE=postgres docker compose --profile database up -d

Kong ile başarılı bir deployment yaptıktan sonra, belirttiğiniz route ve service bilgilerine yapılan istekler yönlendirilir. Tradational veya hybrid mod ile deployment yaptıysanız, bir admin arayüzü üzerinden servis ve endpoint bilgilerinizi yönetebilirsiniz.

Apache APISIX

Apache APISIX, Kong gibi OpenResty üzerine geliştirilmiş bir gateway ürünüdür. Ancak, Kong’un sadece enterprise versiyonunda bulunan özellikleri open source olarak sunarak öne çıkıyor. Bu özellikler arasında GraphQL, Canary release ve secret management gibi özellikler yer alıyor.

APISIX, yüksek sayıda route içeren sistemlerde Kong’a kıyasla daha yüksek performans sunuyor. Kong, route’lar arasında traversal search algoritması kullanırken, APISIX radixtree algoritması ile arama yapar ve plugin kullanılmadığında %140 daha yüksek performans sağlar. Ayrıca, APISIX, konfigurasyonlarını depolamak için etcd veritabanını kullanır. Bu veritabanı, cloud native çalışabilen ve kubernetes ortamında yaygın olarak kullanılan bir veritabanıdır.

APISIX, üç farklı deployment senaryosu sunar:

Traditional Yöntem: Control plane ve data plane aynı instance içerisinde veritabanına bağımlı olarak deploy edilir.
Decoupled Yöntem: Control plane ve data plane farklı instancelar ile deploy edilir ve sadece control plane veritabanına bağımlıdır.
Standalone Yöntem: Veritabanı kullanmadan konfigurasyon dosyasından okuma yaparak çalışır.

Local testlerimde, etcd veritabanı ile traditional yöntem kullanarak Docker Compose üzerinden deployment işlemi gerçekleştirdim. APISIX’in docker repositorysinde bulunan Docker Compose dosyasını küçük değişiklikler yaparak kullandım. Admin key’leri kullanarak Admin API’ya istek atabiliyoruz. Eğer standalone yöntemle deploy edecek olsaydım, route’ları yaml dosyasında tanımlamam gerekecekti.

Eğer enterprise destek almak istenirse, APISIX’in geliştirici takımı tarafından yürütülen API7 üzerinden destek alınabilir.

Docker Compose dosyalarını ve kullandığım kodları blog yazısının sonunda paylaşacağım, böylece siz de kendi localinizde hızlıca deneyimleyebilirsiniz.

APISIX’in performans testlerinde, 1025 milisaniye ortalama cevap süresiyle, 1032 milisaniye ortalama cevap süresine sahip olan Kong’dan daha performanslı olduğu görülebiliyor. Tüketim olarak, Kong çalışır çalışmaz 280MB civarında bellek kullanırken, APISIX 100MB civarında bellek kullanmaktadır. Her iki gateway de %5-10 arasında değişen CPU tüketim oranına sahip.

# Kong
# 280MB RAM | %5 - %10 CPU
ab -k -n 10000 -c 50 http://localhost:8000/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 8000

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.499 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 2730028 bytes
HTML transferred: 140000 bytes
Requests per second: 48.19 [#/sec] (mean)
Time per request: 1037.494 [ms] (mean)
Time per request: 20.750 [ms] (mean, across all concurrent requests)
Transfer rate: 12.85 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.2 0 4
Processing: 1002 1032 120.5 1018 3369
Waiting: 1002 1031 120.5 1018 3369
Total: 1002 1032 120.7 1019 3373

Percentage of the requests served within a certain time (ms)
 50% 1019
 66% 1023
 75% 1026
 80% 1028
 90% 1034
 95% 1043
 98% 1066
 99% 1326
 100% 3373 (longest request)

# APISIX
# 100MB RAM | %5 - %10 CPU
ab -k -n 10000 -c 50 http://localhost:9080/weather

Server Software: APISIX/3.9.0
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 206.130 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1520000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.51 [#/sec] (mean)
Time per request: 1030.650 [ms] (mean)
Time per request: 20.613 [ms] (mean, across all concurrent requests)
Transfer rate: 7.20 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.2 0 7
Processing: 921 1025 126.2 1012 3376
Waiting: 921 1024 126.2 1011 3375
Total: 921 1025 126.3 1012 3378

Percentage of the requests served within a certain time (ms)
 50% 1012
 66% 1015
 75% 1017
 80% 1018
 90% 1023
 95% 1029
 98% 1047
 99% 1327
 100% 3378 (longest request)

Go Tabanlı alternatifler

Go tabanlı API Gateway alternatifi olarakta en çok öne çıkan, KrakenD ürününü ele alacağız, ancak Go ile ikinci bir alternatif olarak Tyk veya Traefik API Gateway gibi seçeneklerde tercih edilebilir, ancak bu ikiside ücretli olarak sunulduğu için deneme yapamadığımdan bu anlatımda yer veremiyorum.

KrakenD

KrakenD, Go ile geliştirilmiş ve hem community hem de enterprise versiyonlarına sahip bir API gateway ürünü. 2021 yılında Linux Foundation’a bağışlanmış olan Lura engine üzerinde çalışır. Diğer API gateway ürünlerine kıyasla güçlü bir aggregation sistemi sunar. Kod yazmadan, sadece konfigurasyon dosyaları ile tüm aggregation işlemlerini gerçekleştirebilirsiniz.

KrakenD, veritabanı kullanmadığı için, deployment seçenekleri arasında karar verirken kafa karışıklığı yaşatmaz, sadece konfigurasyon dosyalarını kullanarak işlemlerimizi gerçekleştirebiliriz. Ancak, veritabanı kullanmadığı için bir admin paneli bulunmamaktadır. Veritabanı olmaması, ek hata kaynaklarını ortadan kaldırır ve daha kolay ölçeklenebilirlik sağlar.

Tüm konfigurasyonlar, git ile takip edilebilecek bir konfigurasyon dosyası üzerinden yönetilir. JSON, YAML, TOML gibi farklı dosya formatlarını destekliyor. KrakenD’nin kendi websitesindeki arayüz ile konfigurasyonları hızlıca oluşturabiliriz. Local geliştirme ortamında, sadece konfigurasyon dosyası üzerinden çalıştığı için hızlıca ayağa kaldırabilir ve servisinize istek atabiliriz. Hot reload özelliği ile kısa bir downtime ile konfigurasyon dosyasını güncelleyebilirsiniz. Ancak, production ortamlarında bu yöntem önerilmez, GitOps yöntemleri ile yeni bir release almanız tavsiye edilir. Enterprise versiyonunda OpenAPI importer ve exporter, gzip sıkıştırma ve response validation gibi ek özellikler bulunur.

KrakenD, Kong ve APISIX’ten çok daha basit bir Docker Compose içeriğine sahiptir, çünkü herhangi bir ek bağımlılığı yoktur. Sadece konfigurasyon dosyasının path’ini volume olarak vermeniz yeterlidir. Örnek olması açısından weather servisini Docker Compose içerisine ekledim ve krakend.json dosyasını hızlıca oluşturarak servisi ayağa kaldırdım. Performans testinde çok iyi sonuçlar verdi.

// krakend.json
{
 "$schema": "https://www.krakend.io/schema/krakend.json",
 "version": 3,
 "name": "KrakenD - API Gateway",
 "timeout": "3000ms",
 "cache_ttl": "300s",
 "output_encoding": "json",
 "port": 9090,
 "endpoints": [
 {
 "endpoint": "/weather",
 "method": "GET",
 "output_encoding": "string",
 "backend": [
 {
 "url_pattern": "/weather",
 "encoding": "string",
 "sd": "static",
 "method": "GET",
 "host": [
 "http://service:8080"
 ],
 "disable_host_sanitize": false
 }
 ]
 }
 ]
}

# docker-compose.yml
version: '3'
services:
 krakend:
 image: devopsfaith/krakend
 ports:
 - 9090:9090
 volumes:
 - ./krakend.json:/etc/krakend/krakend.json
 networks:
 - krakend-net

 weather-service:
 container_name: service
 build: ../service/Service.API
 networks:
 - krakend-net
 ports:
 - "8080:8080"

networks:
 krakend-net:
 external: false

KrakenD, kendi websitesinde de belirttiği gibi, Kong ve APISIX’ten daha hızlı çalışıyor. Benzer test sonuçlarında, Kong ortalama 1032 milisaniye, APISIX ortalama 1025 milisaniye ile cevap verirken, KrakenD ortalama 1024 milisaniye ile en iyi performansı sunuyor. CPU tüketimi %4-6 civarında sabit kalırken en yüksek 30MB memory tüketiyor. Bu sonuçlar, KrakenD’nin diğer rakiplerinden daha az kaynak tükettiğini ve buna rağmen daha hızlı olduğunu gösteriyor.

# KrakenD
# 30MB RAM | %4 - %6 CPU
ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software:
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 206.359 seconds
Complete requests: 10000
Failed requests: 9
 (Connect: 0, Receive: 0, Length: 9, Exceptions: 0)
Non-2xx responses: 9
Keep-Alive requests: 10000
Total transferred: 2439352 bytes
HTML transferred: 139874 bytes
Requests per second: 48.46 [#/sec] (mean)
Time per request: 1031.795 [ms] (mean)
Time per request: 20.636 [ms] (mean, across all concurrent requests)
Transfer rate: 11.54 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 3
Processing: 1000 1024 122.7 1010 3021
Waiting: 1000 1024 122.7 1010 3021
Total: 1000 1024 122.8 1010 3023

Percentage of the requests served within a certain time (ms)
 50% 1010
 66% 1012
 75% 1013
 80% 1015
 90% 1018
 95% 1023
 98% 1037
 99% 1520
 100% 3023 (longest request)

Sonuç

İncelediğimiz 5 API gateway ürününü karşılaştırmak için aşağıdaki gibi bir tablo hazırladım. Bu tablo, sunumun içeriğin özetini oluşturuyor ve araştırmalarım sonucunda birkaç önemli noktayı vurgulamak istiyorum.

Kong ve APISIX

Eğer farklı projelere sahip takımlar, tek bir API gateway üzerinden internete açılacaksa ve canlı olarak güncellenebilen bir admin arayüzüne ihtiyaç duyuyorsa, Kong veya APISIX tercih edilebilir. Her iki gateway de güçlü özelliklere sahip ve genişletilebilir yapıları ile öne çıkıyorlar. Ayrıca, admin arayüzü sayesinde, konfigurasyonları yönetmek ve güncellemeleri canlı olarak yapmak mümkün.

KrakenD

Eğer API gateway projesi, takımların ortak sorumluluğunda ise ve geliştiriciler konfigurasyon dosyasını güncelleyip pipeline çalıştırabilirlerse, yüksek performans ve düşük kaynak tüketimi hedeflenen durumlarda, KrakenD iyi bir seçim olabilir. KrakenD, Go ile geliştirilmiş olup, güçlü bir aggregation sistemi sunar ve veritabanı kullanmadığı için daha kolay ölçeklenebilir.

Ocelot ve YARP

Performans ve kaynak tüketimi kritik değilse ve aşina olduğumuz bir teknoloji yeterliyse, .NET tabanlı Ocelot veya YARP ile yolumuza devam edebiliriz. Bu araçlar, benzer özellikleri farklı şekillerde destekliyorlar ve .NET ekosistemine entegrasyonları kolaydır.

Diğer Kriterler

Deployment Yöntemleri: Hangi gateway’in nasıl deploy edileceği, konfigurasyon dosyalarının yapısı ve düzenlenebilirliği önemlidir.
Community ve Enterprise Desteği: Gateway’in ne kadar geniş bir kullanıcı kitlesine sahip olduğu ve destek alabileceğimiz kaynakların bulunup bulunmadığı da karar verirken göz önünde bulundurulmalıdır.

Tüm ihtiyaçlarımıza tek başına kusursuz bir çözüm sunacak bir ürün maalesef yok. Bu nedenle, kendi ihtiyaçlarımızı değerlendirerek, seçeceğimiz aracın özelliklerine göre karar vermeliyiz. Doğru API gateway seçimi, projenizin başarısı için kritik bir adımdır ve ihtiyaçlarınıza en uygun olanı tercih etmek her zaman en iyi yaklaşımdır.

Feature	YARP	Ocelot	Kong	APISIX	KrakenD
Request aggregation	NO	Simple, can be done with configuration	NO	YES	Powerful,, can be done with configuration
OAuth & OpenID	YES	YES	YES	YES	YES
Request validation	Needs custom logic	Needs custom logic	Comes with enterprise	YES	YES
HTTP to gRPC	YES	NO	YES	YES	YES
Websocket	YES	YES	?	YES	Comes with enterprise
State	File	File	File, PostgreSQL, Cassandra, Redis, InfluxDB, Kafka	File, etcd	File
Plugin	C#	C#	Native: Lua & IPC: Go, Javascript, Python & WASM: Go, Rust vs.	Native: Lua & IPC: Go, Javascript, Python & WASM: Go, Rust vs.	Go & Lua
Performance	Mean response: 1029ms, Memory: 100MB, CPU: %10 - %20	Mean response: 1030ms, Memory: 100MB, CPU: %10 - %20	Mean response: 1035ms, Memory: 280MB, CPU: %5 - %10	Mean response: 1025ms, Memory: 100MB CPU: %5 - %10	Mean response: 1024ms, Memory: 30MB, CPU: %4 - %6

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

GitHub - berkslv/lecture-api-gateway-comparison

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

RSA ile JavaScript'te Şifreleme ve .NET'te Şifre Çözme Nasıl Yapılır

Thu, 07 Mar 2024 00:00:00 +0300

Dijital dünyada, farklı sistemler arasındaki iletişimin güvence altına alınması çok önemlidir. RSA şifreleme, iki adet anahtar kullanarak şifreleme ve şifre çözme için sağlam bir yol sağlar. Öte yandan, AES gibi simetrik şifreleme algoritmaları, şifreleme ve şifre çözme için tek bir anahtar kullanır. Bu nedenlerle, anahtarı halka açık olarak kullanmak ve hatta bir saldırganın eline geçse bile sorunları önlemek için asimetrik şifreleme algoritmalarından olan RSA tercih edilebilir.

Bu blog yazısında, OpenSSL ile RSA anahtar oluşturmayı, JavaScript’te şifrelemeyi ve .NET’te şifre çözmeyi, bir frontend uygulaması ile bir backend servisi arasında güvenli veri alışverişi sağlayacak uygulamayı ele alacağım.

Understanding RSA Encryption

RSA (Rivest-Shamir-Adleman), güvenli veri iletimi için yaygın olarak kullanılan ilk açık anahtarlı kriptosistemlerden biridir. İki anahtarı içerir: açık anahtar, mesajları şifrelemek için açıkça paylaşılabilen ve onları şifrelemek için gizli tutulması gereken bir özel anahtar. RSA’nın gücü, iki büyük asal sayının çarpımını faktörleme zorluğunda yatar, bu da güvenliğini destekler.

Generation of Public/Private key pairs with OpenSSL

RSA şifreleme ve şifre çözmenin uygulanmasındaki temel adımlardan biri, açık ve özel anahtar çiftlerinin oluşturulmasıdır. OpenSSL, kriptografi için sağlam bir açık kaynaklı araç olan bu anahtarları oluşturmanın basit bir yolunu sunar. Ancak, bu adım isteğe bağlıdır. .NET kütüphaneleri başarılı bir şekilde RSA anahtarları oluşturur. Ancak, bu gibi açık kaynaklı araçları kullanmak bize standartların güvencesini sağlar. Bu bölüm, OpenSSL’i kullanarak RSA açık/özel anahtar çifti oluşturma sürecini adım adım ele alacaktır.

Private anahtar oluşturma işlemiyle başlayabiliriz:

$ openssl genrsa -out privatekey.pem 2048

$ cat privatekey.pem
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDuOitcIPd5UpGN
/4GEwNhc4fAmGP6fREJJk/byRgiLiWcyXwdoPwXdXjKSjkSIcETdz/hLAlb6+zNY
Gi4Ap0S5flZSRiKh60xWRA4vZVgsLqhEi2IsclSlWu3R7KD5dkBGsyf5xlCfNSs4
DbYYMgrXXZxXQ0c4qCikpnEB6OpqSzm19Cwrdq9GwophoAPxnf00d7S+y5QpRa+l
Ca70xQ42FxBpMuK76a1g6i+JtmPgTYqXZ0FCMnUEzBq+u3N8LKoNzcSNdrLgvmHQ
oOLFA/9BPe34YgLxoCUi+HhEiLSnvgz/Kn1yprvsz37baYizU/YWFG8s80SPmFsY
JARxvZiJAgMBAAECggEAEboc42Jln+7Lu34NmIAUKZc7fE5EVjwpVZnP2Lfq510+
Y2JsZe64pEAf8cVp5qA6E6pn3scKC2uZZr8t+Kj5xXbX/A/RgGyGte2jA5ZeQQ1o
wo7/q3CHiXVyeHpMATwyLMCkoyLFeY9mi6mDiRniMiP6YAj22gmzWoszIhH/rZCO
NjdpWRsIkFp8jIiyRhhoaBoJtZ1qV3twk8HH590rgjS7QUGJWK9uUsi5SDh69MsR
r/SJ00gTMYFozFd6dB29aKj/p8fSk6qzh2noxU37AuiVc1A2H8Z6SAfRUDSvPkxA
FdqVr62iLWmypBX2VYQ2p1pH1N0v8oG7NTxtrxgRTQKBgQD3YdxKNT0dWZJRGPFC
DIRZVn86UgDAHRw29aToLARnepE5XOrLSmlGMqbK8vzRyUnlctJyG7x5ure2BMp4
gKSLuhz48n7ZvpHyCVnNsqqkc21iM/whL/yKiI11Jz5koXmRDltz9IioQH/PwXvD
RJbjxISHjG5YEKlVmztWtTup/QKBgQD2hqouE8JLePAUzK3SlfgVTlmaHDUeJev4
u95RWPnMNOOwLUWbGYiKBoJ8uc2nSHmxIvEvEPGNwafR6etf0YocpwDfF5pnPDjk
yA4hOdZrCyYa/UDqkB5pHTOZj5iVct1hBNbiANz6kL7Pl+H221U+HxD9rhaDPDez
gdYPhLF4fQKBgQCdi2QomlkufOHS5eiXoLMU1iI2eQzjTGawlaYM+iNf503fU05w
YxZCT3WroC3kSKXYC1T8uK9CcugWclyje4HPPpq+7GhesZ/unYfkmRlVm/EYbnTu
icnyS96Ssohou/FYsOULJrt1M4ZyQA1aoS7bJUclsAiB6zJ8Q1z57ndt3QKBgEwa
9p6S6wBxrWw+Y8sHETdCoNa6rotIGbkIBnIGjddE3KWe1EY1c7lomQ/4LEzgSvEs
YFivWmLwzeY32LoT7hc6V0KH/tqv9MBsIjCPsmoJXxIl7Mx9AWZh5XQaqHg6pa01
2UCcE5wm40EjGlcjDwXGgXBPNhP9mxSHmJXh2QfhAoGANouUrF3qv8ofb1HGrUXx
DO/WkGMzwbkNmwwdgcGYVsGr3Dv/zx1y3TJEvqNh0ViVgmfdYveCo3VrSawq890U
GJZXld2KFE1icEJpNoURkM9okZMzTDIMs+r4vq5Or2jB04mMuoCbG6rjfqUMtkll
oAIFOSKH+F3TrXjNgy4/juo=
-----END PRIVATE KEY-----

Başarıyla private anahtarı oluşturduktan sonra, oluşturduğumuz private anahtar ile public anahtarı oluşturabiliriz.

$ openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

$ cat privatekey.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7jorXCD3eVKRjf+BhMDY
XOHwJhj+n0RCSZP28kYIi4lnMl8HaD8F3V4yko5EiHBE3c/4SwJW+vszWBouAKdE
uX5WUkYioetMVkQOL2VYLC6oRItiLHJUpVrt0eyg+XZARrMn+cZQnzUrOA22GDIK
112cV0NHOKgopKZxAejqaks5tfQsK3avRsKKYaAD8Z39NHe0vsuUKUWvpQmu9MUO
NhcQaTLiu+mtYOovibZj4E2Kl2dBQjJ1BMwavrtzfCyqDc3EjXay4L5h0KDixQP/
QT3t+GIC8aAlIvh4RIi0p74M/yp9cqa77M9+22mIs1P2FhRvLPNEj5hbGCQEcb2Y
iQIDAQAB
-----END PUBLIC KEY-----

Setting Up the Environment for .NET RSA Decryption

.NET şifre çözme için .NET 8’i kullanacağım ve System.Security.Cryptography ad alanınından faydalanacağım. RSA şifre çözme için başka bir nuget paketine ihtiyacımız yoktur, bunun için şöyle bir Helper sınıf oluşturdum.

RsaKey’i appsettings.json dosyasından okuyoruz. RsaKey alanında yeni satırlar için \n eklemeniz gerekir. Bu anahtarı appsettings.json dosyasına koyduk çünkü her istekte aynı anahtarı kullanmak istiyoruz. Ancak .NET kütüphanesinin sorumluluğuna bırakırsanız, her başlangıçta yeni bir anahtar oluşturulacaktır.

// appsettings.json
{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*",
 "RsaKey": "-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCuan+y++Eqc2Vx3QIt9gv0r6rzfcxpsBRubcWCmI+8tqb40oflv5dViPSiCSWNgg5xKk7K8WTeEQQ6NDg1IJ2OwoQ2dfzat5qlpfV9EeF3u8iTY/hyQaaYFwB77cV9t5Czb8oG/+IIOByorJVds9tAoKjssKUZ3W9IU7ffElZjZrbjoiy/H4z8u9fOq8IL9Zf3pHgzv2FxF4BPJamqr4s1VtMqGJ5g18wV1OD9gcz9pJOHHUVieZ0+xP4WD4+1wCv/uwEgIcqmEs0os6birHZL1X/CSqBSPc8e/+kkZyyzoF+MBWPzvAwmW32alIxz2ZV0Z+jJtoOrh/qVqbrGAf+RAgMBAAECggEAEWYu4IJHg0ZZOZtgRwj7RtjKXzluraFi3GRHdoB1IFCBRiOsamMrO91qeAqdDCmL+saLbyvXEd8VMqA4djZPeWkWqt8ozwHPY9RzMZuZyCm7t9Zad71sWtI6mmJNF/46qWfOudWHbSX51+rFiMAzMFaGm3wAsFyaaBbv6gkohIhVrrMvpIuV8X8JNI8/VNlOR6vExHd/3uWKi8vPrFEFTNQ1UE+WJDkVojcmx0t63jlP8C/O4ofaJeCYRkAaM9+FXnM+jVNf0qZU+3JGYmy1R/B7L+LyrbG2uYTaBa1Ba9zGsXD1HQ4dctK+MltBd4p+MWgHAQV+xuVmGGDkylpb8QKBgQDP9zY4UzLmnt0werJF9SGmAJU51Y/+gannUC/+XYqnK/NA5iUDR86rlYCJbqQCceyMYJSYuePumygWOVL9rHnu1/fTMG/sXnRktmTSFemgeCYfPyn8/KeZKn6E5xw8GbtfLJLA8uM4DakDf9vSpilKDYT4UbZyKgq7/yodPXbgCQKBgQDWs4gL4yOtDLAY/OQKZvoyXClapldkVFRzf97pBJQGLYfdTzkVFviWsgI/yrA+t5tlzaWtZieuv2KsSmazVyO2W5ei9HILx4yRFK7K56OM5o7wqjN62ZmF0R+422YNaAyqYAd9nhLjgdsrmZ9FTxhQ91asBSH1AO3j6xaZUvh1SQKBgAZuo/ur/xgI89hrAxaM1WSYAgWO6Gw7wHCKF2HrrL0s69InDCAE2YyPDDGz/ViiA2n4FsB+h2E65UuCrGFyMzdC8MRUbDHIXhs7VPT2fopbDPrMblUHz3s6SD1+FG57cUMpUsSq/oIeUgrsqnTidMZ4kpNHm7f+OuTDqJ7M5t9ZAoGAAfm2570YR/BU8nXpNztJVAtLCh17sl2gRUvI5kX3grMKi/u9n7cNZH2Qzbt0sa8Iy///ZUAKX249Xy50EXRczMG8/G/ZWMhmP7N8BDvrYlGAwTAftyKnafbJnu7N2pO5ghvOFdbNf7BjLtyD/aRDqgMMlhqZ/GIczjsMgy6jQJkCgYATxkjdW/mnWLDDZAYm1V10Gnm7YDMwX3gKdhpoYleeeapZiDlurkR3YAEvQezcnhv3NpjaKQtF1/3Q0fZJ0wBc5FflaevHRjHTa0IrU5QIa48dLDx+jxn+cUCFx9kirkb7JcfJLZWtToPMLfCZt324P2ogZgWBwweVPiz1/voEXw==\n-----END PRIVATE KEY-----"
}

// Helpers/RsaEncryptionHelper.cs 
public class RsaEncryptionHelper
{
 private readonly RSA _rsa = RSA.Create();

 public RsaEncryptionHelper(IConfiguration configuration)
 {
 var privateKeyPem = configuration["RsaKey"];
 if (string.IsNullOrEmpty(privateKeyPem)) throw new ArgumentNullException(nameof(privateKeyPem));
 ImportKey(privateKeyPem);
 }


 public void ImportKey(string privateKey)
 {
 _rsa.ImportFromPem(privateKey.ToCharArray());
 }

 public string GetPublicKey()
 {
 var publicKey = _rsa.ExportSubjectPublicKeyInfoPem();
 return publicKey;
 }

 public string GetPrivateKey()
 {
 var privateKey = _rsa.ExportPkcs8PrivateKeyPem();
 return privateKey;
 }

 public string Encrypt(string data)
 {
 var dataBytes = Encoding.UTF8.GetBytes(data);
 var encryptedData = _rsa.Encrypt(dataBytes, RSAEncryptionPadding.OaepSHA256);
 return Convert.ToBase64String(encryptedData);
 }

 public string Decrypt(string data)
 {
 var dataBytes = Convert.FromBase64String(data);
 var decryptedData = _rsa.Decrypt(dataBytes, RSAEncryptionPadding.OaepSHA256);
 return Encoding.UTF8.GetString(decryptedData);
 }
}

Ve bu helper sınıfı EncryptionController içinde kullanarak helper sınıfın methodlarını kullanın. Production ortamlarında, PrivateKey’in kimseye açığa çıkarılmaması gerekir. Bu gizli tutulmalıdır.

// Controllers/EncryptionController.cs 
[ApiController]
[Route("api/[controller]")]
public class EncryptionController : ControllerBase
{
 private readonly RsaEncryptionHelper _rsaEncryptionHelper;

 public EncryptionController(RsaEncryptionHelper rsaEncryptionHelper)
 {
 _rsaEncryptionHelper = rsaEncryptionHelper;
 }

 [HttpPost("Encrypt")]
 public string Encrypt([FromBody] EncryptionRequest request)
 {
 return _rsaEncryptionHelper.Encrypt(request.Data);
 }

 [HttpPost("Decrypt")]
 public string Decrypt([FromBody] EncryptionRequest request)
 {
 return _rsaEncryptionHelper.Decrypt(request.Data);
 }

 [HttpGet("PublicKey")]
 public string PublicKey()
 {
 return _rsaEncryptionHelper.GetPublicKey();
 }

 [HttpGet("PrivateKey")]
 public string PrivateKey()
 {
 return _rsaEncryptionHelper.GetPrivateKey();
 }

 [HttpPost("ImportKey")]
 public void ImportKey([FromBody] ImportKeyRequest request)
 {
 _rsaEncryptionHelper.ImportKey(request.PrivateKey);
 }

}

public record ImportKeyRequest
{
 public string PrivateKey { get; init; } = null!;
}

public record EncryptionRequest
{
 public string Data { get; init; } = null!;
}

Bu backend tarafında yaptığımız geliştirmelerden sonra JavaScript tarafına geçerek devam edebiliriz. Yaptıklarımız sayesinde, public anahtarımızı istemciyle endpoint’ten paylaşabiliriz, ardından istemciler bu public anahtarı kullanarak verilerini güvenli iletişim için şifreleyebilirler.

Setting Up the Development environment for JavaScript RSA Encryption

rnekte, modern tarayıcılara yerleşik olan ve RSA şifrelemeyi içeren kriptografik işlemleri sağlayan Web Crypto API’sini kullanacağız. Bu nedenle, herhangi bir npm paketi indirmenize gerek yoktur.

JavaScript ile tarayıcı uygulaması geliştireceksem genellikle Vite ile başlarım. Bunu yapmak için, aşağıdaki komutu girerek vanilla js veya React ile bir proje başlatabiliriz. Gösterim amaçlı küçük bir React projesi geliştireceğim, ancak vanilla js ile devam etmeniz durumda bile yeterli olacaktır.

npm create vite@latest

Bundan sonra src/utils/RsaEncryptionHelper.js dosyasını oluşturup o dosyayı aşağıdaki gibi dolduracağım. Bu dosyanın method’larıyla RSA algoritması ile şifreleyebilir ve şifresini çözebilirsiniz, ancak şifre çözme genellikle backend sorumluluğundadır çünkü şifre çözme private anahtar gerektirir ve güvenlik nedenlerinden dolayı javascript istemcisinin private anahtarları herkese açık olarak saklamaması veya private anahtarlara erişmemesi gerekir. Ancak SSL’deki gibi iki yönlü anahtar şifrelemeye benzer bir şey denemek isteyen olursa diye bunuda paylaşıyorum.

// src/utils/RsaEncryptionHelper.js
const encryptAlgorithm = {
 name: "RSA-OAEP",
 modulusLength: 2048,
 publicExponent: new Uint8Array([1, 0, 1]),
 extractable: true,
 hash: {
 name: "SHA-256",
 },
};

function arrayBufferToBase64(arrayBuffer) {
 const byteArray = new Uint8Array(arrayBuffer);
 let byteString = "";
 for (let i = 0; i < byteArray.byteLength; i++) {
 byteString += String.fromCharCode(byteArray[i]);
 }
 const b64 = window.btoa(byteString);
 return b64;
}

function base64StringToArrayBuffer(b64str) {
 const byteStr = atob(b64str);
 const bytes = new Uint8Array(byteStr.length);
 for (let i = 0; i < byteStr.length; i++) {
 bytes[i] = byteStr.charCodeAt(i);
 }
 return bytes.buffer;
}

function convertPemToArrayBuffer(pem) {
 const lines = pem.split("\n");
 let encoded = "";
 for (let i = 0; i < lines.length; i++) {
 if (
 lines[i].trim().length > 0 &&
 lines[i].indexOf("-----BEGIN RSA PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----BEGIN PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----BEGIN PUBLIC KEY-----") < 0 &&
 lines[i].indexOf("-----END RSA PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----END PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----END PUBLIC KEY-----") < 0
 ) {
 encoded += lines[i].trim();
 }
 }
 return base64StringToArrayBuffer(encoded);
}

export const encryptRsa = async (str, pemString) => {
 try {
 // convert string into ArrayBuffer
 const encodedPlaintext = new TextEncoder().encode(str).buffer;
 const keyArrayBuffer = convertPemToArrayBuffer(pemString);
 // import public key
 const secretKey = await crypto.subtle.importKey(
 "spki",
 keyArrayBuffer,
 encryptAlgorithm,
 true,
 ["encrypt"]
 );
 // encrypt the text with the public key
 const encrypted = await crypto.subtle.encrypt(
 {
 name: "RSA-OAEP",
 },
 secretKey,
 encodedPlaintext
 );
 // store data into base64 string
 return arrayBufferToBase64(encrypted);
 } catch (error) {
 console.error("Encryption Error:", error);
 }
};

export const decryptRsa = async (str, pemString) => {
 try {
 // convert base64 encoded input string into ArrayBuffer
 const encodedPlaintext = base64StringToArrayBuffer(str);
 const keyArrayBuffer = convertPemToArrayBuffer(pemString);
 // import private key
 const secretKey = await crypto.subtle.importKey(
 "pkcs8",
 keyArrayBuffer,
 encryptAlgorithm,
 true,
 ["decrypt"]
 );
 // decrypt the text with the public key
 const decrypted = await crypto.subtle.decrypt(
 {
 name: "RSA-OAEP",
 },
 secretKey,
 encodedPlaintext
 );
 // decode the decrypted ArrayBuffer output
 const uint8Array = new Uint8Array(decrypted);
 const textDecoder = new TextDecoder();
 const decodedString = textDecoder.decode(uint8Array);
 return decodedString;
 } catch (error) {
 console.error("Decryption Error:", error);
 }
};

Bu yardımcı yöntemleri kullanarak küçük bir React projesi geliştirdim. Verileri şifrelemek ve şifresini çözmek için .NET API’den paylaşılacak genel ve özel anahtarlarınızı kullanabilirsiniz, ancak şifre çözme işleminin arka uçta gizli tutulan özel anahtarla yapılması gerektiğini unutmayın.

RSA Encryption (lecture-rsa-dotnet-javascript.vercel.app)

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

GitHub - berkslv/lecture-rsa-dotnet-javascript

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Ocelot ve Keycloak'i birlikte kullanarak API Gateway'den Mikroservis güvenliğini nasıl sağlarız?

Tue, 30 Jan 2024 00:00:00 +0300

Mikroservis mimarisinin dinamik dünyasında, güçlü bir güvenliğe olan ihtiyaç çok daha önemli hale gelmiştir. Kuruluşlar uygulamalarını daha küçük, bağımsız bir şekilde deploy edilebilir servislere böldükçe, bu servisler arasında alınan ve gönderilen verilerin bütünlüğünü ve gizliliğini sağlamak kritik bir önem haline gelir.

Bu blog yazısında, Ocelot’u kullanan ve güçlü bir açık kaynak kimlik ve erişim yönetimi çözümü olan Keycloak ile mikroservisleri güvence altına almak için kapsamlı bir çözümü keşfedeceğiz. Keycloak’u API Gateway’in arkasına yerleştirerek, bu entegrasyonun kaynakları koruduğunu, diğer hizmetlere yönelik istekleri kimlik doğruladığını ve taleplere erişimi yetkilendirdiğini claim yapılarını kullanarak sunar. Bu, mikroservis ekosisteminiz için sorunsuz ve güvenli bir iletişim çerçevesi sunar. Başlayalım.

Create Keycloak instance

Docker içinde Keycloak’u çalıştırmak çok kolaydır. Bu Docker dosyasını projenizin /Identity dizinine yerleştirin. Tüm kodları yazının sonundaki GitHub reposunda bulabilirsiniz.

FROM quay.io/keycloak/keycloak:latest as builder 
 
# Enable health and metrics support 
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor 
ENV KC_DB=postgres

WORKDIR /opt/keycloak 
# for demonstration purposes only, please make sure to use proper certificates in production instead 
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore 
RUN /opt/keycloak/bin/kc.sh build 
 
FROM quay.io/keycloak/keycloak:latest 
COPY --from=builder /opt/keycloak/ /opt/keycloak/ 
 
# change these values to point to a running postgres instance 
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

And create docker-compose.yml file that access /Identity/Dockerfile and builds image from it. We can use base image rather than custom Dockerfile but with this approach you can customize much more features of Keycloak like frontend theme and secret keys.

/Identity/Dockerfile dosyasına erişen ve ondan bir image oluşturan docker-compose.yml dosyasını oluşturun. Özel Docker dosyası yerine bir temel image kullanabiliriz, ancak bu yaklaşımla Keycloak’un frontend teması ve secret key bilgileri gibi çok daha fazla özelliğini özelleştirebilirsiniz.

version: "3"

services:
 # PostgreSQL for keycloak 
 secured-identity-db:
 container_name: secured-identity-db 
 image: postgres:16-alpine 
 ports:
 - 6063:5432
 expose:
 - 6063
 volumes:
 - ./data/secured-identity-db:/var/lib/postgresql/data 
 restart: always 
 environment:
 - POSTGRES_PASSWORD=myStrongPassword123 
 - POSTGRES_USER=keycloak 
 - POSTGRES_DB=keycloak 
 networks:
 - secured-network 

 # Keycloak 
 secured-identity:
 container_name: secured-identity 
 build: ./Keycloak 
 command: ["start-dev"]
 ports:
 - 5053:8080
 expose:
 - 5053
 environment:
 - KEYCLOAK_ADMIN=admin 
 - KEYCLOAK_ADMIN_PASSWORD=admin 
 - KC_HOSTNAME_URL=http://localhost:5050/identity 
 - KC_DB=postgres 
 - KC_DB_USERNAME=keycloak 
 - KC_DB_PASSWORD=myStrongPassword123 
 - KC_DB_URL=jdbc:postgresql://secured-identity-db:5432/keycloak 
 depends_on:
 - secured-identity-db 
 networks:
 - secured-network 

networks:
 secured-network:
 driver: bridge 

volumes:
 secured-data:
 driver: local

Ve sadece bu docker-compose.yml dosyasından docker’ı çalıştırmamız yeterlidir.

docker compose build
docker compose up -d

Put keycloak behind Ocelot API Gateway to protect resources

Microservice architecture with Ocelot and Keycloak

Kimlik hizmetinizin (keycloak) güvenliğini sağlamak ve diğer hizmetler gibi istek alabilecek uç noktaları sınırlandırarak saldırı vektörünü azaltmak önemlidir. Keycloak admin paneline harici bir ağdan erişilmemelidir, bu özelliğe yalnızca bu ağdaki kişiler erişebilir. Daha fazla bilgi edinmek için reverse proxy kullanma hakkındaki Keycloak dökümantasyonunu göz atın.

Exposed path recommendations

Öncelikle Ocelot projesini oluşturalım. Burada .NET 8 kullanıyorum

dotnet new sln -n Secured
dotnet new webapi -o Secured.ApiGateway
cd Secured.ApiGateway/
dotnet add package Ocelot --version 22.0.1

Projeyi başarıyla oluşturduktan sonra Program.cs dosyasını aşağıdaki gibi değiştirip root dizinde ocelot.json dosyasını oluşturun.

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();
await app.RunAsync();

Bundan sonra bu ocelot.json dosyasını localhost:5053 üzerinde çalışan keycloak uygulamamıza erişimi sınırlamak için kullanabiliriz.

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/realms/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/realms/{everything}",
 "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
 },
 {
 "DownstreamPathTemplate": "/resources/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/resources/{everything}",
 "UpstreamHttpMethod": [ "Get" ]
 },
 {
 "DownstreamPathTemplate": "/js/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/js/{everything}",
 "UpstreamHttpMethod": [ "Get" ]
 }
 ],
 "GlobalConfiguration": {
 "BaseUrl": "https://localhost:5050"
 }
}

Bu yapılandırmalardan sonra, API Gateway’in adresi olan localhost:5050’den keycloak’a erişebilirsiniz. Ancak, bu adres aracılığıyla Keycloak yönetici paneline erişemezsiniz çünkü erişimi sınırladık.

Keycloak yapılandırmalarımızı yapmak için, hala local olarak erişilebilen keycloak adresinde, yani localhost:5053’te yönetici paneline giriş yapabiliriz. Deployment senaryosunda, yalnızca Ocelot’un harici internete erişimi olduğundan emin olacağız.

localhost:5053 adresine admin kullanıcı adı ve admin şifresiyle giriş yapabiliriz. Bu kimlik bilgilerini docker-compose.yml dosyasından değiştirebiliriz.

Giriş yaptıktan sonra, kullanıcıları yönetmek için yeni bir alan (realm) oluşturmak ve uygulamamız için istemci oluşturmak için bu açılır menüden yeni alan (realm) oluştur seçeneğine tıklıyoruz. “Yeni alan (realm) oluştur” düğmesine tıkladıktan sonra, basitçe secured‘ı alan (realm) adı olarak girin ve diğer her şeyi olduğu gibi bırakın.

Clients sekmesinde client oluştur’a tıklayın. Client ID alanını postman olarak adlandırın ve geçerli redirect URL’sini https://oauth.pstmn.io/v1/callback olarak adlandırın. diğer şeyleri olduğu gibi bırakın.

Kullanıcılar sekmesinde Keycloak’ta oturum açacak kullanıcıları ekleyin.

Bu adımlardan sonra, yeni oluşturulan kullanıcıyla Keycloak’a giriş yaparak erişim belirteci alabiliriz. API gateway’e erişmek için Postman kullanıyorum. Postman’de Keycloak ile oturum açabilirsiniz. Yetkilendirme bölümünde OAuth 2.0’ı seçin ve aşağıdaki gibi yapılandırın ve Yeni Erişim Belgesi Al’a tıklayın. Postman, tarayıcı penceresini açacak ve sizi Keycloak giriş sayfasına yönlendirecektir, yeni kullanıcınızın kimlik bilgilerini girin. Admin kimlik bilgilerini girmeyin, bu kimlik bilgileri yalnızca ana (master) alan için geçerlidir.

Grant type: Authorization code
Auth URL: http://localhost:5050/identity/realms/secured/protocol/openid-connect/auth
Access Token URL: http://localhost:5050/identity/realms/secured/protocol/openid-connect/token
Client ID: postman
Scope: openid profile roles

Her şeyi doğru yaptıysanız, Postman ile API Gateway’in arkasındaki Keycloak’a başarıyla kimlik doğrulaması yaptınız 🎉

Authenticate requests to other services

Ocelot’ta bir isteğin kimliğini doğrulamak istiyorsanız Program.cs ve ocelot.json’da aşağıdaki güncellemeleri yapın. MetadataAddress, JWT doğrulaması için gerekli anahtarları alır. Ancak ekstra network isteklerinden kaçınmak istiyorsanız anahtarları appsettings.json dosyasına yerleştirip kullanabilirsiniz.

Ocelot.json dosyasındaki AuthenticationOptions ile kimlik doğrulama tamamlandı, burada JWT tokenımızı Bearer önekiyle birlikte göndereceğimizi ve JWT token doğrulamasını Program.cs’den yapılandırma ile yapacağımızı söylüyoruz.

var builder = WebApplication.CreateBuilder(args);

builder.Services
 .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, o =>
 {
 o.MetadataAddress = "http://localhost:5050/identity/realms/secured/.well-known/openid-configuration";
 o.RequireHttpsMetadata = false;
 o.Authority = "http://localhost:5050/realms/secured";
 o.Audience = "account";
 });

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);


builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

await app.UseOcelot();
await app.RunAsync();

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/get",
 "DownstreamScheme": "https",
 "DownstreamHostAndPorts": [
 {
 "Host": "httpbin.org",
 "Port": 443
 }
 ],
 "UpstreamPathTemplate": "/test",
 "UpstreamHttpMethod": [ "Get" ],
 "AuthenticationOptions": {
 "AuthenticationProviderKey": "Bearer"
 }
 },

//...

Authorize requests to other services

Yetkilendirme biraz daha zor ve ek çalışma gerektirir çünkü Keycloak, kullanıcı rollerini JWT yükünde nested yani iç içe geçmiş olarak yerleştirir. Aşağıdaki gibi bir şeydir. Görüldüğü gibi, roller alanı realm_access alanı altına yerleştirilir. Bu, Ocelot’ta karışıklığa neden olur, çünkü Ocelot, talepleri string veya object değerleri olarak okur ve nested alanları değerlendirmez. Bu sorunu önlemek için Keycloak token eşlemesini yapılandırırız ve nested biçimi kullanmayız.

{
 //...
 "exp": 1706600524,
 "realm_access": {
 "roles": [
 "offline_access",
 "default-roles-microcommerce",
 "uma_authorization",
 "customer"
 ]
 },
 "resource_access": {
 "account": {
 "roles": [
 "manage-account",
 "manage-account-links",
 "view-profile"
 ]
 }
 },
 "scope": "openid email profile",
 "preferred_username": "berkslv",
}

Bu özel eşleme için sol menüden Client scopes’a tıklayın ve rolleri seçin.

Rollerin altında, Mappers bölümünü seçin ve ardından realm roles’a tıklayın.

Açılan menüde Token Claim Name seçeneğine realm_access.roles hali hazırda girilidir. Bunu realm_roles olarak güncelliyoruz.

Bu konfigürasyonları yaptıktan sonra Postman üzerinden tekrar giriş yaparak tokenımızı güncelliyoruz. Güncellenen token ile yaptığımız isteklerin Ocelot tarafından talep kontrolüne tabi olması için ocelot.json dosyasında aşağıdaki güncellemeyi yapıyoruz. Kullanıcımızda customer rolü yoksa 403 yanıtı alıyoruz. Keycloak yönetici panelinde özel rollerinizi oluşturabilir ve atayabilirsiniz.

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/get",
 "DownstreamScheme": "https",
 "DownstreamHostAndPorts": [
 {
 "Host": "httpbin.org",
 "Port": 443
 }
 ],
 "UpstreamPathTemplate": "/test",
 "UpstreamHttpMethod": [ "Get" ],
 "AuthenticationOptions": {
 "AuthenticationProviderKey": "Bearer"
 },
 "RouteClaimsRequirement": {
 "realm_roles": "customer"
 }
 },

//...

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

GitHub - berkslv/lecture-ocelot-and-keycloak

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

.NET ile Background jobs ve Hangfire

Sun, 17 Sep 2023 00:00:00 +0300

.NET ekosisteminde bir uygulama geliştirirken, işler karmaşıklaştığında, bazı yöntemlerimizin birden fazla servise gitmesi, yanıtlarını değerlendirmesi ve bu sonuçları farklı servislere bildirmesi gerekebilir ve bu uzun zaman alabilir! Bu tür uzun süre çalışan yöntemleri bir endpoint’in arkasına yerleştirerek ve TCP bağlantımızı o HTTP isteğinin yanıtı için açık tutarak kaynakları boşa harcamak istemeyiz. Bu kullanımı on demand job olarak adlandırabiliriz çünkü bir istek yapıldığında çalışacaktır. Ayrıca, belirli günler veya haftanın belirli zamanlarında otomatik olarak çalışmasını isteyebiliriz, bunu bir recurring job olarak adlandırabiliriz; Bu tür durumlarda, işimizi uygulamanın çalıştığı main thread’den farklı bir thread başlatarak “background job” kullanabiliriz.

.NET’te arka plan işlerini yönetmenin birçok farklı yöntemi bulunmaktadır. Bu blog yazısında adım adım bu yöntemlerden bahsedeceğim, nasıl sorunları çözdüklerini ve bize hangi sorunları getirdiklerini anlatacağım ve background job’larıyla uğraşırken en çok sevdiğim paket olan Hangfire’da detaylı kullanım örnekleri sunacağım. Ayrıca, tüm kodlara repodan erişebilirsiniz:

GitHub - berkslv/lecture-dotnet-background-jobs

Task.Run()

Background job’larına ihtiyacım olduğunda aklıma ilk gelen çözüm, Task.Run() yöntemiyle yeni bir thread oluşturmak ve bir methodu onun üzerinde çalıştırmak oldu. Birçok dış servise bağımlılığı olan ve tamamlanması 5 dakikaya kadar sürebilen bir yöntemim var ve bu yöntemi oluşturduğum bir controller aracılığıyla bir HTTP isteği üzerinden çağırıyordum, ancak bu isteğe yanıt vermek sorunluydu çünkü TCP bağlantısının 5 dakika boyunca açık kalması gerekiyordu, bu yüzden isteği çağırdığımda, işlem başarıyla başlatıldıysa, istemciye işlemin başarıyla başlatıldığını 200 durum koduyla bildirmem gerekiyor.

// TestService.cs 

public class TestService : ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests()
 {
 _logger.LogInformation($"{DateTime.Now} RunTests is started");

 // ... 
 Thread.Sleep(5000);
 // ... 

 _logger.LogInformation($"{DateTime.Now} RunTests is finished");
 return true;
 }
}

// Program.cs 

// ... 

builder.Services.AddTransient<ITestService, TestService>();

// ...

Task.Run() kullanmadan işlemi çağırmazsam, bu örnekte tarayıcıda /job endpoint’ine yönelik istek 3 saniye boyunca yükleniyor olacak.

// JobController.cs 

[ApiController]
[Route("[controller]")]
public class JobController : ControllerBase
{
 private readonly ITestService _testService;
 public JobController(ITestService testService)
 {
 _testService = testService;
 }

 [HttpGet]
 public IActionResult Get()
 {
 _testService.RunTests();

 return Ok("Ok");
 }
}

Task.Run() ile aşağıdaki gibi kullandığımda, controller başarılı bir şekilde yanıt verecek ve RunTests yöntemim arka planda çalışmaya devam edecek.

[HttpGet]
public IActionResult Get()
{
 Task.Run(() => {
 _testService.RunTests();
 });

 return Ok("Ok");
}

Artılar

İsteğe bağlı olarak arka planda bir işlem çalıştırabiliriz.
Ek bir paket gerektirmez.

Eksiler

Mevcut durumda recurring job desteği bulunmamaktadır, özel bir sistem geliştirilmesi gerekmektedir.
Dependency Injection kullanıldığında, enjekte edilen interface’ler main thread üzerinde kalacağından, gereken interface’ü Service scope aracılığıyla yeniden oluşturmamız gerekebilir.
Yöntem çalışırken bir hata oluşursa ne olur?

Hosted Service

Önceki örneğimizde uygulayamadığımız yinelenen işleri yönetmek için kendi sistemimizi geliştirmemiz gerekiyordu, ancak Hosted servis ile bu yönetimi kendimiz geliştirmemize gerek kalmaz, bunun yerine Program.cs dosyasında AddHostedService yöntemimizi aşağıdaki gibi çağırırız ve TestService sınıfımızı BackgroundService sınıfından türetiriz. Bu örnekte, RunTests yöntemimiz her 10 saniyede bir çalışacaktır. Bu zaman aralığı, BackgroundService abstract sınıfından miras alınan ExecuteAsync yönteminden ayarlanır.

// Program.cs 

// ... 

builder.Services.AddHostedService<TestService>();

// ...

// TestService.cs 


public class TestService : BackgroundService, ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests(TestType testType)
 {
 var type = Enum.GetName(typeof(TestType), testType);

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is started");

 // ... 
 Thread.Sleep(5000);
 // ... 

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is finished");

 return true;
 }

 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
 var timer = new PeriodicTimer(TimeSpan.FromSeconds(10));
 while (await timer.WaitForNextTickAsync(stoppingToken))
 {
 RunTests(TestType.Recurring);
 }
 }
}

Ancak, yöntemimizi on demand olarak çalıştırmak istiyorsak, Task.Run() yönteminin yardımıyla yeni bir thread üzerinden çalışırız, bu nedenle JobController.cs’de herhangi bir değişiklik yapmamıza gerek yoktur.

Artılar

Recurring job yönetimi sağlar
Ek paket kurmaya gerek yoktur

Eksiler

Talep üzerine çalışma için bir sistem bulunmamaktadır.
Yöntem çalışırken bir hata alınırsa ne olur?

Hangfire

Hangfire, job’ımızı tek bir sistem aracılığıyla talep üzerine ve recurring job’ları yönetmeyi çok daha kolay hale getirir. Diğer iki yöntemde bulunmayan job storage sistemi sayesinde, uygulama o anda çalışmıyor olsa bile cron job ile süresi gelmişse ilgili job’ı otomatik olarak çalıştırır. Belirli job’ları çalıştırabilir ve job oluşturulurken sağlanan id bilgileri ile o job’ı silme yeteneğine sahip oluruz. Ayrıca, /hangfire adresindeki bir dashboard üzerinden şu anda çalışan job’larımızı izleyebiliriz.

Hangfire dashboard

Hangfire resmi olarak Sql Server veritabanını destekler, ancak açık kaynaklı bir uzantı ile Sqlite ve Postgresql gibi sık tercih edilen veritabanları da kullanılabilir. Ayrıca, Hangfire, ücretli sürümüyle Redis veritabanı desteği ve batch job’larının çalıştırılması gibi enterprise ihtiyaçları da karşılar.

Hangfire – Background Jobs for .NET and .NET Core

Bu kısa Hangfire girişten sonra, Hangfire’ı uygulamamızda nasıl kullanabileceğimiz ve yeteneklerinden kısaca bahsedelim. Örneğimizde job storage olarak Postgresql kullanacağız, ancak yukarıdaki link üzerinden istediğiniz veritabanını seçebilirsiniz. Uygulamamıza aşağıdaki paketleri yükledikten ve Docker ile bir Postgre SQL veritabanı kurduktan sonra, kodlarımıza geçelim.

dotnet add package Hangfire
dotnet add package Hangfire.Core
dotnet add package Hangfire.PostgreSql
dotnet add package TimeZoneConverter

docker run -d --name postgres_db -e POSTGRES_USER="root" -e POSTGRES_PASSWORD="1234" -e POSTGRES_DB="postgres" -v postgres_data:/var/lib/postgresql/data -p 5432:5432 postgres

İlk olarak, appsettings.json dosyasında Postgresql için connection string bilgilerini aşağıdaki gibi sağlıyoruz.

"ConnectionStrings": {
 "HangfireConnection": "Host=localhost;Port=5432;Password=1234;Username=root;Database=postgres;Pooling=true;Integrated Security=true;"
}

Program.cs’de ilgili yapılandırmaları aşağıdaki gibi yapıyoruz.

TZConvert.GetTimeZoneInfo yöntemiyle gerekli zaman dilimi bilgisini işletim sisteminden alırsınız. Bu kod satırı, local makinenizin, frontend uygulamanızın ve cloud makinenizin farklı zaman dilimlerine sahip olabileceği için gereklidir.

var builder = WebApplication.CreateBuilder(args);

// ... 

builder.Services.AddHangfire(config => {
 config
 .UseSimpleAssemblyNameTypeSerializer()
 .UseRecommendedSerializerSettings()
 .UsePostgreSqlStorage(builder.Configuration.GetConnectionString("HangfireConnection"));

 var cronEveryMinute = "*/1 * * * *";
 var recurringJobOptions = new RecurringJobOptions
 {
 TimeZone = TZConvert.GetTimeZoneInfo("Etc/GMT+3")
 };
 RecurringJob.AddOrUpdate<ITestService>("id-run-and-wait", x => x.RunTests(Guid.NewGuid(), TestType.Recurring, CancellationToken.None), cronEveryMinute, recurringJobOptions);
});

builder.Services.AddHangfireServer();

var app = builder.Build();

// ... 

app.UseHangfireDashboard();
app.MapHangfireDashboard();

app.Run();

To showcase Hangfire’s capabilities, we add a few more endpoints to our controller class.

/run, we can start a job and that method returns us a job id

/stop, we can stop the job related to the job id given to us by Hangfire.

/continue, if many different jobs are to be run but they are dependent on each other, another job can be run after the parent job is finished with the given job id.

/reschedule, the job’s working intervals can be dynamically adjusted by cron or TimeSpan.

/deschedule, recurring jobs can be deleted by their unique id.

/trigger, we can manually trigger a recurring job.

Hangfire’nin yeteneklerini sergilemek için, controller sınıfımıza birkaç ek endpoint ekliyoruz.

/run, bir job başlatabilir ve bu yöntem bize job’ın id bilgisini döndürür.

/stop, bize Hangfire tarafından verilen job id ile ilişkili job sürecini durdurabiliriz.

/continue, birçok farklı job’ın çalıştırılması gerekiyorsa, ama bunlar birbirlerine bağımlıysa, verilen job id ile ana job tamamlandıktan sonra başka bir iş çalıştırılabilir.

/reschedule, job’un çalışma aralıkları cron veya TimeSpan ile dinamik olarak ayarlanabilir.

/deschedule, recurring job’lar, job id bilgileriyle silinebilir.

/trigger, recurring bir job’ları manuel olarak tetikleyebiliriz.

// JobController.cs 


[ApiController]
[Route("[controller]")]
public class JobController : ControllerBase
{
 [HttpGet("/run")]
 public IActionResult Run()
 {
 var jobId = BackgroundJob.Enqueue<ITestService>(x => x.RunTests(Guid.NewGuid(), TestType.OnDemand, CancellationToken.None));

 return Ok(jobId);
 }

 [HttpGet("/stop")]
 public IActionResult Stop(string jobId)
 {
 BackgroundJob.Delete(jobId);

 return Ok("Stopped");
 }

 [HttpGet("/continue")]
 public IActionResult Continue(string jobId)
 {
 BackgroundJob.ContinueJobWith<ITestService>(jobId, x => x.RunTests(Guid.NewGuid(), TestType.OnDemand, CancellationToken.None));

 return Ok("Continued");
 }

 [HttpGet("/reschedule")]
 public IActionResult Reschedule(string cron)
 {
 var recurringJobOptions = new RecurringJobOptions
 {
 TimeZone = TZConvert.GetTimeZoneInfo("Etc/GMT+3")
 };
 RecurringJob.AddOrUpdate<ITestService>("id-run-and-wait", x => x.RunTests(Guid.NewGuid(), TestType.Recurring, CancellationToken.None), cron, recurringJobOptions);
 return Ok("Rescheduled");
 }

 [HttpGet("/deschedule")]
 public IActionResult Deschedule(string id)
 {
 if (String.IsNullOrEmpty(id))
 {
 id = "id-run-and-wait";
 }

 RecurringJob.RemoveIfExists(id);
 return Ok("Descheduled");
 }

 [HttpGet("/trigger")]
 public IActionResult Trigger(string id)
 {
 if (String.IsNullOrEmpty(id))
 {
 id = "id-run-and-wait";
 }

 RecurringJob.TriggerJob(id);
 return Ok("Triggered");
 }
}

Finally, error management, which is not in our toolkit previously with Task.Run and Hosted service but with Hangfire if an error occurs while running a method, Hangfire runs that method 10 more times with the same parameters at certain time intervals. As an example, we add a method called ThrowRandomly to our TestService class. With this method, we simply add a system that will throw an exception from the method that works with probability 1/2, but Hangfire will try to get successful results by re-running the methods that get errors for us. But errors that catches successfully cannot trigger the retry system. Therefore in the end of catch block we throw again.

Son olarak, önceki Task.Run() ve Hosted servis ile sahip olmadığımız hata yönetimi sayesinde Hangfire ile bir yöntem çalışırken bir hata oluşursa, Hangfire belirli zaman aralıklarında aynı parametrelerle bu yöntemi 10 kez daha çalıştırır. Bir örnek olarak, TestService sınıfımıza ThrowRandomly adında bir method ekliyoruz. Bu method ile, 1/2 olasılıkla gerçekleşen bir exception fırlatan yapı oluşturuyoruz, ancak Hangfire, bizim için hata alan methodları tekrar çalıştırarak başarılı sonuçlar elde etmeye çalışır. Ancak başarılı bir şekilde catch’lenen exception’lar, yeniden deneme sistemini tetiklemez. Bu nedenle catch bloğunun sonunda tekrar bir exception fırlatıyoruz.

// TestService.cs 

public class TestService : ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests(Guid id, TestType testType, CancellationToken cancellationToken)
 {
 var type = Enum.GetName(typeof(TestType), testType);

 try
 {
 _logger.LogInformation($"{DateTime.Now} {type} RunTests is started. Id: {id}");

 cancellationToken.ThrowIfCancellationRequested();
 // ... 
 Thread.Sleep(5000);
 ThrowRandomly();
 // ... 

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is finished. Id: {id}");
 return true;
 }
 catch (OperationCanceledException exception)
 {
 _logger.LogError($"{DateTime.Now} {type} RunTests is failed. Exception: {exception.Message} Id: {id}");
 throw;
 }
 catch(Exception exception)
 {
 _logger.LogError($"{DateTime.Now} {type} RunTests is failed. Exception: {exception.Message} Id: {id}");
 throw;
 }
 }

 private void ThrowRandomly()
 {
 var random = new Random();
 var number = random.Next(1, 3);

 if (number == 2)
 {
 throw new Exception("Error is throwed!");
 }
 }
}

Ayrıca, Hangfire ayrı servis üzerinde çalışır, bu ihtiyaçlarınıza bağlı olarak iyi veya kötü olabilir. Ölçeklendirme gerektiğinde uygulama ve Hangfire sunucularını ayırabilir ve bunları farklı makinelerde çalıştırabiliriz.

Artılar

Güçlü bir soyutlama ile talep üzerine ve yinelenen işleri birlikte yönetebilir.
Cron iş zamanlamasını dinamik olarak ayarlayabiliriz ve zamanlaması çok hassastır.
Çalışan ve cron job’larımızı Dashboard ile izleyebiliriz.
Zorunlu interface uygulaması veya başka özel bir uygulama yoktur, yalnızca Hangfire tarafından sağlanan yöntemleri kullanarak job’larımızı yönetebiliriz.

Eksiler

Harici depolama gereklidir, varsayılan olarak SQL Server ile çalışır.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Dotnet ve Vue.js uygulamasını Keycloak ile nasıl güvenliği sağlanır?

Mon, 21 Aug 2023 00:00:00 +0300

Bu yazıda, dotnet ve vue uygulamalarımızı keycloak kullanarak nasıl güvence altına alabileceğimizi konuşacağım.

Öncelikle, Keycloak uygulamamızı docker kullanarak çalıştırıyoruz, bu uygulamayı Azure veya benzeri bir bulut sağlayıcısında yayınlarsanız, production uygulamalarınızda kolayca kullanabilirsiniz.

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0.1 start-dev

Keycloak çalıştıktan sonra, localhost:8080/admin adresine kullanıcı adı: admin ve şifre: admin ile giriş yaptıktan sonra sol taraftan uygulamamız için bir alan (realm) oluştururuz. Ana (master) alan keycloak’un kendi kullanımına atandığından, başka bir realm üzerinde çalışmamız gerekmektedir.

Create realm

Create realm confirmation

Realm’i oluşturduktan sonra client kısmından vue adında bir client oluşturuyoruz. Yönlendirme URL’lerimiz Vue uygulamamızın URL’sidir. production ortamı için ek güncellemeler yapmanız gerekebilir.

Vue uygulamamızda kullanmak üzere Kullanıcılar menüsünden dotnet-vue realm altında kullanıcılar oluşturabiliriz.

Uygulamamız için kullanıcı oluşturmak istiyorsak realm ayarlarında bu seçeneği açarak kullanıcılarımızın keycloak’a kayıt olmalarını sağlayabiliriz.

Vue

Bu konfigürasyonları tamamladıktan sonra keycloak admin paneli ile işimiz bitiyor, vue uygulamamıza yetkisiz bir istek geldiğinde onu keycloak giriş sayfamıza yönlendirmemiz gerekiyor. Bunun için Secure Vue.js app with Keycloak makalesinden yararlanıyoruz.

Vue uygulamamızı vite kullanarak şu şekilde oluşturabiliriz, sorulan sorulardan Vue ve Javascript seçip devam edebilirsiniz.

npm create vite@latest vue
cd vue
npm install
npm run dev

Daha sonra main.js içeriğini aşağıdaki gibi güncelliyoruz. Bu komut dosyası, yetkisiz oturum açma isteklerini yeniden yönlendirir ve token’ın süresinin onTokenExpired ile sona ermesi durumunda token’ı refrest token kullanarak günceller. Bu işlem sonrasında uygulamayı npm run dev ile çalıştırıp http://localhost:5173 adresine gidersek keycloak giriş url’si yönlendirilecektir. Oluşturduğumuz kullanıcı bilgileriyle giriş yaparsak sistemimize giriş yapmış olacağız.


import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";
import Keycloak from "keycloak-js";

let initOptions = {
 url: "http://localhost:8080",
 realm: "dotnet-vue",
 clientId: "vue",
 onLoad: "login-required",
};

let keycloak = new Keycloak(initOptions);

keycloak
 .init({ onLoad: initOptions.onLoad })
 .then((auth) => {
 if (!auth) {
 window.location.reload();
 } else {
 console.log("Authenticated");
 }

 createApp(App).mount("#app");
 })
 .catch((error) => {
 console.log(error);
 console.error("Authenticated Failed");
 });

keycloak.onTokenExpired = () => {
 console.log("Token expired");

 keycloak
 .updateToken(30 * 60)
 .then(() => {
 console.log("Token renewed");
 })
 .catch(() => {
 keycloak.login()
 })
}

export default keycloak;

.NET

.NET 6 ile aşağıdaki gibi bir webapi projesi oluşturabiliriz.

cd dotnet
dotnet new sln -n Secured
dotnet new webapi -o Secured.API
cd Secured.API
dotnet watch run

Keycloak ve .NET’in desteklediği standartlar sayesinde Program.cs’de yapacağımız konfigürasyonlarla özel bir kod yazmadan sadece yetkilendirebiliyoruz. Bu kodda, ihraççı ile tokenın nereden geldiğini doğruluyoruz ve IssuerSigningKey sayesinde keycloak’a gitmeden oluşturulan tokenı doğrulayabiliyoruz.

RequireHttpsMetadata yalnızca geliştirme ortamı için kullanılmalıdır; production ortamında çalışan bir uygulamanız varsa bu satırı silebilirsiniz; değeri true olarak değerlendirilecektir.

builder.Services.AddSwaggerGen();

// ... 

var issuer = builder.Configuration["Jwt:Issuer"];
var key = builder.Configuration["Jwt:Key"];
builder.Services.AddAuthentication(options =>
 {
 options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
 options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
 })
 .AddJwtBearer(o =>
 {
 o.Authority = issuer;
 o.RequireHttpsMetadata = false;
 o.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = false,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = issuer,
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(key))
 };
 });

// ... 

var app = builder.Build();

// ... 

app.UseAuthentication();
app.UseAuthorization();

// ... 

app.Run();

Appsettings.json dosyasındaki verileri aşağıdaki gibi tutarak builder.Configuration adresinden erişebiliriz. RSA256 anahtarına keycloak admin panelinde ilgili realm altında Realm ayarları menüsündeki Keys sekmesindeki RSA256 Kid değerinden ulaşabilirsiniz.

"Jwt": {
 "Issuer": "https://localhost:8080/realms/dotnet-vue",
 "Key": "secret-rsa-key"
},

Consuming .NET API from Vue app

Öncelikle .NET projemize CORS ayarlarını ve Authorize niteliklerini ekliyoruz. Bunun için Program.csyi aşağıdaki gibi düzenliyoruz.


// ... 

builder.Services.AddCors(options =>
{
 options.AddDefaultPolicy(
 policy => policy.WithOrigins("http://localhost:5137")
 .AllowAnyHeader()
 .AllowAnyMethod()
 .AllowAnyOrigin()
 );
});

// ... 

var app = builder.Build();

// app.UseHttpsRedirection(); 

app.UseCors();

WeatherForecastController.cs dosyası aşağıdaki attirbute ile yetkilendirme gerektirir.

// ... 

[Authorize]
public class WeatherForecastController : ControllerBase

// ...

Daha sonra aşağıdaki komutla vue uygulamamıza axios kütüphanesini kuruyoruz.

npm install axios

Kurulumdan sonra services isimli bir klasör oluşturup base.api.js isimli dosyamızda axios konfigürasyonlarını yapıyoruz.


import axios from "axios";
import keycloak from "../main"

const http = axios.create({
 baseURL: "http://localhost:5050",
 headers: {
 "Content-Type": "application/json",
 },
});

http.interceptors.request.use(
 async (config) => {
 const token = localStorage.getItem("vue-token");
 config.headers = {
 Authorization: `Bearer ${keycloak.token}`,
 Accept: "application/json",
 };
 return config;
 },
 (error) => {
 Promise.reject(error);
 }
);

export default http;

Örnek bir endpoint olan WeatherForecast’e erişmek için, aynı dizine weather.api.js dosyasını oluşturuyoruz.


import axios from "./base.api";

export const getWeather = async () => {
 const response = await axios.get(`/WeatherForecast`);
 return response.data;
}

App.vueda API isteğimizi yaparak verileri görüntülüyoruz, burada logout yöntemi ile çıkış yapabiliyoruz.


<script>
import Keycloak from './main';
import { getWeather } from './service/weather.api';

export default {
 name: 'App',
 data() {
 return {
 weathers: []
 }
 },
 async mounted() {
 this.weathers = await getWeather();
 },
 methods: {
 logout() {
 Keycloak.logout();
 }
 },
}

</script>

<template>
 <button @click="logout" style="margin-bottom: 30px;">Logout</button>
 <table>
 <tr>
 <th>Date</th>
 <th>Summary</th>
 </tr>
 <tr v-for="weather in weathers">
 <td>{{ weather.date }}</td>
 <td>{{ weather.summary }}</td>
 </tr>
 </table>
</template>

Kaynak koduna erişmek isterseniz projenin tamamını GitHub hesabımda bulabilirsiniz:

GitHub - berkslv/lecture-dotnet-vue-keycloak

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Zero downtime ile Deployment: Azure DevOps Deployment Slots Kullanarak Azure App Service Deployment işlemi

Sun, 21 May 2023 00:00:00 +0300

Selamlar! Azure App Service’te tek instance olarak çalışan uygulamamızı Azure DevOps işlem hatlarını kullanarak dağıtırken büyük olasılıkla birkaç saniyelik kesinti yaşanacaktır. Çünkü tek instance olarak çalışan uygulamanın yeni sürüme güncellenmesi için yeniden başlatılması gerekecektir. En kötü senaryoda, uygulama sürümlerimizin geçişinde bir hata oluşması durumunda geri alma nedeniyle kesinti süresi uzayacaktır.

Bu özel sorunu app servisi için deployment slot özelliğini kullanarak çözebiliriz. Bu özellikle, genellikle ayrı örnekler olarak aynı app servis planında çalışan iki farklı örnek, genellikle staging ve production uygulamaları, birbirinden ayrı örnekler olarak çalışır ve production ortamına geçiş yapıldığında app servisi tarafından değiştirme işlemi yönetilir ve kesinti yaşanmaz.

Bu yazıda, çok basit bir Dotnet Web API projesi oluşturacak, Azure DevOps Repository kullanarak barındıracak, Azure DevOps pipeline ile CI/CD pipeline oluşturarak Azure App Service’e dağıtacak ve deployment slot özelliği ile kesintisiz deployment yapacağız. Aşağıdaki adımları takip ederek süreci 5 adımda tamamlayacağız. Başlayalım.

Uygulamanın Oluşturulması
Azure DevOps Repo
Azure DevOps build pipeline
Azure App service
Zero downtime testing

## Uygulamanın Oluşturulması

Deploy etmek için basit bir Dotnet Web API projesi oluşturuyoruz. Bunun için aşağıdaki komutları kullanıyoruz.

mkdir backend
cd ./backend
dotnet new sln -n Slot
dotnet new webapi -n Slot.API
dotnet sln add ./Slot.API/

properties/launchSetting.json dosyasındaki profiles.http özelliğini aşağıdaki gibi güncelliyoruz. Burada yalnızca applicationUrl ve launchBrowser özelliklerini güncelledik.

// ...
 "profiles": {
 "http": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": false,
 "launchUrl": "swagger",
 "applicationUrl": "http://localhost:5050",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
// ...

Aşağıdaki güncellemeyi Program.cs dosyasında yaparak, uygulamanın erişilebilir ve /health uç noktasına yapılan isteklere yanıt verebileceğini test edeceğiz. Uygulamanızda bir veritabanı kullanıyorsanız, AddDbContextCheck yöntemi ile veritabanına erişimde bir sorun olup olmadığını da test edebilirsiniz.

var builder = WebApplication.CreateBuilder(args);

// ... 

builder.Services.AddHealthChecks();

var app = builder.Build();

// ... 

// app.UseHttpsRedirection(); 

app.MapControllers();

app.UseHealthChecks("/health");

app.Run();

Uygulamamız için bu kadar! Şimdi şu komutları çalıştırarak localhost:5050/health adresine erişebiliriz.

cd ./Slot.API
dotnet run
curl -4 http://localhost:5050/health
# Healthy

Daha sonra uygulamamızı dağıtmak için Docker kullanacağız, bu yüzden Dockerfile dosyamızı sln dosyamızla aynı dizine koyuyoruz.

# Build Stage 
FROM mcr.microsoft.com/dotnet/aspnet:7.0-alpine AS base 
WORKDIR /app 
EXPOSE 8080 
 
 
# Publish Stage 
FROM mcr.microsoft.com/dotnet/sdk:7.0-alpine AS build 
COPY ["Slot.API/Slot.API.csproj", "Slot.API/"] 
RUN dotnet restore "Slot.API/Slot.API.csproj" 
COPY . . 
WORKDIR "/Slot.API" 
RUN dotnet build "Slot.API.csproj" -c Release -o /app/build 
 
FROM build AS publish 
RUN dotnet publish "Slot.API.csproj" -c Release -o /app/publish /p:UseAppHost=false 
 
FROM base AS final 
WORKDIR /app 
COPY --from=publish /app/publish . 
ENV ASPNETCORE_URLS=http://*:8080 
ENV ASPNETCORE_ENVIRONMENT=Production
ENTRYPOINT ["dotnet", "Slot.API.dll"]

Aşağıdaki iki komutu kullanarak imajı başarıyla oluşturup container’ı build edip çalıştırabiliriz.

docker build -t deployment-slots-demo .
docker run -it -p 80:8080 deployment-slots-demo -n deployment-slots-demo-container

Uygulamanın Çalışıyor Olduğunu Doğrulayın

Önceki adımda sağlık kontrolü özelliği ile uygulamamızı oluşturduktan sonra, bu adrese her saniye bir istek yaparak uygulamanın erişilebilir olduğunu doğrulayabiliriz. Bu şekilde, Azure’a dağıtıldığında erişilebilir olduğunu doğrulamış olacağız.

Bu bölümde, uygulamanın her 50 milisaniyede bir istek yaparak erişilebilir olup olmadığını doğrulamak için basit bir Node.js script’i yazacağız. Bunun için aşağıdaki komutları kullanıyoruz.

mkdir health-check
npm init -y
touch index.js
npm install node-fetch

Aşağıdaki kısmı package.json dosyasına ekliyoruz.

// ...
"scripts": {
 "start": "node index.js"
},
"type": "module",
// ...

index.js dosyamızı aşağıdaki gibi oluşturabiliriz. Bu kod ile belirtilen url’e her 50 milisaniyede bir istek yapacak ve yanıtı konsola yazacaktır.

import fetch from "node-fetch";

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("http://localhost:5050/health");
 }, 50);
 setInterval(() => {
 check("http://localhost:5050/health");
 }, 50);
})();

API projemizde UseHttpsRedirection middleware’ini kapatmazsanız, geçersiz bir SSL sertifikası hatası alabilirsiniz. Bunu aşağıdaki gibi düzeltebilirsiniz.

import fetch from "node-fetch";
import https from "https";

const httpsAgent = new https.Agent({
 rejectUnauthorized: false,
});

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 agent: httpsAgent,
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("https://localhost:5051/health");
 }, 50);
 setInterval(() => {
 check("https://localhost:5051/health");
 }, 50);
})();

Azure DevOps Repo

Azure DevOps hesabımıza giriş yapıyoruz ve aşağıdaki gibi yeni bir repo oluşturuyoruz.

Bu repo’yu bilgisayarımıza klonluyoruz, yazdığımız kodu bu repo klasörüne taşıyoruz ve kodları origin’e iletiyoruz.

git add .
git commit -m "inital commit"
git push origin

Azure DevOps build pipeline

Pipeline ekranında, en sağ üstteki New pipeline düğmesine tıklıyoruz. Ardından aşağıdaki adımları izleyerek docker dosyasını oluşturup ve Azure Container Registry’e iteleriyoruz.

Şimdi Azure Container Registry’de image deployment işlemimizin başarılı olduğunu kontrol ediyoruz.

Görüldüğü gibi, boru hattı çalıştırıldığında, Docker image’i başarıyla Azure Container Registry’de oluşturulmuş ve kullanılmak üzere bizi bekliyor. Bu ayarların ardından, main branch’de /backend dizininde yapılan her değişiklik ile tetiklenerek yeni bir Docker image’i oluşturulacak.

Azure App service

Azure App servisi, güvenlik, yük dengeleme, otomatik ölçeklendirme gibi özellikleriyle Azure tarafından yönetilen web uygulamalarını dağıtmamıza olanak tanır. Azure app servisleri ekranı üzerinden yeni bir app servisi oluşturabiliriz.

App servisini oluşturduktan sonra, Container Registry şifresini yapılandırma sekmesinden güncellemeniz gerekebilir.

## Azure DevOps release pipeline

release pipeline ile, build pipeline tarafından oluşturulan Docker image’i kullanarak App servisine deploy edilir ve uygulamamızı yayınlamış oluruz.

Staging dağıtımına girdiğimizde, staging versiyonumuz için dağıtım alırız ve Docker image’inde yaptığımız değişikliklerin canlı hale gelmesini sağlamak için uygulama servisimizi yeniden başlatırız.

production aşamasında, app service’de bir deployment yapmıyoruz, bunun yerine staging aşamasıyla değişim işlemini gerçekleştiriyoruz ve bu şekilde, production erişiminde herhangi bir kesinti yaşamadan staging’de çalışan uygulamamızı production ile değiştirdiğimiz için production uygulamamıza erişebiliyoruz.

Şimdi, main bracnh’te yapılan herhangi bir değişiklik önce build pipeline (CI) ile geçecek, ardından release pipeline (CD) geçecek ve release, staging ortamına yapılacak. Production ortamına geçmek isterseniz, production deployment işlemi manuel olarak release ekranından tetiklenmelidir.

Zero downtime testing

Uygulamamız için gerekli pipeline’ları başarıyla oluşturduk, bundan sonra release sırasında herhangi bir kesinti olup olmadığını test etmemiz gerekecek. Bunun için health-check/index.js dosyamızı aşağıdaki gibi güncelliyorum ve uygulamayı npm run start komutuyla çalıştırıp pipeline’ı tetikliyorum. Ardından, konsolda herhangi bir hata mesajı almadan, yani herhangi bir kesinti olmadan deployment sürecini tamamlıyorum!

import fetch from "node-fetch";

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("https://deployment-slot-demo.azurewebsites.net/health");
 }, 50);
 setInterval(() => {
 check("https://deployment-slot-demo-staging.azurewebsites.net/health");
 }, 50);
})();

Benzer bir işlemi deployment slots özelliği uygulamayan bir App Service ile denersek, aşağıdaki gibi bir hata alırız.

2023-11-14T12:28:39.506Z, [some-url]/health error is request to [some-url]/health failed, reason: connect ETIMEDOUT 100.100.100.100:443

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

React-router-dom kullanarak bir React uygulamasını Docker ile Nginx'e nasıl deploy ederiz?

Sat, 21 Jan 2023 00:00:00 +0300

Bir React uygulamasını deploy etmek istiyorsanız, web sunucusuna deployment veya Docker gibi bir container aracı kullanma gibi birkaç seçenek mevcuttur. Bu kılavuzda, bir React uygulamasını Nginx kullanarak Docker ile nasıl deploy edebileceğimizi göreceğiz. Nginx, yüksek performansı ve düşük kaynak kullanımı ile tanınan popüler bir açık kaynaklı web sunucusudur. React uygulamamız için bir Docker dosyası oluşturacağız ve uygulamayı sunmak için Nginx’i kullanacağız. Ayrıca, Nginx’e uygulamayı nasıl sunacağını söylemek için bir Nginx yapılandırma dosyası da oluşturacağız. Son olarak, uygulamamızın bir Docker image’ini oluşturacak ve uygulamayı deploy etmek için bir Docker container çalıştıracağız.

Önkoşullar:

Docker hakkında temel bir bilgi
Deploy edilecek bir React uygulaması

Step 1: Create a Dockerfile

İlk adım, React uygulamamız için bir Docker dosyası oluşturmaktır. Bu dosya, uygulamamızın bir Docker görüntüsünü nasıl oluşturacağımıza dair talimatlar içerecektir. İşte Nginx ile bir React uygulaması için bir Docker dosyası örneği:

# Use an official Node runtime as a parent image
FROM node:19-alpine as build

# Set the working directory to /app
WORKDIR /app

# Copy the package.json and package-lock.json to the container
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy the rest of the application code to the container
COPY . .

# Build the React app
RUN npm run build

# Use an official Nginx runtime as a parent image
FROM nginx:1.21.0-alpine

# Copy the ngnix.conf to the container
COPY ngnix.conf /etc/nginx/conf.d/default.conf

# Copy the React app build files to the container
COPY --from=build /app/build /usr/share/nginx/html

# Expose port 80 for Nginx
EXPOSE 80

# Start Nginx when the container starts
CMD ["nginx", "-g", "daemon off;"]

Bu Docker dosyası, offical Node runtime ana image’i olarak kullanarak React uygulamasını kurmak ve derlemek için kullanır. Daha sonra React uygulamasını sunmak için resmi Nginx runtime ana image’ini base olarak kullanır.

Step 2: Create an Nginx configuration file

Sonraki adım olarak, Nginx’e uygulamamızı nasıl sunacağını söylemek için bir Nginx yapılandırma dosyası oluşturmamız gerekiyor. İşte bir örnek yapılandırma dosyası:

server {
listen 80;
server_name example.com;
root /usr/share/nginx/html;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}

Bu nginx.conf dosyasını Dockerfile ile aynı dizine oluşturmalısınız. Bu yapılandırma dosyası, Nginx’in port 80’de dinlemesini ve React uygulamasını sunmasını sağlar. try_files yönergesi, Nginx’e istenen dosyayı sunmaya çalışmasını, ardından dosyayı içeren dizini ve son olarak istenen dosya veya dizin mevcut değilse index.html dosyasını sunmaya çalışmasını söyler.

Step 3: Build the Docker image

Docker dosyası ve Nginx yapılandırma dosyası oluşturulduktan sonra, şimdi Docker image’i oluşturabiliriz. Docker dosyasını içeren dizine gidin ve aşağıdaki komutu çalıştırın:

docker build -t my-react-app .

Bu komut, Docker’a mevcut dizindeki Docker dosyasını kullanarak bir image oluşturmasını ve ona my-react-app adını etiketlemesini söyler. Komutun sonundaki nokta, Docker’ın oluşturma bağlamı olarak mevcut dizini kullanmasını sağlar.

Step 4: Run the Docker container

Oluşturulan Docker görüntüsüyle şimdi aşağıdaki komutu kullanarak bir container çalıştırabiliriz:

docker run -p 80:80 my-react-app

Bu komut, my-react-app Docker görüntüsünden bir konteyner oluşturur ve konteynerdeki 80 numaralı bağlantı noktasını ana makinedeki 80 numaralı bağlantı noktasına eşler. Ardından, web tarayıcınızda http://localhost adresine giderek React uygulamanıza erişebilirsiniz.

Tebrikler, bir React uygulamasını Nginx kullanarak Docker ile başarıyla dağıttınız! Artık bu yöntemi kullanarak React uygulamalarınızı Docker’ı destekleyen herhangi bir sunucuya veya sunucu platformuna kolayca deploy edebilirsiniz.

Step 5: Use Docker Compose to deploy the app

Uygulamanızı deploy etmek için daha basit bir yaklaşımı tercih ediyorsanız, container’larınızı yönetmek için Docker Compose’u kullanabilirsiniz. Docker Compose, çoklu container Docker uygulamalarını tanımlamanıza ve çalıştırmanıza olanak tanıyan bir araçtır.

Docker Compose’u kullanmak için, projenizin root dizininde bir docker-compose.yml dosyası oluşturmanız gerekecektir. İşte önceki Docker dosyasıyla kullanabileceğiniz bir örnek docker-compose.yml dosyası:

version: '3'

services:
 my-react-app:
 build:
 context: .
 dockerfile: Dockerfile
 ports:
 - "80:80"
 volumes:
 - ./ngnix.conf:/etc/nginx/conf.d/default.conf

Bu docker-compose.yml dosyasında, my-react-app adında tek bir servis tanımlıyoruz. Oluşturma bağlamını (.) ve Docker dosyasının adını Dockerfile olarak belirtiyoruz. Ayrıca, konteynerdeki 80 numaralı bağlantı noktasını ana makinedeki 80 numaralı bağlantı noktasına ports yapılandırması kullanarak eşleriz.

Son olarak, ana makinedeki ngnix.conf dosyasını konteynerin Nginx yapılandırma dizinindeki default.conf dosyasına eşleyen bir volume bağlarız. Bu, Docker görüntüsünü yeniden oluşturmadan Nginx yapılandırmasını özelleştirmemizi sağlar.

Bu docker-compose.yml dosyasını kullanmak için, sadece dosyayı içeren dizine gidin ve aşağıdaki komutu çalıştırın:


docker-compose up -d

Bu komut, Docker Compose’un my-react-app servisini Docker dosyasını kullanarak oluşturmasını ve bir konteyner çalıştırmasını söyler. -d bayrağı, konteynerin arka planda çalışmasını sağlayan detached modunda çalıştırır. Ardından, web tarayıcınızda http://localhost adresine giderek React uygulamanıza erişebilirsiniz.

Tebrikler! Bir React uygulamasını Nginx kullanarak Docker ve Docker Compose ile başarıyla dağıttınız. Artık React uygulamalarınızı Docker’ı destekleyen herhangi bir sunucuya veya barındırma platformuna kolayca dağıtabilirsiniz.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Bir şey nasıl çok iyi öğrenilir

Wed, 09 Mar 2022 10:01:10 +0300

Nasıl öğreneceğinizi öğrendiğinizde, bilgi ile dünyadaki hemen hemen tüm olasılıkların kilidini açarsınız. Bazılarınız pratiğin bilgiden daha önemli olduğunu düşünebilir, ama inanın bana, çalışma alanınız hakkında bir şey bilmiyorsanız, pratik yapamazsınız ve yapabilirseniz de işe yaramaz çünkü altta yatan süreçleri bilmiyorsunuzdur.

Bu kılavuz basit ve sonuç odaklıdır, bu harika kitapla konu hakkında daha fazla bilgi edinebilirsiniz.

Öğrenmeden önce

Zihin sabit değildir ve geliştirilebilir, sadece zihin ve IQ değil, entelektüel beceriler de çalışarak geliştirilebilir. Her şeyden önce sağlam bir öz disipline sahip olmalısınız, bu farklı şekillerde kazanılabilir, ancak kendi yolunuzu bulmalı ve izlemelisiniz. Dilerseniz askeri disiplin yöntemlerini takip edebilir, dilerseniz Uzakdoğu felsefelerine sadık kalabilirsiniz. Tamamen size kalmış.

Ve unutmayın, para gibi değerli şeyler birikir. Buna bilgi de dahildir ve ne kadar çok yeni şeyler öğrenirseniz, yeni şeyleri öğrenmek ve anlamlandırmak o kadar kolay olur.

Öğrenmek değil

Aynı konuyu tekrar tekrar çalışmak, aynı şeyleri tekrar tekrar okumak öğrenme hissi yaratabilir ama bu büyük ihtimalle yanlış bir duygudur. öğrenme duygusu ve akıcılık birbiriyle kolayca karıştırılabilir.

Kendinizi test etmeden devam etmeyin, bu şekilde öğrendiğinizi düşünebilirsiniz, ancak büyük olasılıkla bu da yanlış bir duygu olacaktır.

Yapılacak şeyler

Hafızadan hatırlama, tekrarlı okuma gibi yöntemlere göre çok daha harika bir yöntemdir. Makaleleri okurken cümlelerin veya paragrafların başında durun ve “Ana fikir nedir? Vermek istediğiniz mesaj nedir?” Bunun gibi sorular sormak, geri arama yöntemimiz için harika bir uygulamadır. Bu sayede öğrenilen konularla ilgili zihinsel bağlantılar güçlendirilecektir.

Bölüm sonu soruları ve kendi oluşturduğunuz sorular harika öğrenme yöntemleridir. Burada quizlerde ve sınavlarda kullanılabilir, Quizleri bir öğrenme aracı olarak kullanmak tehlike açısından alışılmışın dışında olabilir, ancak hatırlama için çok iyi çalışır ve sorulara verdiğiniz cevaplar önemlidir. Eksiklerinizi bu şekilde ortaya koyabilirsiniz ve bu alanları tamamlamak sizi ileriye taşıyacaktır.

Bu iki yöntem tamamen geri arama (callback) ile ilgilidir. Geri çağırma konusundaki son söz, ne kadar zorlayıcı olursa, etkilerinin o kadar kalıcı olacağıdır.

Blok çalışmanın kısa vadeli faydalarını kullanmak yerine, konuya aralıklı çalışma ile yaklaşmak bilgiyi daha kalıcı hale getirecektir. Gerekli aralık, çalışılan konuya ve kişiye bağlıdır. 1 gün, 1 hafta, 1 ay gibi. Bir konuyu periyodik olarak hatırlamaya çalışmak, onu hafızada kalıcı kılar ve artık bir refleks gibi olur.

Bir matematik konusuyla ilgili benzer soruları arka arkaya çözmek aşinalık hissi yaratır, ancak uygulama sırasında aynı konudaki diğer sorularla farklılıkları ve benzerlikleri görmenize yardımcı olmaz. Soruları çözerken soru tekrarı yaptığınızı fark ederseniz hemen farklı soru türlerine geçin.

Öğrendiğiniz konuya yeni anlam katmanları eklemek detaylandırmadır. Buna bir örnek, bir konuyu not alırken kendi cümlelerinizle ifade etmek ve gerçek hayatla ilişkisini incelemektir. Yeni öğrenilen konunun daha önce öğrendiklerinizle ilişkisini incelemek öğrenmeyi artırır. Konuyu kendiniz ve hayatınız ile ilişkilendirin.

Öğrenmeden önce üretin. Bir matematik sorusunu cevap verilmeden önce bildiklerinizle çözmeye çalışmak, çözüm anlatıldıktan sonra çözümü kavramanızı ve hatırlamanızı kolaylaştırır.

Geri çağırma ve detaylandırmayı harmanlayın. Bir konu veya dersten sonra kendinize sorun, “Nasıl gitti? Daha iyi olabilir mi? Bu sana geçmişten bir şey hatırlatıyor mu?” Bunun gibi sorular sormak öğrenmeye yardımcı olur ve buna yansıtma denir.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.

Her Geliştiricinin Sahip Olması Gereken 5 Temel Felsefe

Sun, 26 Sep 2021 00:00:00 +0300

Ben kendim, yazılımın bir işten önce bir yaşam felsefesi olduğunu düşünüyorum ve çoğu sorunu bir yazılım geliştirici olarak yaklaşarak ve bu şekilde çözerek büyük keyif alıyorum. Bu makalede, bu felsefenin temel taşlarından bahsedeceğim.

İçindekiler

Sorumlu bir kişi olun
Kodunuzda hiçbir şeyi mahvetmeyin
Mükemmeliyetçi olmayın
Varlığınız bilginizdir
Topluluğunuzu geliştirin!

Sorumlu bir kişi olun

Bir programcı olarak, yazdığınız JavaScript kodunda bir hata varsa, bu hatanın nedeninin C++ derleyicisi olduğunu söyleyemezsiniz. Bu saçma gelebilir, ancak bu durumu kendinize uyarlamayı düşünün!

Bir iş almadan önce, o işin gereksinimlerini iyi planlayın çünkü projede uzun bir yol kat ettiğinizde ve bir müşteriye veya patronunuza gittiğinizde size geçerli bir soru sorarlar, “neden bunu önceden düşünmediniz” Bu tür durumları göz önünde bulundurarak işe koyulursanız, karşılaşabileceğiniz herhangi bir soruya hazırlıklı olun. Ancak verdiğiniz cevap kesinlikle “bu imkansız yapılacak bir şey değil!” olmamalıdır. O problem için uygun farklı çözüm alternatifleri sunmaya çalışmalısınız.

Kodunuzda hiçbir şeyi mahvetmeyin

Yazılımı bir bina gibi düşünün, bir apartmandaki bir pencere kırıldığında ve onarılmadığında, başka bir pencere kırıldığında ve kimse ilgilenmezse, bu böyle devam eder ve sonunda duvarlara grafiti yazılmaya başlar ve bina tamamen düzensiz hale gelir. Sonra; asla kırık bir camla yaşamayın. Bu yazılım için kırık cam örneği, gelecekteki hatalara yol açabilecek kötü tasarımı ve kötü bir kodu içerebilir.

Aslında bu durum oldukça bilimsel, fizikte entropiyi düşünürseniz, düzensizlik her zaman artmak ister. Bunu engellememek size bağlıdır. Yazılımda bir hata varsa, yeni bir özellik eklemeye odaklanmaktan önce onu düzeltmeye odaklanın ve devam edin. Bunu yapamam dediğinizde değil, yaptım dediğinizde durun.

Mükemmeliyetçi olmayın

Harika bir fikriniz varsa, üzerinde bir yıl veya iki yıl çalıştıktan ve yayınladıktan sonra, geri bildirimlerden öğrenmek çok hayal kırıklığı olabilir ve gerçekten değersiz bir fikir olduğunu öğrenmek. Herhangi bir projede kusursuz ilerlemeden önce, o projenin temel özelliklerine sahip bir MVP’ye sahip olmak ve onu yayınlamak, geri bildirimleri değerlendirmek ve her şey yolundaysa ilerlemek çok daha mantıklıdır.

Kısacası, mükemmeliyetçilik genellikle yazılım için işe yaramaz. Üründen emin olmak ve sonra onu mükemmelleştirmek daha iyi bir fikirdir. Sonuç olarak, dünya her gün değişiyor ve her dakika yeni teknolojiler ve ürünler ortaya çıkıyor!

Varlığınız bilginizdir

Bilginiz ve deneyiminiz en önemli varlığınızdır. Ancak bu varlıklar zamanla eskimiş olabilir, özellikle teknoloji dünyasında, her şey çok hızlı bir şekilde değişiyor. Bir yıl önce sahip olduğunuz değerli varlıklar şimdi değersiz olabilir. Bu yüzden güncel kalmaya odaklanmalısınız.

Bir bilgi ve deneyim portföyünü yönetmek, finansal varlıkları yönetmek gibi belirli gereksinimlere sahiptir;

Ciddi yatırımcılar alışkanlık olarak düzenli olarak yatırım yaparlar: Düzenli olarak yatırım yaparsanız, ne kadar az veya çok kazanırsanız kazanın, toplamda büyük bir kar elde edersiniz.
Çeşitlendirme uzun vadeli başarının anahtarıdır: Ne kadar fazla teknolojiye hakim olursanız, değişime o kadar iyi adapte olabilirsiniz.
Akıllı yatırımcılar portföylerini düşük risk, düşük getiri ve yüksek risk, yüksek getiri yatırımları arasında dengelemektedir: Tüm varlığınızı (zaman ve çaba) gelecekte değerli olacağını düşündüğünüz yüksek getirili bir varlığa yatırmak yerine, varlığınızı güvenli dall

ara dalın ve varlığınızı aynı kutuya koymayın.

Yatırımcılar maksimum getiri için düşük al ve yüksek satın: Gelecekte değer kazanacağını düşündüğünüz varlıklara yatırım yapmak büyük getiriler sağlayabilir.
Portföyler periyodik olarak gözden geçirilmeli ve yeniden dengelenmelidir: Çok dalgalı bir endüstride iş yapıyoruz, bu yüzden yatırımlarınızı düzenli olarak gözden geçirmeli ve değer kaybeden varlıklara dikkat etmelisiniz.

Ancak tüm bu hedeflerin en önemlisi ve vazgeçilmezi düzenli olarak yatırım yapmaktır. Yatırım yapmazsanız, nereye yatırım yaparsanız yapmanızın bir önemi yoktur. Bu hedeflere ulaşmanın bir aracı olarak kullanabileceğiniz birkaç araç aşağıda verilmiştir.

Her yıl en az bir yeni dil öğrenin. Farklı diller aynı sorunları farklı yollarla çözer. Farklı yaklaşımları öğrenmek düşünme yeteneğinizi genişletebilir ve rutine sıkışıp kalmaktan kaçınmanıza yardımcı olabilir.
Her çeyrek teknik bir kitap okuyun. Alışkanlık kazandıktan sonra, ayda bir kitap okuyun. Kullanmakta olduğunuz teknolojileri öğrendikten sonra, farklı dallarda çalışın ve ilgisiz dallarda çalışın.
Teknik olmayan kitaplar da okuyun. Bilgisayarlar insanlar içindir ve insanları daha iyi anlarsanız, onların çözümlerine çok daha iyi yaklaşabilirsiniz.
Yerel kullanıcı gruplarına katılın. Sadece gitmeyin ve dinlemeyin, aktif olarak katılın. İzolasyon kariyerinize ölümcül olabilir.

Bu teknolojilerden herhangi birini bir projede kullansanız veya hatta özgeçmişinize koyduğunuzda önemli değil. Bunları öğrenmek öğrenme yeteneğinizi artırır ve problem çözme yeteneğinize katkı sağlar.

Bir sorunla karşılaşırsanız ve bunun cevabını bilmiyorsanız, bu sorunu bir hedef olarak seçin ve öğrenmeye çalışın. Etrafınızda bir guruya sorun, etrafınızda yoksa çevrimiçi bir tane bulun. Bu hem sorunu yanıtlayacak hem de ağınızı genişletecektir. Sürekli olarak öğrenmeye devam edin. Otobüste seyahat ederken okuyacak bir şey taşıyın ve değerlendirin.

Bir kitapçının size pazarladığı ürünün en iyi ürünü olmadığı gibi, arama motorlarında ilk sıralara çıkan içeriğe güvenmeyin, doğruluğunu düşünün ve kafanızda tartın ve sorgusuz sualsiz kabul etmeyin.

Topluluğunuzu geliştirin!

Etkili iletişiminiz olmadığında iyi bir fikir yetimdir. Geliştiriciler olarak, son kullanıcılarla iletişim kurarken veya belgeler oluştururken, patronlarımız veya üstlerimizle iletişim kurarken iletişim becerilerimizi kullanıyoruz. İletişim becerilerinizi güçlendirmenin birkaç yolu şunlardır;

Bir programcı olarak göreviniz kelime oyunları oynamak değil, istediğiniz bilgileri doğru ve net bir şekilde iletmektir. Ne demek istediğinizi planlayın. Bir taslak yazın. Sonra kendinize sorun, “Bu söylemek istediğim her şeyi kapsıyor mu?” Bu gereksinimi karşılayana kadar tekrarlayın. Bu planı sadece bir belge yazarken değil, toplantılar ve konuşmalar öncesinde, hatta önemsediğiniz müşterilerle buluşmadan önce yapın.
Bilgi aktarabiliyorsanız, doğru iletişimi sağlayabilirsiniz. Bu nedenle, diğer kişinin karşılayabileceği bilgi seviyesini belirlemelisiniz.
İletişimin çeşitli yolları vardır. Bazı müşteriler e-posta ile bilgilendirilmek isteyebilirken, diğerleri telefonla aranmak isteyebilir.
İnsanların sizi dinlemesini istiyorsanız, yapmanız gereken ilk şey onları dinlemektir. Bir toplantıyı diyaloga dönüştürebilirseniz, bundan daha iyisi yoktur.
İnsanları bekletmeyin, size geri döneceğim, en kısa sürede cevaplayacağım gibi şeyler söyleyerek insanları bekletmeyin.

Sonuç

Okuduğunuz için teşekkürler! 🎉 Yazılım geliştirme alanındaki araştırmalarımı kaçırmamak için @berkslv adresinden takipte kalabilirsiniz.