Node.js İle Zamanlanmış Görev Çalıştırma İşlemi Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Zamanlanmış görevleri uygulamaya başlamadan önce sisteminizde Node.js'in güncel bir sürümünün (LTS sürümü önerilir) yüklü olduğundan emin olmalısınız. Projenizi başlatmak için bir terminal açın ve aşağıdaki adımları takip edin.

# Proje klasörünü oluşturun
mkdir node-cron-projesi
cd node-cron-projesi

# Projeyi başlatın
npm init -y

# Gerekli kütüphaneyi yükleyin
npm install node-cron

Bu komutlar, Node.js projenizi başlatır ve zamanlanmış görevler için endüstri standardı kabul edilen node-cron kütüphanesini projenize dahil eder. 2026 yılı itibarıyla bu kütüphane, performans ve kararlılık açısından en güvenilir çözümdür.

Node-cron Kullanarak İlk Görevi Oluşturma

Node-cron, Linux sistemlerdeki "cron" sözdizimini (syntax) temel alır. Bu sözdizimi, görevin ne zaman çalışacağını belirleyen beş farklı parametreden oluşur. İlk adım olarak, her dakika çalışan basit bir loglama işlemi yapalım.

const cron = require('node-cron');

// Her dakikanın 0. saniyesinde çalışır
cron.schedule('* * * * *', () => {
  console.log('Zamanlanmış görev çalıştı: ' + new Date().toLocaleString());
});

Yukarıdaki örnekte * * * * * ifadesi, görevin her dakika başı tetiklenmesini sağlar. Bu ifade sırasıyla; saniye (opsiyonel), dakika, saat, ayın günü, ay ve haftanın günü değerlerini temsil eder.

Zamanlama Sözdizimi (Cron Syntax) Detayları

Zamanlanmış görevlerinizi özelleştirmek için cron sözdizimine hakim olmanız gerekir. Aşağıdaki tablo, zamanlama mantığını anlamanıza yardımcı olacaktır.

Bu yapı sayesinde görevlerinizi saatlik, günlük veya haftalık olarak hassas bir şekilde planlayabilirsiniz. Özellikle 1-5 gibi aralıklar kullanarak hafta içi/hafta sonu ayrımları yapmanız mümkündür.

Asenkron Görevler ve Hata Yönetimi

Node.js'te zamanlanmış görevlerin çoğu veritabanı sorgusu gibi asenkron işlemler içerir. async/await yapısını kullanmak, uygulamanızın çökmesini engellemek için kritiktir. Hataları yakalamak için mutlaka try-catch bloklarını kullanmalısınız.

const cron = require('node-cron');

cron.schedule('0 0 * * *', async () => {
  try {
    console.log('Veritabanı temizleme işlemi başlıyor...');
    // await veritabaniTemizle();
    console.log('İşlem başarıyla tamamlandı.');
  } catch (error) {
    console.error('Görev sırasında hata oluştu:', error.message);
  }
});

Bu örnekte, hata oluşması durumunda uygulamanın geri kalanının etkilenmemesi için try-catch mekanizması kullanılmıştır. Üretim ortamında hataları bir log dosyasına veya harici bir izleme servisine göndermeniz önerilir.

Kritik Uyarı: Zamanlanmış görevler içerisinde asla kullanıcıdan gelen doğrulanmamış verileri doğrudan veritabanı sorgularında kullanmayın. SQL Injection riskine karşı her zaman parametreli sorgular (prepared statements) kullanın.

Görevleri Yönetme: Durdurma ve Başlatma

Bazen bir görevi dinamik olarak durdurmanız veya yeniden başlatmanız gerekebilir. node-cron kütüphanesi size bir görev nesnesi döndürür ve bu nesne üzerinden kontrol sağlamanıza olanak tanır.

const cron = require('node-cron');

const gorev = cron.schedule('* * * * *', () => {
  console.log('Bu görev dinamik olarak durdurulabilir.');
}, {
  scheduled: false // Otomatik başlamasını engeller
});

// Görevi başlat
gorev.start();

// 10 saniye sonra görevi durdur
setTimeout(() => {
  gorev.stop();
  console.log('Görev durduruldu.');
}, 10000);

Bu yöntem, özellikle belirli bir koşul gerçekleştiğinde (örneğin bir abonelik süresi dolduğunda) görevleri devre dışı bırakmanız gereken senaryolarda hayat kurtarıcıdır.

Üretim Ortamı İçin En İyi Pratikler

Node.js uygulamanızın sunucuda sürekli çalışması için bir süreç yöneticisine (Process Manager) ihtiyacınız vardır. PM2, bu konuda en güvenilir araçtır. Uygulamanızın sunucu yeniden başladığında otomatik çalışmasını sağlar.

# PM2 kurulumu
npm install pm2 -g

# Uygulamanızı başlatın
pm2 start app.js --name "zamanlayici-servisi"

# Sunucu açılışında otomatik başlatmayı ayarla
pm2 save
pm2 startup

PM2 kullanmak, uygulamanızda bir hata oluşup süreç kapansa bile otomatik olarak yeniden başlatılmasını sağlar. Bu, 7/24 çalışması gereken zamanlanmış görevler için olmazsa olmazdır.

Güvenlik Sorumluluk Reddi: Bu rehberde paylaşılan kod örnekleri eğitim amaçlıdır. Üretim ortamında hassas verilerle çalışırken şifreleme, çevresel değişkenlerin (.env) kullanımı ve yetkilendirme standartlarına mutlaka uyun. Yazılım güvenliği sorumluluğu geliştiriciye aittir.

Sıkça Sorulan Sorular

Node-cron ile node-schedule arasındaki fark nedir?

