Modern Flutter uygulamalari cogunlukla backend servisleriyle konusur. API entegrasyonu yalnizca HTTP GET çağrısı yapmak degil; zaman asimi, yeniden deneme, hata siniflandirma, kimlik dogrulama ve cache stratejisi ile birlikte dusunulmelidir. Iyi tasarlanmis istemci katmanı, kotu ag kosullarinda bile kullanıcıya tutarlı deneyim sunar.
HTTP istemci katmanı
http paketi basit senaryolar icin yeterlidir; uretimde dio tercih edilir cunku interceptor, iptal token'i, dosya yükleme ve gelismis hata yönetimi sunar. Base URL, timeout ve header'lar tek yerde yapilandirilmalidir.
final dio = Dio(BaseOptions(
baseUrl: 'https://api.ornek.com/v1',
connectTimeout: const Duration(seconds: 8),
receiveTimeout: const Duration(seconds: 12),
headers: {'Accept': 'application/json'},
));Interceptor zinciri
Auth interceptor access token ekler; 401 alindiginda refresh akisi calistirir. Log interceptor yalnizca debug build'de aktif olmali. Retry interceptor idempotent isteklerde sinirli tekrar dener; POST create islemlerinde kör retry tehlikelidir.
Repository pattern
UI katmanı dogrudan Dio cagirmamali. Repository arayüzü domain dilini kullanır; implementasyon REST detayini bilir. Bu ayrim testte mock repository enjekte etmeyi ve ileride GraphQL'e gecisi kolaylastirir.
Future<User> getProfile()UI icin yeterli.- DTO -> domain map işlemi repository'de kalir.
- Hata kodlari domain exception'a cevrilir.
REST sozlesmesi ve versiyonlama
Path versiyonlama (/v1/) veya header ile API surumu yönetilir. Breaking degisiklikte istemci migration plani gerekir. Pagination icin cursor tabanli API'ler büyük listelerde offset'e gore daha kararlıdır; Flutter tarafinda ScrollController listener ile sonraki sayfa istenir.
Cache katmanları
Cache uc seviyede dusunulur: bellek (in-memory), disk (Hive, Isar, sqflite) ve HTTP cache (ETag, Cache-Control). Her seviyenin TTL ve invalidation kurali açık olmalidir.
Bellek cache
Kisa omurlu, sik okunan veriler icin LinkedHashMap veya LRU paketi kullanılır. Ekrandan cikinca temizlenmesi gereken veriler AutoDisposeProvider veya sayfa scope'unda tutulur.
Disk cache
Offline okuma ve hızlı acilis icin JSON snapshot veya normalize tablolar saklanir. Yazma islemlerinde optimistic UI: once local güncelle, arka planda API'ye gonder, basarisizlikta geri al veya kuyruğa al.
HTTP cache
Dio icin dio_cache_interceptor veya manuel ETag header yönetimi. Stale-while-revalidate: once cache goster, arka planda yenile, veri degisirse UI güncelle.
Stale data ve tutarlılık
Kullanıcıya verinin ne kadar güncel oldugunu göstermek guven oluşturur. Pull-to-refresh, son güncelleme zamani etiketi ve arka plan sync islemleri birlikte çalışır. Kritik finans verisinde cache devre disi birakilabilir; katalog listesinde agresif cache kabul edilebilir.
- Okuma agir ekranlar: disk + bellek.
- Form gonderimi: cache yok, idempotency key.
- Profil sayfasi: kisa TTL + manuel refresh.
- Arama sonuclari: query hash ile bellek cache.
Hata yönetimi ve UX
Ag hatasi, 4xx/5xx ve parse hatasi ayri ele alinir. Kullanıcıya teknik exception string gostermeyin; retry butonu ve destek kodu sunun. ConnectivityPlus ile offline banner gosterip cache'ten okumaya gecin.
Güvenlik
Token'lari flutter_secure_storage ile saklayin. Certificate pinning dikkatli kullanın; yanlış yapılandırma sürüm guncellemelerini kilitler. Log'larda Authorization header maskeleyin.
Test ve gozlemlenebilirlik
Repository birim testlerinde Dio icin MockAdapter kullanın. Entegrasyon testlerinde fake HTTP server (örneğin mocktail + local socket) ile gecikme ve hata senaryolarini simule edin. Uretimde Firebase Performance veya Sentry ile API latency izleyin.
Orkestrasyon: Riverpod + repository
AsyncNotifier refresh metodu cache invalidation ile birlestirilebilir. Aile parametreleri sayfa basina cache anahtari üretir. Parallel istekler icin Future.wait yerine bagimsiz provider'lar daha iyi hata izolasyonu sağlar.
Pagination ve sonsuz scroll
Cursor tabanli API'lerde sonraki sayfa token'i repository'de saklanir. Kullanıcı listeyi asagi kaydirdikca fetchNextPage cagrilir; yükleme footer'i ayri state tutar. Offset pagination'da sayfa numarasi ve toplam kayıt senkron tutulmalidir; silme islemlerinde offset kaymasi olusabilir.
Deduplication
Hızlı scroll sirasinda ayni sayfa iki kez istenebilir. In-flight istekleri CancelToken veya request key ile birlestirmek gereksiz ag yukunu azaltir.
Offline kuyruk ve sync
Yazma islemleri offline iken local kuyruğa alinip bağlantı gelince syncPendingChanges ile gonderilebilir. Her kuyruk ogesine idempotency key ve timestamp ekleyin; başarısız öğeler exponential backoff ile tekrar denenmelidir.
Observability
Her API cagrisina correlation id header eklemek backend loglari ile istemci hatalarini eslestirir. Dio interceptor'da X-Request-Id uretip Sentry breadcrumb'a yazmak üretim debug'unu hizlandirir.
API entegrasyonu ve caching birbirinden ayrilmaz. HTTP istemcisini interceptor'larla zenginlestirin, repository ile domain sınırını koruyun, bellek-disk-HTTP uc katmanli cache ile hiz ve tutarlılık dengesini kurun. Bu yapı, Flutter istemcisini ag dalgalanmalarina karşı dayanikli hale getirir.
GraphQL veya gRPC kullaniyorsanız ayni repository soyutlamasi gecerlidir; transport degisir, UI etkilenmez. gql_dio_link veya grpc paketleri icin ayri data source implementasyonu yazilir.
Dosya indirme ve resume icin dio download + Range header destegi; büyük medya cache'i icin ayri dizin ve maksimum disk kotasi politikasi tanimlayin.
Webhook veya push ile gelen invalidation olaylari cache TTL'i tamamlayabilir; real-time gerektiren modullerde WebSocket + local merge stratejisi dusunun.
Çoklu ortam (dev/stage/prod) base URL yönetimi flavor veya dart-define ile yapilmali; yanlislikla prod'a test verisi gonderimini onlemek icin build-time assert ekleyin.
Serialization icin json_serializable ve freezed kullanımı parse hatalarini erken yakalar; API sozlesmesi degistiginde codegen yeniden calistirilmali ve migration testleri yazilmalidir.
Rate limiting (429) ve Retry-After header destegi istemci tarafinda exponential backoff ile uygulanmali; kullanıcıya sonsuz spinner göstermek yerine bekleme suresi ve tekrar dene secenegi sunulmali.
Multipart upload ve presigned URL akislari büyük dosyalarda bellek tuketimini sinirlamak icin stream upload kullanır; dio'da onSendProgress ile UI güncellenir, iptal icin CancelToken zorunludur.
Cache poisoning ve yanlış ETag senaryolarina karşı disk cache'e yazmadan once response status ve content-type dogrulayin; HTML hata sayfasi JSON cache'e yazilirsa uygulama sessizce bozulur.
Background sync icin workmanager veya platform task scheduler ile periyodik refresh planlanabilir; foreground iken öncelik kullanıcının actigi ekrandaki provider refresh'ine verilmelidir.
API mock sunucusu olarak openapi generator ile uretilen stub'lar veya mockoon kullanmak frontend-backend paralel gelistirmeyi hizlandirir.
Sensitive response alanlarini disk cache'e yazmadan once maskeleyin; kredi karti son dört hane gibi alanlar bile policy'ye tabidir.
GraphQL persisted query veya REST field filtering ile payload boyutunu kucultmek mobil cache verimliligini artirir.
Token yenileme sirasinda paralel istekler 401 alabilir; auth interceptor'da refresh lock veya queue pattern kullanarak yarismayi onleyin.
Cache TTL degerlerini endpoint bazinda ayarlayin; statik konfigurasyon uzun, kullanıcı profili orta, arama sonuclari kisa omurlu olmalidir.
Integration testlerde fake HTTP ile gecikme, timeout ve kismi response senaryolarini otomatiklestirmek regresyon riskini dusurur.
Son olarak API katmanini UI'dan tamamen ayirmak, cache politikasini repository seviyesinde uygulamak ve her katman icin ayri test yazmak sürdürülebilir Flutter istemcisinin temelidir.
Health check endpoint'i ile uygulama acilisinda backend erisilebilirligini dogrulayip kullanıcıya anlamli bakım modu mesaji gosterebilirsiniz.
Dio adapter seçimi (IOHttpClientAdapter vs cupertino) platforma gore farklilik gösterir; certificate pinning ve proxy ayarlarini adapter uzerinden yapilandirin.
Bu detaylar üretim ortaminda güvenli ve ölçeklenebilir API entegrasyonu icin kritiktir.
