← Tüm yazılar

Laravel kuyruklarıyla TMDB'den toplu film içe aktarma

30 Haziran 20262 dk okuma

Film Arşivim'in en çok emek isteyen özelliği ekranda en az görüneni: toplu içe aktarma. Kullanıcı yüzlerce film adını yapıştırıyor, arka planda her satır TMDB'de aranıyor, eşleşenler arşive giriyor, eşleşmeyenler rapora düşüyor. Bu yazı o boru hattının tasarım kararlarını anlatıyor.

Senkron import neden ölür

İlk akla gelen yol — tek request içinde döngüyle TMDB'ye sormak — üç yerden kırılıyor: request timeout'u, tek bir kötü satırın tüm batch'i düşürmesi ve kullanıcının dakikalarca boş ekrana bakması. Çözüm klasik ama detayları önemli: her satır ayrı bir queue job'ı.

class ProcessImportItemJob implements ShouldQueue
{
    public int $tries = 3;
    public int $timeout = 45;

    public function __construct(public int $importItemId)
    {
        $this->onQueue('imports');
    }
}

Job'a modelin kendisi değil ID'si veriliyor — kuyruğa serialize edilen veri küçük kalıyor ve job çalıştığında her zaman güncel kaydı okuyor.

İki modelli tasarım: batch + item

ImportBatch toplam durumu tutuyor (kaç madde, kaçı bitti, iptal edildi mi); ImportItem her satırın kendi yaşam döngüsünü (pending → processing → done/not_found/error). Bu ayrım üç şeyi bedavaya getiriyor: canlı ilerleme (batch sayaçları), madde bazlı hata raporu ve iptal — batch cancelled işaretlenince sıradaki job'lar işe başlamadan çıkıyor.

Idempotentlik pazarlık edilemez

Kuyruk dünyasında her job en az bir kez çalışır — bazen iki kez. Job'ın ilk satırları bu yüzden savunma:

if (! in_array($item->status, ['pending', 'error'], true)) {
    return; // zaten işlenmiş — ikinci çalıştırma zararsız
}

Aynı savunma mükerrer filmde de var: kullanıcının arşivinde o tmdb_id zaten varsa madde duplicate olarak kapanıyor, ikinci kopya yazılmıyor.

Serbest metin TMDB'ye nasıl bağlanır

Kullanıcı "Esaretin Bedeli 1994" da yazıyor, "shawshank" de. Ham sorgu doğrudan aramaya verilmiyor; yıl ayıklama ve normalizasyondan geçen bir akıllı arama en iyi adayı seçiyor. Sonuç bulunamazsa madde sessizce kaybolmuyor — not_found durumuyla rapora düşüyor. Toplu işlemde en kötü davranış sessiz veri kaybıdır.

Öğrenilenler

  • Job'a ID ver, model verme: küçük payload + her zaman taze veri.
  • Durum makinesini önce kâğıda çiz: hangi durumdan hangisine geçilebilir netleşmeden kod yazmak, yarısı processing'de asılı kalan batch'ler demek.
  • İlerleme algısı özelliğin yarısı: aynı süre, canlı sayaçla "çalışıyor", boş ekranla "donmuş" hissettiriyor.
0%▌