node-cron daha çok Linux cron sözdizimine odaklanır ve basittir. node-schedule ise daha esnek tarih ve saat tanımlamalarına (örneğin "her ayın son Cuma günü") imkan tanır. İhtiyacınıza göre ikisi de tercih edilebilir.

Zamanlanmış görevler sunucuyu yavaşlatır mı?

Eğer görevleriniz çok ağır işlemler (büyük veri işleme, video kodlama vb.) içeriyorsa ana Node.js süreç döngüsünü (event loop) bloklayabilir. Bu tür durumlarda görevleri ayrı bir "worker" sürecinde çalıştırmalısınız.

Birden fazla sunucuda aynı görevin çalışmasını nasıl engellerim?

Dağıtık sistemlerde (load balancer arkasındaki sunucular) görevin sadece tek bir sunucuda çalışması için Redis gibi bir merkezi kilit mekanizması kullanmanız gerekir.

Zaman dilimi (timezone) ayarlarını nasıl yaparım?

node-cron kütüphanesinde timezone seçeneğini kullanarak görevin belirli bir bölgenin saatine göre çalışmasını sağlayabilirsiniz: { timezone: "Europe/Istanbul" }.

Görevlerimin çalışıp çalışmadığını nasıl takip ederim?

Görevlerinize mutlaka bir "başladı", "bitti" ve "hata" logu ekleyin. Ayrıca Sentry veya Winston gibi kütüphanelerle logları merkezi bir yere aktararak izleme yapın.

İleri Seviye Senaryo: Veritabanı Temizleme ve Raporlama

Zamanlanmış görevlerin en yaygın kullanım alanlarından biri, veritabanı üzerinde bakım işlemleri yapmaktır. Örneğin, her gün gece yarısı eski oturum kayıtlarını silmek veya kullanıcılara günlük özet e-postaları göndermek gibi işlemler için node-cron ile veritabanı bağlantılarını optimize ederek kullanmalısınız.

Aşağıdaki örnekte, MongoDB üzerinde 30 günden eski olan "log" kayıtlarını temizleyen ve işlem sonucunu konsola raporlayan bir yapı yer almaktadır:

const cron = require('node-cron');
const LogModel = require('./models/Log');

// Her gün saat 03:00'te çalışır
cron.schedule('0 3 * * *', async () => {
  try {
    const thirtyDaysAgo = new Date();
    thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

    const result = await LogModel.deleteMany({ createdAt: { $lt: thirtyDaysAgo } });
    console.log(`[${new Date().toISOString()}] Temizlik tamamlandı. Silinen kayıt sayısı: ${result.deletedCount}`);
  } catch (error) {
    console.error(`[${new Date().toISOString()}] Temizlik sırasında hata oluştu:`, error);
  }
}, {
  scheduled: true,
  timezone: "Europe/Istanbul"
});

Zamanlanmış Görevlerde Performans ve Kaynak Yönetimi

Zamanlanmış görevleriniz yoğun işlem gücü (CPU) gerektiriyorsa, bu durum ana Node.js event loop'unu bloklayabilir ve web sunucunuzun yanıt süresini (latency) olumsuz etkileyebilir. Bu tür durumlarda "Worker Thread" yapısını veya görevleri ayrı bir mikroservis olarak çalıştırmayı düşünmelisiniz.

İşlem Yoğunluğu Olan Görevler İçin İpuçları

• Bloklamadan Kaçının: JSON parse etme veya büyük dosya okuma gibi işlemleri fs.promises veya worker_threads modülleri ile asenkron yürütün.
• Bellek Sızıntısı Kontrolü: Uzun süre çalışan görevlerde, özellikle döngüler içinde büyük objeler oluşturuyorsanız bellek kullanımını process.memoryUsage() ile takip edin.
• İşlem Önceliği: Eğer aynı anda çok sayıda görev tetikleniyorsa, görevleri bir kuyruk sistemine (Queue) aktararak sırayla işlenmelerini sağlayın.

Örneğin, büyük bir veri setini işlerken belleği korumak için "stream" yapısını kullanmak en iyi pratiktir:

const fs = require('fs');
const readline = require('readline');

async function processLargeFile(filePath) {
  const fileStream = fs.createReadStream(filePath);
  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });

  for await (const line of rl) {
    // Her satırı tek tek işleyerek belleği düşük tutun
    await processLine(line);
  }
}

Görevlerin Test Edilmesi

Zamanlanmış görevlerin doğruluğunu test etmek için "zamanı manipüle etme" tekniklerini kullanabilirsiniz. sinon gibi kütüphaneler, clock özelliği sayesinde kodunuzu saatlerce bekletmeden, zamanın akışını simüle etmenize olanak tanır.

Ayrıca, görevlerinizi test edilebilir parçalara bölmek için mantığı (logic) cron fonksiyonunun dışına çıkarıp ayrı bir servis dosyasına taşımanız, birim test (unit test) yazmanızı kolaylaştıracaktır.

Profesyonel İpucu: Geliştirme ortamında test yaparken, cron sözdizimini * * * * * * (her saniye) yaparak görevlerinizin tetiklenip tetiklenmediğini hızlıca doğrulayabilirsiniz.

Sonuç

Node.js ile zamanlanmış görev çalıştırma işlemi, doğru kütüphaneler ve süreç yöneticileriyle oldukça güvenilir bir hale getirilebilir. Bu rehberde öğrendiğiniz node-cron kullanımı, asenkron hata yönetimi ve PM2 ile süreç yönetimi, profesyonel bir arka plan servisi kurmanız için temel taşları oluşturur. Bir sonraki adım olarak, veritabanı tabanlı bir görev kuyruğu sistemi olan BullMQ kütüphanesini inceleyerek daha karmaşık ve ölçeklenebilir görev yönetimi sistemleri kurmayı deneyebilirsiniz.