Bölüm 11 — Konu 52: GraphQL (Opsiyonel)

Bu konu opsiyonel işaretli — GraphQL, her projede karşına çıkmaz, ama özellikle büyük/kurumsal API'lerde (GitHub API, Shopify, birçok modern SaaS ürünü) giderek yaygınlaşan bir alternatif. Temel fikri anlaman, bir gün "bu API GraphQL kullanıyor" ile karşılaştığında şaşırmaman için yeterli.

#REST'in Sorunu — Over-fetching ve Under-fetching

Bölüm 5 Konu 20'de öğrendiğimiz REST API'leri hatırla — her endpoint, sabit bir yapıda veri döner:

GET /kullanicilar/123
→ { id, isim, eposta, adres, telefon, kayitTarihi, ... TÜM ALANLAR }

Diyelim ki arayüzünde sadece kullanıcının ismini göstermen gerekiyor — REST, yine de tüm alanları gönderir (over-fetching — ihtiyacından fazlasını çekme). Ya da tam tersi: kullanıcının hem bilgilerini hem son 5 siparişini göstermen gerekiyorsa, iki ayrı istek atman gerekebilir (under-fetching — bir istekte yetmemesi).

#GraphQL'in Çözümü — "Ne İstediğini Sen Söyle"

query {
  kullanici(id: "123") {
    isim
    siparisler(limit: 5) {
      urunAdi
      fiyat
    }
  }
}

GraphQL'de, istemci (senin Flutter uygulaman), tam olarak hangi alanları istediğini sorgunun içinde belirtir — sunucu, sadece istenen alanları, tek bir istekte döner. Bu, Bölüm 11 Konu 51'de Supabase'in .select('isim') ile "sadece bu sütunu getir" demesine kavramsal olarak benziyor — ama GraphQL bunu iç içe geçmiş ilişkiler için de (yukarıdaki örnekte olduğu gibi, kullanıcı + siparişleri tek seferde) doğal olarak destekler.

#Şema ve Tip Sistemi — Dart'ın Statik Tiplemesine Benzer Bir Güvence

type Kullanici {
  id: ID!
  isim: String!
  eposta: String!
  siparisler: [Siparis!]!
}

GraphQL API'leri, Dart Bölüm 1-2'de öğrendiğimiz statik tip sistemine benzer bir şema ile tanımlanır — ! işareti, Dart'ın non-nullable (String vs String?) mantığına birebir karşılık gelir ("bu alan asla null olamaz" demektir). Bu şema sayesinde, bir GraphQL sorgusu derleme zamanında bile (uygun araçlarla) doğrulanabilir — "böyle bir alan yok" hatası, API'ye istek atmadan önce yakalanabilir.

#Flutter'da Kullanım — graphql_flutter

flutter pub add graphql_flutter

final HttpLink httpLink = HttpLink('https://api.ornek.com/graphql');
final ValueNotifier<GraphQLClient> client = ValueNotifier(
  GraphQLClient(link: httpLink, cache: GraphQLCache()),
);

#Query — Veri Okuma

const String kullaniciSorgusu = r'''
  query KullaniciGetir($id: ID!) {
    kullanici(id: $id) {
      isim
      eposta
    }
  }
''';

Query(
  options: QueryOptions(
    document: gql(kullaniciSorgusu),
    variables: {'id': '123'},
  ),
  builder: (QueryResult sonuc, {refetch, fetchMore}) {
    if (sonuc.isLoading) return const CircularProgressIndicator();
    if (sonuc.hasException) return Text('Hata: ${sonuc.exception}');

    final kullanici = sonuc.data!['kullanici'];
    return Text(kullanici['isim']);
  },
)

Query widget'ı, Bölüm 5 Konu 18'de öğrendiğimiz FutureBuilder'a kavramsal olarak çok benziyor — isLoading/hasException/data durumlarını, Flutter'ın builder pattern'i (Bölüm 3 Konu 11) ile tutarlı bir şekilde yönetiyor. $id: ID! gibi değişkenler, Dart Bölüm 6'da öğrendiğimiz parametreli fonksiyon çağrısına benzer bir mantıkla, sorguyu yeniden kullanılabilir yapıyor (variables: {'id': '123'} ile "doldurulur").

#Mutation — Veri Değiştirme

