Flutter'da REST API Hatalarını Ele Alma: Dio Interceptor ile Retry ve Hata Yönetimi Rehberi

Flutter ile mobil uygulama geliştirirken REST API hataları kaçınılmazdır. Ağ bağlantısı kesintileri, sunucu sorunları veya geçici hatalar, kullanıcı deneyimini doğrudan etkiler. Bu yazıda, Dio interceptor yapısını kullanarak hataları merkezi bir şekilde yönetmeyi, otomatik yeniden deneme (retry) mekanizması kurmayı ve kullanıcıya anlamlı hata mesajları göstermeyi adım adım ele alacağız.

Hata yönetimi, mobil uygulamalarda yalnızca kod kalitesini artırmakla kalmaz; kullanıcıların uygulamaya olan güvenini de pekiştirir. Özellikle Flutter gibi cross-platform frameworklerde, bir kez yazılan hata yönetimi katmanı tüm platformlarda tutarlı çalışır.

Dio Interceptor ile Hata Yönetiminin Temelleri

Flutter'da popüler HTTP istemcisi Dio, interceptor (aracı) yapısı sayesinde istek ve yanıt akışını kesip müdahale etmenize olanak tanır. Herhangi bir API çağrısında hata oluştuğunda, onError yöntemi tetiklenir. Burada hata tipine göre özel işlemler yapabilirsiniz.

Interceptor Türleri ve Görevleri

Retry (Yeniden Deneme) Mekanizması Kurulumu

Geçici hatalar (örneğin 503 Service Unavailable veya zaman aşımı) için otomatik retry, kullanıcının işlemini kesintiye uğratmadan tamamlamasını sağlar. Dio interceptor içinde onError'da bir retry sayacı tutarak belirli sayıda tekrar deneyebilirsiniz.

class RetryInterceptor extends Interceptor {
  final int maxRetries;
  int _retryCount = 0;

  RetryInterceptor({this.maxRetries = 3});

  @override
  void onError(DioError err, ErrorInterceptorHandler handler) {
    if (_retryCount < maxRetries && _shouldRetry(err)) {
      _retryCount++;
      // Yeniden deneme için handler'i kullanma
      handler.resolve(err.response ?? Response(requestOptions: err.requestOptions));
    } else {
      handler.next(err);
    }
  }

  bool _shouldRetry(DioError err) {
    return err.type == DioErrorType.connectionTimeout ||
        err.type == DioErrorType.receiveTimeout ||
        (err.response?.statusCode == 503);
  }
}

Yukarıdaki örnekte, yalnızca bağlantı zaman aşımı ve 503 hatası durumunda retry yapılır. Diğer hatalar (401, 404 gibi) doğrudan kullanıcıya iletilir.

Retry Sırasında Dikkat Edilmesi Gerekenler

• İdempotent olmayan istekler: POST, PUT gibi veri değiştiren isteklerde retry yan etkilere yol açabilir. Yalnızca GET gibi idempotent isteklerde retry uygulayın.
• Gecikme stratejisi: Her denemede artan bir gecikme (exponential backoff) kullanarak sunucuya aşırı yüklenmeyin.
• Kullanıcı bildirimi: Retry sırasında kullanıcıya bir ilerleme göstergesi veya “yeniden bağlanıyor” mesajı gösterin.

Hata Dönüştürme ve Kullanıcı Dostu Mesajlar

Ham DioError nesnesini doğrudan kullanıcıya göstermek yerine, interceptor içinde hata kodunu analiz edip anlamlı bir metin oluşturabilirsiniz. Örneğin:

