<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Affan Emirhan Çüçen on Medium]]></title>
        <description><![CDATA[Stories by Affan Emirhan Çüçen on Medium]]></description>
        <link>https://medium.com/@affanccn?source=rss-778321f76ab2------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*fcC8cLS9o9jnjYOI-3FrJQ.jpeg</url>
            <title>Stories by Affan Emirhan Çüçen on Medium</title>
            <link>https://medium.com/@affanccn?source=rss-778321f76ab2------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 11:33:04 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@affanccn/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Flutter’da Isolate ve Background Worker Mimarisi: Compute vs Worker Isolate ile 120 FPS Akıcılık]]></title>
            <link>https://affanccn.medium.com/flutterda-isolate-ve-background-worker-mimarisi-compute-vs-worker-isolate-ile-120-fps-ak%C4%B1c%C4%B1l%C4%B1k-1aa820ee3808?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/1aa820ee3808</guid>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[dart]]></category>
            <category><![CDATA[sendport]]></category>
            <category><![CDATA[concurrency]]></category>
            <category><![CDATA[receiveport]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 05:48:44 GMT</pubDate>
            <atom:updated>2026-11-02T05:48:44.022Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BWh9UciLMh2AO2oa8eeqyQ.jpeg" /></figure><h3>Flutter’da Isolate ve Background Worker Mimarisi: compute() vs Worker Isolate</h3><p>Flutter uygulamalarında akıcı bir kullanıcı deneyimi sunmak yalnızca iyi tasarlanmış widget’lar kullanmakla ilgili değildir. Uygulamanın arka planda gerçekleştirdiği işlemler de ekran performansını doğrudan etkiler.</p><p>Örneğin 10 MB boyutunda bir JSON yanıtını ayrıştırmak, büyük bir görseli işlemek veya yoğun kriptografik hesaplamalar gerçekleştirmek UI isolate üzerinde yapıldığında arayüzde takılmalar yaşanabilir. Flutter dünyasında bu durum <strong>UI Jank</strong> olarak adlandırılır.</p><p>Bir ekran 60 Hz yenileme hızında çalışıyorsa her kare için yaklaşık 16,67 milisaniye, 120 Hz ekranda ise yaklaşık 8,33 milisaniye bulunur. Bu süre yalnızca uygulama koduna ait değildir; Flutter’ın çizim işlemleri ve diğer işler de aynı kare bütçesini paylaşır.</p><p>Dolayısıyla uzun süren CPU ağırlıklı işlemleri arayüzün çalıştığı isolate üzerinden yürütmek performans sorunlarına neden olabilir.</p><p>Bu noktada Dart’ın <strong>Isolate</strong> mimarisi devreye girer.</p><p>Bu rehberde Dart Isolate yapısını, Flutter’ın compute() fonksiyonunu ve sürekli çalışan Worker Isolate mimarisini inceleyeceğiz.</p><h3>1. Dart Isolate’lar Nasıl Çalışır?</h3><p>Dart, Java veya C++ gibi geleneksel paylaşımlı bellek kullanan thread modellerinden farklı bir eşzamanlılık yaklaşımına sahiptir.</p><p>Dart uygulamaları isolate adı verilen bağımsız çalışma birimleri kullanır. Her isolate kendi:</p><ul><li>Bellek alanına (Heap)</li><li>Event Loop mekanizmasına</li><li>Değişkenlerine ve nesnelerine</li><li>Mesaj alma ve gönderme kanallarına</li></ul><p>sahiptir.</p><p>İki isolate aynı nesne belleğine doğrudan erişemez. Aralarında iletişim kurmak için SendPort ve ReceivePort kullanılır.</p><p>Basitleştirilmiş mimari:</p><pre>Flutter Uygulaması<br>                     |<br>              Main Isolate<br>                     |<br>              SendPort<br>                     |<br>              ReceivePort<br>                     |<br>              Worker Isolate<br>                     |<br>              CPU İşlemleri<br>                     |<br>              SendPort<br>                     |<br>              ReceivePort<br>                     |<br>              Main Isolate<br>                     |<br>               UI Güncelleme</pre><p>Bu yaklaşım, paylaşımlı bellek üzerinde oluşabilecek birçok yarış koşulunu önler. Ancak isolate kullanmak bütün eşzamanlılık problemlerini otomatik olarak ortadan kaldırmaz. Mesaj sıralaması, kaynak yönetimi ve işlemlerin yaşam döngüsü yine uygulama tarafından yönetilmelidir.</p><p>Burada bir başka önemli ayrım da async / await konusudur.</p><pre>Future&lt;void&gt; loadData() async {<br>  final data = await apiService.getData();<br>  final result = jsonDecode(data);<br>}</pre><p>Bu kodda await, ağ isteğinin tamamlanmasını beklerken event loop&#39;un başka işlerle ilgilenmesine izin verir. Ancak jsonDecode çalışmaya başladığında CPU işlemi mevcut isolate üzerinde senkron olarak yürütülür.</p><p>Yani async / await tek başına CPU ağırlıklı işlemleri arka plana taşımaz.</p><h3>2. Tek Seferlik İşlemler İçin: compute()</h3><p>Tek seferlik ve birbirinden bağımsız CPU ağırlıklı işlemler için Flutter’ın compute() fonksiyonu oldukça kullanışlıdır.</p><p>Örneğin büyük bir JSON yanıtını ayrıştırmak için yeni bir Worker mimarisi kurmak yerine compute() kullanabiliriz.</p><p>Öncelikle JSON ayrıştırma fonksiyonunu tanımlayalım:</p><pre>import &#39;dart:convert&#39;;</pre><pre>import &#39;package:flutter/foundation.dart&#39;;</pre><pre>// Örnek model<br>class Product {<br>  final int id;<br>  final String name;<br>  final double price;</pre><pre>  Product({<br>    required this.id,<br>    required this.name,<br>    required this.price,<br>  });</pre><pre>  factory Product.fromJson(Map&lt;String, dynamic&gt; json) {<br>    return Product(<br>      id: json[&#39;id&#39;] as int,<br>      name: json[&#39;name&#39;] as String,<br>      price: (json[&#39;price&#39;] as num).toDouble(),<br>    );<br>  }<br>}</pre><pre>// Top-level fonksiyon<br>List&lt;Product&gt; parseProducts(String rawJson) {<br>  final List&lt;dynamic&gt; parsedList = jsonDecode(rawJson);</pre><pre>  return parsedList<br>      .map(<br>        (item) =&gt; Product.fromJson(<br>          item as Map&lt;String, dynamic&gt;,<br>        ),<br>      )<br>      .toList();<br>}</pre><p>Şimdi UI katmanında bu fonksiyonu çağırabiliriz:</p><pre>Future&lt;void&gt; loadProducts() async {<br>  final rawResponse = await apiService.getRawCatalog();</pre><pre>  final products = await compute(<br>    parseProducts,<br>    rawResponse,<br>  );</pre><pre>  print(<br>    &#39;${products.length} ürün başarıyla ayrıştırıldı.&#39;,<br>  );<br>}</pre><p>Burada compute() fonksiyonuna gönderdiğimiz callback&#39;in isolate dışında çalışabilecek şekilde tasarlanması gerekir. Top-level veya static fonksiyon kullanmak bu nedenle yaygın bir yaklaşımdır.</p><p>Ayrıca gönderilen ve döndürülen verilerin isolate’lar arasında aktarılabilir olması gerekir. Karmaşık nesneler, açık kaynaklar ve bazı özel nesne türleri doğrudan taşınamayabilir.</p><p><strong>compute() nasıl çalışır?</strong></p><p>Native platformlarda compute(), verilen işlemi ayrı bir isolate üzerinde çalıştırır. İşlem tamamlandığında sonucu ana isolate&#39;a döndürür ve geçici isolate&#39;ın yaşam döngüsünü yönetir.</p><p>Ancak önemli bir platform farkı vardır:</p><ul><li>Android, iOS ve diğer native platformlarda ayrı isolate kullanılır.</li><li>Flutter Web üzerinde compute() callback&#39;i mevcut event loop üzerinde çalışır; native platformlardaki gibi gerçek arka plan isolate paralelliği sağlamaz.</li></ul><p>Bu nedenle büyük JSON ayrıştırma gibi CPU ağırlıklı işlemlerde platform farklarını dikkate almak gerekir.</p><h3>3. Sürekli İşlemler İçin: Worker Isolate</h3><p>Her işlem için yeni bir isolate başlatmak bazı senaryolarda gereksiz maliyet oluşturabilir.</p><p>Örneğin:</p><ul><li>Sürekli gelen WebSocket verilerinin ayrıştırılması</li><li>Kamera görüntülerinin işlenmesi</li><li>Büyük veri kümeleri üzerinde tekrarlanan hesaplamalar</li><li>Sürekli çalışan dosya dönüştürme işlemleri</li></ul><p>gibi durumlarda uzun ömürlü bir Worker Isolate daha uygun olabilir.</p><p>Bu mimaride isolate bir kez başlatılır ve uygulama ihtiyaç duydukça ona mesaj gönderir.</p><p>Örnek olarak bir görüntü işleme Worker’ı oluşturalım.</p><p><strong>Worker mimarisi:</strong></p><pre>Main Isolate<br>     |<br>     | İş isteği<br>     v<br>SendPort<br>     |<br>     v<br>Worker Isolate<br>     |<br>     | Görüntü işleme<br>     |<br>     v<br>Sonuç mesajı<br>     |<br>     v<br>Main Isolate</pre><p>Öncelikle Worker sınıfını oluşturalım:</p><pre>// core/isolate/image_processor_worker.dart</pre><pre>import &#39;dart:async&#39;;<br>import &#39;dart:isolate&#39;;</pre><pre>class ImageProcessorWorker {<br>  SendPort? _workerSendPort;</pre><pre>  Isolate? _isolate;</pre><pre>  ReceivePort? _mainReceivePort;</pre><pre>  final Map&lt;int, Completer&lt;List&lt;int&gt;&gt;&gt; _pendingTasks = {};</pre><pre>  final Completer&lt;void&gt; _readyCompleter = Completer&lt;void&gt;();</pre><pre>  int _taskCounter = 0;</pre><pre>  Future&lt;void&gt; init() async {<br>    _mainReceivePort = ReceivePort();</pre><pre>    _isolate = await Isolate.spawn(<br>      _workerEntryPoint,<br>      _mainReceivePort!.sendPort,<br>    );</pre><pre>    _mainReceivePort!.listen((message) {<br>      if (message is SendPort) {<br>        // Worker hazır olduğunu bildiriyor.<br>        _workerSendPort = message;</pre><pre>        if (!_readyCompleter.isCompleted) {<br>          _readyCompleter.complete();<br>        }</pre><pre>        return;<br>      }</pre><pre>      if (message is Map) {<br>        final taskId = message[&#39;id&#39;] as int;</pre><pre>        final completer = _pendingTasks.remove(taskId);</pre><pre>        if (completer == null) return;</pre><pre>        if (message[&#39;error&#39;] != null) {<br>          completer.completeError(<br>            Exception(message[&#39;error&#39;]),<br>          );<br>        } else {<br>          completer.complete(<br>            List&lt;int&gt;.from(message[&#39;result&#39;]),<br>          );<br>        }<br>      }<br>    });<br>    <br>    await _readyCompleter.future;<br>  }</pre><pre>  // Worker Isolate&#39;ın giriş noktası.<br>  static void _workerEntryPoint(SendPort mainSendPort) {<br>    final workerReceivePort = ReceivePort();</pre><pre>    // Ana isolate&#39;a kendi SendPort&#39;unu gönder.<br>    mainSendPort.send(workerReceivePort.sendPort);</pre><pre>    workerReceivePort.listen((message) {<br>      if (message == &#39;shutdown&#39;) {<br>        workerReceivePort.close();<br>        return;<br>      }</pre><pre>      if (message is! Map) return;</pre><pre>      final taskId = message[&#39;id&#39;] as int;</pre><pre>      final bytes = List&lt;int&gt;.from(message[&#39;bytes&#39;]);</pre><pre>      try {<br>        final processedBytes = _heavyImageResize(bytes);</pre><pre>        mainSendPort.send({<br>          &#39;id&#39;: taskId,<br>          &#39;result&#39;: processedBytes,<br>        });<br>      } catch (error) {<br>        mainSendPort.send({<br>          &#39;id&#39;: taskId,<br>          &#39;error&#39;: error.toString(),<br>        });<br>      }<br>    });<br>  }</pre><pre>  // Ana isolate üzerinden işlem gönder.<br>  Future&lt;List&lt;int&gt;&gt; processImage(List&lt;int&gt; bytes) async {<br>    await _readyCompleter.future;</pre><pre>    final sendPort = _workerSendPort;</pre><pre>    if (sendPort == null) {<br>      throw StateError(&#39;Worker başlatılamadı.&#39;);<br>    }</pre><pre>    final taskId = ++_taskCounter;</pre><pre>    final completer = Completer&lt;List&lt;int&gt;&gt;();</pre><pre>    _pendingTasks[taskId] = completer;</pre><pre>    sendPort.send({<br>      &#39;id&#39;: taskId,<br>      &#39;bytes&#39;: bytes,<br>    });</pre><pre>    return completer.future;<br>  }</pre><pre>  // Worker kaynaklarını temizle.<br>  Future&lt;void&gt; dispose() async {<br>    _workerSendPort?.send(&#39;shutdown&#39;);</pre><pre>    _mainReceivePort?.close();</pre><pre>    _isolate?.kill(priority: Isolate.immediate);</pre><pre>    _workerSendPort = null;<br>    _isolate = null;<br>    _mainReceivePort = null;</pre><pre>    for (final task in _pendingTasks.values) {<br>      if (!task.isCompleted) {<br>        task.completeError(<br>          StateError(&#39;Worker kapatıldı.&#39;),<br>        );<br>      }<br>    }</pre><pre>    _pendingTasks.clear();<br>  }</pre><pre>  static List&lt;int&gt; _heavyImageResize(List&lt;int&gt; bytes) {<br>    // Temsili yoğun CPU işlemi.<br>    // Gerçek uygulamada görüntü işleme algoritması kullanılabilir.</pre><pre>    int sum = 0;</pre><pre>    for (int i = 0; i &lt; 1000000; i++) {<br>      sum += i % 255;<br>    }</pre><pre>    return bytes.reversed.toList();<br>  }<br>}</pre><p>Bu örnekte birkaç önemli tasarım tercihi bulunuyor:</p><p><strong>1. Worker tek sefer başlatılıyor.</strong></p><p>init() çağrısıyla isolate oluşturuluyor ve sonraki işlemlerde aynı Worker kullanılıyor.</p><p><strong>2. SendPort ve ReceivePort çift yönlü iletişim sağlıyor.</strong></p><p>Ana isolate iş gönderirken Worker sonuçları ana isolate’a geri iletiyor.</p><p><strong>3. Task ID kullanılıyor.</strong></p><p>Birden fazla işlem aynı anda gönderildiğinde sonuçların hangi isteğe ait olduğunu anlamak için her göreve benzersiz bir ID veriliyor.</p><p><strong>4. Hata yönetimi bulunuyor.</strong></p><p>Worker içerisindeki bir işlem başarısız olduğunda ilgili Completer hata ile tamamlanıyor.</p><p>Bu örnek temel Worker yaşam döngüsünü gösterir. Üretim ortamında isolate hata ve çıkış portları (onError, onExit) da izlenmeli; başlatma başarısızlıkları, zaman aşımı, kapatma sırasında devam eden işler ve yeniden başlatma senaryoları ayrıca ele alınmalıdır.</p><p>Ayrıca List&lt;int&gt; gibi büyük veriler mesajla gönderildiğinde veri kopyalama maliyeti oluşabilir. Büyük binary veriler için TransferableTypedData kullanmak, uygun senaryolarda aktarım maliyetini azaltabilir.</p><h3>4. compute() ve Worker Isolate Karşılaştırması</h3><p>İki yaklaşım da CPU ağırlıklı işlemleri UI isolate dışına taşımaya yardımcı olur. Ancak kullanım amaçları farklıdır.</p><p>Kritercompute()Worker IsolateKullanım amacıTek seferlik işlemlerSürekli veya tekrarlanan işlemlerBaşlatmaHer çağrıda geçici isolateUygulama başına bir kezYaşam döngüsüOtomatik yönetilirManuel yönetilirMesajlaşmaBasitleştirilmiş veri aktarımıSendPort / ReceivePortKod karmaşıklığıDüşükDaha yüksekUygun senaryoJSON parse, tek seferlik hesaplamaKamera, sürekli veri işleme, Worker görevleri</p><p>Burada compute() için her zaman 10-20 milisaniye gibi sabit bir başlatma maliyeti vermek doğru değildir. Bu süre cihaz donanımına, platforma, isolate başlatma maliyetine ve aktarılan verinin boyutuna göre değişir.</p><p>Benzer şekilde Worker Isolate kullanmak her durumda daha hızlı sonuç vermez. Çok küçük işlemlerde mesajlaşma ve veri aktarımı maliyeti, elde edilen performans avantajından daha yüksek olabilir.</p><h3>5. Büyük Verilerde TransferableTypedData Kullanımı</h3><p>Isolate’lar arasında veri aktarırken dikkat edilmesi gereken konulardan biri bellek kopyalama maliyetidir.</p><p>Özellikle büyük görsel veya binary veriler gönderildiğinde standart mesajlaşma mekanizması ek bellek ve işlem maliyeti oluşturabilir.</p><p>Dart’ın TransferableTypedData sınıfı bu tür durumlar için geliştirilmiştir.</p><p>Örnek:</p><pre>import &#39;dart:isolate&#39;;<br>import &#39;dart:typed_data&#39;;</pre><pre>Future&lt;Uint8List&gt; processBinaryData(<br>  Uint8List bytes,<br>) async {<br>  final transferable = TransferableTypedData.fromList([<br>    bytes,<br>  ]);</pre><pre>  final result = await compute(<br>    processTransferableData,<br>    transferable,<br>  );</pre><pre>  return result;<br>}</pre><pre>Uint8List processTransferableData(<br>  TransferableTypedData data,<br>) {<br>  final bytes = data.materialize().asUint8List();</pre><pre>  // Binary veri üzerinde yoğun işlem.<br>  return Uint8List.fromList(bytes.reversed.toList());<br>}</pre><p>TransferableTypedData, verinin isolate&#39;lar arasında aktarılmasını daha verimli hâle getirebilir. Ancak oluşturma ve materialize işlemlerinin de maliyeti vardır. Bu nedenle her küçük veri aktarımında kullanmak yerine büyük veri senaryolarında performans ölçümü yapmak daha doğrudur.</p><h3>6. Performans İçin Mimari Öneriler</h3><p>Isolate kullanımı, Flutter performansını iyileştirmek için önemli bir araçtır. Ancak her işlemi arka plana taşımak doğru yaklaşım değildir.</p><p>Aşağıdaki prensipler daha sağlıklı bir mimari kurmaya yardımcı olur:</p><ul><li><strong>UI isolate’ı hafif tutun:</strong> Widget oluşturma, animasyon ve kullanıcı etkileşimlerini gereksiz CPU işlemleriyle bloke etmeyin.</li><li><strong>CPU ağırlıklı işlemleri ayırın:</strong> Büyük JSON ayrıştırma, görüntü işleme ve karmaşık hesaplamaları gerektiğinde Worker’a taşıyın.</li><li><strong>I/O işlemlerini doğru yönetin:</strong> Ağ ve dosya bekleme işlemleri çoğunlukla async / await ile yönetilebilir. Her I/O işlemi için yeni isolate açmaya gerek yoktur.</li><li><strong>Veri aktarım maliyetini hesaba katın:</strong> Büyük nesnelerin isolate’lar arasında taşınması da zaman ve bellek tüketir.</li><li><strong>Gereksiz isolate oluşturmayın:</strong> Küçük işlemlerde isolate başlatma maliyeti, işlemin kendisinden daha yüksek olabilir.</li><li><strong>Performansı ölçün:</strong> Flutter DevTools Performance ekranıyla kare sürelerini, jank oluşumunu ve CPU kullanımını inceleyin.</li></ul><p>Özellikle 120 Hz ekranlarda kare bütçesi yaklaşık 8,33 milisaniyedir. Ancak tüm işlemler için evrensel bir 5 milisaniye sınırı yoktur. Uygulamanın gerçek performansı cihaz, ekran yenileme hızı, GPU yükü ve Flutter’ın çizim süreçleriyle birlikte değerlendirilmelidir.</p><h3>Sonuç</h3><p>Flutter uygulamalarında akıcı bir kullanıcı deneyimi oluşturmak için yalnızca widget optimizasyonu yeterli değildir. CPU ağırlıklı işlemlerin doğru yerde çalıştırılması da mimarinin önemli bir parçasıdır.</p><p>Dart Isolate yapısı, bağımsız bellek alanları ve mesajlaşma mekanizması sayesinde ağır hesaplamaları UI isolate dışına taşıma imkânı sunar.</p><p>Tek seferlik işlemlerde compute() pratik bir çözüm sağlarken, sürekli çalışan ve birden fazla görev yöneten sistemlerde Worker Isolate mimarisi daha esnek bir yapı sunar.</p><p>Önemli olan her işlemi arka plana taşımak değil, işlemin niteliğine göre doğru eşzamanlılık modelini seçmektir.</p><p><strong>Performanslı bir Flutter uygulamasının sırrı, UI isolate’ı gereksiz işlerden arındırmak ve işlem yükünü doğru şekilde dağıtmaktır.</strong></p><h3>Kaynaklar</h3><ul><li><a href="https://dart.dev/language/concurrency">Dart — Concurrency and Isolates</a></li><li><a href="https://docs.flutter.dev/packages-and-plugins/background-processes">Flutter — Background Processes</a></li><li><a href="https://api.flutter.dev/flutter/foundation/compute.html">Dart API — compute()</a></li><li><a href="https://api.dart.dev/dart-isolate/Isolate-class.html">Dart API — Isolate</a></li><li><a href="https://api.dart.dev/dart-isolate/TransferableTypedData-class.html">Dart API — TransferableTypedData</a></li><li><a href="https://docs.flutter.dev/tools/devtools/performance">Flutter DevTools — Performance View</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1aa820ee3808" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dağıtık Sistemlerde Idempotency Mimarisi: Node.js ve Redis ile Güvenli Ödeme Yönetimi]]></title>
            <link>https://affanccn.medium.com/da%C4%9F%C4%B1t%C4%B1k-sistemlerde-idempotency-mimarisi-node-js-ve-redis-ile-g%C3%BCvenli-%C3%B6deme-y%C3%B6netimi-1fb1de663004?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/1fb1de663004</guid>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[microservices]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 05:46:26 GMT</pubDate>
            <atom:updated>2026-11-02T05:46:26.637Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N61tE4PGyF2VxnXOSjINuw.jpeg" /></figure><h3>Dağıtık Sistemlerde Idempotency Mimarisi: Node.js ve Redis ile Güvenli Ödeme Yönetimi</h3><p>Dağıtık mimarilerde ağ bağlantılarının her zaman güvenilir olacağını varsayamayız. Bir mobil kullanıcı satın alma butonuna bastığında, ödeme sağlayıcısı işlemi başarıyla tamamlayabilir ancak sunucu yanıtı istemciye ulaşmadan bağlantı kopabilir.</p><p>Kullanıcı işlemin başarısız olduğunu düşünerek tekrar denediğinde backend aynı ödemeyi yeniden gerçekleştirirse ciddi bir problem ortaya çıkar: <strong>Müşteriden iki kez para çekilebilir.</strong></p><p>Bu senaryoyu yalnızca istemci tarafında butonu devre dışı bırakarak çözmek mümkün değildir. İstekler ağ katmanında tekrarlanabilir, proxy veya istemci yeniden deneme yapabilir ve sunucu bir işlemin sonucunu öğrenemeden bağlantı kesilebilir.</p><p>Bu noktada devreye <strong>Idempotency (Eşgüçlülük)</strong> kavramı girer.</p><p>Idempotency, aynı işlemin aynı kimlikle tekrar gönderilmesi durumunda sistemin yeni bir yan etki üretmek yerine önceki işlemin sonucunu döndürmesini sağlayan tasarım yaklaşımıdır.</p><p>Bu rehberde Node.js, Express ve Redis kullanarak idempotency mekanizmasını inceleyeceğiz. Ayrıca gerçek ödeme sistemlerinde Redis’in tek başına yeterli olmadığını ve ödeme sağlayıcısıyla birlikte nasıl kullanılacağını ele alacağız.</p><h3>1. Idempotency Nedir ve Neden Gereklidir?</h3><p>Matematiksel olarak idempotent bir işlem şu şekilde ifade edilir:</p><p>[ f(f(x)) = f(x) ]</p><p>Yani bir işlem bir kez uygulandığında ortaya çıkan sonuç, aynı işlem tekrar uygulandığında değişmez.</p><p>HTTP tarafında bunun en bilinen örneği GET isteğidir. Bir kaynağı tekrar tekrar okumak normal şartlarda sunucu durumunu değiştirmez.</p><p>Ancak POST gibi durum değiştiren isteklerde aynı garanti varsayılan olarak bulunmaz.</p><p>Örneğin:</p><pre>POST /api/orders/checkout<br>Content-Type: application/json</pre><pre>{<br>  &quot;cartId&quot;: &quot;cart_123&quot;,<br>  &quot;amount&quot;: 1500<br>}</pre><p>Bu istek iki kez gönderildiğinde uygulama iki ayrı sipariş oluşturabilir.</p><p>Bunu önlemek için istemci her mantıksal işlem için benzersiz bir Idempotency-Key üretir:</p><pre>POST /api/orders/checkout<br>Idempotency-Key: 8f2d9c1a-7b4e-4a2c-9e1d-123456789abc<br>Content-Type: application/json</pre><p>Aynı ödeme işleminin yeniden denenmesi durumunda aynı anahtar kullanılmalıdır.</p><p>Yeni bir ödeme veya yeni bir sipariş için ise yeni bir anahtar üretilmelidir.</p><p>Burada önemli ayrım şudur: Idempotency Key, her HTTP isteği için değil, kullanıcının gerçekleştirmek istediği tek bir mantıksal işlem için oluşturulur.</p><h3>2. Idempotency Yaşam Döngüsü ve Durum Makinesi</h3><p>Bir istek Idempotency-Key başlığıyla geldiğinde sistemin temel olarak üç durumu yönetmesi gerekir.</p><p><strong>1. STARTED — İşlem Başlatıldı</strong></p><p>İstek ilk kez geldiğinde Redis üzerinde atomik bir kayıt oluşturulur. Bu kayıt, aynı anahtarla gelen diğer isteklerin işlemi tekrar başlatmasını engeller.</p><p><strong>2. COMPLETED — İşlem Tamamlandı</strong></p><p>İşlem başarıyla sonuçlandığında HTTP durum kodu ve yanıt gövdesi saklanır. Aynı anahtarla gelen sonraki isteklerde kayıtlı yanıt döndürülür.</p><p><strong>3. IN_PROGRESS — İşlem Devam Ediyor</strong></p><p>İlk istek henüz tamamlanmadan aynı anahtarla ikinci bir istek geldiğinde sistem yeni bir işlem başlatmaz. İstemciye 409 Conflict döndürerek işlemin devam ettiğini bildirir.</p><p>Örnek akış:</p><pre>İstemci                  Express API                 Redis<br>   |                         |                         |<br>   |--- POST + Key ---------&gt;|                         |<br>   |                         |--- SET NX EX ----------&gt;|<br>   |                         |&lt;-- Kilit alındı ---------|<br>   |                         |                         |<br>   |                         |--- Ödeme sağlayıcısı --&gt;|<br>   |                         |                         |<br>   |--- POST + Aynı Key ----&gt;|                         |<br>   |                         |--- GET kayıt ----------&gt;|<br>   |                         |&lt;-- STARTED -------------|<br>   |&lt;-- 409 Conflict --------|                         |<br>   |                         |                         |<br>   |                         |&lt;-- Ödeme başarılı ------|<br>   |                         |                         |<br>   |                         |--- COMPLETED ----------&gt;|<br>   |&lt;-- 201 Created ---------|                         |<br>   |                         |                         |<br>   |--- POST + Aynı Key ----&gt;|                         |<br>   |                         |--- GET kayıt ----------&gt;|<br>   |                         |&lt;-- Önceki yanıt ---------|<br>   |&lt;-- 201 Created ---------|                         |</pre><p>Bu yapının temelinde Redis’in atomik SET NX EX komutu bulunur:</p><pre>SET idempotency:abc-123 STARTED NX EX 120</pre><ul><li>NX: Anahtar yalnızca daha önce mevcut değilse oluşturulur.</li><li>EX: Kayda saniye cinsinden yaşam süresi verir.</li><li>SET: Kilit oluşturma işlemini atomik şekilde gerçekleştirir.</li></ul><p>Böylece aynı anda gelen iki isteğin de ilk işlemmiş gibi davranması engellenir.</p><h3>3. Node.js ve Redis ile Idempotency Middleware</h3><p>Öncelikle Express ve Redis bağlantısını hazırlayalım.</p><pre>npm install express ioredis<br>npm install -D typescript @types/express @types/node</pre><p>Redis bağlantısı:</p><pre>// config/redis.ts</pre><pre>import Redis from &quot;ioredis&quot;;</pre><pre>export const redis = new Redis(<br>  process.env.REDIS_URL ?? &quot;redis://localhost:6379&quot;,<br>  {<br>    maxRetriesPerRequest: 1,<br>    enableReadyCheck: true<br>  }<br>);</pre><p>Şimdi middleware mekanizmasını oluşturalım.</p><p>Burada önemli bir tasarım tercihi yapıyoruz: res.json() metodunu ezmek yerine, işlem sonucunu açıkça kaydeden bir yardımcı fonksiyon kullanacağız.</p><p>Çünkü Express yanıtını gönderdikten sonra Redis’e asenkron kayıt yapmak, Redis yazımı tamamlanmadan aynı anahtarla yeni bir isteğin gelmesine neden olabilir. Bu da tekrar işlem riskini doğurur.</p><p>Önce istek üzerinde kullanılacak idempotency yardımcı fonksiyonunun tipini tanımlayalım:</p><pre>// types/idempotency.ts</pre><pre>import { Request } from &quot;express&quot;;</pre><pre>export interface IdempotencyContext {<br>  key: string;</pre><pre>  complete: (<br>    statusCode: number,<br>    body: unknown<br>  ) =&gt; Promise&lt;void&gt;;<br>}</pre><pre>export type IdempotentRequest = Request &amp; {<br>  idempotency?: IdempotencyContext;<br>};</pre><p>Şimdi middleware:</p><pre>// middleware/idempotency.ts</pre><pre>import {<br>  Request,<br>  Response,<br>  NextFunction<br>} from &quot;express&quot;;</pre><pre>import { createHash, randomUUID } from &quot;node:crypto&quot;;<br>import { redis } from &quot;../config/redis&quot;;<br>import { IdempotentRequest } from &quot;../types/idempotency&quot;;</pre><pre>const LOCK_TTL = 120;<br>const RESULT_TTL = 86400;</pre><pre>const COMPLETE_SCRIPT = `<br>  local current = redis.call(&quot;GET&quot;, KEYS[1])</pre><pre>  if not current then<br>    return 0<br>  end</pre><pre>  local record = cjson.decode(current)</pre><pre>  if record.owner ~= ARGV[1] then<br>    return 0<br>  end</pre><pre>  redis.call(<br>    &quot;SET&quot;,<br>    KEYS[1],<br>    ARGV[2],<br>    &quot;EX&quot;,<br>    ARGV[3]<br>  )</pre><pre>  return 1<br>`;</pre><pre>export function idempotencyMiddleware() {<br>  return async (<br>    req: Request,<br>    res: Response,<br>    next: NextFunction<br>  ) =&gt; {<br>    if (![&quot;POST&quot;, &quot;PATCH&quot;].includes(req.method)) {<br>      return next();<br>    }</pre><pre>    const key = req.header(&quot;Idempotency-Key&quot;);</pre><pre>    // Bu middleware&#39;de anahtar zorunlu.<br>    if (!key) {<br>      return res.status(400).json({<br>        error: &quot;Idempotency-Key başlığı zorunludur.&quot;<br>      });<br>    }</pre><pre>    if (key.length &gt; 128) {<br>      return res.status(400).json({<br>        error: &quot;Idempotency-Key çok uzun.&quot;<br>      });<br>    }</pre><pre>    // Anahtarı kullanıcı ve işlem kapsamıyla sınırlandır.<br>    const userId = req.user?.id;</pre><pre>    if (!userId) {<br>      return res.status(401).json({<br>        error: &quot;Kimlik doğrulaması gerekli.&quot;<br>      });<br>    }</pre><pre>    const scope = [<br>      userId,<br>      req.method,<br>      req.baseUrl + req.path,<br>      key<br>    ].join(&quot;:&quot;);</pre><pre>    const redisKey = `idempotency:${scope}`;</pre><pre>    // İstek içeriğinin parmak izini oluştur.<br>    const fingerprint = createHash(&quot;sha256&quot;)<br>      .update(JSON.stringify(req.body))<br>      .digest(&quot;hex&quot;);</pre><pre>    const owner = randomUUID();</pre><pre>    try {<br>      // 1. Atomik olarak işlem kaydını oluştur.<br>      const acquired = await redis.set(<br>        redisKey,<br>        JSON.stringify({<br>          status: &quot;STARTED&quot;,<br>          owner,<br>          fingerprint<br>        }),<br>        &quot;EX&quot;,<br>        LOCK_TTL,<br>        &quot;NX&quot;<br>      );</pre><pre>      if (!acquired) {<br>        // 2. Anahtar daha önce kullanılmış.<br>        const cached = await redis.get(redisKey);</pre><pre>        if (!cached) {<br>          return res.status(409).json({<br>            error: &quot;İşlem durumu belirlenemedi. Tekrar deneyin.&quot;<br>          });<br>        }</pre><pre>        const record = JSON.parse(cached);</pre><pre>        // Aynı anahtar farklı içerikle kullanılmış.<br>        if (record.fingerprint !== fingerprint) {<br>          return res.status(422).json({<br>            error: &quot;Idempotency-Key farklı bir istek için kullanılmış.&quot;<br>          });<br>        }</pre><pre>        if (record.status === &quot;STARTED&quot;) {<br>          res.setHeader(&quot;Retry-After&quot;, &quot;2&quot;);</pre><pre>          return res.status(409).json({<br>            error: &quot;İşlem halen devam ediyor.&quot;<br>          });<br>        }</pre><pre>        if (record.status === &quot;COMPLETED&quot;) {<br>          res.setHeader(<br>            &quot;X-Idempotency-Replayed&quot;,<br>            &quot;true&quot;<br>          );</pre><pre>          return res<br>            .status(record.statusCode)<br>            .json(record.body);<br>        }</pre><pre>        return res.status(409).json({<br>          error: &quot;İşlem durumu geçersiz.&quot;<br>        });<br>      }</pre><pre>      // 3. İşlem sonucunu Redis&#39;e güvenli biçimde kaydet.<br>      const idempotentReq = req as IdempotentRequest;</pre><pre>      idempotentReq.idempotency = {<br>        key,</pre><pre>        async complete(statusCode, body) {<br>          const result = JSON.stringify({<br>            status: &quot;COMPLETED&quot;,<br>            fingerprint,<br>            statusCode,<br>            body<br>          });</pre><pre>          const saved = await redis.eval(<br>            COMPLETE_SCRIPT,<br>            1,<br>            redisKey,<br>            owner,<br>            result,<br>            RESULT_TTL<br>          );</pre><pre>          if (saved !== 1) {<br>            throw new Error(<br>              &quot;Idempotency kaydı güvenli şekilde tamamlanamadı.&quot;<br>            );<br>          }<br>        }<br>      };</pre><pre>      next();<br>    } catch (error) {<br>      console.error(&quot;Idempotency hatası:&quot;, error);</pre><pre>      // Ödeme işlemlerinde Redis erişilemiyorsa<br>      // güvenli tarafta kal ve işlemi başlatma.<br>      if (!res.headersSent) {<br>        return res.status(503).json({<br>          error: &quot;İşlem şu anda gerçekleştirilemiyor.&quot;<br>        });<br>      }</pre><pre>      next(error);<br>    }<br>  };<br>}</pre><p>Bu middleware’in önemli özellikleri:</p><ul><li>Aynı anahtarla gelen eş zamanlı istekleri Redis üzerinde atomik olarak kontrol eder.</li><li>İstek gövdesinin SHA-256 parmak izini saklar.</li><li>Aynı anahtar farklı bir istek için kullanılırsa 422 döndürür.</li><li>Tamamlanan işlemin HTTP durum kodunu ve yanıt gövdesini saklar.</li><li>Sonuç kaydını yalnızca kilidin sahibi olan işlem güncelleyebilir.</li></ul><p>Burada req.user alanının uygulamanızdaki kimlik doğrulama middleware&#39;i tarafından tanımlandığını varsayıyoruz. TypeScript projenizde Express Request tipine uygun bir genişletme yapılmalıdır.</p><p>Ayrıca JSON.stringify(req.body) basit bir örnek için yeterlidir; ancak üretim ortamında gövdeyi deterministik biçimde kanonikleştirmek gerekir. Nesne anahtarlarının sırası, özel veri türleri ve sayısal değerlerin gösterimi parmak izini etkileyebilir.</p><h3>4. Ödeme Rotasında Kullanımı</h3><p>Şimdi middleware’i bir ödeme rotasında kullanalım.</p><p>Önemli nokta: Redis idempotency kaydı ile ödeme sağlayıcısının idempotency mekanizması birlikte kullanılmalıdır.</p><pre>// routes/orderRoutes.ts</pre><pre>import { Router } from &quot;express&quot;;<br>import Stripe from &quot;stripe&quot;;</pre><pre>import { idempotencyMiddleware } from &quot;../middleware/idempotency&quot;;<br>import { IdempotentRequest } from &quot;../types/idempotency&quot;;</pre><pre>const router = Router();</pre><pre>const stripe = new Stripe(<br>  process.env.STRIPE_SECRET_KEY!<br>);</pre><pre>router.post(<br>  &quot;/checkout&quot;,<br>  idempotencyMiddleware(),<br>  async (req, res, next) =&gt; {<br>    const idempotentReq = req as IdempotentRequest;</pre><pre>    try {<br>      const {<br>        cartId,<br>        paymentMethodId,<br>        amount<br>      } = req.body;</pre><pre>      if (<br>        typeof amount !== &quot;number&quot; ||<br>        !Number.isInteger(amount) ||<br>        amount &lt;= 0<br>      ) {<br>        return res.status(400).json({<br>          error: &quot;Geçersiz ödeme tutarı.&quot;<br>        });<br>      }</pre><pre>      // Gerçek uygulamada tutar ve sepet bilgisi<br>      // güvenilir sunucu/veritabanı kayıtlarından alınmalı.</pre><pre>      const payment = await stripe.paymentIntents.create(<br>        {<br>          amount,<br>          currency: &quot;try&quot;,<br>          payment_method: paymentMethodId,<br>          confirm: true<br>        },<br>        {<br>          idempotencyKey: idempotentReq.idempotency!.key<br>        }<br>      );</pre><pre>      const result = {<br>        paymentId: payment.id,<br>        cartId,<br>        status: payment.status,<br>        amount<br>      };</pre><pre>      // Önce idempotency sonucu kalıcılaştırılır.<br>      await idempotentReq.idempotency!.complete(<br>        201,<br>        result<br>      );</pre><pre>      // Ardından istemciye yanıt gönderilir.<br>      return res.status(201).json(result);<br>    } catch (error) {<br>      next(error);<br>    }<br>  }<br>);</pre><pre>export default router;</pre><p>Bu örnekte Stripe kullanılıyor. Farklı ödeme sağlayıcılarında idempotency desteğinin kapsamı ve anahtar saklama süresi değişebilir.</p><p>Ayrıca gerçek bir ödeme uygulamasında amount değerini doğrudan istemciden güvenilir kabul etmemeliyiz. Tutar, kullanıcının sepeti ve sipariş bilgileri üzerinden sunucu tarafında hesaplanmalıdır.</p><p><strong>Neden hem Redis hem ödeme sağlayıcısı?</strong></p><p>Çünkü Redis ile ödeme sağlayıcısı birbirinden bağımsız sistemlerdir.</p><p>Örneğin:</p><ol><li>Sunucu Redis’te STARTED kaydını oluşturur.</li><li>Ödeme sağlayıcısı karttan başarılı şekilde tahsilat yapar.</li><li>Sunucu yanıtı almadan bağlantı kopar veya işlem zaman aşımına uğrar.</li><li>Redis kaydı hâlâ STARTED durumundadır.</li><li>Kullanıcı aynı anahtarla tekrar istek gönderir.</li></ol><p>Bu durumda yalnızca Redis’e bakarak ödemenin gerçekleşip gerçekleşmediğini kesin olarak anlayamayız.</p><p>Ödeme sağlayıcısına aynı idempotency anahtarıyla tekrar başvurmak, sağlayıcının önceki işlem sonucunu döndürmesini sağlar. Böylece ikinci bir tahsilat oluşturulması önlenebilir.</p><h3>5. Kritik Mimari Konular</h3><h3>5.1. Redis Tek Başına Exactly-Once Garantisi Vermez</h3><p>Dağıtık sistemlerde bir işlemin ağ üzerinden tam olarak bir kez yürütüldüğünü garanti etmek oldukça zordur.</p><p>İstemci, sunucu, Redis ve ödeme sağlayıcısı farklı zamanlarda hata verebilir.</p><p>Bu nedenle hedefimiz, tek bir sistem üzerinden mutlak bir exactly-once garantisi vermek değil; tekrarlanan isteklerin aynı iş sonucuna ulaşmasını sağlayan bir mimari kurmaktır.</p><p>Bunun için:</p><ul><li>Redis üzerinde idempotency kayıtları tutulmalı.</li><li>Ödeme sağlayıcısının idempotency özelliği kullanılmalı.</li><li>Veritabanında sipariş ve ödeme kayıtları benzersiz işlem kimlikleriyle korunmalı.</li><li>Belirsiz kalan işlemler için uzlaştırma (reconciliation) mekanizması kurulmalı.</li></ul><h3>5.2. Payload Fingerprint Doğrulaması</h3><p>Aynı Idempotency Key ile farklı bir tutar veya farklı bir sipariş gönderilmesi engellenmelidir.</p><p>Örneğin:</p><p>İlk istek:</p><pre>{<br>  &quot;cartId&quot;: &quot;cart_123&quot;,<br>  &quot;amount&quot;: 1500<br>}</pre><p>İkinci istek:</p><pre>{<br>  &quot;cartId&quot;: &quot;cart_123&quot;,<br>  &quot;amount&quot;: 2500<br>}</pre><p>Anahtar aynı olsa bile içerik farklıdır.</p><p>Bu durumda sistem yeni bir ödeme başlatmak yerine 422 Unprocessable Content döndürmelidir.</p><p>Fingerprint oluştururken yalnızca gövdeyi değil, işlemin kapsamını da dikkate almak önemlidir. Kullanıcı kimliği, HTTP metodu ve endpoint bilgisi anahtarın farklı işlemler arasında yanlışlıkla paylaşılmasını önlemeye yardımcı olur.</p><h3>5.3. TTL ve Kilit Süresi</h3><p>Idempotency kayıtları sonsuza kadar saklanmak zorunda değildir.</p><p>Örneğin:</p><pre>const LOCK_TTL = 120;<br>const RESULT_TTL = 86400;</pre><ul><li>LOCK_TTL: İşlemin devam ettiği süre boyunca geçerli olan geçici kilit süresi.</li><li>RESULT_TTL: Tamamlanmış işlemin sonucunun saklanacağı süre.</li></ul><p>Ancak burada önemli bir risk vardır: İşlem 120 saniyeden uzun sürerse kilit süresi dolabilir ve aynı anahtarla yeni bir istek tekrar işlem başlatabilir.</p><p>Gerçek sistemlerde bu risk; uygun işlem süreleri, kontrollü lease yenileme mekanizması, ödeme sağlayıcısı idempotency desteği ve veritabanı benzersizlik kısıtlarıyla yönetilmelidir.</p><p>TTL değerleri her sistem için sabit değildir. Ödeme sağlayıcısının anahtar saklama süresiyle de uyumlu olmalıdır.</p><h3>5.4. Redis Hatasında Fail-Closed Yaklaşımı</h3><p>Ödeme gibi finansal yan etkiler oluşturan işlemlerde Redis’e erişilemiyorsa isteği normal şekilde işleme almak tehlikelidir.</p><p>Çünkü idempotency kontrolü devre dışı kalır ve mükerrer işlem riski ortaya çıkar.</p><p>Bu nedenle ödeme rotalarında Redis kullanılamadığında işlemi başlatmamak ve geçici bir 503 Service Unavailable yanıtı döndürmek daha güvenli bir tercihtir.</p><h3>5.5. Veritabanı ve Redis Arasındaki Tutarlılık</h3><p>Redis hızlı bir idempotency katmanı sunar ancak kalıcı iş kayıtlarının tek kaynağı olarak düşünülmemelidir.</p><p>Sipariş ve ödeme kayıtları ilişkisel veritabanında tutulmalıdır.</p><p>Örneğin:</p><pre>CREATE UNIQUE INDEX unique_payment_idempotency<br>ON payments (user_id, idempotency_key);</pre><p>Bu kısıt, aynı kullanıcı ve idempotency anahtarı için birden fazla ödeme kaydı oluşturulmasını engeller.</p><p>Redis ile veritabanı arasında atomik bir transaction bulunmadığından her iki sistemin hata senaryoları ayrıca tasarlanmalıdır. Özellikle ödeme sağlayıcısında başarılı olan ancak veritabanına kaydedilemeyen işlemler için webhook ve uzlaştırma süreçleri önemlidir.</p><h3>Sonuç</h3><p>Idempotency, ödeme sistemleri ve dağıtık mimarilerde güvenilir işlem yönetiminin temel parçalarından biridir.</p><p>Ağ hataları, zaman aşımları ve istemci retry mekanizmaları tamamen ortadan kaldırılamaz. Ancak doğru tasarlanmış bir idempotency katmanı sayesinde aynı mantıksal işlemin tekrar tekrar gerçekleştirilmesi önlenebilir.</p><p>Node.js ve Redis ile kurulan yapı, isteklerin eş zamanlı kontrolünü ve önceki yanıtların yeniden kullanılmasını sağlar. Fakat gerçek finansal işlemlerde bunu ödeme sağlayıcısının idempotency desteği, veritabanı benzersizlik kısıtları ve uzlaştırma mekanizmalarıyla tamamlamak gerekir.</p><p>Unutulmaması gereken temel prensip şudur:</p><p><strong>Bir isteğin tekrar gelmesini engelleyemeyebilirsiniz; ancak aynı iş etkisinin ikinci kez oluşmasını mimari olarak engelleyebilirsiniz.</strong></p><h3>Kaynaklar</h3><ul><li><a href="https://docs.stripe.com/api/idempotent_requests">Stripe — Idempotent Requests</a></li><li><a href="https://redis.io/docs/latest/commands/set/">Redis — SET Command</a></li><li><a href="https://redis.io/docs/latest/commands/eval/">Redis — EVAL Command</a></li><li><a href="https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/">AWS Builders’ Library — Making retries safe with idempotent APIs</a></li><li><a href="https://www.rfc-editor.org/rfc/rfc9110">IETF — HTTP Semantics (RFC 9110)</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1fb1de663004" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Next.js App Router’da Server-Sent Events (SSE) ve AI Streaming Mimarisi]]></title>
            <link>https://affanccn.medium.com/next-js-app-routerda-server-sent-events-sse-ve-ai-streaming-mimarisi-a5e286cedfe3?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/a5e286cedfe3</guid>
            <category><![CDATA[chatgpt]]></category>
            <category><![CDATA[nextjs]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[server-sent-events]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 05:44:05 GMT</pubDate>
            <atom:updated>2026-11-02T05:44:05.329Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FKV7wZWEu9UFofUyMsNcFQ.jpeg" /></figure><h3>Next.js App Router’da Server-Sent Events (SSE) ve AI Streaming Mimarisi</h3><p>Yapay zekâ odaklı modern web uygulamalarında, kullanıcının yanıtın tamamının üretilmesini beklemesi kötü bir deneyime dönüşebilir. Özellikle LLM tabanlı sohbet uygulamalarında modelin yanıtı üretmesi birkaç saniye, bazen daha uzun sürebilir.</p><p>Bunun yerine yanıtı üretildikçe kullanıcıya aktarmak, bekleme deneyimini önemli ölçüde iyileştirir. Kullanıcı tüm cevabın hazırlanmasını beklemek yerine ilk metin parçalarını erkenden görmeye başlar.</p><p>Bu yaklaşımın arkasındaki temel teknolojilerden biri <strong>Server-Sent Events (SSE)</strong> ve Web Streams API’dir.</p><p>Geleneksel WebSocket bağlantıları çift yönlü ve sürekli iletişim gerektiren uygulamalar için oldukça kullanışlıdır. Ancak yalnızca sunucudan istemciye veri aktarmak istediğimiz senaryolarda SSE daha basit bir alternatif sunar.</p><p>Bu rehberde Next.js App Router Route Handler, ReadableStream ve React fetch API&#39;lerini kullanarak ChatGPT benzeri bir token akışı oluşturacağız.</p><h3>1. Neden WebSocket yerine SSE?</h3><p>SSE, sunucunun istemciye HTTP üzerinden olay ve veri göndermesini sağlayan bir mekanizmadır. İstemci bağlantıyı başlatır, sunucu ise bağlantı açık kaldığı sürece veri gönderebilir.</p><p>AI sohbet uygulamalarında kullanıcı mesajı gönderir ve sunucu modelin ürettiği metni parça parça geri iletir. Bu iletişim biçimi SSE için oldukça uygundur.</p><p>ÖzellikServer-Sent Events (SSE)WebSocketİletişim yönüSunucudan istemciyeÇift yönlüTaşımaHTTPWebSocket protokolüBağlantı yönetimiHTTP isteği ve açık yanıt akışıSürekli WebSocket bağlantısıYeniden bağlanmaEventSource ile yerleşik destekUygulama tarafından yönetilirKullanım alanıAI yanıtları, bildirimler, canlı loglarSohbet, oyun, çift yönlü canlı iletişimAltyapıHTTP streaming desteği yeterlidirWebSocket bağlantısını destekleyen altyapı gerekir</p><p>Burada önemli bir ayrıntı var: SSE, WebSocket’e kıyasla her durumda daha hızlı veya daha ucuz değildir. Her ikisinin de bağlantı, kaynak tüketimi ve dağıtım maliyetleri vardır.</p><p>SSE’nin asıl avantajı, tek yönlü veri akışı için standart HTTP altyapısını kullanması ve istemci tarafında kolay tüketilebilmesidir.</p><p>Ayrıca SSE kullanmak için mutlaka Edge Runtime’a geçmek gerekmez. Next.js’in Node.js Runtime ortamında da streaming yapılabilir.</p><h3>2. Next.js Route Handler ile SSE Akışı</h3><p>Next.js App Router, app dizini altında tanımlanan Route Handler dosyalarıyla özel HTTP uç noktaları oluşturmamızı sağlar.</p><p>Örneğin:</p><pre>app/<br>└── api/<br>    └── stream/<br>        └── route.ts</pre><p>Bu örnekte ReadableStream kullanarak istemciye metin parçaları göndereceğiz.</p><pre>// app/api/stream/route.ts</pre><pre>export const runtime = &quot;edge&quot;;</pre><pre>export async function POST(req: Request) {<br>  try {<br>    const { prompt } = await req.json();</pre><pre>    if (<br>      typeof prompt !== &quot;string&quot; ||<br>      prompt.trim().length === 0<br>    ) {<br>      return Response.json(<br>        { error: &quot;Geçerli bir prompt girilmelidir.&quot; },<br>        { status: 400 }<br>      );<br>    }</pre><pre>    const encoder = new TextEncoder();</pre><pre>    const stream = new ReadableStream({<br>      async start(controller) {<br>        try {<br>          const simulatedTokens = [<br>            &quot;Merhaba&quot;,<br>            &quot;! &quot;,<br>            &quot;Bu &quot;,<br>            &quot;yanıt &quot;,<br>            &quot;Next.js &quot;,<br>            &quot;App Router &quot;,<br>            &quot;ve &quot;,<br>            &quot;SSE &quot;,<br>            &quot;kullanılarak &quot;,<br>            &quot;canlı &quot;,<br>            &quot;olarak &quot;,<br>            &quot;aktarılıyor.&quot;<br>          ];</pre><pre>          for (const token of simulatedTokens) {<br>            const payload = JSON.stringify({<br>              text: token<br>            });</pre><pre>            controller.enqueue(<br>              encoder.encode(`data: ${payload}\n\n`)<br>            );</pre><pre>            await new Promise((resolve) =&gt;<br>              setTimeout(resolve, 35)<br>            );<br>          }</pre><pre>          controller.enqueue(<br>            encoder.encode(&quot;data: [DONE]\n\n&quot;)<br>          );</pre><pre>          controller.close();<br>        } catch {<br>          const errorPayload = JSON.stringify({<br>            error: &quot;Akış sırasında bir hata oluştu.&quot;<br>          });</pre><pre>          controller.enqueue(<br>            encoder.encode(`data: ${errorPayload}\n\n`)<br>          );</pre><pre>          controller.close();<br>        }<br>      }<br>    });</pre><pre>    return new Response(stream, {<br>      headers: {<br>        &quot;Content-Type&quot;: &quot;text/event-stream; charset=utf-8&quot;,<br>        &quot;Cache-Control&quot;: &quot;no-cache, no-transform&quot;,<br>        &quot;X-Accel-Buffering&quot;: &quot;no&quot;<br>      }<br>    });<br>  } catch {<br>    return Response.json(<br>      { error: &quot;İstek işlenemedi.&quot; },<br>      { status: 400 }<br>    );<br>  }<br>}</pre><p>Bu örnekte gerçek bir yapay zekâ modeli kullanılmıyor. Bunun yerine yanıt, belirli aralıklarla parçalara bölünerek gönderiliyor.</p><p>SSE mesajlarının temel formatı şöyledir:</p><pre>data: {&quot;text&quot;:&quot;Merhaba&quot;}</pre><pre>data: {&quot;text&quot;:&quot; Dünya&quot;}</pre><pre>data: [DONE]</pre><p>Her mesajın sonunda iki satır sonu (\n\n) bulunur. Bu ayraç, istemcinin bir SSE olayının tamamlandığını anlamasını sağlar.</p><p>Kullandığımız önemli başlıklar:</p><ul><li>Content-Type: text/event-stream: Yanıtın SSE formatında olduğunu belirtir.</li><li>Cache-Control: no-cache, no-transform: Akışın önbelleğe alınmasını ve bazı ara dönüşümlerin uygulanmasını engellemeye yardımcı olur.</li><li>X-Accel-Buffering: no: Nginx gibi destekleyen ters vekil sunucularda yanıtın tamponlanmasını engellemek için kullanılır.</li></ul><p>X-Accel-Buffering her CDN veya proxy üzerinde geçerli değildir. Gerçek dağıtım ortamında streaming davranışını ayrıca test etmek gerekir.</p><p><strong>Edge Runtime zorunlu değildir.</strong> Edge ortamı Web API’leriyle çalışan hafif işlemler için avantaj sağlayabilir; ancak Node.js bağımlılıkları kullanan bazı kütüphaneler Edge Runtime ile uyumlu olmayabilir. Bu nedenle çalışma ortamı, kullandığınız AI SDK ve diğer bağımlılıklara göre seçilmelidir.</p><h3>3. React Tarafında SSE Akışını Okumak</h3><p>İstemci tarafında fetch ve ReadableStreamDefaultReader kullanarak sunucudan gelen verileri okuyabiliriz.</p><p>Neden doğrudan EventSource kullanmıyoruz?</p><p>Çünkü EventSource standart olarak GET isteği açar. POST gövdesi veya özel Authorization başlıkları göndermek istediğimizde fetch daha esnektir.</p><p>Ancak fetch ile SSE tüketirken önemli bir ayrıntıya dikkat etmeliyiz:</p><p><strong>Bir ağ chunk’ı ile bir SSE mesajı aynı şey değildir.</strong></p><p>Sunucu iki ayrı SSE mesajı göndermiş olsa bile tarayıcı bunları tek bir chunk içinde teslim edebilir. Tam tersi de mümkündür: Tek bir SSE mesajı birkaç farklı chunk’a bölünebilir.</p><p>Bu nedenle her chunk’ı doğrudan \n\n üzerinden bölüp işlemek güvenilir değildir. Eksik kalan veriyi bir tamponda tutmamız gerekir.</p><pre>// components/AiChatStream.tsx</pre><pre>&quot;use client&quot;;</pre><pre>import { useState } from &quot;react&quot;;</pre><pre>export function AiChatStream() {<br>  const [prompt, setPrompt] = useState(&quot;&quot;);<br>  const [response, setResponse] = useState(&quot;&quot;);<br>  const [isLoading, setIsLoading] = useState(false);<br>  const [error, setError] = useState(&quot;&quot;);</pre><pre>  const handleSendPrompt = async () =&gt; {<br>    if (!prompt.trim() || isLoading) return;</pre><pre>    setIsLoading(true);<br>    setResponse(&quot;&quot;);<br>    setError(&quot;&quot;);</pre><pre>    const abortController = new AbortController();</pre><pre>    try {<br>      const res = await fetch(&quot;/api/stream&quot;, {<br>        method: &quot;POST&quot;,<br>        headers: {<br>          &quot;Content-Type&quot;: &quot;application/json&quot;,<br>          &quot;Accept&quot;: &quot;text/event-stream&quot;<br>        },<br>        body: JSON.stringify({ prompt }),<br>        signal: abortController.signal<br>      });</pre><pre>      if (!res.ok) {<br>        throw new Error(`HTTP hatası: ${res.status}`);<br>      }</pre><pre>      if (!res.body) {<br>        throw new Error(&quot;Yanıt akışı bulunamadı.&quot;);<br>      }</pre><pre>      const reader = res.body.getReader();<br>      const decoder = new TextDecoder();</pre><pre>      let buffer = &quot;&quot;;<br>      let streamFinished = false;</pre><pre>      while (!streamFinished) {<br>        const { value, done } = await reader.read();</pre><pre>        if (done) break;</pre><pre>        buffer += decoder.decode(value, {<br>          stream: true<br>        });</pre><pre>        // Tamamlanmış SSE olaylarını işle.<br>        const events = buffer.split(/\r?\n\r?\n/);</pre><pre>        // Son parça henüz tamamlanmamış olabilir.<br>        buffer = events.pop() ?? &quot;&quot;;</pre><pre>        for (const event of events) {<br>          const dataLines = event<br>            .split(/\r?\n/)<br>            .filter((line) =&gt; line.startsWith(&quot;data:&quot;))<br>            .map((line) =&gt; line.slice(5).replace(/^ /, &quot;&quot;));</pre><pre>          if (dataLines.length === 0) continue;</pre><pre>          const data = dataLines.join(&quot;\n&quot;);</pre><pre>          if (data === &quot;[DONE]&quot;) {<br>            streamFinished = true;<br>            break;<br>          }</pre><pre>          try {<br>            const parsed = JSON.parse(data);</pre><pre>            if (parsed.error) {<br>              throw new Error(parsed.error);<br>            }</pre><pre>            if (typeof parsed.text === &quot;string&quot;) {<br>              setResponse((prev) =&gt; prev + parsed.text);<br>            }<br>          } catch (error) {<br>            if (error instanceof SyntaxError) {<br>              console.error(&quot;SSE verisi ayrıştırılamadı:&quot;, error);<br>              continue;<br>            }</pre><pre>            throw error;<br>          }<br>        }<br>      }</pre><pre>      await reader.cancel().catch(() =&gt; {});<br>    } catch (err) {<br>      if (err instanceof Error) {<br>        setError(err.message);<br>      } else {<br>        setError(&quot;Beklenmeyen bir hata oluştu.&quot;);<br>      }<br>    } finally {<br>      setIsLoading(false);<br>    }<br>  };</pre><pre>  return (<br>    &lt;div className=&quot;max-w-2xl mx-auto p-6 bg-slate-900 text-white rounded-2xl shadow-xl border border-slate-800&quot;&gt;<br>      &lt;h2 className=&quot;text-xl font-bold mb-4 text-sky-400&quot;&gt;<br>        Canlı AI Akış Terminali<br>      &lt;/h2&gt;</pre><pre>      &lt;div className=&quot;flex gap-2 mb-4&quot;&gt;<br>        &lt;input<br>          type=&quot;text&quot;<br>          value={prompt}<br>          onChange={(e) =&gt; setPrompt(e.target.value)}<br>          placeholder=&quot;Yapay zekaya bir soru sorun...&quot;<br>          className=&quot;flex-1 bg-slate-800 border border-slate-700 px-4 py-2 rounded-lg&quot;<br>        /&gt;</pre><pre>        &lt;button<br>          onClick={handleSendPrompt}<br>          disabled={isLoading}<br>          className=&quot;bg-sky-500 hover:bg-sky-600 disabled:opacity-50 px-6 py-2 rounded-lg font-semibold&quot;<br>        &gt;<br>          {isLoading ? &quot;Yazıyor...&quot; : &quot;Gönder&quot;}<br>        &lt;/button&gt;<br>      &lt;/div&gt;</pre><pre>      &lt;div className=&quot;bg-slate-950 p-4 rounded-xl min-h-[120px] border border-slate-800 font-mono text-sm leading-relaxed whitespace-pre-wrap&quot;&gt;<br>        {response || (<br>          &lt;span className=&quot;text-slate-500 italic&quot;&gt;<br>            Cevap bekleniyor...<br>          &lt;/span&gt;<br>        )}<br>      &lt;/div&gt;</pre><pre>      {error &amp;&amp; (<br>        &lt;p className=&quot;mt-3 text-sm text-red-400&quot;&gt;<br>          {error}<br>        &lt;/p&gt;<br>      )}<br>    &lt;/div&gt;<br>  );<br>}</pre><p>Bu örnek, SSE’nin temel data olaylarını ve [DONE] sinyalini işler. Üretim ortamında bağlantıyı kullanıcı iptal ettiğinde durdurmak için AbortController nesnesini bileşen yaşam döngüsüyle ilişkilendirmek, akış hatalarını ayrıca ele almak ve gerektiğinde yeniden deneme mantığı kurmak gerekir.</p><p>Ayrıca bu basit ayrıştırıcı, özel SSE olay türlerini, id ve retry alanlarını tam olarak uygulamaz. Daha kapsamlı bir SSE istemcisi gerekiyorsa standart bir SSE parser kütüphanesi tercih edilebilir.</p><h3>4. Gerçek Bir AI Modeline Bağlanmak</h3><p>Yukarıdaki örnek, akış mekanizmasını anlamak için simüle edilmiş veriler kullanıyor. Gerçek bir LLM entegrasyonunda token’ları elle üretmek yerine model sağlayıcısının streaming API’sini kullanırız.</p><p>Next.js projelerinde bunun için kullanılabilecek seçeneklerden biri <strong>Vercel AI SDK</strong>’dır.</p><p>Örneğin streamText fonksiyonu, model yanıtını tamamını beklemeden parça parça tüketmemizi sağlar.</p><p>Basitleştirilmiş bir Route Handler:</p><pre>// app/api/chat/route.ts</pre><pre>import { streamText } from &quot;ai&quot;;<br>import { openai } from &quot;@ai-sdk/openai&quot;;</pre><pre>export const maxDuration = 30;</pre><pre>export async function POST(req: Request) {<br>  try {<br>    const { prompt } = await req.json();</pre><pre>    if (<br>      typeof prompt !== &quot;string&quot; ||<br>      prompt.trim().length === 0<br>    ) {<br>      return Response.json(<br>        { error: &quot;Prompt boş olamaz.&quot; },<br>        { status: 400 }<br>      );<br>    }</pre><pre>    const result = streamText({<br>      model: openai(&quot;gpt-4o-mini&quot;),<br>      prompt<br>    });</pre><pre>    return result.toTextStreamResponse();<br>  } catch {<br>    return Response.json(<br>      { error: &quot;AI isteği başlatılamadı.&quot; },<br>      { status: 500 }<br>    );<br>  }<br>}</pre><p>Bu örnek için ai ve @ai-sdk/openai paketlerinin kurulması ve sunucu tarafında API anahtarının tanımlanması gerekir.</p><pre>npm install ai @ai-sdk/openai</pre><p>Ortam değişkeni:</p><pre>OPENAI_API_KEY=your_api_key</pre><p>API anahtarı kesinlikle NEXT_PUBLIC_ önekiyle tanımlanmamalıdır. Böylece anahtar istemci JavaScript paketine dahil edilmez.</p><p>toTextStreamResponse() basit metin akışı döndürür. Daha gelişmiş sohbet arayüzlerinde araç çağrıları, mesaj durumları ve farklı içerik türleri de gerekiyorsa AI SDK&#39;nın UI Message Stream yaklaşımı değerlendirilebilir.</p><p>Burada önemli nokta, AI SDK’nın kendi akış protokolünün her zaman yukarıdaki özel JSON SSE formatıyla aynı olmamasıdır. İstemci tarafındaki tüketici, sunucunun döndürdüğü protokole uygun olmalıdır.</p><h3>5. Mimari ve Performans Kazanımları</h3><p>Streaming mimarisinin asıl faydası, modelin toplam üretim süresini sihirli biçimde azaltması değil, üretilen içeriğin kullanıcıya ulaşmasını erkene çekmesidir.</p><p><strong>1. Daha İyi İlk Yanıt Deneyimi</strong></p><p>Geleneksel yaklaşımda uygulama, model yanıtının tamamlanmasını bekleyip tek bir JSON yanıtı döndürebilir.</p><p>Streaming yaklaşımında ise ilk içerik parçası hazır olduğunda istemciye gönderilebilir. Böylece kullanıcı yanıtın oluşmaya başladığını daha erken görür.</p><p><strong>2. Standart HTTP Altyapısı</strong></p><p>SSE, HTTP üzerinden çalıştığı için ayrı bir WebSocket sunucusu kurmadan tek yönlü veri akışı sağlayabilir. Bununla birlikte hosting sağlayıcısının, CDN’in ve proxy katmanlarının streaming’i desteklemesi gerekir.</p><p><strong>3. Backpressure ve Bellek Yönetimi</strong></p><p>Web Streams API, üretici ve tüketici arasındaki veri akışını yönetmeye yardımcı olur. Özellikle uzun yanıtlar ve yüksek trafikli uygulamalarda akışın kontrolsüz biçimde bellekte biriktirilmesini önlemek önemlidir.</p><p><strong>4. Daha Basit İstemci Entegrasyonu</strong></p><p>SSE’nin standart olay formatı, metin parçaları, bildirimler ve ilerleme durumları gibi verilerin istemciye aktarılmasını kolaylaştırır.</p><h3>6. Üretim Ortamında Dikkat Edilmesi Gerekenler</h3><p>Geliştirme ortamında çalışan bir streaming örneği, üretim ortamında otomatik olarak sorunsuz çalışacağı anlamına gelmez.</p><p>Özellikle şu konulara dikkat edilmelidir:</p><ul><li><strong>Bağlantı ömrü:</strong> Serverless fonksiyonların çalışma süresi ve platform limitleri vardır. maxDuration gibi ayarlar kullanılan hosting platformuna göre yapılandırılmalıdır.</li><li><strong>İptal yönetimi:</strong> Kullanıcı sayfadan ayrıldığında veya isteği iptal ettiğinde model üretimini durdurmak için AbortSignal ve sağlayıcının iptal mekanizmaları kullanılmalıdır.</li><li><strong>Hata yönetimi:</strong> Akış başladıktan sonra HTTP durum kodunu değiştirmek mümkün değildir. Bu nedenle akış içi hatalar ayrıca tanımlanmalıdır.</li><li><strong>Kimlik doğrulama:</strong> API uç noktası herkese açık bırakılmamalı; oturum, yetki ve kullanıcı bazlı erişim kontrolleri uygulanmalıdır.</li><li><strong>Rate limiting:</strong> Kullanıcıların sınırsız sayıda AI isteği göndermesi engellenmelidir.</li><li><strong>Proxy ve CDN davranışı:</strong> Bazı ara katmanlar yanıtları tamponlayabilir. Gerçek dağıtım ortamında ilk veri parçasının ne zaman ulaştığı test edilmelidir.</li><li><strong>Gözlemlenebilirlik:</strong> İlk token süresi (TTFT), toplam üretim süresi, hata oranı ve bağlantı kopmaları takip edilmelidir.</li></ul><p>Ayrıca SSE’nin otomatik yeniden bağlanma özelliği yalnızca EventSource API&#39;sinin standart davranışıdır. fetch ile manuel akış okurken yeniden bağlanma mekanizmasını uygulamanın kendisi kurmalıdır.</p><h3>Sonuç</h3><p>Next.js App Router, Web Streams API ve SSE birlikte kullanıldığında gerçek zamanlı metin akışı oluşturmak için güçlü ve esnek bir mimari sunar.</p><p>Özellikle AI sohbet uygulamalarında kullanıcı deneyimini iyileştirmek için tüm yanıtın hazırlanmasını beklemek yerine, modelden gelen içerikleri üretildikçe istemciye aktarmak oldukça etkili bir yaklaşımdır.</p><p>Her proje için WebSocket kullanmak zorunda değiliz. İhtiyaç tek yönlü veri akışıysa SSE, daha az karmaşık bir çözüm olabilir. Çift yönlü ve sürekli iletişim gerekiyorsa WebSocket daha uygun bir tercih hâline gelir.</p><p>Önemli olan teknolojiyi popüler olduğu için değil, uygulamanın iletişim ihtiyacına göre seçmektir.</p><h3>Kaynaklar</h3><ul><li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">MDN — Using Server-Sent Events</a></li><li><a href="https://nextjs.org/docs/app/getting-started/route-handlers">Next.js — Route Handlers</a></li><li><a href="https://ai-sdk.dev/docs/ai-sdk-core/generating-text">Vercel AI SDK — Generating Text</a></li><li><a href="https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol">Vercel AI SDK — Stream Protocols</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a5e286cedfe3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Flutter’da FVM ve Fastlane ile Otomatik Dağıtım (CI/CD) Mimarisi]]></title>
            <link>https://affanccn.medium.com/flutterda-fvm-ve-fastlane-ile-otomatik-da%C4%9F%C4%B1t%C4%B1m-ci-cd-mimarisi-7d9ea017906d?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/7d9ea017906d</guid>
            <category><![CDATA[ci-cd-pipeline]]></category>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[dart]]></category>
            <category><![CDATA[fastlane]]></category>
            <category><![CDATA[fvm]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 05:41:49 GMT</pubDate>
            <atom:updated>2026-11-02T05:41:49.436Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3Ce6RylrtbDFGExWpuOLBg.jpeg" /></figure><h3>Flutter’da FVM ve Fastlane ile Otomatik Dağıtım (CI/CD) Mimarisi</h3><p>Mobil uygulama geliştirirken ekiplerin karşılaştığı iki önemli operasyonel problem vardır:</p><ol><li><strong>SDK sürüm uyuşmazlığı:</strong> Bir geliştiricinin bilgisayarında Flutter 3.24, CI/CD sunucusunda farklı bir sürüm bulunduğunda beklenmedik derleme hataları ortaya çıkabilir.</li><li><strong>Manuel mağaza dağıtımları:</strong> Her güncellemede uygulamayı derlemek, sertifikaları yönetmek, Xcode üzerinden arşiv almak ve Google Play Console’a .aab dosyası yüklemek zaman kaybettirir.</li></ol><p>Bu sorunları çözmek için iki aracı birlikte kullanabiliriz:</p><ul><li><strong>FVM (Flutter Version Management):</strong> Her proje için kullanılacak Flutter SDK sürümünü sabitler.</li><li><strong>Fastlane:</strong> Mobil uygulamaların derlenmesi, imzalanması ve mağazalara dağıtılması gibi işlemleri otomatikleştirir.</li></ul><p>Bu yazıda FVM ile proje bazlı SDK yönetimini, Fastlane ile Android ve iOS dağıtımını ve GitHub Actions üzerinden CI/CD pipeline oluşturmayı inceleyeceğiz.</p><h3>1. FVM ile Flutter SDK sürümünü sabitleme</h3><p>FVM, aynı bilgisayarda birden fazla Flutter sürümünü yönetmemizi sağlar. Böylece bir projede eski Flutter sürümü kullanırken başka bir projede daha yeni bir sürümle çalışabiliriz.</p><p>Öncelikle FVM’i yükleyelim:</p><pre>dart pub global activate fvm</pre><p>Ardından proje dizininde kullanacağımız Flutter sürümünü belirleyelim:</p><pre>fvm use 3.24.3</pre><p>Bu işlem proje kökünde .fvm/fvm_config.json dosyasını oluşturur:</p><pre>{<br>  &quot;flutterSdkVersion&quot;: &quot;3.24.3&quot;<br>}</pre><p>FVM, seçilen SDK’ya erişmek için .fvm/flutter_sdk bağlantısını da oluşturur.</p><p>Artık Flutter komutlarını doğrudan flutter yerine fvm flutter üzerinden çalıştırabiliriz:</p><pre>fvm flutter --version</pre><pre>fvm flutter pub get</pre><pre>fvm flutter analyze</pre><pre>fvm flutter test</pre><pre>fvm flutter build appbundle --release</pre><p>Böylece komutlar global Flutter kurulumuna değil, projenin belirlediği SDK sürümüne yönlendirilir.</p><h3>Git yapılandırması</h3><p>.fvm/fvm_config.json dosyası Git&#39;e eklenmelidir. Böylece ekipteki geliştiriciler proje için hangi Flutter sürümünün kullanıldığını görebilir.</p><p>Ancak .fvm/flutter_sdk bağlantısını Git&#39;e eklemek gerekmez. Bu bağlantı her geliştiricinin makinesinde FVM tarafından oluşturulur.</p><p>Örnek .gitignore:</p><pre>.fvm/flutter_sdk<br>.fvm/versions/</pre><p>IDE entegrasyonu için VS Code ayarları:</p><p>.vscode/settings.json:</p><pre>{<br>  &quot;dart.flutterSdkPath&quot;: &quot;.fvm/flutter_sdk&quot;<br>}</pre><p>Bu yapı sayesinde ekip üyeleri aynı proje yapılandırmasını kullanabilir.</p><p><strong>Önemli:</strong> FVM sürümü sabitlemek tek başına bütün geliştirme ortamını aynı hâle getirmez. Dart sürümü, Java/JDK, Xcode, CocoaPods ve Android Gradle Plugin gibi bağımlılıklar da CI ortamında kontrol edilmelidir.</p><p>Kaynak: <a href="https://fvm.app/">FVM — Flutter Version Management</a>.</p><h3>2. Fastlane kurulumu ve proje yapısı</h3><p>Fastlane, Android ve iOS uygulamalarının dağıtım süreçlerini otomatikleştiren bir araçtır.</p><p>Android tarafında Google Play Console’a AAB yüklemek, iOS tarafında ise App Store Connect ve TestFlight’a IPA göndermek için kullanılabilir.</p><p>Fastlane’i macOS üzerinde Homebrew ile kurabiliriz:</p><pre>brew install fastlane</pre><p>Ancak ekip projelerinde Fastlane’i Ruby bağımlılıklarıyla birlikte sürüm kontrolüne almak daha sağlıklıdır.</p><p>Proje kökünde bir Gemfile oluşturalım:</p><pre>source &quot;https://rubygems.org&quot;</pre><pre>gem &quot;fastlane&quot;</pre><p>Bağımlılıkları yükleyelim:</p><pre>bundle install</pre><p>Böylece Gemfile.lock dosyası oluşur. Bu dosyayı da Git&#39;e ekleyerek ekip üyelerinin ve CI ortamının aynı Ruby bağımlılık sürümlerini kullanmasını sağlayabiliriz.</p><p>Örnek proje yapısı:</p><pre>my_flutter_app/<br>│<br>├── .fvm/<br>│   └── fvm_config.json<br>│<br>├── android/<br>│   └── fastlane/<br>│       └── Fastfile<br>│<br>├── ios/<br>│   └── fastlane/<br>│       └── Fastfile<br>│<br>├── .github/<br>│   └── workflows/<br>│       └── deploy.yml<br>│<br>├── Gemfile<br>├── Gemfile.lock<br>└── pubspec.yaml</pre><p>Android ve iOS için ayrı Fastfile kullanmak, platforma özgü dağıtım işlemlerini birbirinden bağımsız yönetmemizi sağlar.</p><h3>3. Android dağıtım hattı: Google Play Internal Testing</h3><p>Android tarafında Fastlane’in upload_to_play_store aksiyonu, uygulamanın Google Play Console&#39;a yüklenmesini sağlar.</p><p>Öncelikle Google Cloud üzerinden bir Service Account oluşturmalı, bu hesabı Google Play Console ile ilişkilendirmeli ve gerekli izinleri vermeliyiz.</p><p>Kimlik bilgilerini doğrudan Git deposuna eklemek yerine GitHub Secrets gibi güvenli bir ortamda saklamalıyız.</p><p>android/fastlane/Fastfile:</p><pre>default_platform(:android)</pre><pre>platform :android do</pre><pre>  desc &quot;Google Play Internal Testing dağıtımı&quot;</pre><pre>  lane :deploy_internal do</pre><pre>    # Proje kök dizinine geç<br>    Dir.chdir(&quot;..&quot;) do</pre><pre>      # Flutter bağımlılıklarını yükle<br>      sh(&quot;fvm flutter pub get&quot;)</pre><pre>      # Release AAB üret<br>      sh(&quot;fvm flutter build appbundle --release&quot;)</pre><pre>    end</pre><pre>    # Google Play&#39;e yükle<br>    upload_to_play_store(<br>      track: &quot;internal&quot;,</pre><pre>      aab: &quot;../build/app/outputs/bundle/release/app-release.aab&quot;,</pre><pre>      json_key_data: ENV[&quot;GOOGLE_PLAY_JSON_KEY&quot;],</pre><pre>      release_status: &quot;completed&quot;,</pre><pre>      skip_upload_metadata: true,<br>      skip_upload_images: true,<br>      skip_upload_screenshots: true<br>    )</pre><pre>  end</pre><pre>end</pre><p>Burada json_key_data, Service Account JSON içeriğini ortam değişkeninden alır. Böylece anahtar dosyasını Git deposunda tutmamız gerekmez.</p><p>GitHub Secrets bölümünde GOOGLE_PLAY_JSON_KEY adında bir secret oluşturup JSON içeriğini saklamalıyız.</p><p>Fastlane komutunu çalıştırmak için:</p><pre>cd android</pre><pre>bundle exec fastlane deploy_internal</pre><p>Bu işlem sırasıyla:</p><ol><li>FVM üzerinden Flutter bağımlılıklarını yükler.</li><li>Android App Bundle üretir.</li><li>AAB dosyasını Google Play Console’a gönderir.</li><li>Uygulamayı Internal Testing kanalına yükler.</li></ol><p><strong>Önemli:</strong> Google Play Console’da uygulamanın ilk kurulumu ve gerekli yapılandırmaları önceden tamamlanmış olmalıdır. Ayrıca versionCode her yeni yüklemede uygun şekilde artırılmalıdır.</p><p>Kaynak: <a href="https://docs.fastlane.tools/actions/supply/">Fastlane — upload_to_play_store</a>.</p><h3>4. iOS sertifika yönetimi: Fastlane Match</h3><p>iOS dağıtımının en önemli konularından biri kod imzalama sürecidir.</p><p>Apple ekosisteminde uygulamanın dağıtılabilmesi için uygun sertifikalar ve provisioning profile dosyaları gerekir. Bu dosyaları ekip üyelerinin bilgisayarlarında ayrı ayrı yönetmek zamanla karmaşaya dönüşebilir.</p><p>Fastlane’in match aracı bu süreci merkezileştirir.</p><p>Match:</p><ul><li>Apple Developer hesabındaki sertifikaları ve provisioning profile dosyalarını yönetir.</li><li>Bunları özel bir Git deposunda şifreli biçimde saklayabilir.</li><li>Yeni ekip üyelerinin gerekli imzalama dosyalarını aynı kaynaktan almasını sağlar.</li><li>CI ortamında imzalama sürecini otomatikleştirebilir.</li></ul><p>İlk kurulumda:</p><pre>cd ios</pre><pre>bundle exec fastlane match init</pre><p>Özel Git deposu ve şifreleme parolası yapılandırıldıktan sonra dağıtım sertifikaları oluşturulabilir:</p><pre>bundle exec fastlane match appstore</pre><p>CI ortamında ise mevcut sertifikaları değiştirmeden almak için readonly kullanılmalıdır:</p><pre>match(<br>  type: &quot;appstore&quot;,<br>  readonly: true<br>)</pre><p>Bu sayede CI süreci yeni sertifika oluşturmaya çalışmaz.</p><h3>iOS Fastfile</h3><p>ios/fastlane/Fastfile:</p><pre>default_platform(:ios)</pre><pre>platform :ios do</pre><pre>  desc &quot;TestFlight dağıtımı&quot;</pre><pre>  lane :beta do</pre><pre>    # Proje kök dizinine geç<br>    Dir.chdir(&quot;..&quot;) do</pre><pre>      # Flutter bağımlılıklarını yükle<br>      sh(&quot;fvm flutter pub get&quot;)</pre><pre>    end</pre><pre>    # Apple App Store Connect API anahtarını tanımla<br>    api_key = app_store_connect_api_key(<br>      key_id: ENV[&quot;APP_STORE_CONNECT_KEY_ID&quot;],<br>      issuer_id: ENV[&quot;APP_STORE_CONNECT_ISSUER_ID&quot;],<br>      key_filepath: ENV[&quot;APP_STORE_CONNECT_KEY_PATH&quot;],<br>      duration: 1200<br>    )</pre><pre>    # Mevcut imzalama dosyalarını al<br>    match(<br>      type: &quot;appstore&quot;,<br>      readonly: true<br>    )</pre><pre>    # IPA üret<br>    Dir.chdir(&quot;..&quot;) do</pre><pre>      sh(&quot;fvm flutter build ipa --release&quot;)</pre><pre>    end</pre><pre>    # TestFlight&#39;a yükle<br>    upload_to_testflight(<br>      api_key: api_key,<br>      ipa: &quot;../build/ios/ipa/Runner.ipa&quot;,<br>      skip_waiting_for_build_processing: true<br>    )</pre><pre>  end</pre><pre>end</pre><p>Burada App Store Connect API anahtarı kullanıyoruz. Apple’ın resmi API anahtarı yöntemi, CI ortamında Apple ID ve iki faktörlü doğrulama akışına bağımlılığı azaltır.</p><p>GitHub Secrets tarafında şu değerler tanımlanmalıdır:</p><ul><li>APP_STORE_CONNECT_KEY_ID</li><li>APP_STORE_CONNECT_ISSUER_ID</li><li>APP_STORE_CONNECT_KEY_P8</li><li>MATCH_PASSWORD</li><li>MATCH_GIT_URL</li></ul><p>APP_STORE_CONNECT_KEY_P8 içeriği CI ortamında bir .p8 dosyasına dönüştürülmeli ve APP_STORE_CONNECT_KEY_PATH değişkeniyle Fastlane&#39;e gösterilmelidir.</p><p>Match deposuna erişim için CI ortamında ayrıca uygun Git kimlik doğrulaması yapılandırılmalıdır.</p><p><strong>Önemli:</strong> match tek başına Xcode imzalama ayarlarını her projede otomatik olarak doğru hâle getirmez. Bundle Identifier, Team ID, provisioning profile ve Xcode signing yapılandırmaları birbiriyle uyumlu olmalıdır.</p><p>Kaynaklar: <a href="https://docs.fastlane.tools/actions/match/">Fastlane Match</a>, <a href="https://docs.fastlane.tools/app-store-connect-api/">Fastlane App Store Connect API</a>.</p><h3>5. GitHub Actions ile CI/CD entegrasyonu</h3><p>Şimdi FVM ve Fastlane süreçlerini GitHub Actions ile birleştirelim.</p><p>Burada önemli bir mimari tercih yapacağız:</p><ul><li>Android derlemesi Linux runner üzerinde gerçekleştirilebilir.</li><li>iOS derlemesi için macOS ve Xcode gerekir.</li></ul><p>Dolayısıyla iki platformu aynı job içerisinde çalıştırmak yerine ayrı job’lara ayırmak daha doğrudur.</p><p>Aşağıdaki örnek, v* formatındaki Git tag&#39;leri gönderildiğinde iki platform için dağıtım sürecini başlatır.</p><p>.github/workflows/deploy.yml:</p><pre>name: Flutter Mobile CI/CD</pre><pre>on:<br>  push:<br>    tags:<br>      - &quot;v*&quot;</pre><pre>permissions:<br>  contents: read</pre><pre>jobs:</pre><pre>  deploy_android:<br>    name: Android Internal Testing<br>    runs-on: ubuntu-latest</pre><pre>    steps:<br>      - name: Repository Checkout<br>        uses: actions/checkout@v4</pre><pre>      - name: Setup Dart<br>        uses: dart-lang/setup-dart@v1<br>        with:<br>          sdk: stable</pre><pre>      - name: Install FVM<br>        run: dart pub global activate fvm</pre><pre>      - name: Add Pub Cache to PATH<br>        run: echo &quot;$HOME/.pub-cache/bin&quot; &gt;&gt; $GITHUB_PATH</pre><pre>      - name: Install Flutter SDK<br>        run: fvm install</pre><pre>      - name: Verify Flutter Version<br>        run: fvm flutter --version</pre><pre>      - name: Setup Ruby<br>        uses: ruby/setup-ruby@v1<br>        with:<br>          ruby-version: &quot;3.3&quot;<br>          bundler-cache: true</pre><pre>      - name: Deploy Android<br>        working-directory: android<br>        env:<br>          GOOGLE_PLAY_JSON_KEY: ${{ secrets.GOOGLE_PLAY_JSON_KEY }}<br>        run: bundle exec fastlane deploy_internal<br></pre><pre>  deploy_ios:<br>    name: iOS TestFlight<br>    runs-on: macos-latest</pre><pre>    steps:<br>      - name: Repository Checkout<br>        uses: actions/checkout@v4</pre><pre>      - name: Setup Dart<br>        uses: dart-lang/setup-dart@v1<br>        with:<br>          sdk: stable</pre><pre>      - name: Install FVM<br>        run: dart pub global activate fvm</pre><pre>      - name: Add Pub Cache to PATH<br>        run: echo &quot;$HOME/.pub-cache/bin&quot; &gt;&gt; $GITHUB_PATH</pre><pre>      - name: Install Flutter SDK<br>        run: fvm install</pre><pre>      - name: Verify Flutter Version<br>        run: fvm flutter --version</pre><pre>      - name: Setup Ruby<br>        uses: ruby/setup-ruby@v1<br>        with:<br>          ruby-version: &quot;3.3&quot;<br>          bundler-cache: true</pre><pre>      - name: Prepare Apple API Key<br>        env:<br>          APP_STORE_CONNECT_KEY_P8: ${{ secrets.APP_STORE_CONNECT_KEY_P8 }}<br>        run: |<br>          mkdir -p &quot;$RUNNER_TEMP/keys&quot;<br>          echo &quot;$APP_STORE_CONNECT_KEY_P8&quot; &gt; &quot;$RUNNER_TEMP/keys/AuthKey.p8&quot;<br>          echo &quot;APP_STORE_CONNECT_KEY_PATH=$RUNNER_TEMP/keys/AuthKey.p8&quot; &gt;&gt; $GITHUB_ENV</pre><pre>      - name: Deploy iOS<br>        working-directory: ios<br>        env:<br>          APP_STORE_CONNECT_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}<br>          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}<br>          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}<br>          MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}<br>        run: bundle exec fastlane beta</pre><p>Bu örnek temel pipeline mimarisini gösterir. Gerçek projede aşağıdaki ayrıntılar da tamamlanmalıdır:</p><ul><li>MATCH_GIT_URL için özel sertifika deposuna erişim yetkisi.</li><li>Apple API anahtarının doğru dosya izinleriyle oluşturulması.</li><li>Google Play Service Account yetkileri.</li><li>iOS için Xcode ve CocoaPods uyumluluğu.</li><li>Android için Java/JDK ve Gradle uyumluluğu.</li><li>versionCode ve iOS build number değerlerinin benzersiz olması.</li></ul><p>Ayrıca ruby/setup-ruby ile kullanılan Ruby sürümü, projenin Gemfile.lock dosyasındaki bağımlılıklarla uyumlu olmalıdır.</p><p>iOS tarafında runs-on: macos-latest kullanılması önemlidir. Flutter&#39;ın resmi dokümantasyonuna göre iOS uygulaması derlemek ve dağıtmak için macOS ve Xcode gerekir.</p><p>Kaynak: <a href="https://docs.flutter.dev/deployment/ios">Flutter — Build and Release an iOS App</a>.</p><h3>6. Güvenli dağıtım ve sürüm yönetimi</h3><p>CI/CD pipeline’ının başarılı olması yalnızca uygulamanın mağazaya yüklenmesiyle ölçülmemelidir. Dağıtım sürecinin güvenli ve tekrarlanabilir olması da gerekir.</p><h3>Secret yönetimi</h3><p>Aşağıdaki dosyalar ve bilgiler kesinlikle doğrudan Git deposuna eklenmemelidir:</p><ul><li>Google Play Service Account JSON anahtarı.</li><li>Apple App Store Connect .p8 anahtarı.</li><li>Match şifreleme parolası.</li><li>Özel sertifika deposuna erişim anahtarları.</li><li>İmzalama sertifikalarının özel anahtarları.</li></ul><p>Bu bilgiler GitHub Secrets veya uygun bir secret yönetim servisi üzerinden aktarılmalıdır.</p><h3>Build numarası yönetimi</h3><p>Her mağaza yüklemesinde benzersiz build numarası kullanılması gerekir.</p><p>Flutter’da sürüm bilgileri pubspec.yaml üzerinden yönetilebilir:</p><pre>version: 1.2.0+15</pre><p>Burada:</p><ul><li>1.2.0: Kullanıcıya gösterilen uygulama sürümü.</li><li>15: Build numarası.</li></ul><p>Yeni bir dağıtımda build numarasını artırmalıyız:</p><pre>version: 1.2.0+16</pre><p>CI/CD ortamında bu değer tag, GitHub Actions run number veya başka bir sürüm yönetim mekanizması üzerinden otomatik üretilebilir.</p><h3>Dağıtım öncesi testler</h3><p>Mağazaya doğrudan release göndermek yerine pipeline’a kalite kontrolleri eklemek daha güvenlidir:</p><pre>fvm flutter pub get</pre><pre>fvm flutter analyze</pre><pre>fvm flutter test</pre><pre>fvm flutter build appbundle --release</pre><p>iOS için de uygun test ve derleme adımları eklenebilir. Böylece statik analiz veya test aşaması başarısız olduğunda mağaza dağıtımı başlamaz.</p><h3>7. Mimari kazanımlar</h3><p>FVM ve Fastlane birlikte kullanıldığında mobil geliştirme süreçlerinde önemli avantajlar elde edilir.</p><p>BileşenSorumlulukKazanımFVMFlutter SDK yönetimiProje bazlı sürüm tutarlılığıFastlaneDağıtım otomasyonuTekrarlanabilir mağaza yüklemeleriMatchiOS imzalama yönetimiMerkezi sertifika yönetimiGitHub ActionsCI/CD orkestrasyonuOtomatik build ve deployGitHub SecretsGizli bilgi yönetimiAnahtarların güvenli saklanması</p><p>Bu mimarinin en önemli avantajı, geliştiricinin manuel mağaza işlemleriyle uğraşmak yerine kod kalitesine ve uygulama geliştirmeye odaklanabilmesidir.</p><h3>Sonuç</h3><p>Flutter projelerinde sürdürülebilir bir mobil DevOps süreci oluşturmak için SDK yönetimi ve dağıtım otomasyonunu birlikte ele almak gerekir.</p><p>FVM, projenin hangi Flutter sürümüyle geliştirileceğini belirler. Fastlane, Android ve iOS dağıtım adımlarını otomatikleştirir. GitHub Actions ise bu süreçleri belirlenen olaylara göre çalıştırır.</p><p>Ancak başarılı bir CI/CD mimarisi yalnızca birkaç komuttan oluşmaz. Sertifika yönetimi, gizli anahtarların korunması, benzersiz build numaraları, test aşamaları ve platforma özgü derleme gereksinimleri de tasarımın parçasıdır.</p><p>Doğru yapılandırıldığında geliştirici kodunu Git’e gönderir, pipeline gerekli kontrolleri gerçekleştirir ve uygulama test kanallarına otomatik olarak dağıtılır.</p><p><strong>Hedef, dağıtımı tek komuta indirmekten daha fazlasıdır: Her sürümün aynı kurallarla, güvenli ve tekrarlanabilir biçimde üretilebilmesini sağlamaktır.</strong></p><h3>Kaynaklar</h3><ul><li><a href="https://fvm.app/">FVM — Flutter Version Management</a></li><li><a href="https://docs.flutter.dev/deployment/cd">Flutter — Continuous Delivery</a></li><li><a href="https://docs.flutter.dev/deployment/android">Flutter — Android Deployment</a></li><li><a href="https://docs.flutter.dev/deployment/ios">Flutter — iOS Deployment</a></li><li><a href="https://docs.fastlane.tools/actions/supply/">Fastlane — Google Play Deployment</a></li><li><a href="https://docs.fastlane.tools/actions/pilot/">Fastlane — TestFlight Deployment</a></li><li><a href="https://docs.fastlane.tools/actions/match/">Fastlane — Match</a></li><li><a href="https://docs.fastlane.tools/app-store-connect-api/">Fastlane — App Store Connect API</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7d9ea017906d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[PostgreSQL’de VACUUM, Autovacuum ve Bloat (Şişme) Yönetimi: Canlı Veritabanı Bakım Rehberi]]></title>
            <link>https://affanccn.medium.com/postgresqlde-vacuum-autovacuum-ve-bloat-%C5%9Fi%C5%9Fme-y%C3%B6netimi-canl%C4%B1-veritaban%C4%B1-bak%C4%B1m-rehberi-b0efeb8cd4b5?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/b0efeb8cd4b5</guid>
            <category><![CDATA[database]]></category>
            <category><![CDATA[dead-tuples]]></category>
            <category><![CDATA[vacuum]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[postgresql]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 05:39:04 GMT</pubDate>
            <atom:updated>2026-11-02T05:39:04.037Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GjGnNUgS_TjPzxEtZWHL_g.jpeg" /></figure><h3>PostgreSQL’de VACUUM, Autovacuum ve Bloat Yönetimi: Canlı Veritabanı Bakım Rehberi</h3><p>PostgreSQL kullanan birçok yazılım ekibi, uygulama canlıya alındıktan birkaç ay sonra beklenmedik veritabanı büyümesi ve performans sorunlarıyla karşılaşabilir. Başlangıçta birkaç gigabayt yer kaplayan bir tablo zamanla çok daha fazla disk alanı kullanabilir. Bazı sorguların performansı düşerken bakım işlemleri de daha uzun sürmeye başlayabilir.</p><p>Bu sorunların önemli nedenlerinden biri PostgreSQL’in eşzamanlılık modeli olan <strong>MVCC (Multi-Version Concurrency Control)</strong> ve bu modelin gerektirdiği düzenli bakım işlemlerinin yetersiz kalmasıdır.</p><p>PostgreSQL, güncellenen veya silinen satırları her zaman anında fiziksel olarak kaldırmaz. Eski satır sürümleri zamanla birikir ve uygun şekilde temizlenmezse tablo ve indekslerde gereksiz alan kullanımına neden olabilir.</p><p>Bu rehberde ölü satırların nasıl oluştuğunu, Autovacuum mekanizmasının nasıl çalıştığını, bloat sorunlarının nasıl teşhis edileceğini ve canlı sistemlerde güvenli bakım stratejilerini inceleyeceğiz.</p><h3>1. MVCC ve ölü satırlar (Dead Tuples) neden oluşur?</h3><p>PostgreSQL, eşzamanlı işlemlerin birbirini mümkün olduğunca engellemeden çalışabilmesi için MVCC yaklaşımını kullanır.</p><p>Bu modelde her satır sürümünün işlem kimlikleriyle ilişkili görünürlük bilgileri bulunur. Bir işlem, kendi snapshot’ına göre hangi satır sürümlerini görebileceğini belirler.</p><p>Örneğin:</p><pre>UPDATE users<br>SET email = &#39;new@example.com&#39;<br>WHERE id = 42;</pre><p>Bu işlem gerçekleştiğinde PostgreSQL genellikle eski satır sürümünü doğrudan fiziksel olarak silmez. Yeni bir satır sürümü oluşturur ve eski sürümün artık geçerli olmadığını belirtir.</p><p>Benzer şekilde:</p><pre>DELETE FROM users<br>WHERE id = 42;</pre><p>işlemi de satırı hemen diskten kaldırmaz. Satırın silindiği işaretlenir; eski sürüm, artık hiçbir aktif transaction tarafından görülmesi gerekmediğinde temizlenebilir.</p><p>Bu eski ve artık görünür olmayan satır sürümlerine <strong>Dead Tuples</strong> denir.</p><p>Önemli bir ayrıntı: Bir satırın eski sürümünün artık görünür olmaması, PostgreSQL’in onu aynı anda fiziksel olarak kaldırabileceği anlamına gelmez. Uzun süre açık kalan transaction’lar, eski snapshot’lar ve bazı replikasyon mekanizmaları temizleme işlemini geciktirebilir.</p><h3>Table Bloat nedir?</h3><p>Dead tuple’lar ve kullanılmayan indeks alanları zamanla gereksiz fiziksel alan kullanımına yol açabilir. Bu duruma genel olarak <strong>Bloat (şişme)</strong> denir.</p><p>Bloat’ın olası etkileri:</p><ul><li>Tablo ve indekslerin disk üzerinde gereğinden fazla yer kaplaması.</li><li>Daha fazla sayfanın okunması nedeniyle bazı sorguların yavaşlaması.</li><li>Buffer cache verimliliğinin düşmesi.</li><li>Yedekleme, geri yükleme ve bakım işlemlerinin daha fazla kaynak tüketmesi.</li></ul><p>Ancak her büyük tablo bloat içeriyor demek değildir. Bir tablonun büyümesi, uygulamanın gerçekten daha fazla veri üretmesinden de kaynaklanabilir. Bu nedenle yalnızca disk boyutuna bakarak bloat teşhisi koymak doğru değildir.</p><h3>2. Dead Tuple birikimini tespit etmek</h3><p>PostgreSQL, tablo istatistiklerini pg_stat_user_tables görünümünde sunar.</p><p>Aşağıdaki sorguyla ölü ve canlı satır tahminlerini, son bakım zamanlarını ve oranları inceleyebiliriz:</p><pre>SELECT<br>    schemaname,<br>    relname AS table_name,<br>    n_live_tup AS live_tuples,<br>    n_dead_tup AS dead_tuples,</pre><pre>    ROUND(<br>        100.0 * n_dead_tup /<br>        NULLIF(n_live_tup + n_dead_tup, 0),<br>        2<br>    ) AS dead_tuple_ratio,</pre><pre>    last_vacuum,<br>    last_autovacuum,<br>    last_analyze,<br>    last_autoanalyze</pre><pre>FROM pg_stat_user_tables</pre><pre>WHERE n_dead_tup &gt; 1000</pre><pre>ORDER BY n_dead_tup DESC;</pre><p>Burada özellikle şu alanlara dikkat etmeliyiz:</p><p>AlanAçıklaman_live_tupTahmini canlı satır sayısın_dead_tupTahmini ölü satır sayısıdead_tuple_ratioTahmini ölü satır oranılast_autovacuumSon otomatik VACUUM zamanılast_autoanalyzeSon otomatik ANALYZE zamanı</p><p><strong>Önemli:</strong> n_dead_tup ve bu sorguda hesaplanan oran, gerçek disk bloat yüzdesi değildir. Bunlar istatistiksel tahminlerdir. Örneğin %20 dead tuple oranı, tablonun fiziksel olarak %20 şiştiğini kanıtlamaz. Bu değeri bir alarm sinyali olarak kullanmalı, tek başına bakım kararı vermemeliyiz.</p><h3>Tablo ve indeks boyutlarını kontrol etmek</h3><p>Fiziksel alan kullanımını incelemek için aşağıdaki sorgu daha yararlı bir başlangıç noktasıdır:</p><pre>SELECT<br>    schemaname,<br>    relname AS table_name,</pre><pre>    pg_size_pretty(<br>        pg_relation_size(relid)<br>    ) AS table_size,</pre><pre>    pg_size_pretty(<br>        pg_indexes_size(relid)<br>    ) AS indexes_size,</pre><pre>    pg_size_pretty(<br>        pg_total_relation_size(relid)<br>    ) AS total_size</pre><pre>FROM pg_stat_user_tables</pre><pre>ORDER BY pg_total_relation_size(relid) DESC</pre><pre>LIMIT 20;</pre><p>Bu sorguyla en fazla alan kullanan tabloları belirleyebiliriz. Ancak tablo boyutu ile indeks boyutunu ayrı incelemek önemlidir. Bazen asıl sorun tablonun kendisinde değil, indekslerdeki gereksiz alan kullanımındadır.</p><p>Daha ayrıntılı bloat analizi için pgstattuple gibi uzantılar da değerlendirilebilir. Bu uzantı, tablo ve indekslerdeki fiziksel alan kullanımını incelemeye yardımcı olur.</p><h3>3. VACUUM ve Autovacuum nasıl çalışır?</h3><p>PostgreSQL’de VACUUM, ölü satır sürümlerinin kapladığı alanı geri kazanmak için kullanılan temel bakım komutudur.</p><p>İki temel kullanım biçimi vardır:</p><h3>Standart VACUUM</h3><pre>VACUUM VERBOSE ANALYZE users;</pre><p>Bu komut:</p><ul><li>Temizlenebilir ölü satır sürümlerini kaldırır.</li><li>Uygun alanları tablonun yeniden kullanabilmesini sağlar.</li><li>ANALYZE sayesinde sorgu planlayıcısının istatistiklerini günceller.</li><li>Visibility Map bilgisinin güncellenmesine yardımcı olur.</li></ul><p>Standart VACUUM, normal koşullarda tabloyu tamamen kilitlemeden okuma ve yazma işlemleriyle birlikte çalışabilir.</p><p>Ancak önemli bir ayrıntı var: Standart VACUUM, çoğu durumda boş alanı işletim sistemine geri vermez. Bu alanı PostgreSQL’in aynı tablo içinde yeniden kullanabilmesini sağlar. Yalnızca tablonun sonundaki tamamen boş sayfalar uygun koşullarda kesilerek işletim sistemine iade edilebilir.</p><p>Bu nedenle VACUUM çalıştırmak, tablo dosyasının mutlaka küçüleceği anlamına gelmez.</p><h3>Autovacuum</h3><p>Autovacuum, VACUUM ve ANALYZE işlemlerini otomatik olarak çalıştıran PostgreSQL mekanizmasıdır.</p><p>Arka planda çalışan launcher, uygun tabloları kontrol eder ve gerekli bakım işlemleri için worker süreçleri başlatır.</p><p>Temel sorumlulukları:</p><ol><li>Ölü satır sürümlerini temizlemek.</li><li>Sorgu planlayıcısının istatistiklerini güncel tutmak.</li><li>Visibility Map bilgisini güncellemek.</li><li>Transaction ID wraparound riskini önlemek için eski transaction kimliklerini freeze etmek.</li></ol><p>Autovacuum varsayılan olarak etkinleştirilir ve çoğu sistemde temel bakım ihtiyaçlarını karşılayabilir. Ancak yüksek yazma hacmine sahip sistemlerde tablo bazlı ayarlamalar gerekebilir.</p><p>Kaynak: <a href="https://www.postgresql.org/docs/current/routine-vacuuming.html">PostgreSQL — Routine Vacuuming</a>.</p><h3>4. Autovacuum neden yoğun tablolarda yetersiz kalabilir?</h3><p>Autovacuum’un ne zaman çalışacağını belirleyen önemli parametrelerden biri autovacuum_vacuum_scale_factor değeridir.</p><p>PostgreSQL, bir tablonun VACUUM ihtiyacını hesaplarken temel eşik ve tablo büyüklüğüne bağlı oranı birlikte değerlendirir.</p><p>Basitleştirilmiş eşik formülü:</p><pre>VACUUM Threshold =<br>    autovacuum_vacuum_threshold<br>    +<br>    autovacuum_vacuum_scale_factor<br>    ×<br>    reltuples</pre><p>Örneğin:</p><pre>Tablo büyüklüğü: 50.000.000 satır<br>Scale Factor:    0.20<br>Threshold:       50</pre><p>Bu örnekte:</p><pre>50 + (0.20 × 50.000.000)</pre><pre>= 10.000.050</pre><p>Yani diğer koşullar ve sürüme özgü eşik sınırlamaları dikkate alınmadan, yaklaşık 10 milyon ölü satır oluştuğunda VACUUM eşiğine ulaşılır.</p><p>Bu nedenle büyük ve yoğun güncellenen tablolarda varsayılan oranlar geç temizlik yapılmasına neden olabilir.</p><p>Ancak burada önemli bir ayrıntı var: PostgreSQL 18&#39;de autovacuum_vacuum_max_threshold gibi ek eşik sınırlamaları da bulunur. Ayrıca INSERT işlemleri için ayrı bir vacuum eşiği vardır. Dolayısıyla gerçek tetiklenme koşulları yalnızca yukarıdaki basitleştirilmiş formülden ibaret değildir.</p><p>Autovacuum’un yetişememesinin diğer nedenleri:</p><ul><li>autovacuum_max_workers değerinin yetersiz olması.</li><li>Worker süreçlerinin büyük tablolar üzerinde uzun süre çalışması.</li><li>autovacuum_vacuum_cost_limit ve autovacuum_vacuum_cost_delay ayarlarının iş yüküne uygun olmaması.</li><li>Uzun süren transaction’ların eski satır sürümlerinin temizlenmesini engellemesi.</li><li>Replication slot’ların eski xmin değerlerini tutması.</li><li>Yoğun disk I/O nedeniyle bakım işlemlerinin yavaşlaması.</li></ul><p>Bu nedenle yalnızca scale factor değerini düşürmek her zaman yeterli değildir.</p><h3>5. Üretim ortamı için Autovacuum optimizasyonu</h3><p>Modern SSD veya NVMe disk kullanmak, Autovacuum ayarlarını düşünmeden agresif biçimde yükseltmek için yeterli bir gerekçe değildir. Disk performansı kadar CPU, RAM, eşzamanlı sorgular ve yazma hacmi de önemlidir.</p><p>Aşağıdaki yapılandırma, yoğun güncellenen bir sistem için başlangıç noktası olarak değerlendirilebilir:</p><pre># postgresql.conf</pre><pre># Autovacuum aktif olmalı<br>autovacuum = on</pre><pre># VACUUM daha erken tetiklensin<br>autovacuum_vacuum_threshold = 1000<br>autovacuum_vacuum_scale_factor = 0.05</pre><pre># ANALYZE daha sık çalışsın<br>autovacuum_analyze_threshold = 500<br>autovacuum_analyze_scale_factor = 0.02</pre><pre># Bakım kapasitesi<br>autovacuum_max_workers = 4<br>autovacuum_naptime = 30s</pre><pre># I/O maliyet kontrolü<br>autovacuum_vacuum_cost_limit = 2000<br>autovacuum_vacuum_cost_delay = 2ms</pre><pre># Autovacuum aktivitelerini izle<br>log_autovacuum_min_duration = 5s</pre><p>Bu değerler her sistem için evrensel bir optimum değildir. Özellikle autovacuum_max_workers artırıldığında daha fazla eşzamanlı bakım işlemi çalışabilir; bunun CPU ve disk I/O maliyeti de artabilir.</p><p>Ayrıca PostgreSQL’in autovacuum cost balancing mekanizması, birden fazla worker çalışırken toplam maliyeti dengelemeye çalışır. Tabloya özel cost ayarları yapıldığında bu dengeleme davranışı farklılaşabilir.</p><h3>Tablo bazlı Autovacuum ayarı</h3><p>Her tablonun aynı yazma yoğunluğuna sahip olması beklenmez.</p><p>Örneğin, sürekli UPDATE ve DELETE alan bir user_activity_logs tablosuna daha düşük bir scale factor tanımlayabiliriz:</p><pre>ALTER TABLE user_activity_logs<br>SET (<br>    autovacuum_vacuum_scale_factor = 0.01,<br>    autovacuum_vacuum_threshold = 500,</pre><pre>    autovacuum_analyze_scale_factor = 0.01,<br>    autovacuum_analyze_threshold = 500,</pre><pre>    autovacuum_vacuum_cost_limit = 3000<br>);</pre><p>Bu ayarla ilgili tablonun VACUUM eşiği düşürülür ve daha erken bakım yapılması hedeflenir.</p><p>Mevcut tablo ayarlarını kontrol etmek için:</p><pre>SELECT<br>    relname,<br>    reloptions<br>FROM pg_class<br>WHERE relname = &#39;user_activity_logs&#39;;</pre><p>Global ayarları incelemek için:</p><pre>SELECT<br>    name,<br>    setting,<br>    unit,<br>    source<br>FROM pg_settings<br>WHERE name LIKE &#39;autovacuum%&#39;<br>ORDER BY name;</pre><p>Önemli: Bu ayarları uygulamadan önce sistemin mevcut bakım davranışını, worker kullanımını ve disk I/O değerlerini incelemek gerekir. Rastgele agresif ayarlar, sorgu performansını iyileştirmek yerine bakım işlemlerinin kaynak tüketimini artırabilir.</p><h3>6. Uzun süren transaction’lar ve VACUUM engelleri</h3><p>Autovacuum doğru yapılandırılmış olsa bile bazı satırlar temizlenemeyebilir. Bunun önemli nedenlerinden biri uzun süren transaction’lardır.</p><p>Örneğin bir transaction saatlerce açık kalırsa PostgreSQL, o transaction’ın snapshot’ı nedeniyle bazı eski satır sürümlerini henüz temizleyemeyebilir.</p><p>Açık transaction’ları incelemek için:</p><pre>SELECT<br>    pid,<br>    usename,<br>    state,<br>    xact_start,<br>    now() - xact_start AS transaction_duration,<br>    backend_xmin,<br>    query<br>FROM pg_stat_activity<br>WHERE xact_start IS NOT NULL<br>ORDER BY xact_start ASC;</pre><p>Uzun süre açık kalan transaction’ları ve eski backend_xmin değerlerini özellikle takip etmek gerekir.</p><p>Replication slot’ları da kontrol edelim:</p><pre>SELECT<br>    slot_name,<br>    slot_type,<br>    active,<br>    xmin,<br>    catalog_xmin<br>FROM pg_replication_slots;</pre><p>Eski xmin veya catalog_xmin değerleri, gerekli satır sürümlerinin temizlenmesini geciktirebilir.</p><p>Ancak bu kayıtları doğrudan silmek veya transaction’ları kontrolsüz biçimde sonlandırmak doğru değildir. Önce uygulamanın, replikasyonun veya bağlantının neden açık kaldığı anlaşılmalıdır.</p><h3>7. VACUUM FULL ve pg_repack karşılaştırması</h3><p>Standart VACUUM, boş alanı çoğunlukla PostgreSQL’in yeniden kullanması için bırakır. Ancak ciddi fiziksel şişme oluşmuşsa ve disk alanının işletim sistemine geri verilmesi gerekiyorsa tabloyu yeniden yazan yöntemler değerlendirilir.</p><h3>VACUUM FULL</h3><pre>VACUUM FULL users;</pre><p>VACUUM FULL, tablonun yeni ve sıkıştırılmış bir kopyasını oluşturarak fiziksel alanı geri kazanabilir.</p><p>Ancak önemli dezavantajları vardır:</p><ul><li>İşlem boyunca ACCESS EXCLUSIVE kilidi alır.</li><li>Tabloya erişen diğer işlemleri engeller.</li><li>Büyük tablolarda uzun sürebilir.</li><li>Yeni tablo kopyası oluşturmak için ek disk alanı gerektirir.</li><li>İndeksler de yeniden oluşturulur.</li></ul><p>Bu nedenle canlı üretim ortamlarında plansız şekilde çalıştırılmamalıdır.</p><h3>pg_repack</h3><p>pg_repack, PostgreSQL tablolarını ve indekslerini minimum kilitle yeniden düzenlemek için kullanılan açık kaynaklı bir uzantıdır.</p><p>VACUUM FULL işleminden farklı olarak yeniden düzenleme sürecinin büyük bölümünde normal okuma ve yazma işlemlerinin devam etmesine izin verir.</p><p>Genel çalışma akışı:</p><pre>Mevcut tablo<br>    ↓<br>Değişiklikleri kaydeden log tablosu oluştur<br>    ↓<br>Yeni tablo kopyasını oluştur<br>    ↓<br>Verileri yeni tabloya aktar<br>    ↓<br>İndeksleri yeniden oluştur<br>    ↓<br>İşlem sırasında oluşan değişiklikleri uygula<br>    ↓<br>Kısa süreli kilitle tabloları değiştir<br>    ↓<br>Eski tabloyu kaldır</pre><p>Bu yaklaşım sayesinde tabloyu uzun süre tamamen erişilemez hâle getirmeden fiziksel olarak yeniden düzenlemek mümkündür.</p><p>Ancak pg_repack için de bazı gereksinimler bulunur:</p><ul><li>Hedef tabloda Primary Key veya NOT NULL bir sütun üzerinde uygun UNIQUE indeks bulunmalıdır.</li><li>İşlem sırasında ek disk alanı gerekir. Tam tablo yeniden düzenlemede tablo ve indeks boyutlarının yaklaşık iki katı kadar ek boş alan gerekebilir.</li><li>Başlangıç ve son geçiş aşamalarında kısa süreli güçlü kilitler alınır.</li><li>Hedef tabloda işlem devam ederken DDL değişiklikleri sınırlandırılır.</li><li>Veritabanı sürümü, uzantı sürümü ve yönetilen veritabanı sağlayıcısının izinleri kontrol edilmelidir.</li></ul><p>Dolayısıyla pg_repack için de mutlak anlamda sıfır kesinti ifadesi doğru değildir. Daha doğru tanım, <strong>minimum kilitle ve normal işlemleri büyük ölçüde sürdürerek tablo yeniden düzenleme</strong> yaklaşımıdır.</p><p>Kaynak: <a href="https://github.com/reorg/pg_repack">pg_repack — Official GitHub Documentation</a>.</p><h3>pg_repack kurulumu ve kullanımı</h3><p>Öncelikle veritabanında uzantının kullanılabilir olup olmadığını kontrol edelim:</p><pre>SELECT<br>    name,<br>    default_version,<br>    installed_version<br>FROM pg_available_extensions<br>WHERE name = &#39;pg_repack&#39;;</pre><p>Destekleniyorsa uzantıyı etkinleştirebiliriz:</p><pre>CREATE EXTENSION IF NOT EXISTS pg_repack;</pre><p>Ardından pg_repack istemci aracını uygun PostgreSQL sürümüyle uyumlu biçimde kurmak gerekir.</p><p>Örnek çalıştırma:</p><pre>pg_repack \<br>  -h localhost \<br>  -p 5432 \<br>  -U postgres \<br>  -d production_db \<br>  --table public.users</pre><p>Bu komut public.users tablosunu yeniden düzenlemeyi hedefler. Gerçek kullanımda bağlantı bilgileri, yetkiler, disk kapasitesi ve çalışma penceresi önceden kontrol edilmelidir.</p><h3>8. Canlı veritabanı için bakım stratejisi</h3><p>Sağlıklı bir PostgreSQL sistemi için yalnızca sorun ortaya çıktığında VACUUM çalıştırmak yeterli değildir. Bakım süreçlerini düzenli olarak izlemek gerekir.</p><p>Önerilen yaklaşım:</p><p>KontrolAmaçn_dead_tupÖlü satır birikimini takip etmeklast_autovacuumOtomatik bakım sıklığını izlemekpg_stat_activityUzun transaction&#39;ları bulmakpg_replication_slotsEski xmin değerlerini tespit etmekTablo ve indeks boyutlarıDisk kullanımındaki değişimi takip etmekAutovacuum loglarıWorker performansını değerlendirmekXID yaşıTransaction ID wraparound riskini önlemek</p><p>Transaction ID yaşını kontrol etmek için:</p><pre>SELECT<br>    datname,<br>    age(datfrozenxid) AS xid_age<br>FROM pg_database<br>ORDER BY xid_age DESC;</pre><p>PostgreSQL’in transaction ID wraparound koruması kritik öneme sahiptir. Autovacuum yalnızca disk alanı temizliği için değil, eski transaction kimliklerinin freeze edilmesi için de gereklidir.</p><p>Bu nedenle Autovacuum’u tamamen kapatmak veya yalnızca disk bloat sorununa odaklanmak ciddi operasyonel risk oluşturabilir.</p><h3>Sonuç</h3><p>PostgreSQL’de VACUUM ve Autovacuum, veritabanının uzun vadeli performansını ve güvenilirliğini korumak için temel bakım mekanizmalarıdır.</p><p>Standart VACUUM, ölü satır sürümlerini temizleyerek alanı yeniden kullanılabilir hâle getirir. Autovacuum ise bu işlemi otomatikleştirir. VACUUM FULL ve pg_repack gibi yeniden yazma yöntemleri, gerçekten fiziksel alanın geri kazanılması gerektiğinde değerlendirilmelidir.</p><p>Canlı sistemlerde en doğru yaklaşım, önce sorunun kaynağını ölçmek, ardından tablo bazlı bakım eşiklerini iş yüküne göre ayarlamak ve uzun transaction’ları izlemektir.</p><p>Unutulmaması gereken temel nokta şu: <strong>İyi veritabanı bakımı, sorun çıktıktan sonra tabloyu küçültmek değil; gereksiz büyümenin ve bakım birikiminin önüne geçmektir.</strong></p><h3>Kaynaklar</h3><ul><li><a href="https://www.postgresql.org/docs/current/routine-vacuuming.html">PostgreSQL — Routine Vacuuming</a></li><li><a href="https://www.postgresql.org/docs/current/sql-vacuum.html">PostgreSQL — VACUUM</a></li><li><a href="https://www.postgresql.org/docs/current/runtime-config-autovacuum.html">PostgreSQL — Autovacuum Configuration</a></li><li><a href="https://github.com/reorg/pg_repack">pg_repack — Official Documentation</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b0efeb8cd4b5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Next.js App Router’da Dynamic OG Image (Open Graph) Üretimi: @vercel/og ve Edge SVG Mimarisi]]></title>
            <link>https://affanccn.medium.com/next-js-app-routerda-dynamic-og-image-open-graph-%C3%BCretimi-vercel-og-ve-edge-svg-mimarisi-90e3a7a7cfa0?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/90e3a7a7cfa0</guid>
            <category><![CDATA[satori]]></category>
            <category><![CDATA[open-graph]]></category>
            <category><![CDATA[vercel]]></category>
            <category><![CDATA[nextjs]]></category>
            <category><![CDATA[seo]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 07:47:34 GMT</pubDate>
            <atom:updated>2026-10-27T07:47:34.285Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7ySWMsqt7Rdl-m6JQkqWvw.jpeg" /></figure><h3>Next.js App Router’da Dynamic OG Image Üretimi: @vercel/og ve Satori Mimarisi</h3><p>Bir blog yazısı veya portföy projesi LinkedIn, WhatsApp, Slack ya da X üzerinde paylaşıldığında bağlantının önizleme kartı, kullanıcının içerikle ilgili ilk izlenimini oluşturur. Başlığı, kategorisi ve yazar bilgilerini içeren özgün bir Open Graph (OG) görseli, sitenin daha tutarlı ve profesyonel görünmesine yardımcı olur.</p><p>Her yazı için Photoshop veya Figma üzerinden ayrı bir kapak hazırlamak yerine görselleri otomatik üretebiliriz. Next.js App Router’ın <strong>opengraph-image.tsx dosya kuralı</strong> ve ImageResponse API&#39;si, JSX benzeri bir şablondan sosyal medya görseli üretmemizi sağlar.</p><p>Bu mimaride Satori, JSX ve desteklenen CSS özelliklerini SVG’ye dönüştürür; Resvg ise SVG’yi PNG gibi bir raster görsele dönüştürür. Böylece her blog yazısına özel görselleri uygulama içinden oluşturabiliriz.</p><blockquote><em>Önemli: Dinamik OG görseli üretimi, tek başına tıklama oranını üç katına çıkarmaz veya her istekte milisaniyeler içinde tamamlanmayı garanti etmez. Sonuç; görsel tasarımına, veri kaynağına, fontlara, çalışma ortamına ve önbelleğe bağlıdır.</em></blockquote><h3>1. @vercel/og ve Satori nasıl çalışır?</h3><p>Mimarinin temel akışı şöyledir:</p><pre>Blog URL&#39;si<br>    ↓<br>app/blog/[slug]/opengraph-image.tsx<br>    ↓<br>Slug üzerinden yazı verisini al<br>    ↓<br>JSX + desteklenen CSS<br>    ↓<br>Satori: JSX → SVG<br>    ↓<br>Resvg: SVG → PNG<br>    ↓<br>Sosyal medya önizleme görseli</pre><p>Burada üç bileşeni birbirinden ayırmak gerekir:</p><ul><li><strong>ImageResponse:</strong> Next.js üzerinden görsel yanıtı oluşturmak için kullanılan API&#39;dir.</li><li><strong>Satori:</strong> JSX benzeri yapıyı ve desteklenen CSS özelliklerini SVG düzenine dönüştürür.</li><li><strong>Resvg:</strong> Oluşturulan SVG’yi PNG gibi raster bir formata dönüştürür.</li></ul><p>Bu sistem, her görsel için ayrı bir headless Chrome başlatmayı gerektirmez. Ancak Satori, tam bir tarayıcı motoru değildir. CSS Grid gibi tüm CSS özellikleri desteklenmez; Flexbox tabanlı tasarımlar daha uygundur.</p><p>Ayrıca Edge Runtime kullanmak zorunlu bir performans garantisi değildir. Çalışma ortamını seçerken kullandığın veri kaynağının, veritabanı sürücüsünün ve dosya erişim yöntemlerinin o ortamla uyumlu olması gerekir.</p><p>Kaynaklar: <a href="https://nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image">Next.js — Open Graph Images</a>, <a href="https://vercel.com/docs/og-image-generation">Vercel — OG Image Generation</a>.</p><h3>2. App Router’da dosya yapısı</h3><p>Next.js, özel metadata dosyalarını otomatik algılar. Her blog yazısı için farklı bir görsel üretmek amacıyla aşağıdaki yapıyı kullanabiliriz:</p><pre>app/<br>└── blog/<br>    └── [slug]/<br>        ├── page.tsx<br>        └── opengraph-image.tsx</pre><p>opengraph-image.tsx, ilgili blog rotasının OG görselini üretir. Next.js, dosya kuralı sayesinde uygun og:image metadata etiketini otomatik olarak oluşturur. Ayrıca alt, size ve contentType dışa aktarımlarıyla görselin alternatif metnini, boyutlarını ve içerik türünü belirtebiliriz.</p><p>Önerilen sosyal medya görseli boyutu <strong>1200 × 630 piksel</strong> şeklindedir.</p><h3>3. Dinamik OG Image kodu</h3><p>Aşağıdaki örnekte slug üzerinden yazı bilgilerini alıp kategori, başlık, yazar ve okuma süresini içeren bir görsel oluşturuyoruz.</p><p>app/blog/[slug]/opengraph-image.tsx:</p><pre>import { ImageResponse } from &quot;next/og&quot;;<br>import { getPostBySlug } from &quot;@/lib/posts&quot;;</pre><pre>export const alt = &quot;Teknik blog yazısı önizlemesi&quot;;</pre><pre>export const size = {<br>  width: 1200,<br>  height: 630,<br>};</pre><pre>export const contentType = &quot;image/png&quot;;</pre><pre>export default async function Image({<br>  params,<br>}: {<br>  params: Promise&lt;{ slug: string }&gt;;<br>}) {<br>  const { slug } = await params;<br>  const post = await getPostBySlug(slug);</pre><pre>  if (!post) {<br>    return new ImageResponse(<br>      (<br>        &lt;div<br>          style={{<br>            width: &quot;100%&quot;,<br>            height: &quot;100%&quot;,<br>            display: &quot;flex&quot;,<br>            alignItems: &quot;center&quot;,<br>            justifyContent: &quot;center&quot;,<br>            backgroundColor: &quot;#0f172a&quot;,<br>            color: &quot;#f8fafc&quot;,<br>            fontSize: 48,<br>          }}<br>        &gt;<br>          Yazı bulunamadı<br>        &lt;/div&gt;<br>      ),<br>      size,<br>    );<br>  }</pre><pre>  return new ImageResponse(<br>    (<br>      &lt;div<br>        style={{<br>          width: &quot;100%&quot;,<br>          height: &quot;100%&quot;,<br>          display: &quot;flex&quot;,<br>          flexDirection: &quot;column&quot;,<br>          justifyContent: &quot;space-between&quot;,<br>          padding: &quot;60px 72px&quot;,<br>          backgroundColor: &quot;#0f172a&quot;,<br>          color: &quot;#f8fafc&quot;,<br>          fontFamily: &quot;sans-serif&quot;,<br>        }}<br>      &gt;<br>        &lt;div<br>          style={{<br>            display: &quot;flex&quot;,<br>            justifyContent: &quot;space-between&quot;,<br>            alignItems: &quot;center&quot;,<br>          }}<br>        &gt;<br>          &lt;div<br>            style={{<br>              display: &quot;flex&quot;,<br>              backgroundColor: &quot;#2563eb&quot;,<br>              color: &quot;#ffffff&quot;,<br>              padding: &quot;10px 18px&quot;,<br>              borderRadius: 999,<br>              fontSize: 20,<br>              fontWeight: 700,<br>            }}<br>          &gt;<br>            {post.category ?? &quot;Yazılım Mühendisliği&quot;}<br>          &lt;/div&gt;</pre><pre>          &lt;div<br>            style={{<br>              display: &quot;flex&quot;,<br>              color: &quot;#94a3b8&quot;,<br>              fontSize: 24,<br>              fontWeight: 600,<br>            }}<br>          &gt;<br>            affanccn.com<br>          &lt;/div&gt;<br>        &lt;/div&gt;</pre><pre>        &lt;div<br>          style={{<br>            display: &quot;flex&quot;,<br>            flexDirection: &quot;column&quot;,<br>            gap: 20,<br>          }}<br>        &gt;<br>          &lt;div<br>            style={{<br>              display: &quot;flex&quot;,<br>              color: &quot;#38bdf8&quot;,<br>              fontSize: 20,<br>              fontWeight: 700,<br>            }}<br>          &gt;<br>            SOFTWARE ENGINEERING<br>          &lt;/div&gt;</pre><pre>          &lt;h1<br>            style={{<br>              margin: 0,<br>              fontSize: 56,<br>              lineHeight: 1.2,<br>              fontWeight: 800,<br>              letterSpacing: -1.5,<br>              color: &quot;#f8fafc&quot;,<br>            }}<br>          &gt;<br>            {post.title}<br>          &lt;/h1&gt;<br>        &lt;/div&gt;</pre><pre>        &lt;div<br>          style={{<br>            display: &quot;flex&quot;,<br>            justifyContent: &quot;space-between&quot;,<br>            alignItems: &quot;center&quot;,<br>            borderTop: &quot;2px solid #334155&quot;,<br>            paddingTop: 24,<br>          }}<br>        &gt;<br>          &lt;div<br>            style={{<br>              display: &quot;flex&quot;,<br>              alignItems: &quot;center&quot;,<br>              gap: 16,<br>            }}<br>          &gt;<br>            &lt;div<br>              style={{<br>                width: 48,<br>                height: 48,<br>                borderRadius: 24,<br>                display: &quot;flex&quot;,<br>                alignItems: &quot;center&quot;,<br>                justifyContent: &quot;center&quot;,<br>                backgroundColor: &quot;#38bdf8&quot;,<br>                color: &quot;#0f172a&quot;,<br>                fontSize: 20,<br>                fontWeight: 800,<br>              }}<br>            &gt;<br>              AE<br>            &lt;/div&gt;</pre><pre>            &lt;div<br>              style={{<br>                display: &quot;flex&quot;,<br>                fontSize: 22,<br>                fontWeight: 600,<br>              }}<br>            &gt;<br>              Affan Emirhan Çüçen<br>            &lt;/div&gt;<br>          &lt;/div&gt;</pre><pre>          &lt;div<br>            style={{<br>              display: &quot;flex&quot;,<br>              color: &quot;#94a3b8&quot;,<br>              fontSize: 20,<br>            }}<br>          &gt;<br>            {post.readingTime ?? &quot;5 dakika okuma&quot;}<br>          &lt;/div&gt;<br>        &lt;/div&gt;<br>      &lt;/div&gt;<br>    ),<br>    size,<br>  );<br>}</pre><h3>Bu kodda dikkat edilmesi gerekenler</h3><p><strong>1. </strong><strong>params artık Promise olarak ele alınıyor.</strong> Next.js 15 ve özellikle Next.js 16 ile uyumlu yaklaşım, dinamik parametreleri await params ile almaktır.</p><p><strong>2. </strong><strong>getPostBySlug uygulamaya ait bir fonksiyondur.</strong> Yukarıdaki örnekte bu fonksiyonun yazıyı bulduğunu ve title, category ve readingTime alanlarını döndürdüğünü varsayıyoruz. Kendi içerik modeline göre uyarlamalısın.</p><p><strong>3. CSS desteği sınırlıdır.</strong> display: flex, flexDirection, justifyContent ve alignItems gibi özellikler uygundur. Karmaşık bir web sayfasını olduğu gibi görsele dönüştürmeye çalışmak yerine görsel üretimine özel, basit bir şablon hazırlamak daha doğrudur.</p><p><strong>4. Runtime seçimini veri kaynağına göre yapmalısın.</strong> getPostBySlug Node.js&#39;e özel bir veritabanı sürücüsü kullanıyorsa Edge uyumluluğunu varsayma. Gerektiğinde Node.js Runtime kullan veya Edge uyumlu bir veri erişim katmanı oluştur.</p><h3>4. Özel font kullanımı</h3><p>Varsayılan fontlar yerine Inter veya Geist gibi bir yazı tipi kullanmak, marka kimliğini güçlendirebilir. Bunun için font dosyasını ImageResponse seçeneklerine aktarabiliriz.</p><p>Örneğin font dosyası public/fonts/Inter-Bold.ttf konumunda bulunuyorsa ve uygulama fontu HTTP üzerinden sunabiliyorsa:</p><pre>import { ImageResponse } from &quot;next/og&quot;;</pre><pre>const fontResponse = await fetch(<br>  new URL(<br>    &quot;https://affanccn.com/fonts/Inter-Bold.ttf&quot;,<br>  ),<br>);</pre><pre>if (!fontResponse.ok) {<br>  throw new Error(&quot;Font dosyası yüklenemedi.&quot;);<br>}</pre><pre>const interBold = await fontResponse.arrayBuffer();</pre><pre>return new ImageResponse(<br>  (<br>    &lt;div<br>      style={{<br>        display: &quot;flex&quot;,<br>        fontFamily: &quot;Inter&quot;,<br>        fontSize: 64,<br>      }}<br>    &gt;<br>      Dinamik OG Image<br>    &lt;/div&gt;<br>  ),<br>  {<br>    width: 1200,<br>    height: 630,<br>    fonts: [<br>      {<br>        name: &quot;Inter&quot;,<br>        data: interBold,<br>        style: &quot;normal&quot;,<br>        weight: 700,<br>      },<br>    ],<br>  },<br>);</pre><p>Bu parça, görseli döndüren fonksiyonun içinde kullanılacak font yükleme örneğidir; tek başına tam bir opengraph-image.tsx dosyası değildir.</p><p>Üretim ortamında font dosyasını güvenilir, sabit bir URL üzerinden sunmak ve gereksiz ağ isteklerinden kaçınmak önemlidir. Yerel dosya sisteminden font okumak istiyorsan bunu kullandığın Runtime’ın desteklediğinden emin olmalısın. Font dosyaları için TTF ve OTF formatları genellikle uygun seçeneklerdir.</p><p>Kaynak: <a href="https://vercel.com/docs/og-image-generation">Vercel — OG Image Generation</a>.</p><h3>5. Önbellekleme ve performans</h3><p>Dinamik görsellerin her sosyal medya taramasında yeniden hesaplanması gerekmeyebilir. Next.js’in özel metadata dosyaları varsayılan olarak uygun durumlarda statik optimizasyona ve önbelleğe alınmaya uygundur. Ancak dinamik API kullanımı, veri erişimi ve segment yapılandırması bu davranışı değiştirebilir.</p><p>Bu nedenle her görsel için koşulsuz olarak s-maxage=31536000, immutable tanımlamak doğru bir varsayılan değildir. İçerik değişebiliyorsa bir yıl boyunca değişmez olarak önbelleğe almak eski başlığın gösterilmesine yol açabilir.</p><p>Uygulamada şu noktaları değerlendirmek gerekir:</p><ul><li><strong>İçerik ne sıklıkla değişiyor?</strong> Başlık ve kategori güncellenebiliyorsa önbellek geçersizleştirme stratejisi belirle.</li><li><strong>Görsel statik mi, dinamik mi?</strong> Derleme sırasında üretilebilen görsellerle istek sırasında veri çeken görsellerin önbellekleme davranışları aynı olmayabilir.</li><li><strong>Font ve veri istekleri ne kadar maliyetli?</strong> Her istekte uzaktaki bir fontu veya içerik servisini çağırmak gereksiz gecikme oluşturabilir.</li><li><strong>Sosyal medya önizlemeleri ne zaman yenileniyor?</strong> Platformlar kendi önbelleklerini tutabilir. Sitedeki görseli güncellemek, önizlemenin her platformda hemen değişeceği anlamına gelmez.</li></ul><p>Next.js’in metadata dosya kuralı, dosyaya ait uygun metadata etiketlerini ve üretim ortamındaki önbellekleme davranışını yönetir. Özel bir Route Handler ile görsel üretiyorsan yanıt başlıklarını ayrıca tasarlaman gerekebilir.</p><p>Kaynaklar: <a href="https://nextjs.org/docs/app/api-reference/file-conventions/metadata">Next.js — Metadata Files</a>, <a href="https://vercel.com/docs/og-image-generation/og-image-api">Vercel — OG Image API</a>.</p><h3>6. SEO ve sosyal medya önizlemesi için kontrol listesi</h3><p>Dinamik OG Image üretimini tamamladıktan sonra yalnızca kodun çalıştığını doğrulamak yeterli değildir.</p><ol><li><strong>Meta etiketlerini kontrol et:</strong> Sayfanın HTML çıktısında doğru og:image, og:image:width, og:image:height ve alternatif metin alanlarının üretildiğini doğrula.</li><li><strong>Görsel URL’sini doğrudan aç:</strong> Her slug için görselin başarıyla üretildiğini, doğru başlığı gösterdiğini ve PNG olarak döndüğünü kontrol et.</li><li><strong>Uzun başlıkları test et:</strong> Türkçe karakterler, uzun kelimeler ve birden fazla satıra yayılan başlıklar görselin dışına taşmamalı.</li><li><strong>Olmayan yazıları ele al:</strong> Geçersiz slug için anlamlı bir hata veya tasarlanmış bir varsayılan görsel üret.</li><li><strong>Sosyal platformlarda doğrula:</strong> LinkedIn ve diğer platformların önizleme araçlarıyla URL’yi kontrol et. Platformların kendi önbelleklerini tuttuğunu unutma.</li><li><strong>Üretim ortamında performansı ölç:</strong> İlk üretim süresiyle önbellekten gelen yanıtı ayrı değerlendir; sabit bir gecikme hedefini tüm dağıtımlar için garanti kabul etme.</li></ol><h3>Sonuç</h3><p>Next.js App Router’ın opengraph-image.tsx dosya kuralı, her blog yazısı için ayrı sosyal medya görseli hazırlama işini otomatikleştirebilir. ImageResponse, Satori ve Resvg birlikte kullanıldığında HTML benzeri bir şablondan görsel üretmek mümkün olur.</p><p>Ancak iyi bir uygulama yalnızca görsel üretmekten ibaret değildir. Doğru veri erişimi, Runtime uyumluluğu, font yükleme stratejisi, önbellek politikası ve hatalı slug davranışı da mimarinin parçasıdır.</p><p>Kişisel blog veya portföy projelerinde bu yaklaşım, içeriklerin görsel tutarlılığını korurken manuel tasarım iş yükünü azaltmak için etkili bir çözümdür.</p><h3>Kaynaklar</h3><ul><li><a href="https://nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image">Next.js — Open Graph Images</a></li><li><a href="https://nextjs.org/docs/app/getting-started/metadata-and-og-images">Next.js — Metadata and OG Images</a></li><li><a href="https://vercel.com/docs/og-image-generation">Vercel — OG Image Generation</a></li><li><a href="https://github.com/vercel/satori">Satori — GitHub</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=90e3a7a7cfa0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Flutter’da MethodChannel ve EventChannel ile Platform Kanalları (Platform Channels) Mimarisi]]></title>
            <link>https://affanccn.medium.com/flutterda-methodchannel-ve-eventchannel-ile-platform-kanallar%C4%B1-platform-channels-mimarisi-f3c8c25096cc?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/f3c8c25096cc</guid>
            <category><![CDATA[event-channel]]></category>
            <category><![CDATA[swift]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[method-channel]]></category>
            <category><![CDATA[flutter]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 07:45:13 GMT</pubDate>
            <atom:updated>2026-10-27T07:45:13.141Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Obbfi8ALZeYcdTujan7fTQ.jpeg" /></figure><h3>Flutter’da MethodChannel ve EventChannel: Platform Channels Mimarisi</h3><p>Flutter, çoğu mobil geliştirme ihtiyacını pub.dev üzerindeki paketlerle karşılayabilir. Ancak kurumsal uygulamalarda özel bir Bluetooth SDK&#39;sı, platforma özgü bir donanım API&#39;si, biyometrik bir modül veya mevcut bir Kotlin/Swift kütüphanesiyle iletişim kurmak gerekebilir.</p><p>Bu gibi durumlarda Dart kodu ile yerel platform kodu arasında bir iletişim köprüsü kurulur. Flutter bu amaçla <strong>Platform Channels</strong> mimarisini sunar.</p><p>Bu yazıda MethodChannel ile tekil istek-yanıt iletişimini, EventChannel ile sürekli veri akışını, hata yönetimini ve daha büyük projelerde Pigeon kullanımını inceleyeceğiz.</p><h3>1. Platform Channels nasıl çalışır?</h3><p>Flutter uygulamasının Dart katmanı ile Android ve iOS’un yerel kodu farklı çalışma ortamlarında bulunur. Bu katmanlar, Platform Channels aracılığıyla mesaj alışverişi yapar.</p><p>Mesajlar BinaryMessenger üzerinden taşınır ve varsayılan olarak StandardMessageCodec ile serileştirilir. Bu codec; sayılar, metinler, boolean değerler, listeler, map&#39;ler ve byte dizileri gibi desteklenen veri türlerini aktarabilir.</p><p>İki temel kanal türü öne çıkar:</p><ul><li><strong>MethodChannel:</strong> Belirli bir işlemi çağırmak ve sonucunu almak için kullanılır. Örneğin, pil seviyesini okumak veya yerel bir SDK üzerinden cihaz başlatmak.</li><li><strong>EventChannel:</strong> Yerel platformdan Dart tarafına zaman içinde birden fazla olay iletmek için kullanılır. Örneğin, sensör değişiklikleri veya Bluetooth bağlantı durumu.</li></ul><p>Her iki tarafta da kanal adlarının ve veri sözleşmesinin eşleşmesi gerekir. Kanal çağrıları asenkron olsa da yerel taraftaki işlemlerin doğru thread üzerinde yürütülmesi önemlidir.</p><p>Kaynak: <a href="https://docs.flutter.dev/platform-integration/platform-channels">Flutter — Writing custom platform-specific code</a>.</p><h3>2. MethodChannel ile pil seviyesi okuma</h3><p>İlk örnekte Dart tarafından getBatteryLevel metodunu çağıracağız. Android&#39;de BatteryManager, iOS&#39;ta ise UIDevice kullanılacak.</p><h3>Dart: Platform servisi</h3><p>lib/services/battery_service.dart:</p><pre>import &#39;package:flutter/services.dart&#39;;</pre><pre>class BatteryService {<br>  static const MethodChannel _channel =<br>      MethodChannel(&#39;com.portfolio.app/battery&#39;);</pre><pre>  static Future&lt;int&gt; getBatteryLevel() async {<br>    final level = await _channel.invokeMethod&lt;int&gt;(<br>      &#39;getBatteryLevel&#39;,<br>    );</pre><pre>    if (level == null || level &lt; 0 || level &gt; 100) {<br>      throw PlatformException(<br>        code: &#39;INVALID_BATTERY_LEVEL&#39;,<br>        message: &#39;Geçerli bir pil seviyesi alınamadı.&#39;,<br>      );<br>    }</pre><pre>    return level;<br>  }<br>}</pre><p>invokeMethod&lt;int&gt; kullanmak, dönen değerin beklenen türünü açıkça belirtir. Ancak kanal üzerinden taşınan veriler çalışma zamanında çözümlendiğinden bu kullanım, uçtan uca derleme zamanı tip güvenliği sağlamaz.</p><p>Burada hata durumunu -1 gibi özel bir dönüş değeriyle gizlemek yerine PlatformException ile çağıran katmana iletiyoruz. Böylece arayüz, hata durumunu başarıyla alınmış bir pil seviyesinden ayırabilir.</p><p>Örneğin çağıran kod:</p><pre>try {<br>  final level = await BatteryService.getBatteryLevel();<br>  // Pil seviyesini arayüzde göster.<br>} on PlatformException catch (e) {<br>  // Hata durumunu kullanıcıya uygun şekilde göster.<br>}</pre><h3>Android: Kotlin</h3><p>MainActivity.kt:</p><pre>package com.portfolio.app</pre><pre>import android.content.Context<br>import android.os.BatteryManager<br>import io.flutter.embedding.android.FlutterActivity<br>import io.flutter.embedding.engine.FlutterEngine<br>import io.flutter.plugin.common.MethodChannel</pre><pre>class MainActivity : FlutterActivity() {</pre><pre>    companion object {<br>        private const val CHANNEL =<br>            &quot;com.portfolio.app/battery&quot;<br>    }</pre><pre>    override fun configureFlutterEngine(<br>        flutterEngine: FlutterEngine<br>    ) {<br>        super.configureFlutterEngine(flutterEngine)</pre><pre>        MethodChannel(<br>            flutterEngine.dartExecutor.binaryMessenger,<br>            CHANNEL<br>        ).setMethodCallHandler { call, result -&gt;</pre><pre>            when (call.method) {<br>                &quot;getBatteryLevel&quot; -&gt; {<br>                    val batteryManager =<br>                        getSystemService(<br>                            Context.BATTERY_SERVICE<br>                        ) as BatteryManager</pre><pre>                    val level = batteryManager.getIntProperty(<br>                        BatteryManager.BATTERY_PROPERTY_CAPACITY<br>                    )</pre><pre>                    if (level in 0..100) {<br>                        result.success(level)<br>                    } else {<br>                        result.error(<br>                            &quot;UNAVAILABLE&quot;,<br>                            &quot;Pil seviyesi okunamadı.&quot;,<br>                            null<br>                        )<br>                    }<br>                }</pre><pre>                else -&gt; result.notImplemented()<br>            }<br>        }<br>    }<br>}</pre><p>Android tarafında result.success() ile başarılı yanıt, result.error() ile yapılandırılmış hata döndürülür. Flutter&#39;daki try-catch bloğu bu hatayı PlatformException olarak yakalayabilir.</p><p>Bu örnekte kullanılan pil API’si basit ve hızlı bir sistem sorgusudur. Daha uzun süren veya yoğun hesaplama yapan yerel işlemler için thread yönetimi ayrıca tasarlanmalıdır.</p><h3>iOS: Swift</h3><p>iOS tarafında pil izleme özelliğini açıp UIDevice.current.batteryLevel değerini okuruz. Bu API&#39;nin sonucu 0.0–1.0 aralığında olabilir; desteklenmeyen veya henüz alınamayan değer -1.0 olarak dönebilir.</p><p>Aşağıdaki kod, kanal kurulumunun mevcut Flutter engine’ine bağlı olarak yapıldığını varsayar:</p><pre>import Flutter<br>import UIKit</pre><pre>final class BatteryChannel {<br>    static func register(<br>        with messenger: FlutterBinaryMessenger<br>    ) {<br>        let channel = FlutterMethodChannel(<br>            name: &quot;com.portfolio.app/battery&quot;,<br>            binaryMessenger: messenger<br>        )</pre><pre>        UIDevice.current.isBatteryMonitoringEnabled = true</pre><pre>        channel.setMethodCallHandler { call, result in<br>            guard call.method == &quot;getBatteryLevel&quot; else {<br>                result(FlutterMethodNotImplemented)<br>                return<br>            }</pre><pre>            let batteryLevel = UIDevice.current.batteryLevel</pre><pre>            guard batteryLevel &gt;= 0 else {<br>                result(<br>                    FlutterError(<br>                        code: &quot;UNAVAILABLE&quot;,<br>                        message: &quot;Pil seviyesi okunamadı.&quot;,<br>                        details: nil<br>                    )<br>                )<br>                return<br>            }</pre><pre>            result(Int(batteryLevel * 100))<br>        }<br>    }<br>}</pre><p>BatteryChannel.register(with:) metodunu uygulamanın Flutter engine kurulumunda, kullanılan Flutter sürümünün ve proje yaşam döngüsünün önerdiği noktada çağırmalısınız. Yeni Flutter şablonlarında UIScene yaşam döngüsü nedeniyle AppDelegate içindeki window?.rootViewController üzerinden controller almaya dayanan eski örnekler güvenilir olmayabilir.</p><p>Önemli bir ayrıntı: UIDevice.current.isBatteryMonitoringEnabled = true ile açılan izleme özelliği, uygulamanın yaşam döngüsüne göre yönetilmelidir. Gerçek zamanlı pil değişiklikleri de dinlenecekse yalnızca bir kez değer okumak yerine uygun bildirimleri dinleyip dinleme sona erdiğinde kaynakları temizlemek gerekir.</p><h3>3. EventChannel ile sürekli veri akışı</h3><p>MethodChannel, tek bir çağrı için idealdir. Ancak Bluetooth bağlantısı, sensör değişiklikleri veya şarj durumu gibi zaman içinde tekrarlanan olayları izlemek için EventChannel daha uygundur.</p><h3>Dart: Stream oluşturma</h3><pre>import &#39;package:flutter/services.dart&#39;;</pre><pre>class ChargingService {<br>  static const EventChannel _channel =<br>      EventChannel(&#39;com.portfolio.app/charging_stream&#39;);</pre><pre>  Stream&lt;String&gt; get chargingStatusStream {<br>    return _channel<br>        .receiveBroadcastStream()<br>        .map((event) =&gt; event as String);<br>  }<br>}</pre><p>Kullanımı:</p><pre>final chargingService = ChargingService();</pre><pre>final subscription =<br>    chargingService.chargingStatusStream.listen(<br>  (status) {<br>    // Örneğin: CHARGING veya NOT_CHARGING<br>  },<br>  onError: (Object error) {<br>    // Platform akışı hatalarını ele al.<br>  },<br>);</pre><pre>// Artık dinlemeye gerek kalmadığında:<br>await subscription.cancel();</pre><p>Bu kodda receiveBroadcastStream() bir Stream üretir. Akışın ne zaman başlayıp duracağı, yerel taraftaki StreamHandler uygulamasıyla ilişkilidir.</p><h3>Android tarafındaki temel yaşam döngüsü</h3><p>Kotlin’de EventChannel.StreamHandler uygulanırken iki metot önemlidir:</p><ul><li>onListen: Dart tarafında dinleme başladığında sistem olaylarına abone olunur.</li><li>onCancel: Dinleme sona erdiğinde alıcılar, listener&#39;lar ve diğer kaynaklar temizlenir.</li></ul><p>Örneğin, BroadcastReceiver kullanılıyorsa dinleme başlarken kaydedilmeli ve iptal edildiğinde uygun biçimde kaldırılmalıdır. Uygulama yaşam döngüsü ve Android sürümüne göre alıcı kaydı ayrıca değerlendirilmelidir.</p><h3>iOS tarafındaki temel yaşam döngüsü</h3><p>Swift tarafında da FlutterStreamHandler kullanılır. onListen sırasında gerekli bildirim gözlemcileri eklenir; onCancel sırasında bunlar kaldırılır.</p><p>Pil durumunu dinlemek için örneğin UIDevice.batteryStateDidChangeNotification değerlendirilebilir. Ancak örneğin gerçek bir pil durumu akışı üretmesi için bildirimlerin EventChannel üzerinden FlutterEventSink nesnesine iletilmesi gerekir.</p><p>Her iki platformda da temel kural aynıdır: <strong>Dart tarafındaki abonelik iptal edildiğinde gereksiz yerel dinleyiciler çalışmaya devam etmemelidir.</strong> Aksi hâlde gereksiz kaynak tüketimi, yinelenen olaylar ve yaşam döngüsü kaynaklı hatalar oluşabilir.</p><p>Ayrıca EventChannel üzerinden gönderilen olaylar varsayılan olarak kalıcı bir mesaj kuyruğu oluşturmaz. Uygulama yeniden açıldığında geçmiş olayların da alınması gerekiyorsa bu geçmişin ayrıca saklanması gerekir.</p><h3>4. PlatformException ve hata sözleşmesi</h3><p>Platform Channels kullanırken yalnızca başarılı senaryoyu değil, hata sözleşmesini de tasarlamak gerekir.</p><p>DurumÖnerilen yaklaşımMetot desteklenmiyornotImplemented()Yerel API kullanılamıyorYapılandırılmış hata kodu döndürmekParametre geçersizGirdiyi doğrulayıp hata döndürmekPlatformdan beklenmeyen yanıtDart tarafında tür ve değer kontrolü yapmakStream hatasıonError ile ele almak ve gerekiyorsa yeniden abonelik stratejisi belirlemek</p><p>Yerel tarafta result.success(), result.error() veya result.notImplemented() çağrıları her metot çağrısı için doğru biçimde sonuçlandırılmalıdır. Birden fazla kez yanıt vermek veya bazı kod yollarında hiç yanıt vermemek, iletişim sorunlarına yol açabilir.</p><p>Hata mesajlarını doğrudan kullanıcıya göstermek yerine hata kodlarını uygulamanın domain veya uygulama katmanındaki anlamlı hata türlerine dönüştürmek daha sağlıklı bir yaklaşımdır.</p><h3>5. Büyük projelerde Pigeon: Tip güvenli iletişim</h3><p>Elle yazılmış MethodChannel çağrılarında kanal adları, metot isimleri ve parametre türleri Dart, Kotlin ve Swift taraflarında ayrı ayrı tutulur. Bu durum yazım hatalarına ve taraflar arasında sözleşme uyuşmazlıklarına neden olabilir.</p><p><a href="https://pub.dev/packages/pigeon">Pigeon</a>, tek bir Dart tanımından platform iletişimi için kod üretir. Kotlin/Java ve Swift/Objective-C desteğinin yanında, uygun yapılandırmayla EventChannel tabanlı API’ler de tanımlanabilir.</p><p>Örnek bir API tanımı:</p><pre>import &#39;package:pigeon/pigeon.dart&#39;;</pre><pre>class BatteryInfo {<br>  final int level;</pre><pre>  BatteryInfo({required this.level});<br>}</pre><pre>@HostApi()<br>abstract class BatteryApi {<br>  @async<br>  BatteryInfo getBatteryLevel();<br>}</pre><p>Bu dosya, kullanılan Pigeon sürümünün yapılandırmasına göre kod üretiminde girdi olarak kullanılır. Üretilen Dart ve yerel platform dosyaları projeye eklenir; Android ve iOS tarafında ilgili arayüz uygulanır.</p><p>Örneğin bağımlılığı geliştirme bağımlılığı olarak ekledikten sonra, yapılandırılmış giriş dosyanız için dart run pigeon komutunu çalıştırabilirsiniz. Üretim seçenekleri ve dosya yolları proje yapılandırmasına göre belirlenir.</p><p>Pigeon’ın başlıca avantajları:</p><ul><li>Kanal ve metot isimlerini elle eşleştirme ihtiyacını azaltır.</li><li>Parametre ve dönüş değerleri için daha güçlü tip denetimi sağlar.</li><li>Daha büyük API sözleşmelerinin bakımını kolaylaştırır.</li><li>Dart ile yerel platform kodu arasındaki iletişim kodunun önemli bir kısmını otomatik üretir.</li></ul><p>Bununla birlikte Pigeon, bütün çalışma zamanı hatalarını ortadan kaldırmaz. Donanımın kullanılamaması, izin eksikliği, bağlantı kopması veya yerel API’nin hata vermesi gibi durumlar yine ele alınmalıdır. Ayrıca iki platformda üretilen kodun aynı Pigeon sürümüyle uyumlu olması önemlidir.</p><h3>6. Clean Architecture içinde Platform Channels</h3><p>Platform Channels kodunu doğrudan widget’ların içine yerleştirmek, kullanıcı arayüzünü platform ayrıntılarına bağımlı hâle getirir. Daha sürdürülebilir bir yapı için yerel iletişimi ayrı bir servis veya data source içinde tutmak daha uygundur.</p><p>Örnek katman ayrımı:</p><pre>lib/<br>├── features/<br>│   └── device_status/<br>│       ├── domain/<br>│       │   ├── entities/<br>│       │   └── repositories/<br>│       ├── data/<br>│       │   ├── datasources/<br>│       │   │   └── battery_platform_datasource.dart<br>│       │   └── repositories/<br>│       └── presentation/<br>│           └── device_status_page.dart<br>└── core/<br>    └── platform/<br>        └── platform_error_mapper.dart</pre><pre>android/<br>└── app/src/main/kotlin/</pre><pre>ios/<br>└── Runner/</pre><p>Burada domain katmanı MethodChannel, FlutterMethodChannel, UIDevice veya BatteryManager gibi teknoloji ayrıntılarını bilmez. Domain yalnızca pil seviyesi gibi bir kavramı ve bu kavrama erişen repository sözleşmesini tanır.</p><p>Data katmanı platform servisini çağırır, dönen veriyi doğrular ve platform hatalarını uygulamanın hata modeline dönüştürür. Presentation katmanı ise yalnızca repository veya use case üzerinden çalışır.</p><p>Bu ayrım, platform kodunun değişmesini, sahte veriyle test yapılmasını ve aynı domain mantığının farklı platformlarda kullanılmasını kolaylaştırır.</p><h3>Sonuç</h3><p>Flutter Platform Channels, Dart ile yerel platform API’leri arasında kontrollü bir iletişim katmanı sağlar. MethodChannel tekil istek-yanıt işlemleri, EventChannel ise sürekli olay akışları için uygundur. Kaynak yönetimi, thread kullanımı ve hata sözleşmesi doğru tasarlanmadığında bu köprü uygulamanın güvenilirliğini olumsuz etkileyebilir.</p><p>Küçük ve basit entegrasyonlarda doğrudan MethodChannel yeterli olabilir. Çok sayıda metot, karmaşık veri modelleri veya iki platform arasında büyüyen bir sözleşme varsa Pigeon daha sürdürülebilir bir seçenek sunar.</p><p>Asıl hedef yalnızca Dart ile Kotlin veya Swift’i konuşturmak değil; bu iletişimi test edilebilir, bakımı kolay ve uygulamanın mimarisine uygun bir sınır içinde tutmaktır.</p><h3>Kaynaklar</h3><ul><li><a href="https://docs.flutter.dev/platform-integration/platform-channels">Flutter — Platform Channels</a></li><li><a href="https://pub.dev/packages/pigeon">Pigeon — pub.dev</a></li><li><a href="https://docs.flutter.dev/packages-and-plugins/developing-packages">Flutter — Developing packages and plugins</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f3c8c25096cc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Node.js ve Mikroservislerde Circuit Breaker (Devre Kesici) Deseni: Opossum ile Sistem Dayanıklılığı]]></title>
            <link>https://affanccn.medium.com/node-js-ve-mikroservislerde-circuit-breaker-devre-kesici-deseni-opossum-ile-sistem-dayan%C4%B1kl%C4%B1l%C4%B1%C4%9F%C4%B1-3df8093a1934?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/3df8093a1934</guid>
            <category><![CDATA[opossum]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[circuit-breaker]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[cascading-failure]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 07:42:36 GMT</pubDate>
            <atom:updated>2026-10-27T07:42:36.527Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z27zaa6-cu3e0qeyZjwlTw.jpeg" /></figure><h3>Node.js ve Mikroservislerde Circuit Breaker (Devre Kesici) Deseni: Opossum ile Sistem Dayanıklılığı</h3><p>Mikroservis mimarilerinde servisler birbirleriyle ağ üzerinden iletişim kurar. Bir e-ticaret uygulamasında ödeme sağlayıcısı, kargo takip API’si veya döviz kuru servisi yanıt vermeyi kestiğinde, bu sorun yalnızca ilgili servisi etkilemekle kalmayabilir. Bekleyen istekler, bağlantı havuzlarının dolması ve kaynak tüketiminin artması sonucunda diğer bileşenler de etkilenebilir.</p><p>Bu durum <strong>kademeli çöküş (cascading failure)</strong> olarak bilinir. Tek bir bağımlılıktaki arıza, yeterli izolasyon yoksa sistemin geri kalanına yayılabilir.</p><p>Bu riski azaltmak için kullanılan tasarım desenlerinden biri <strong>Circuit Breaker (Devre Kesici)</strong> desenidir. Node.js ekosistemindeki opossum kütüphanesi, başarısız olan asenkron işlemleri izleyerek belirli koşullarda yeni çağrıları durdurmaya yardımcı olur.</p><h3>1. Circuit Breaker Durum Makinesi</h3><p>Circuit Breaker üç temel durumda çalışır.</p><p>&lt;box gap={3}&gt;<br> &lt;row align=start gap={3}&gt;<br> &lt;box background=”#DDF5E5&quot; radius=”lg” padding={3}&gt;<br> &lt;icon name=”check-circle” color=”#187344&quot; size=”xl” /&gt;<br> &lt;/box&gt;<br> &lt;box flex=”1&quot; gap={1}&gt;<br> **CLOSED — Normal çalışma**</p><pre>İstekler bağımlı servise gönderilir. Başarılar, hatalar ve gecikmeler izlenir. Hata oranı belirlenen koşulları aşarsa devre açılır.<br>&lt;/box&gt;</pre><p>&lt;/row&gt;<br> &lt;divider color=”subtle” /&gt;<br> &lt;row align=start gap={3}&gt;<br> &lt;box background=”#FCE5E5&quot; radius=”lg” padding={3}&gt;<br> &lt;icon name=”shield-alert” color=”#B42318&quot; size=”xl” /&gt;<br> &lt;/box&gt;<br> &lt;box flex=”1&quot; gap={1}&gt;<br> **OPEN — Devre açık**</p><pre>Yeni çağrılar bağımlı servise gönderilmez. Opossum, yapılandırılmışsa fallback fonksiyonunu çalıştırır; aksi durumda çağrı hata ile sonuçlanır.<br>&lt;/box&gt;</pre><p>&lt;/row&gt;<br> &lt;divider color=”subtle” /&gt;<br> &lt;row align=start gap={3}&gt;<br> &lt;box background=”#FFF0D5&quot; radius=”lg” padding={3}&gt;<br> &lt;icon name=”activity” color=”#925B00&quot; size=”xl” /&gt;<br> &lt;/box&gt;<br> &lt;box flex=”1&quot; gap={1}&gt;<br> **HALF-OPEN — Yeniden deneme**</p><pre>Bekleme süresi dolduğunda bir sonraki çağrı servisi test eder. Başarılı olursa devre kapanır; başarısız olursa yeniden açılır.<br>&lt;/box&gt;</pre><p>&lt;/row&gt;<br>&lt;/box&gt;</p><p>Opossum’un önemli bir ayrıntısı, yarı açık duruma geçildiğinde birden fazla eşzamanlı deneme isteğini serbest bırakmak yerine <strong>bir sonraki çağrıyı test amacıyla kullanmasıdır</strong>. Bu davranış, aynı anda çok sayıda isteğin arızalı servise yönelmesini önlemeye yardımcı olur.</p><h3>2. Node.js’te Opossum Kurulumu</h3><p>Kütüphaneyi yükleyin:</p><pre>npm install opossum axios<br>npm install -D @types/opossum</pre><p>TypeScript projenizde kullandığınız opossum sürümünün Node.js sürümünüzle uyumlu olduğundan emin olun. Güncel Opossum sürümlerinin çalışma zamanı gereksinimleri eski sürümlerden farklı olabilir.</p><h3>Devre kesiciyi oluşturma</h3><p>services/exchangeRateService.ts:</p><pre>import CircuitBreaker from &quot;opossum&quot;;<br>import axios from &quot;axios&quot;;</pre><pre>type ExchangeRateResult = {<br>  base: string;<br>  rates: Record&lt;string, number&gt;;<br>};</pre><pre>async function fetchExchangeRates(<br>  baseCurrency: string,<br>): Promise&lt;ExchangeRateResult&gt; {<br>  const response = await axios.get&lt;ExchangeRateResult&gt;(<br>    &quot;https://api.example.com/v1/rates&quot;,<br>    {<br>      params: { base: baseCurrency },<br>      timeout: 2500,<br>    },<br>  );</pre><pre>  return response.data;<br>}</pre><pre>const breakerOptions: CircuitBreaker.Options = {<br>  name: &quot;exchange-rate-service&quot;,<br>  timeout: 3000,<br>  errorThresholdPercentage: 50,<br>  resetTimeout: 30000,<br>  rollingCountTimeout: 10000,<br>  rollingCountBuckets: 10,<br>  volumeThreshold: 5,<br>};</pre><pre>export const exchangeRateBreaker = new CircuitBreaker(<br>  fetchExchangeRates,<br>  breakerOptions,<br>);</pre><pre>exchangeRateBreaker.fallback(<br>  (baseCurrency: string): ExchangeRateResult =&gt; {<br>    console.warn(<br>      &quot;Döviz kuru servisi kullanılamıyor.&quot;,<br>    );</pre><pre>    // Gerçek uygulamada yalnızca açıkça izin verilen,<br>    // güncellik bilgisi bulunan önbelleği kullanın.<br>    throw new Error(<br>      `Güncel kur verisi alınamadı: ${baseCurrency}`,<br>    );<br>  },<br>);</pre><pre>exchangeRateBreaker.on(&quot;open&quot;, () =&gt; {<br>  console.error(&quot;Circuit Breaker OPEN durumuna geçti.&quot;);<br>});</pre><pre>exchangeRateBreaker.on(&quot;halfOpen&quot;, () =&gt; {<br>  console.warn(&quot;Circuit Breaker HALF-OPEN: test çağrısı bekleniyor.&quot;);<br>});</pre><pre>exchangeRateBreaker.on(&quot;close&quot;, () =&gt; {<br>  console.info(&quot;Circuit Breaker CLOSED durumuna döndü.&quot;);<br>});</pre><pre>exchangeRateBreaker.on(&quot;timeout&quot;, () =&gt; {<br>  console.warn(&quot;Bağımlı servis zaman aşımına uğradı.&quot;);<br>});</pre><pre>exchangeRateBreaker.on(&quot;fallback&quot;, () =&gt; {<br>  console.warn(&quot;Fallback mekanizması çalıştırıldı.&quot;);<br>});</pre><p>Bu örnekteki api.example.com adresi temsili bir uç noktadır. Gerçek servis adresini ve yanıt şemasını kendi uygulamanıza göre değiştirin.</p><h3>Yapılandırma seçenekleri</h3><p>SeçenekÖrnekİşlevtimeout3000 msBir çağrının tamamlanması için izin verilen süreerrorThresholdPercentage%50Hata oranı aşıldığında devrenin açılma eşiğiresetTimeout30000 msAçık devrenin yarı açık duruma geçmesine kadar beklemerollingCountTimeout10000 msİstatistikler için kayan zaman penceresirollingCountBuckets10İstatistik penceresinin bölündüğü dilim sayısıvolumeThreshold5Normal durumda devrenin açılabilmesi için gereken asgari çağrı sayısı</p><p>Bu değerler örnektir; her servise aynı eşikleri uygulamak doğru değildir. Özellikle volumeThreshold, az sayıda isteğin bulunduğu bir zaman aralığında tek bir hatanın devreyi gereksiz yere açmasını önlemeye yardımcı olur.</p><p>Bir başka önemli ayrıntı: timeout değeri, HTTP istemcisinin zaman aşımıyla aynı şey değildir. Örnekte Axios 2,5 saniyede, Opossum ise 3 saniyede zaman aşımına uğrayacak şekilde yapılandırılmıştır. Bu, HTTP çağrısının daha erken sonlanmasına imkân verir.</p><h3>3. API Rotasında Kullanım</h3><p>Express üzerinden devre kesiciyi kullanırken, dış servisin hata vermesiyle devrenin açık olması aynı şekilde ele alınabilir. Ancak fallback’in gerçekten başarılı bir iş sonucu döndürüp döndürmediği de dikkate alınmalıdır.</p><p>controllers/exchangeRateController.ts:</p><pre>import type { Request, Response } from &quot;express&quot;;<br>import { exchangeRateBreaker } from &quot;../services/exchangeRateService&quot;;</pre><pre>export async function getExchangeRates(<br>  req: Request,<br>  res: Response,<br>) {<br>  const baseCurrency = String(<br>    req.query.base ?? &quot;TRY&quot;,<br>  ).toUpperCase();</pre><pre>  if (!/^[A-Z]{3}$/.test(baseCurrency)) {<br>    return res.status(400).json({<br>      error: &quot;Geçersiz para birimi kodu.&quot;,<br>    });<br>  }</pre><pre>  try {<br>    const result = await exchangeRateBreaker.fire(<br>      baseCurrency,<br>    );</pre><pre>    return res.status(200).json({<br>      data: result,<br>    });<br>  } catch {<br>    return res.status(503).json({<br>      error: &quot;Döviz kuru servisi şu anda kullanılamıyor.&quot;,<br>    });<br>  }<br>}</pre><p>Bu örnekte fallback de hata fırlattığı için istek 503 Service Unavailable ile sonuçlanır. Eğer uygulamanızda geçerliliği devam eden bir önbellek varsa, fallback güncellik bilgisiyle birlikte önbellekteki veriyi döndürebilir.</p><p>Örneğin:</p><pre>exchangeRateBreaker.fallback(<br>  async (baseCurrency: string) =&gt; {<br>    const cached = await getCachedExchangeRates(<br>      baseCurrency,<br>    );</pre><pre>    if (cached &amp;&amp; !isCacheExpired(cached)) {<br>      return {<br>        ...cached.data,<br>        source: &quot;cache&quot;,<br>        stale: true,<br>      };<br>    }</pre><pre>    throw new Error(&quot;Güncel veya kullanılabilir önbellek yok.&quot;);<br>  },<br>);</pre><p>Buradaki getCachedExchangeRates ve isCacheExpired uygulamanızda tanımlanması gereken fonksiyonlardır.</p><p><strong>Fallback’in amacı her durumda başarılı yanıt üretmek değildir.</strong> Güvenli bir alternatif varsa onu sunmak, yoksa kontrollü hata döndürmek daha doğru olabilir.</p><h3>4. Ödeme Sistemlerinde Fallback Neden Farklıdır?</h3><p>Ödeme işlemlerinde basit bir fallback özellikle risklidir. Ödeme sağlayıcısına yapılan istek zaman aşımına uğradığında, bu durum ödemenin başarısız olduğu anlamına gelmez. Sağlayıcı işlemi tamamlamış ancak yanıt uygulamaya ulaşmamış olabilir.</p><p>Şu yaklaşım güvenli değildir:</p><pre>paymentBreaker.fallback(() =&gt; ({<br>  status: &quot;PENDING_OFFLINE&quot;,<br>  message: &quot;Siparişiniz sıraya alındı.&quot;,<br>}));</pre><p>Bu kod yalnızca bir nesne döndürür. Herhangi bir sipariş veya ödeme kaydı oluşturmaz, kuyruğa mesaj yazmaz ve işlemin gerçekten tamamlanacağını garanti etmez.</p><p>Daha güvenli bir ödeme mimarisinde:</p><ol><li>Her ödeme girişimi için benzersiz bir <strong>idempotency key</strong> oluşturulur.</li><li>Ödeme girişimi veritabanında kalıcı olarak kaydedilir.</li><li>Sağlayıcıya yapılan isteğin sonucu belirsizse ödeme durumu UNKNOWN veya PENDING_CONFIRMATION olarak tutulur.</li><li>Sağlayıcının sorgulama API’si, webhook’u veya mutabakat süreci üzerinden gerçek durum doğrulanır.</li><li>Yeniden deneme yapılacaksa aynı ödeme girişimi için sağlayıcının desteklediği idempotency mekanizması kullanılır.</li><li>Sipariş yalnızca ödeme durumuna ilişkin güvenilir kanıt elde edildiğinde uygun duruma geçirilir.</li></ol><p>Circuit Breaker burada sağlayıcıya yapılan çağrıları sınırlar; ödeme durum makinesinin veya idempotency mekanizmasının yerini almaz.</p><h3>5. Kademeli Çöküşü Önlemek İçin Ek Önlemler</h3><p>Circuit Breaker, dayanıklılık mimarisinin tek bileşeni değildir.</p><ul><li><strong>Timeout:</strong> Her dış servis çağrısına uygun zaman aşımı belirleyin. Sınırsız bekleyen istekler kaynakları tüketebilir.</li><li><strong>Retry:</strong> Geçici hatalarda yeniden deneme kullanın; exponential backoff ve jitter ile eşzamanlı tekrar yükünü azaltın. Her hata için tekrar denemeyin.</li><li><strong>Bulkhead:</strong> Bağımlı servis başına eşzamanlı çağrı sayısını sınırlayın. Opossum’un capacity seçeneği bu amaçla değerlendirilebilir.</li><li><strong>Idempotency:</strong> Özellikle ödeme, sipariş ve veri yazma işlemlerinde tekrar çağrıların mükerrer sonuç üretmesini önleyin.</li><li><strong>Queue:</strong> Arka planda işlenebilecek işleri kalıcı bir kuyruğa yazın. Bellekteki bir nesneyi döndürmek, işi kuyruğa almakla aynı değildir.</li><li><strong>Graceful degradation:</strong> Alternatif sonuç yalnızca iş kuralları açısından güvenliyse sunulmalıdır.</li></ul><p>Bu mekanizmalar farklı sorunları çözer. Örneğin Circuit Breaker arızalı servise çağrıları azaltırken, Retry geçici hatalardan kurtulmayı dener. Yanlış yapılandırılmış retry politikası, arızalı servisin üzerindeki yükü artırabilir.</p><h3>6. Gözlemlenebilirlik: Metrikler ve Alarmlar</h3><p>Opossum, stats nesnesi üzerinden çağrı ve hata istatistikleri sağlar. Bunları Prometheus ve Grafana gibi araçlarla izlemek, devrenin ne zaman ve neden açıldığını anlamayı kolaylaştırır.</p><pre>setInterval(() =&gt; {<br>  const stats = exchangeRateBreaker.stats;</pre><pre>  console.info({<br>    service: &quot;exchange-rate-service&quot;,<br>    fires: stats.fires,<br>    successes: stats.successes,<br>    failures: stats.failures,<br>    timeouts: stats.timeouts,<br>    rejects: stats.rejects,<br>    fallbacks: stats.fallbacks,<br>    opened: exchangeRateBreaker.opened,<br>    halfOpen: exchangeRateBreaker.halfOpen,<br>  });<br>}, 10000).unref();</pre><p>Bu basit örnek yapılandırılmış log üretir; Prometheus metriğini kendiliğinden yayımlamaz. Üretim ortamında uygun bir metrik exporter kullanın ve setInterval gibi mekanizmaları uygulamanın yaşam döngüsüne göre yönetin.</p><p>İzlenebilecek temel göstergeler:</p><ul><li>Bağımlı servis çağrılarının toplam sayısı</li><li>Başarısız çağrı ve timeout oranı</li><li>Açık devrede reddedilen çağrılar</li><li>Fallback kullanım sıklığı</li><li>Bağımlı servisin yanıt süreleri</li><li>Circuit Breaker’ın açık kaldığı süre</li></ul><p>Alarmları yalnızca devrenin açılmasına göre değil, kullanıcıya etkisi ve hatanın devam süresine göre de tasarlayın. Bir devrenin açılması her zaman ana uygulamanın çöktüğü anlamına gelmez; bazen koruma mekanizmasının doğru çalıştığını gösterir.</p><h3>Sonuç</h3><p>Node.js mikroservislerinde Circuit Breaker deseni, arızalı veya yavaş bağımlılıkların etkisini sınırlandırmak için yararlı bir dayanıklılık mekanizmasıdır. Opossum; zaman aşımı, kayan istatistik penceresi, durum geçişleri, fallback ve olay izleme özellikleriyle bu deseni uygulamayı kolaylaştırır.</p><p>Üretim ortamında başarılı bir tasarım için:</p><ul><li>Servis başına uygun timeout ve hata eşiği belirleyin.</li><li>Düşük trafik dönemleri için volumeThreshold değerini değerlendirin.</li><li>Fallback’in gerçekten güvenli bir iş sonucu ürettiğinden emin olun.</li><li>Ödeme gibi kritik işlemlerde idempotency ve kalıcı durum yönetimi kullanın.</li><li>Circuit Breaker’ı retry, bulkhead ve gözlemlenebilirlik mekanizmalarıyla birlikte ele alın.</li><li>Eşik değerlerini gerçek trafik ve hata verileriyle test edin.</li></ul><p>Dayanıklı sistemler, hataların hiç yaşanmadığı sistemler değildir. Hata oluştuğunda etkisini sınırlayan, belirsiz sonuçları doğru yöneten ve hizmeti kontrollü biçimde sürdüren sistemlerdir.</p><h3>Kaynaklar</h3><ul><li><a href="https://github.com/nodeshift/opossum">Opossum — Resmî GitHub deposu ve kullanım rehberi</a></li><li><a href="https://www.npmjs.com/package/opossum">Opossum — npm paketi ve sürüm bilgileri</a></li><li><a href="https://martinfowler.com/bliki/CircuitBreaker.html">Martin Fowler — Circuit Breaker</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3df8093a1934" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Next.js App Router’da Server Actions ile Dosya Yükleme ve S3 Presigned URL Mimarisi]]></title>
            <link>https://affanccn.medium.com/next-js-app-routerda-server-actions-ile-dosya-y%C3%BCkleme-ve-s3-presigned-url-mimarisi-25d07b13e79c?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/25d07b13e79c</guid>
            <category><![CDATA[aws-s3]]></category>
            <category><![CDATA[cloudflare-r2]]></category>
            <category><![CDATA[nextjs]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[servers]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 07:39:01 GMT</pubDate>
            <atom:updated>2026-10-27T07:39:01.379Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*J2lew2zCSbcNpDO6s6mO8A.jpeg" /></figure><h3>Next.js App Router’da Server Actions ile Dosya Yükleme ve S3 Presigned URL Mimarisi</h3><p>Web uygulamalarında görsel, PDF veya video yüklemek için kullanılan geleneksel yöntemlerden biri, dosyayı önce Node.js sunucusuna göndermek ve ardından sunucudan depolama servisine aktarmaktır. Bu yaklaşım küçük dosyalarda çalışabilir; ancak yüksek eşzamanlılıkta gereksiz ağ trafiği, işlem yükü ve bellek tüketimi oluşturabilir.</p><p>Serverless ortamlarda ayrıca istek gövdesi boyutu sınırları bulunur. Örneğin Vercel Functions için istek gövdesi sınırı 4,5 MB iken Next.js Server Actions varsayılan olarak 1 MB istek gövdesi sınırına sahiptir. Bu iki sınır farklı katmanlara aittir ve yapılandırmaya göre değişebilir. <a href="https://vercel.com/docs/functions/limitations">Vercel Functions limitleri</a> ve <a href="https://nextjs.org/docs/app/api-reference/config/next-config-js/serverActions">Next.js Server Actions yapılandırması</a>.</p><p>Bu soruna yönelik etkili çözümlerden biri <strong>Presigned URL (önceden imzalanmış URL)</strong> mimarisidir. Sunucu, dosyanın kendisini taşımak yerine belirli bir depolama nesnesine sınırlı süreyle yükleme izni veren bir URL üretir. Tarayıcı da dosyayı doğrudan Amazon S3 veya Cloudflare R2&#39;ye gönderir.</p><p>Bu rehberde Next.js App Router, Server Actions, AWS SDK v3 ve istemci tarafında doğrudan yükleme akışını ele alacağız.</p><h3>1. Presigned URL Mimarisi Nasıl Çalışır?</h3><p>Temel akış üç adımdan oluşur:</p><ol><li><strong>Yetkilendirme:</strong> İstemci, dosyanın adı, türü ve boyutu gibi metadata bilgilerini Server Action’a gönderir. Sunucu kullanıcı oturumunu ve yükleme politikasını kontrol eder.</li><li><strong>URL üretimi:</strong> Sunucu, benzersiz bir nesne anahtarı için kısa süre geçerli bir PUT URL&#39;si imzalar.</li><li><strong>Doğrudan yükleme:</strong> İstemci, dosyanın baytlarını bu URL üzerinden doğrudan depolama servisine gönderir.</li></ol><p>&lt;escape&gt;<br>Tarayıcı → Next.js Server Action → Presigned URL<br>Tarayıcı ───────────────→ S3 / R2<br>&lt;/escape&gt;</p><p>İkinci istekte dosya Next.js sunucusundan geçmez. Sunucunun rolü yetkilendirme ve imzalama işlemleriyle sınırlı kalır.</p><p>Bununla birlikte, sunucu tarafındaki yetkilendirme ortadan kalkmaz. Aksine, hangi kullanıcının hangi konuma dosya yükleyebileceğini belirlemek mimarinin en önemli güvenlik adımlarından biridir.</p><h3>2. Gerekli Paketler ve Ortam Değişkenleri</h3><p>AWS SDK v3 paketlerini yükleyin:</p><pre>npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner</pre><p>Amazon S3 için ortam değişkenleri:</p><pre>AWS_REGION=eu-central-1<br>AWS_S3_BUCKET_NAME=your-private-bucket<br>AWS_ACCESS_KEY_ID=your-access-key<br>AWS_SECRET_ACCESS_KEY=your-secret-key</pre><p>Gerçek erişim bilgilerini istemciye gönderilen kodlara, Git deposuna veya log kayıtlarına eklemeyin. Üretim ortamında mümkünse kısa ömürlü IAM kimlik bilgileri ya da platformun sunduğu güvenli kimlik doğrulama mekanizmalarını tercih edin.</p><p>Cloudflare R2 kullanıyorsanız S3 uyumlu API uç noktası ve R2 erişim anahtarları gerekir. AWS bölgesi yerine R2 hesabınızın API endpoint’i yapılandırılır. İki servisin aynı SDK’yı kullanabilmesi, tüm özelliklerinin birebir aynı olduğu anlamına gelmez.</p><h3>3. Server Action ile Güvenli İmzalı URL Üretimi</h3><p>Aşağıdaki örnek, dosyanın kendisini değil yalnızca yükleme isteğinin metadata bilgilerini alır.</p><p>Üretim ortamında requireUser() fonksiyonunu uygulamanızın gerçek kimlik doğrulama mekanizmasıyla değiştirmelisiniz. Bu fonksiyon, doğrulanmış kullanıcının kimliğini döndürmeli veya yetkisiz isteklerde hata vermelidir.</p><p>app/actions/upload.ts:</p><pre>&quot;use server&quot;;</pre><pre>import {<br>  S3Client,<br>  PutObjectCommand,<br>} from &quot;@aws-sdk/client-s3&quot;;<br>import { getSignedUrl } from &quot;@aws-sdk/s3-request-presigner&quot;;<br>import { randomUUID } from &quot;node:crypto&quot;;</pre><pre>// Projenizin kimlik doğrulama modülünü kullanın.<br>import { requireUser } from &quot;@/lib/auth&quot;;</pre><pre>const region = process.env.AWS_REGION;<br>const bucket = process.env.AWS_S3_BUCKET_NAME;<br>const accessKeyId = process.env.AWS_ACCESS_KEY_ID;<br>const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;</pre><pre>if (!region || !bucket || !accessKeyId || !secretAccessKey) {<br>  throw new Error(&quot;S3 yapılandırması eksik.&quot;);<br>}</pre><pre>const s3 = new S3Client({<br>  region,<br>  credentials: {<br>    accessKeyId,<br>    secretAccessKey,<br>  },<br>});</pre><pre>const ALLOWED_TYPES = new Set([<br>  &quot;image/jpeg&quot;,<br>  &quot;image/png&quot;,<br>  &quot;image/webp&quot;,<br>  &quot;application/pdf&quot;,<br>]);</pre><pre>const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MiB</pre><pre>export async function createUploadUrl(input: {<br>  fileName: string;<br>  fileType: string;<br>  fileSize: number;<br>}) {<br>  const user = await requireUser();</pre><pre>  const { fileName, fileType, fileSize } = input;</pre><pre>  if (<br>    typeof fileName !== &quot;string&quot; ||<br>    fileName.trim().length === 0 ||<br>    fileName.length &gt; 255<br>  ) {<br>    return {<br>      success: false as const,<br>      error: &quot;Geçersiz dosya adı.&quot;,<br>    };<br>  }</pre><pre>  if (!ALLOWED_TYPES.has(fileType)) {<br>    return {<br>      success: false as const,<br>      error: &quot;Desteklenmeyen dosya türü.&quot;,<br>    };<br>  }</pre><pre>  if (<br>    !Number.isSafeInteger(fileSize) ||<br>    fileSize &lt;= 0 ||<br>    fileSize &gt; MAX_FILE_SIZE<br>  ) {<br>    return {<br>      success: false as const,<br>      error: &quot;Dosya 1 bayt ile 10 MiB arasında olmalıdır.&quot;,<br>    };<br>  }</pre><pre>  // Kullanıcı tarafından gönderilen dosya adını S3 key olarak kullanmıyoruz.<br>  const key = `uploads/${user.id}/${randomUUID()}`;</pre><pre>  const command = new PutObjectCommand({<br>    Bucket: bucket,<br>    Key: key,<br>    ContentType: fileType,<br>  });</pre><pre>  const uploadUrl = await getSignedUrl(s3, command, {<br>    expiresIn: 60,<br>  });</pre><pre>  return {<br>    success: true as const,<br>    uploadUrl,<br>    key,<br>  };<br>}</pre><h3>Bu tasarım neden daha güvenli?</h3><p><strong>Benzersiz nesne anahtarı:</strong> Dosya adı doğrudan S3 anahtarına eklenmediği için kullanıcı kontrollü dosya adlarından kaynaklanabilecek çakışma ve karakter sorunları azaltılır. Orijinal dosya adını gerekiyorsa veritabanında metadata olarak saklayabilirsiniz.</p><p><strong>Kullanıcıya özel alan:</strong> uploads/${user.id}/... yapısı, uygulama tarafında sahiplik kontrolü için kullanışlıdır. Ancak yalnızca anahtarı bu şekilde oluşturmak tek başına yetkilendirme sağlamaz; her işlemde sahiplik doğrulaması yapılmalıdır.</p><p><strong>Kısa süreli URL:</strong> 60 saniyelik süre, bağlantının kullanılabileceği zaman aralığını sınırlar. Fakat URL bir kez kullanılınca otomatik olarak geçersiz olmaz. S3&#39;te aynı URL, süresi dolana kadar tekrar kullanılabilir ve aynı anahtardaki nesnenin üzerine yazabilir. Bu nedenle benzersiz anahtar kullanmak önemlidir. <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html">AWS S3 presigned URL dokümantasyonu</a>.</p><p><strong>Önemli güvenlik notu:</strong> fileType ve fileSize değerleri istemciden gelir; dolayısıyla güvenilir kanıt olarak kabul edilemez. Örnekteki kontroller yalnızca ilk filtrelemedir. Yükleme sonrası doğrulama da gereklidir.</p><h3>4. İstemciden Doğrudan S3&#39;e Dosya Yükleme</h3><p>İstemci tarafında dosya önce Server Action’a gönderilmez. Action’dan URL alındıktan sonra dosyanın kendisi depolama servisine yüklenir.</p><p>components/DirectUploader.tsx:</p><pre>&quot;use client&quot;;</pre><pre>import { useState } from &quot;react&quot;;<br>import { createUploadUrl } from &quot;@/app/actions/upload&quot;;</pre><pre>export function DirectUploader() {<br>  const [uploading, setUploading] = useState(false);<br>  const [message, setMessage] = useState(&quot;&quot;);</pre><pre>  async function handleFileChange(<br>    event: React.ChangeEvent&lt;HTMLInputElement&gt;,<br>  ) {<br>    const file = event.target.files?.[0];</pre><pre>    if (!file) return;</pre><pre>    setUploading(true);<br>    setMessage(&quot;&quot;);</pre><pre>    try {<br>      // 1. Yalnızca metadata sunucuya gönderilir.<br>      const result = await createUploadUrl({<br>        fileName: file.name,<br>        fileType: file.type,<br>        fileSize: file.size,<br>      });</pre><pre>      if (!result.success) {<br>        throw new Error(result.error);<br>      }</pre><pre>      // 2. Dosya doğrudan depolama servisine gönderilir.<br>      const response = await fetch(result.uploadUrl, {<br>        method: &quot;PUT&quot;,<br>        headers: {<br>          &quot;Content-Type&quot;: file.type,<br>        },<br>        body: file,<br>      });</pre><pre>      if (!response.ok) {<br>        throw new Error(<br>          `Yükleme başarısız: HTTP ${response.status}`,<br>        );<br>      }</pre><pre>      // Yükleme tamamlandı; henüz sunucu tarafında<br>      // içerik doğrulamasının yapıldığı varsayılmamalıdır.<br>      setMessage(&quot;Dosya depolama alanına yüklendi.&quot;);<br>    } catch (error) {<br>      setMessage(<br>        error instanceof Error<br>          ? error.message<br>          : &quot;Beklenmeyen bir hata oluştu.&quot;,<br>      );<br>    } finally {<br>      setUploading(false);<br>      // Aynı dosyanın tekrar seçilebilmesini sağlar.<br>      event.target.value = &quot;&quot;;<br>    }<br>  }</pre><pre>  return (<br>    &lt;div className=&quot;mx-auto max-w-md space-y-4 rounded-xl border p-6&quot;&gt;<br>      &lt;h2 className=&quot;text-lg font-bold&quot;&gt;<br>        Doğrudan dosya yükleme<br>      &lt;/h2&gt;</pre><pre>      &lt;input<br>        type=&quot;file&quot;<br>        accept=&quot;image/jpeg,image/png,image/webp,application/pdf&quot;<br>        disabled={uploading}<br>        onChange={handleFileChange}<br>      /&gt;</pre><pre>      {uploading &amp;&amp; (<br>        &lt;p role=&quot;status&quot;&gt;Dosya yükleniyor...&lt;/p&gt;<br>      )}</pre><pre>      {message &amp;&amp; (<br>        &lt;p role=&quot;status&quot; aria-live=&quot;polite&quot;&gt;<br>          {message}<br>        &lt;/p&gt;<br>      )}<br>    &lt;/div&gt;<br>  );<br>}</pre><p>Buradaki accept özelliği kullanıcıya dosya seçerken yardımcı olur; güvenlik kontrolü değildir. Benzer şekilde, istemcinin yükleme tamamlandı mesajını göstermesi dosyanın uygulama tarafından güvenli kabul edildiği anlamına gelmez.</p><h3>5. Yükleme Sonrası Doğrulama</h3><p>Güvenli bir dosya yükleme akışı, PUT isteğinin başarılı dönmesiyle bitmemelidir.</p><p>Üretim mimarisinde sunucu tarafında ikinci bir doğrulama adımı oluşturun. Örneğin:</p><ol><li>İstemci yükleme için bir kayıt veya yükleme oturumu başlatır.</li><li>Sunucu kullanıcıyı doğrular ve benzersiz nesne anahtarını oluşturur.</li><li>İstemci dosyayı depolama alanına yükler.</li><li>İstemci bir tamamlanma Server Action’ı çağırır.</li><li>Sunucu, HeadObject gibi bir işlemle nesnenin varlığını ve boyutunu kontrol eder.</li><li>Gerekirse dosyanın gerçek türü, içeriği, zararlı yazılım durumu ve kullanıcı sahipliği doğrulanır.</li><li>Başarılı doğrulamadan sonra veritabanındaki dosya kaydı ready veya eşdeğer bir duruma geçirilir.</li></ol><p>Bu yaklaşım, dosya kaydının henüz yüklenmemiş veya doğrulanmamış bir nesneyi kullanılabilir göstermesini önlemeye yardımcı olur.</p><p>Örnek bir kontrol:</p><pre>import { HeadObjectCommand } from &quot;@aws-sdk/client-s3&quot;;</pre><pre>const object = await s3.send(<br>  new HeadObjectCommand({<br>    Bucket: bucket,<br>    Key: expectedKey,<br>  }),<br>);</pre><pre>if (<br>  object.ContentLength == null ||<br>  object.ContentLength &lt;= 0 ||<br>  object.ContentLength &gt; MAX_FILE_SIZE<br>) {<br>  throw new Error(&quot;Yüklenen dosyanın boyutu geçersiz.&quot;);<br>}</pre><p>expectedKey değerini istemciden gelen rastgele bir anahtar olarak güvenmeden kullanmayın. Önceden oluşturulmuş yükleme kaydından alın ve ilgili kaydın mevcut kullanıcıya ait olduğunu doğrulayın. Yalnızca Content-Type başlığına güvenerek dosyanın gerçek içeriğini doğrulamış olmazsınız.</p><p>Ayrıca bu HeadObject kontrolü yükleme tamamlandıktan sonra boyutu tespit eder. Büyük veya kötü niyetli yüklemelerin baştan engellenmesi gereken senaryolarda, yalnızca sonradan kontrol etmek yeterli değildir.</p><h3>6. Dosya Boyutu ve İçerik Türü Güvenliği</h3><p>PutObjectCommand içinde ContentType belirtilmesi, yükleme isteğinin imzasına bu başlığın dahil edilmesini sağlar. İstemcinin aynı imzalanmış başlık değerini kullanması gerekir; farklı bir değer imza hatasına neden olabilir. Ancak bu, dosyanın gerçek içeriğinin MIME türüyle eşleştiğini kanıtlamaz.</p><p>Örneğin bir kullanıcı, PNG olarak bildirdiği bir dosyanın içine farklı bir içerik yerleştirebilir. Bu nedenle hassas sistemlerde:</p><ul><li>Dosya boyutunu sunucu tarafında doğrulayın.</li><li>Dosya uzantısını ve MIME türünü tek başına güvenlik sınırı olarak görmeyin.</li><li>Gerektiğinde dosyanın gerçek imzasını (magic bytes) inceleyin.</li><li>PDF ve görselleri sunmadan önce uygun içerik kontrolleri uygulayın.</li><li>Riskli dosyaları karantinada tutun ve zararlı yazılım taramasından geçirin.</li><li>Yükleme başına ve kullanıcı başına kota uygulayın.</li><li>Yükleme URL’si üretimini hız sınırlamasıyla koruyun.</li></ul><h3>Büyük dosyalar için ne yapmalı?</h3><p>S3 PUT presigned URL yaklaşımı birçok dosya için yeterli olsa da büyük dosyalarda multipart upload değerlendirilmelidir. Amazon S3 multipart upload, büyük nesnelerin parçalara ayrılarak yüklenmesini ve başarısız parçaların yeniden gönderilmesini sağlar.</p><p>Cloudflare R2 de S3 uyumlu presigned URL’leri destekler; ancak özellikler birebir aynı değildir. Örneğin R2, HTML form tabanlı presigned POST yüklemelerini desteklemez. <a href="https://developers.cloudflare.com/r2/api/s3/presigned-urls/">Cloudflare R2 presigned URL belgeleri</a>.</p><p>Boyut sınırının yükleme başlamadan önce kesin olarak uygulanması gerekiyorsa depolama servisinin desteklediği yükleme yöntemini seçmek önemlidir. S3 presigned POST politikaları uygun senaryolarda content-length-range kısıtlaması sağlayabilir; yalnızca PUT URL&#39;sine istemcinin bildirdiği boyutu eklemek aynı güvenceyi sağlamaz.</p><h3>7. CORS Yapılandırması</h3><p>Tarayıcıdan başka bir origin’e yapılan PUT isteği için depolama alanında uygun CORS politikası tanımlanmalıdır. CORS, presigned URL&#39;nin kimlik doğrulama mekanizması değildir; tarayıcının çapraz origin isteklerini yönetmesine ilişkin bir kuraldır.</p><p>Örneğin, yalnızca uygulamanızın alan adından dosya yüklenmesine izin veren bir politika şu şekilde olabilir:</p><pre>[<br>  {<br>    &quot;AllowedOrigins&quot;: [<br>      &quot;https://example.com&quot;<br>    ],<br>    &quot;AllowedMethods&quot;: [<br>      &quot;PUT&quot;<br>    ],<br>    &quot;AllowedHeaders&quot;: [<br>      &quot;Content-Type&quot;<br>    ],<br>    &quot;ExposeHeaders&quot;: [<br>      &quot;ETag&quot;<br>    ],<br>    &quot;MaxAgeSeconds&quot;: 3600<br>  }<br>]</pre><p>example.com değerini kendi alan adınızla değiştirin. Yerel geliştirme için gerekiyorsa http://localhost:3000 gibi ayrı bir origin ekleyebilirsiniz.</p><p>İstemcinin gönderdiği checksum veya başka başlıklar varsa AllowedHeaders ayarını bunları kapsayacak şekilde güncelleyin. Üretimde AllowedOrigins: [&quot;*&quot;] kullanmak yerine gerekli origin&#39;leri açıkça tanımlayın. <a href="https://developers.cloudflare.com/r2/buckets/cors/">Cloudflare R2 CORS belgeleri</a>.</p><h3>8. Dosyanın URL’sini Kullanıcıya Nasıl Sunmalı?</h3><p>Örnekte uploadUrl ile dosyanın kalıcı erişim adresi aynı şey değildir.</p><ul><li><strong>uploadUrl:</strong> Belirli bir nesneye yükleme izni veren, süreli ve gizli tutulması gereken bağlantı.</li><li><strong>Nesne anahtarı (</strong><strong>key):</strong> Depolama alanındaki nesnenin tanımlayıcısı.</li><li><strong>Erişim URL’si:</strong> Dosyayı görüntülemek veya indirmek için kullanılan, uygulamanın erişim politikasına bağlı adres.</li></ul><p>Bucket özel ise https://bucket.s3.amazonaws.com/key şeklinde bir adresin herkese açık çalışacağını varsaymayın. Dosyayı göstermek için ayrı bir presigned GET URL&#39;si veya kimlik doğrulamalı bir indirme endpoint&#39;i kullanabilirsiniz. Herkese açık görseller için özel bir CDN alan adı da tercih edilebilir.</p><p>Dosya URL’sini veritabanında saklamak yerine nesne anahtarını ve dosya metadata bilgilerini saklamak, depolama sağlayıcısını değiştirmeyi ve erişim politikasını yönetmeyi kolaylaştırabilir.</p><h3>Sonuç</h3><p>Next.js App Router ile doğrudan dosya yükleme mimarisi kurarken Server Actions, kimlik doğrulama ve imzalı URL üretimi için kullanışlıdır. Dosyanın kendisinin tarayıcıdan doğrudan S3 veya R2&#39;ye gönderilmesi, uygulama sunucusunun veri aktarımındaki rolünü azaltır.</p><p>Başarılı bir üretim mimarisi için şu ilkeleri uygulayın:</p><ul><li>Server Action içinde kullanıcıyı ve yükleme yetkisini doğrulayın.</li><li>Her yükleme için benzersiz nesne anahtarı üretin.</li><li>Presigned URL’leri kısa süreli tutun ve gizli kabul edin.</li><li>İstemci metadata bilgilerini güvenilir kabul etmeyin.</li><li>Yükleme sonrasında nesnenin boyutunu ve gerekli içerik özelliklerini doğrulayın.</li><li>CORS’u yalnızca gerekli origin, method ve header’larla yapılandırın.</li><li>Özel dosyalar için herkese açık erişim URL’si varsaymayın.</li><li>Büyük dosyalar için multipart upload ve yükleme kotalarını değerlendirin.</li></ul><p>Bu yaklaşım, dosya aktarımını Next.js sunucusundan depolama katmanına taşırken güvenlik ve ölçeklenebilirlik sorumluluklarını açık biçimde ayırmanıza yardımcı olur.</p><h3>Kaynaklar</h3><ul><li><a href="https://nextjs.org/docs/app/api-reference/config/next-config-js/serverActions">Next.js — Server Actions yapılandırması</a></li><li><a href="https://vercel.com/docs/functions/limitations">Vercel — Functions limitleri</a></li><li><a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html">AWS — Presigned URL ile dosya yükleme</a></li><li><a href="https://developers.cloudflare.com/r2/api/s3/presigned-urls/">Cloudflare R2 — Presigned URL’ler</a></li><li><a href="https://developers.cloudflare.com/r2/buckets/cors/">Cloudflare R2 — CORS yapılandırması</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=25d07b13e79c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Flutter’da Slivers Mimarisi: CustomScrollView ile İleri Seviye Kaydırma ve Dinamik Başlıklar]]></title>
            <link>https://affanccn.medium.com/flutterda-slivers-mimarisi-customscrollview-ile-i%CC%87leri-seviye-kayd%C4%B1rma-ve-dinamik-ba%C5%9Fl%C4%B1klar-bd653f788c9d?source=rss-778321f76ab2------2</link>
            <guid isPermaLink="false">https://medium.com/p/bd653f788c9d</guid>
            <category><![CDATA[ui-ux-design]]></category>
            <category><![CDATA[slivers]]></category>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[dart]]></category>
            <category><![CDATA[flutter-sliverappbar]]></category>
            <dc:creator><![CDATA[Affan Emirhan Çüçen]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 07:35:59 GMT</pubDate>
            <atom:updated>2026-10-27T07:35:59.581Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*njg0PeuYiw7X7505-ZjFaQ.jpeg" /></figure><h3>Flutter’da Slivers Mimarisi: CustomScrollView ile İleri Seviye Kaydırma ve Dinamik Başlıklar</h3><p>Mobil uygulamalarda Spotify, sosyal medya platformları veya Airbnb gibi modern arayüzleri incelediğinizde, sayfa kaydırıldıkça küçülen profil başlıkları, ekranın üstüne sabitlenen sekmeler ve tek bir akışta birleşen listeler görebilirsiniz.</p><p>Flutter’da bu tür arayüzleri oluşturmanın en güçlü yollarından biri <strong>Slivers mimarisi</strong> ve CustomScrollView kullanmaktır.</p><p>SingleChildScrollView içine ListView yerleştirmek gibi yaklaşımlar, doğru kısıtlamalar sağlanmadığında Vertical viewport was given unbounded height gibi hatalara yol açabilir. Slivers ise kaydırılabilir içeriklerin aynı viewport içinde birlikte çalışmasını sağlayarak daha esnek bir düzen sunar.</p><p>Bu rehberde CustomScrollView, SliverAppBar, SliverPersistentHeader ve SliverList bileşenlerini kullanarak dinamik başlık ve yapışkan sekme tasarımını inceleyeceğiz.</p><h3>1. Box Widget’lar ve Slivers Arasındaki Fark</h3><p>Flutter’ın geleneksel widget’larının çoğu, RenderBox tabanlı yerleşim sistemiyle çalışır. Container, Row, Column ve SizedBox bu gruba örnektir.</p><p>Slivers ise RenderSliver tabanlıdır ve kaydırılabilir alanın yerleşim sürecine doğrudan katılır. Bu sayede görünür alan, kaydırma mesafesi ve kalan viewport alanı gibi bilgilere göre içeriklerin nasıl yerleşeceği belirlenebilir.</p><p>ÖzellikBox tabanlı widget’larSliver tabanlı widget’larTemel yerleşimBoxConstraintsSliverConstraintsKaydırılabilir içerikle ilişkiGenellikle bir scroll widget&#39;ı içinde kullanılırViewport ile doğrudan çalışırDinamik başlıkEk düzenleme gerekebilirSliverAppBar ile yerleşik olarak desteklenirYapışkan başlıkEk mantık gerekebilirSliverPersistentHeader desteklerBüyük listelerUygun liste widget&#39;ıyla verimli olabilirSliverList ve delegate yapısıyla verimli olabilir</p><p>Önemli ayrıntı: Slivers her durumda Box widget’larından daha hızlı değildir. Asıl avantajları, farklı içerik türlerini tek bir kaydırma akışında birleştirebilmeleri ve bu akışın yerleşimini kontrol edebilmeleridir.</p><h3>2. CustomScrollView Nasıl Çalışır?</h3><p>CustomScrollView, farklı Sliver widget&#39;larını aynı kaydırılabilir alan içinde birleştiren temel bileşendir.</p><pre>CustomScrollView(<br>  slivers: [<br>    SliverAppBar(<br>      // Genişleyip daralan başlık<br>    ),<br>    SliverToBoxAdapter(<br>      // Banner gibi tekil Box widget&#39;ları<br>    ),<br>    SliverPersistentHeader(<br>      // Sabitlenebilen başlık veya sekmeler<br>      delegate: MyHeaderDelegate(),<br>    ),<br>    SliverList(<br>      // Dikey ve gerektiğinde tembel oluşturulan liste<br>      delegate: SliverChildBuilderDelegate(<br>        (context, index) =&gt; ListTile(<br>          title: Text(&#39;Öğe $index&#39;),<br>        ),<br>        childCount: 100,<br>      ),<br>    ),<br>  ],<br>)</pre><p>Sık kullanılan Sliver bileşenleri şunlardır:</p><ul><li><strong>SliverAppBar:</strong> Kaydırma sırasında genişleyip daralabilen uygulama başlığı.</li><li><strong>SliverToBoxAdapter:</strong> Normal bir Box widget&#39;ını Sliver akışına dahil eder.</li><li><strong>SliverPersistentHeader:</strong> Kaydırma sırasında boyutu değişebilen veya viewport&#39;un üstüne sabitlenebilen başlık.</li><li><strong>SliverList:</strong> Dikey liste içeriklerini görüntüler.</li><li><strong>SliverGrid:</strong> Izgara biçiminde içerik oluşturur.</li><li><strong>SliverFillRemaining:</strong> Kalan viewport alanını bir widget ile doldurur.</li></ul><p>Bu bileşenlerin tamamı CustomScrollView içinde birlikte kullanılabilir. Böylece başlık, banner, sekmeler ve liste için ayrı dikey kaydırma alanları oluşturmak zorunda kalmazsınız.</p><h3>3. Kod Örneği: Dinamik Başlık ve Yapışkan Sekmeler</h3><p>Şimdi bir sanatçı profili ekranı oluşturalım. Başlık başlangıçta geniş görünecek, kaydırıldıkça daralacak ve sekme çubuğu üst kısımda sabit kalacak.</p><p>Örnekteki sekmeler, yapışkan başlık davranışını göstermek içindir. Sekmelerin seçildiğinde farklı içerik göstermesi için ayrıca TabBarView veya sekme durumuna bağlı içerik yönetimi eklenmelidir.</p><h3>Tam örnek</h3><pre>import &#39;package:flutter/material.dart&#39;;</pre><pre>class ArtistProfileScreen extends StatelessWidget {<br>  const ArtistProfileScreen({super.key});</pre><pre>  @override<br>  Widget build(BuildContext context) {<br>    final primaryColor = Colors.indigo.shade900;</pre><pre>    return DefaultTabController(<br>      length: 2,<br>      child: Scaffold(<br>        body: CustomScrollView(<br>          physics: const BouncingScrollPhysics(),<br>          slivers: [<br>            // 1. Genişleyip daralan başlık<br>            SliverAppBar(<br>              expandedHeight: 280,<br>              pinned: true,<br>              stretch: true,<br>              backgroundColor: primaryColor,<br>              foregroundColor: Colors.white,<br>              flexibleSpace: FlexibleSpaceBar(<br>                title: const Text(<br>                  &#39;Sanatçı Profili&#39;,<br>                  style: TextStyle(<br>                    fontWeight: FontWeight.bold,<br>                  ),<br>                ),<br>                background: Image.network(<br>                  &#39;https://images.unsplash.com/photo-1511671782779-c97d3d27a1d4?w=1200&#39;,<br>                  fit: BoxFit.cover,<br>                  errorBuilder: (context, error, stackTrace) {<br>                    return ColoredBox(<br>                      color: primaryColor,<br>                      child: const Center(<br>                        child: Icon(<br>                          Icons.music_note,<br>                          size: 72,<br>                          color: Colors.white,<br>                        ),<br>                      ),<br>                    );<br>                  },<br>                ),<br>                stretchModes: const [<br>                  StretchMode.zoomBackground,<br>                  StretchMode.blurBackground,<br>                ],<br>              ),<br>            ),</pre><pre>            // 2. Ekranın üstüne sabitlenen sekmeler<br>            SliverPersistentHeader(<br>              pinned: true,<br>              delegate: StickyTabBarDelegate(<br>                TabBar(<br>                  labelColor: primaryColor,<br>                  unselectedLabelColor: Colors.grey,<br>                  indicatorColor: primaryColor,<br>                  tabs: const [<br>                    Tab(text: &#39;Popüler Parçalar&#39;),<br>                    Tab(text: &#39;Albümler&#39;),<br>                  ],<br>                ),<br>              ),<br>            ),</pre><pre>            // 3. Tembel oluşturulan liste<br>            SliverList(<br>              delegate: SliverChildBuilderDelegate(<br>                (context, index) {<br>                  return ListTile(<br>                    leading: CircleAvatar(<br>                      backgroundColor: primaryColor,<br>                      foregroundColor: Colors.white,<br>                      child: Text(&#39;${index + 1}&#39;),<br>                    ),<br>                    title: Text(&#39;Parça Başlığı #${index + 1}&#39;),<br>                    subtitle: const Text(&#39;3:45 • 1,2 Mn dinlenme&#39;),<br>                    trailing: const Icon(Icons.more_vert),<br>                  );<br>                },<br>                childCount: 40,<br>              ),<br>            ),<br>          ],<br>        ),<br>      ),<br>    );<br>  }<br>}</pre><pre>class StickyTabBarDelegate extends SliverPersistentHeaderDelegate {<br>  StickyTabBarDelegate(this.tabBar);</pre><pre>  final TabBar tabBar;</pre><pre>  @override<br>  double get minExtent =&gt; tabBar.preferredSize.height;</pre><pre>  @override<br>  double get maxExtent =&gt; tabBar.preferredSize.height;</pre><pre>  @override<br>  Widget build(<br>    BuildContext context,<br>    double shrinkOffset,<br>    bool overlapsContent,<br>  ) {<br>    return Material(<br>      color: Colors.white,<br>      elevation: overlapsContent ? 2 : 0,<br>      child: tabBar,<br>    );<br>  }</pre><pre>  @override<br>  bool shouldRebuild(covariant StickyTabBarDelegate oldDelegate) {<br>    return oldDelegate.tabBar != tabBar;<br>  }<br>}</pre><h3>Kodun önemli noktaları</h3><p><strong>expandedHeight: 280</strong></p><p>Başlığın geniş durumdaki yüksekliğini belirler. Bu değer, SliverAppBar tamamen genişlediğinde kullanılır.</p><p><strong>pinned: true</strong></p><p>Başlık daraldığında tamamen kaybolmak yerine üst kısımda kalır. SliverPersistentHeader için de benzer şekilde pinned: true kullanılarak sekme çubuğunun sabitlenmesi sağlanır.</p><p><strong>stretch: true</strong></p><p>Kullanıcı listenin başlangıcından daha fazla aşağı kaydırdığında başlığın esnemesine izin verir. StretchMode.zoomBackground arka plan görselinin büyümesini, StretchMode.blurBackground ise bulanıklık efektini sağlar.</p><p><strong>SliverChildBuilderDelegate</strong></p><p>Liste öğelerini ihtiyaç duyuldukça oluşturur. Böylece binlerce öğeyi tek seferde widget olarak üretmek zorunda kalmazsınız.</p><p><strong>shouldRebuild</strong></p><p>Yeni delegate örneğinin önceki örnekten anlamlı biçimde farklı olup olmadığını bildirir. Delegate’in ürettiği görünüm veya boyutlar değişebiliyorsa bu değişikliklerin doğru şekilde bildirilmesi gerekir.</p><h3>4. SliverPersistentHeaderDelegate Nasıl Çalışır?</h3><p>SliverPersistentHeaderDelegate, özel bir kaydırılabilir başlığın boyutunu ve görünümünü tanımlamanızı sağlar.</p><p>Üç temel metodu ve özelliği vardır:</p><ul><li><strong>minExtent:</strong> Başlığın daralabileceği en küçük yükseklik.</li><li><strong>maxExtent:</strong> Başlığın geniş durumdaki en büyük yüksekliği.</li><li><strong>build:</strong> Başlığın görünümünü oluşturan metot.</li></ul><p>Örneğimizde minExtent ve maxExtent aynı değere eşit olduğu için sekme çubuğunun yüksekliği sabittir. Başlığın kendisinin kaydırma boyunca küçülmesini istiyorsanız bu iki değeri farklı tanımlayabilir ve shrinkOffset parametresini kullanabilirsiniz.</p><p>Örneğin, 160 pikselden 64 piksele daralan bir başlık:</p><pre>class CollapsingHeaderDelegate<br>    extends SliverPersistentHeaderDelegate {<br>  @override<br>  double get minExtent =&gt; 64;</pre><pre>  @override<br>  double get maxExtent =&gt; 160;</pre><pre>  @override<br>  Widget build(<br>    BuildContext context,<br>    double shrinkOffset,<br>    bool overlapsContent,<br>  ) {<br>    final progress =<br>        (shrinkOffset / (maxExtent - minExtent))<br>            .clamp(0.0, 1.0);</pre><pre>    return Container(<br>      color: Colors.indigo.shade900,<br>      alignment: Alignment.centerLeft,<br>      padding: const EdgeInsets.symmetric(horizontal: 16),<br>      child: Opacity(<br>        opacity: 1.0 - progress,<br>        child: const Text(<br>          &#39;Öne Çıkan İçerikler&#39;,<br>          style: TextStyle(<br>            color: Colors.white,<br>            fontSize: 22,<br>            fontWeight: FontWeight.bold,<br>          ),<br>        ),<br>      ),<br>    );<br>  }</pre><pre>  @override<br>  bool shouldRebuild(<br>    covariant CollapsingHeaderDelegate oldDelegate,<br>  ) =&gt; false;<br>}</pre><p>Buradaki progress, başlığın daralma miktarını yaklaşık olarak 0 ile 1 arasında ifade eder. Örnekte başlık küçüldükçe metin saydamlaşır. Bu, yalnızca boyut değiştirmenin ötesinde kaydırma konumuna bağlı görsel efektler oluşturmanın basit bir yoludur.</p><h3>5. Sekmelerin Gerçek İçerikle Çalışması</h3><p>Yapışkan bir TabBar oluşturmak ile sekmelere bağlı içerikleri değiştirmek iki ayrı konudur.</p><p>Yukarıdaki örnekte DefaultTabController, sekmelerin seçimini yönetir. Ancak SliverList aynı listeyi göstermeye devam eder; seçilen sekmeye göre otomatik olarak değişmez.</p><p>Sekmelerin her birinde ayrı bir kaydırılabilir içerik göstermek istiyorsanız NestedScrollView, SliverAppBar, TabBar ve TabBarView birlikte değerlendirilebilir. Bu yapı, dıştaki başlık ile içteki sekme içeriklerinin kaydırma davranışlarını senkronize etmek için tasarlanmıştır.</p><p>Basitleştirilmiş yapı:</p><pre>DefaultTabController(<br>  length: 2,<br>  child: NestedScrollView(<br>    headerSliverBuilder: (context, innerBoxIsScrolled) {<br>      return [<br>        SliverAppBar(<br>          expandedHeight: 240,<br>          pinned: true,<br>          forceElevated: innerBoxIsScrolled,<br>          flexibleSpace: const FlexibleSpaceBar(<br>            title: Text(&#39;Sanatçı Profili&#39;),<br>          ),<br>          bottom: const TabBar(<br>            tabs: [<br>              Tab(text: &#39;Parçalar&#39;),<br>              Tab(text: &#39;Albümler&#39;),<br>            ],<br>          ),<br>        ),<br>      ];<br>    },<br>    body: const TabBarView(<br>      children: [<br>        Center(child: Text(&#39;Parça listesi&#39;)),<br>        Center(child: Text(&#39;Albüm listesi&#39;)),<br>      ],<br>    ),<br>  ),<br>)</pre><p>Bu yaklaşım, her sekmenin kendi içerik alanına sahip olduğu ekranlar için daha uygundur. Çok karmaşık kaydırma senaryolarında iç içe kaydırma davranışını ve ScrollController kullanımını ayrıca test etmek gerekir.</p><h3>6. Performans ve Akıcı Kaydırma İçin Kritik Kurallar</h3><p>Slivers, büyük listelerin verimli oluşturulmasına yardımcı olur; ancak <strong>120 FPS veya belirli bir bellek kullanımını garanti etmez</strong>. Gerçek performans cihazın donanımına, öğelerin karmaşıklığına, görsel boyutlarına ve yapılan işin miktarına bağlıdır.</p><h3>1. Büyük listelerde lazy builder kullanın</h3><pre>SliverList(<br>  delegate: SliverChildBuilderDelegate(<br>    (context, index) =&gt; ListTile(<br>      title: Text(&#39;Öğe $index&#39;),<br>    ),<br>    childCount: 1000,<br>  ),<br>)</pre><p>Bu yapı, öğelerin ihtiyaç duyuldukça oluşturulmasını sağlar. Sabit bir widget listesine zaten sahipseniz SliverChildListDelegate de uygun olabilir. Dolayısıyla builder kullanımı her durumda zorunlu değildir; özellikle büyük veya dinamik listelerde avantajlıdır.</p><h3>2. Gereksiz iç içe kaydırmalardan kaçının</h3><p>Birden fazla dikey kaydırma alanı birbirinin içine yerleştirildiğinde yükseklik kısıtlamaları, kaydırma jestleri ve performans sorunları ortaya çıkabilir.</p><p>Bir ekranın tamamı tek bir akış gibi davranacaksa içeriği CustomScrollView içinde SliverList, SliverGrid ve SliverToBoxAdapter gibi bileşenlerle birleştirmek genellikle daha sade bir çözümdür.</p><p>SliverToBoxAdapter içine uzun bir liste yerleştirmek yerine, listeyi doğrudan SliverList ile oluşturun. SliverToBoxAdapter daha çok banner, açıklama veya tekil kart gibi sınırlı içerikler için uygundur.</p><h3>3. Sabit yükseklikli listeleri değerlendirin</h3><p>Listedeki tüm öğeler aynı yüksekliğe sahipse SliverFixedExtentList kullanmayı değerlendirin:</p><pre>SliverFixedExtentList(<br>  itemExtent: 64,<br>  delegate: SliverChildBuilderDelegate(<br>    (context, index) {<br>      return ListTile(<br>        title: Text(&#39;Öğe $index&#39;),<br>      );<br>    },<br>    childCount: 1000,<br>  ),<br>)</pre><p>itemExtent, her öğenin ana eksendeki boyutunu sabitler. Bu bilgi, Flutter&#39;ın yerleşim hesaplamalarını kolaylaştırabilir. Ancak içeriklerin gerçekten aynı yüksekliğe sahip olduğundan emin olun.</p><h3>4. Görselleri optimize edin</h3><p>Büyük görseller, liste kaydırılırken bellek tüketimini ve kare oluşturma süresini artırabilir. Uygun çözünürlükte görsel sunmak, önbellekleme davranışını değerlendirmek ve gereksiz görsel işlemlerinden kaçınmak önemlidir.</p><h3>5. Performansı profil modunda ölçün</h3><p>Geliştirme modundaki sonuçları tek başına gerçek kullanıcı performansının göstergesi olarak değerlendirmeyin. Flutter DevTools ile kare sürelerini, raster işlemlerini ve bellek kullanımını inceleyin. Hedefiniz 60 Hz ekranlarda yaklaşık 16,7 ms, 120 Hz ekranlarda yaklaşık 8,3 ms kare bütçesi içinde kalmak olmalıdır.</p><p>Bu değerler hedeflenen kare süreleridir; her cihazda veya her ekran için garanti edilen sonuçlar değildir.</p><h3>7. Sık Karşılaşılan Hatalar</h3><p><strong>Vertical viewport was given unbounded height</strong></p><p>Çoğunlukla bir scroll widget’ının uygun olmayan veya sınırsız yükseklik kısıtlamaları içinde kullanılmasından kaynaklanır. İç içe liste yapısını gözden geçirin ve tek bir scroll akışı kullanmanın mümkün olup olmadığını değerlendirin.</p><p><strong>RenderBox was not laid out</strong></p><p>Bu hata tek bir nedene bağlı değildir. Hatalı constraint zinciri, geçersiz boyutlar veya başka bir yerleşim problemi buna yol açabilir. Hata mesajındaki widget zincirini inceleyerek asıl kaynağı bulun.</p><p><strong>Yapışkan başlığın içeriğin altında kalması</strong></p><p>SliverPersistentHeader için pinned: true kullanıldığını ve başlığın arka planının uygun biçimde çizildiğini kontrol edin. Gerektiğinde Material ve elevation kullanarak üstte kalan başlığın görsel ayrımını belirginleştirin.</p><p><strong>Sekme seçiliyor ama içerik değişmiyor</strong></p><p>TabBar tek başına içerik değiştirmez. Sekmeleri TabBarView ile ilişkilendirin veya seçili sekme durumuna göre ilgili Sliver içeriğini üretin.</p><h3>Sonuç</h3><p>Flutter Slivers mimarisi, dinamik başlıklar, yapışkan sekmeler, listeler ve ızgaraları tek bir kaydırılabilir alanda birleştirmek için güçlü bir araçtır.</p><ul><li>CustomScrollView, farklı Sliver bileşenlerini aynı viewport içinde birleştirir.</li><li>SliverAppBar, genişleyip daralan başlıklar oluşturur.</li><li>SliverPersistentHeader, kaydırma sırasında sabit kalabilen veya boyutu değişebilen başlıklar sağlar.</li><li>SliverList ve SliverFixedExtentList, uzun listelerin verimli biçimde oluşturulmasına yardımcı olur.</li><li>NestedScrollView, ayrı sekme içeriklerinin başlıkla birlikte kaydırılması gereken senaryolarda değerlendirilebilir.</li></ul><p>Doğru widget seçimi, sade bir kaydırma hiyerarşisi ve gerçek cihazlarda yapılan profil ölçümleriyle daha akıcı ve sürdürülebilir Flutter arayüzleri geliştirebilirsiniz.</p><h3>Kaynaklar</h3><ul><li><a href="https://api.flutter.dev/flutter/widgets/CustomScrollView-class.html">Flutter — CustomScrollView</a></li><li><a href="https://api.flutter.dev/flutter/material/SliverAppBar-class.html">Flutter — SliverAppBar</a></li><li><a href="https://api.flutter.dev/flutter/widgets/SliverPersistentHeaderDelegate-class.html">Flutter — SliverPersistentHeaderDelegate</a></li><li><a href="https://api.flutter.dev/flutter/widgets/CustomScrollView/slivers.html">Flutter — SliverList ve diğer Sliver widget’ları</a></li></ul><p>💡<em>Bu yazının orijinalini, diğer yazılım ve mimari makalelerimi ve geliştirdiğim projeleri incelemek için kişisel web sitemi ziyaret edebilirsiniz: </em><strong>affanccn.com</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bd653f788c9d" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>