Bölüm 5 — Konu 21: JSON Serialization (Manuel → `json_serializable`/`freezed`)

Bir önceki derste Map<String, dynamic> ile JSON verisiyle çalıştık — ama bu, Bölüm 4 Konu 18'de (Dart) "geçici bir kullanım, genelde sonra somut bir modele çevrilir" dediğimiz durumun tam olarak henüz o adımı atmadığımız halidir. Bu derste, JSON'u somut Dart sınıflarına çevirmeyi öğreneceğiz.

#Sorun: Map<String, dynamic> ile Çalışmanın Riskleri

final veri = jsonDecode(response.body);
print(veri['titel']); // ❌ Yazım hatası! "titel" değil "title" olmalıydı

Bu kod derlenir (çünkü dynamic — Dart Bölüm 2 Konu 8'i hatırla, tip kontrolünü kapatır) ama çalışma zamanında null döner (çünkü titel diye bir anahtar yok) — bu, tam olarak Bölüm 2'de "dynamic'ten mümkün olduğunca kaçın" dediğimiz riskin somut bir örneği.

#Manuel Model Sınıfı — fromJson/toJson

class Gonderi {
  final int id;
  final String title;
  final String body;

  Gonderi({required this.id, required this.title, required this.body});

  factory Gonderi.fromJson(Map<String, dynamic> json) {
    return Gonderi(
      id: json['id'],
      title: json['title'],
      body: json['body'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'title': title,
      'body': body,
    };
  }
}

factory Gonderi.fromJson(...) — Dart Bölüm 6 Konu 27'de öğrendiğimiz factory constructor'ı hatırlıyor musun? "Oluşturma mantığını özelleştirmeye izin verir" demiştik — işte tam olarak budur: bir Map<String, dynamic> alıp, onu doğrulayıp/dönüştürüp bir Gonderi nesnesi üreten özel bir oluşturma yolu.

Kullanımı:

Future<Gonderi> gonderiGetir() async {
  final response = await http.get(Uri.parse('https://jsonplaceholder.typicode.com/posts/1'));
  final Map<String, dynamic> json = jsonDecode(response.body);
  return Gonderi.fromJson(json); // artık tip güvenli!
}

final gonderi = await gonderiGetir();
print(gonderi.title); // ✅ IDE, 'title' alanının VAR OLDUĞUNU biliyor, yazım hatası imkansız

Artık gonderi.titel yazarsan, bu derleme zamanında hata verir (Dart Bölüm 6'da öğrendiğimiz alan erişimi kuralları geçerli) — tıpkı Bölüm 4'te (Dart) "JSON'u kısa süre sonra somut bir modele çevireceksen dynamic meşrudur" dediğimiz geçiş sürecinin tamamlandığı an.

#Listelerle Çalışma

Future<List<Gonderi>> gonderilerGetir() async {
  final response = await http.get(Uri.parse('https://jsonplaceholder.typicode.com/posts'));
  final List<dynamic> jsonListesi = jsonDecode(response.body);
  return jsonListesi.map((json) => Gonderi.fromJson(json)).toList();
}

jsonListesi.map(...) — Dart Bölüm 11'de öğrendiğimiz .map() metodu, burada son derece doğal bir kullanım alanı buluyor: her ham JSON nesnesini, Gonderi.fromJson() ile somut bir Dart nesnesine dönüştürüyoruz. Bu, Dart Bölüm 11'de öğrendiğimiz "koleksiyon dönüşümü" bilgisinin, gerçek dünya API entegrasyonunda doğrudan kullanıldığı bir andır.

#Manuel Yazmanın Sorunu — Tekrarlayan, Sıkıcı Kod

Küçük modellerde manuel fromJson/toJson yazmak makul, ama büyük, çok alanlı modellerde bu hem uzun hem hataya açık hale gelir. İşte bu yüzden Dart Bölüm 13 Konu 66'da öğrendiğimiz kod üretimi (code generation) burada devreye giriyor.

#json_serializable — Otomatik Üretim

flutter pub add json_annotation
flutter pub add --dev json_serializable build_runner

import 'package:json_annotation/json_annotation.dart';

part 'gonderi.g.dart'; // Dart Bölüm 12'de öğrendiğimiz part/part of!

@JsonSerializable()
class Gonderi {
  final int id;
  final String title;
  final String body;

  Gonderi({required this.id, required this.title, required this.body});

  factory Gonderi.fromJson(Map<String, dynamic> json) => _$GonderiFromJson(json);
  Map<String, dynamic> toJson() => _$GonderiToJson(this);
}

dart run build_runner build

Bu, Dart Bölüm 13 Konu 66'da tam olarak işlediğimiz kalıbın birebir aynısı — @JsonSerializable() annotation'ı, build_runner'a "bu class için fromJson/toJson implementasyonunu otomatik üret" diyor. Üretilen gonderi.g.dart dosyası, _$GonderiFromJson/_$GonderiToJson fonksiyonlarının gerçek kodunu içeriyor — sen bunu elle yazmak zorunda değilsin.

Neden değerli? 20 alanlı bir modelde, her alanı elle json['alan_adi'] şeklinde eşleştirmek yerine, build_runner bunu senin için, hatasız yapıyor — ve model değiştiğinde (yeni alan eklediğinde), sadece dart run build_runner build'i tekrar çalıştırman yeterli.

#freezed — Immutable Modeller + JSON Serialization Bir Arada

flutter pub add freezed_annotation
flutter pub add --dev build_runner freezed

import 'package:freezed_annotation/freezed_annotation.dart';

part 'gonderi.freezed.dart';
part 'gonderi.g.dart';

@freezed
class Gonderi with _$Gonderi {
  const factory Gonderi({
    required int id,
    required String title,
    required String body,
  }) = _Gonderi;

  factory Gonderi.fromJson(Map<String, dynamic> json) => _$GonderiFromJson(json);
}

Dart Bölüm 13 Konu 66'da freezed'i kısaca tanıtmıştık — burada tam olarak neyi otomatikleştirdiğini görelim. freezed, sadece JSON serialization'ı değil, tüm immutable veri sınıfı davranışlarını üretir:

• == ve hashCode (içerik bazlı eşitlik — Dart Bölüm 6'da bahsettiğimiz ama elle yazmadığımız bir konu).
• toString() (Bölüm 6'da elle yazdığımız kalıbın otomasyonu).
• copyWith() — Bölüm 3 Konu 12'de (Flutter) öğrendiğimiz TextStyle.copyWith() kalıbının, kendi modellerin için otomatik üretilmiş hali!

final gonderi = Gonderi(id: 1, title: 'Başlık', body: 'İçerik');
final guncellenmisGonderi = gonderi.copyWith(title: 'Yeni Başlık');
// id ve body aynı kaldı, sadece title değişti

#Manuel vs json_serializable vs freezed — Ne Zaman Hangisi?

Pratik tavsiye: Küçük prototiplerde manuel yazmak hızlıdır. Gerçek, büyüyen bir projede, freezed, hem JSON serialization'ı hem immutability (Bölüm 6'da state management'ta çok değerli olacak) hem de copyWith()'i tek bir araçla hallettiği için genelde en tercih edilen seçenektir.

#🎯 Bu Dersten Çıkarılması Gerekenler

• Map<String, dynamic> ile doğrudan çalışmak, yazım hatalarını çalışma zamanına kadar gizler; somut model sınıfları (fromJson/toJson) bunu derleme zamanına taşır.
• factory Gonderi.fromJson(...), Dart'ta öğrendiğimiz factory constructor'ın gerçek bir JSON dönüştürme senaryosudur.
• .map() ile bir JSON listesini, somut model nesnelerinin listesine dönüştürmek, Dart'ta öğrendiğimiz koleksiyon dönüşümünün doğal bir uygulamasıdır.
• json_serializable, build_runner ile fromJson/toJson kodunu otomatik üretir — Dart Bölüm 13'te öğrendiğimiz kod üretimi kalıbının gerçek kullanımı.
• freezed, JSON serialization'a ek olarak copyWith(), ==, toString() gibi tüm immutable veri sınıfı davranışlarını otomatik üretir.

#📝 Ödevler

• [ ] Basit bir JSON yanıtı için (örn. bir kullanıcı: id, isim, email) manuel bir model sınıfı yaz, fromJson/toJson ekle.
• [ ] Bir JSON listesini, .map() ile model nesnelerinin listesine dönüştür.
• [ ] json_serializable kurup, aynı modeli @JsonSerializable() ile yeniden yaz, build_runner ile kod üret, üretilen dosyayı incele.
• [ ] freezed kurup, aynı modeli @freezed ile yeniden yaz, copyWith()'i kullanarak bir alanı güncelle.
• [ ] Kendi cümlelerinle, "neden büyük projelerde manuel JSON serialization yerine kod üretimi tercih edilir" sorusunu açıkla.

#🎮 Mini Uygulama — Gerçek API'den Gönderi Listesi

Bölüm 5'te öğrendiğin her şeyi birleştiren bir mini proje:

Gereksinimler:

• jsonplaceholder.typicode.com/posts API'sinden gönderi listesini çek (http paketi).
• Ham JSON'u, kendi yazdığın Gonderi model sınıfına (fromJson ile) dönüştür.
• FutureBuilder + initState()/late final kalıbıyla, listeyi bir ListView.builder (Bölüm 3 Konu 11'i hatırla) içinde göster.
• Her gönderiye tıklandığında (Bölüm 3 Konu 14'ü hatırla), o gönderinin tam detayını gösteren bir ekrana geç (constructor parametresi ile veri gönder).
• Yükleme sırasında CircularProgressIndicator, hata durumunda anlamlı bir mesaj göster.

Bu, artık gerçek, uçtan uca çalışan bir uygulama parçası — internetten veri çekiyor, tip güvenli modellere dönüştürüyor, listeliyorsun ve detaya gidebiliyorsun.

Sıradaki konu: Bölüm 5 — Konu 22: Local Storage (shared_preferences → Hive → sqflite/Drift)