@override
void onError(DioError err, ErrorInterceptorHandler handler) {
  String userMessage;
  switch (err.type) {
    case DioErrorType.connectionTimeout:
      userMessage = 'İnternet bağlantınız kontrol edin.';
      break;
    case DioErrorType.badResponse:
      userMessage = _messageForStatusCode(err.response?.statusCode);
      break;
    default:
      userMessage = 'Beklenmeyen bir hata oluştu.';
  }
  // Hata mesajını özel bir Exception ile sarmalayıp fırlatın
  handler.next(DioError(
    requestOptions: err.requestOptions,
    error: UserFriendlyException(userMessage),
    type: err.type,
    response: err.response,
  ));
}

String _messageForStatusCode(int? statusCode) {
  switch (statusCode) {
    case 400: return 'Geçersiz istek.';
    case 401: return 'Oturum süreniz doldu, lütfen tekrar giriş yapın.';
    case 404: return 'Aradığınız kaynak bulunamadı.';
    case 500: return 'Sunucu hatası, lütfen daha sonra tekrar deneyin.';
    default: return 'Bir hata oluştu. (Hata kodu: $statusCode)';
  }
}

Gerçek Proje Uygulaması

Bir Flutter projesinde bu interceptor'ı kullanmak için Dio örneğine eklemeniz yeterlidir:

final dio = Dio();
dio.interceptors.add(RetryInterceptor(maxRetries: 2));
dio.interceptors.add(ErrorHandlingInterceptor());
// Artık tüm API çağrıları bu interceptor'lardan geçer.

Bu yapı, kod tekrarını azaltır ve hata yönetimini merkezileştirir. Ayrıca, Dio'nun sunduğu diğer özelliklerle (örneğin, loglama interceptor'ı) birleştirerek daha sağlam bir altyapı oluşturabilirsiniz. Detaylı karşılaştırma için Flutter'da HTTP İstekleri: Dio vs http Paketi yazımıza göz atabilirsiniz.

Platformlar Arası Farklılıklar ve Öneriler

iOS ve Android'de ağ hatalarının davranışı benzer olsa da, platforma özel durumlar olabilir. Örneğin, iOS'ta VPN veya hücresel veri geçişleri zaman aşımına neden olabilir. Bu tür senaryolar için iOS'da URLSession ile Zaman Aşımı ve Retry Stratejileri yazımızda detaylı çözümler bulabilirsiniz.

Sık Yapılan Hatalar ve Kaçınılması Gerekenler

• Tüm hatalarda retry yapmak: 401 (yetkilendirme hatası) gibi kalıcı hataları tekrarlamak sunucu yükünü artırır ve kullanıcı deneyimini bozar.
• Retry sayısını sınırlamamak: Sonsuz döngüye girmemek için maksimum deneme sayısı belirleyin.
• Kullanıcıya teknik detay göstermek: “DioError: connectionTimeout” gibi mesajlar yerine anlaşılır ifadeler kullanın.

Unutmayın, iyi bir hata yönetimi uygulamanızın kalitesini doğrudan yansıtır. Dio interceptor ile bu süreci profesyonelce yönetebilirsiniz.

Sık Sorulan Sorular

Flutter'da Dio Interceptor nedir?

Dio Interceptor, Dio HTTP istemcisinin istek ve yanıt akışına müdahale etmenizi sağlayan bir yapıdır. onRequest, onResponse ve onError gibi yöntemlerle hata yönetimi, retry, token yenileme gibi işlemleri merkezi olarak gerçekleştirebilirsiniz.

Retry mekanizması nasıl kurulur?

Dio interceptor içinde onError yöntemini kullanarak, hata tipine göre otomatik yeniden deneme yapabilirsiniz. Bir sayaç tutarak maksimum deneme sayısını belirleyin ve yalnızca geçici hatalarda (zaman aşımı, 503) retry uygulayın.

Hata kodlarına göre özel mesajlar nasıl gösterilir?

Dio Interceptor'ün onError metodunda, gelen DioError nesnesinin statusCode veya errorType değerini kontrol ederek kullanıcı dostu bir mesaj oluşturabilirsiniz. Örneğin 401 hatasında 'Oturum süreniz doldu' mesajı gösterilebilir.