const String kullaniciGuncelle = r'''
  mutation KullaniciGuncelle($id: ID!, $isim: String!) {
    kullaniciGuncelle(id: $id, isim: $isim) {
      id
      isim
    }
  }
''';

Mutation(
  options: MutationOptions(document: gql(kullaniciGuncelle)),
  builder: (RunMutation calistir, QueryResult? sonuc) {
    return ElevatedButton(
      onPressed: () => calistir({'id': '123', 'isim': 'Yeni İsim'}),
      child: const Text('Güncelle'),
    );
  },
)

GraphQL'de okuma işlemleri query, yazma/değiştirme işlemleri mutation olarak adlandırılır — bu, REST'teki GET (okuma) ile POST/PUT/DELETE (değiştirme) ayrımının GraphQL karşılığıdır.

#Subscription — Gerçek Zamanlı Veri

const String yeniMesajAkisi = r'''
  subscription {
    yeniMesaj {
      gonderen
      icerik
    }
  }
''';

Subscription(
  options: SubscriptionOptions(document: gql(yeniMesajAkisi)),
  builder: (QueryResult sonuc) {
    if (!sonuc.hasException && sonuc.data != null) {
      return Text(sonuc.data!['yeniMesaj']['icerik']);
    }
    return const Text('Mesaj bekleniyor...');
  },
)

subscription, Bölüm 11 Konu 50-51'de Firestore'un .snapshots()'ı ve Supabase'in .stream()'i ile aynı fikri — sunucudan sürekli akan veri — GraphQL dünyasında ifade eder. Altyapıda genelde WebSocket kullanılır (Bölüm 5 Konu 19'da öğrendiğimiz Stream kavramının, ağ üzerinden sürekli açık bir bağlantı ile taşınan hali).

#GraphQL vs REST vs Firestore/Supabase — Nerede Durur?

#Pratik Gerçek — Ne Zaman Karşına Çıkar?

Kendi backend'ini (Bölüm 11 Konu 50-51'deki Firebase/Supabase ya da kendi yazdığın bir sunucu) sen tasarlıyorsan, GraphQL'i baştan seçmen nadiren gerekir — REST (Bölüm 5 Konu 20) ya da Firestore/Supabase'in kendi sorgu API'leri genelde yeterlidir. GraphQL'in asıl değeri, büyük, birden fazla ekibin aynı API'yi farklı ihtiyaçlarla kullandığı kurumsal ortamlarda ortaya çıkar — ya da hazır bir GraphQL API'sine (örneğin bir üçüncü parti servis) client olarak bağlanman gerektiğinde.

#🎯 Bu Dersten Çıkarılması Gerekenler

• GraphQL, REST'in over-fetching/under-fetching sorununu, istemcinin tam olarak hangi alanları istediğini sorgunun içinde belirtmesine izin vererek çözer.
• Şema ve tip sistemi (! ile non-nullable), Dart'ın statik tiplemesine benzer bir güvence sağlar.
• query (okuma), mutation (yazma), subscription (gerçek zamanlı akış) — REST'teki HTTP metodlarının ve Firestore/Supabase'in stream API'lerinin GraphQL karşılıkları.
• graphql_flutter'daki Query/Mutation widget'ları, FutureBuilder'a kavramsal olarak çok benzer bir builder pattern kullanır.
• Pratikte, kendi backend'ini tasarlarken GraphQL zorunlu değildir — büyük/kurumsal API'lerde ya da hazır bir GraphQL servisine bağlanırken karşına çıkar.

#📝 Ödevler (Opsiyonel)

• [ ] Herkese açık bir GraphQL API'sini (örn. countries.trevorblades.com) graphql_flutter ile sorgula, sonucu bir listede göster.
• [ ] Aynı veriyi REST ile çekmiş olsaydın kaç istek gerekeceğini, GraphQL'in tek istekte nasıl çözdüğünü karşılaştırarak kendi cümlelerinle yaz.
• [ ] Bir GraphQL şemasındaki ! işaretlerinin, Dart'ın nullable/non-nullable (String vs String?) sistemiyle nasıl paralel olduğunu açıkla.

Sıradaki konu: Bölüm 11 — Konu 53: Store Yayınlama Süreci (İmzalama, Listing, Versiyonlama)