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

Gereksinimler ve Ön Hazırlık

Bu rehberdeki uygulamaları gerçekleştirmek için bilgisayarınızda Node.js'in güncel bir LTS (Long Term Support) sürümünün kurulu olması gerekir. 2026 standartlarına göre Node.js 22.x veya üzeri sürümleri kullanmanız önerilir.

• Node.js: v22.x veya üzeri.
• Paket Yöneticisi: npm veya pnpm.
• Editör: VS Code veya benzeri bir IDE.
• Temel Bilgi: JavaScript (ES6+ modülleri) ve asenkron programlama mantığı.

Çalışma ortamınızı hazırlamak için terminalinizde yeni bir proje klasörü oluşturun ve gerekli paketleri başlatın:

mkdir node-cron-projesi
cd node-cron-projesi
npm init -y

Node-Cron Kütüphanesi ile Temel Görev Zamanlama

Node.js dünyasında zamanlanmış görevler için en çok tercih edilen kütüphane node-cron paketidir. Bu paket, Linux sistemlerdeki standart "cron" sözdizimini (syntax) kullanarak görevlerinizi planlamanıza olanak tanır.

Öncelikle paketi projenize dahil edin:

npm install node-cron

Şimdi, her dakika çalışan basit bir görev tanımlayalım. Bu örnek, cron'un temel çalışma mantığını anlamanızı sağlayacaktır:

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

// Her dakika başında çalışan görev
cron.schedule('* * * * *', () => {
  console.log('Zamanlanmış görev çalıştı: ' + new Date().toLocaleString());
});

Buradaki * * * * * ifadesi; dakika, saat, ayın günü, ay ve haftanın günü değerlerini temsil eder. Bu yapı sayesinde görevlerinizi saniyelik hassasiyetten yıllık periyotlara kadar ölçeklendirebilirsiniz.

Cron Sözdizimi ve Detaylı Zamanlama Kuralları

Cron sözdizimi başlangıçta karmaşık görünebilir ancak belirli bir hiyerarşiye sahiptir. Aşağıdaki tablo, zamanlama parametrelerini anlamanıza yardımcı olacaktır.

Örneğin, her gün saat 03:00'da çalışacak bir yedekleme görevi için şu sözdizimini kullanmalısınız:

cron.schedule('0 3 * * *', () => {
  console.log('Günlük veritabanı yedeklemesi başlatılıyor...');
});

Node.js'de Görevleri Yönetme ve Durdurma

Zamanlanmış görevlerinizi dinamik olarak başlatmak veya durdurmak gerekebilir. node-cron kütüphanesi, görev nesneleri üzerinden bu kontrolü sağlar.

Aşağıdaki örnekte, bir görevi başlatıp 5 saniye sonra durduran bir mekanizma göreceksiniz:

const task = cron.schedule('* * * * * *', () => {
  console.log('Bu görev her saniye çalışır.');
}, {
  scheduled: false // Otomatik başlamasını engelle
});

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

setTimeout(() => {
  task.stop();
  console.log('Görev durduruldu.');
}, 5000);

Bu yöntem, özellikle kullanıcı etkileşimine bağlı olarak arka plan işlemlerini tetiklemek istediğiniz senaryolarda hayat kurtarıcıdır.

Node-Schedule ile Gelişmiş Zamanlama

Eğer cron sözdizimi yerine daha okunabilir (tarih tabanlı) bir yapı tercih ederseniz, node-schedule kütüphanesi harika bir alternatiftir. Bu kütüphane, belirli bir tarih veya nesne tabanlı zamanlama yapmanıza imkan tanır.

npm install node-schedule

Belirli bir tarihte veya her Salı günü saat 14:00'da çalışacak bir görev tanımlayalım:

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

// Her Salı 14:00'da çalışır
const rule = new schedule.RecurrenceRule();
rule.dayOfWeek = 2;
rule.hour = 14;
rule.minute = 0;

schedule.scheduleJob(rule, () => {
  console.log('Haftalık rapor gönderimi tetiklendi.');
});

Üretim Ortamında Dikkat Edilmesi Gerekenler

Zamanlanmış görevler üretim ortamında (production) ciddi yük oluşturabilir. Aşağıdaki uyarıları mutlaka dikkate alın:

Kritik Uyarı: Zamanlanmış görevlerinizin hata yönetimi (error handling) çok güçlü olmalıdır. Bir görev hata verip tüm Node.js ana sürecini (process) çökertirse, web uygulamanız erişilemez hale gelir. Her zaman try-catch blokları kullanın.

Güvenlik ve performans için şu pratikleri uygulayın:

• Loglama: Görevlerin başarı ve hata durumlarını mutlaka bir log dosyasına veya harici bir servise yazın.
• Örtüşme Kontrolü: Bir görev bir öncekini bitirmeden yeni bir görev başlamamalıdır.
• Çevre Değişkenleri: Hassas verileri (API anahtarları, veritabanı şifreleri) asla koda yazmayın, .env dosyalarını kullanın.

// Güvenli bir görev örneği
cron.schedule('0 0 * * *', async () => {
  try {
    await performDatabaseCleanup();
  } catch (error) {
    console.error('Görev sırasında hata oluştu:', error);
    // Burada bir bildirim sistemi (Slack/E-posta) tetikleyebilirsiniz
  }
});

Sıkça Sorulan Sorular

Node.js zamanlanmış görevler için güvenli mi?

Evet, ancak tek süreçli (single-threaded) yapısı nedeniyle uzun süren görevlerin ana döngüyü (event loop) bloklamamasına dikkat etmelisiniz. Çok ağır işler için "Worker Threads" veya harici bir kuyruk sistemi (BullMQ gibi) kullanmanız önerilir.

Görevler sunucu yeniden başladığında çalışır mı?

Node.js süreci kapandığında görevler de durur. Uygulamanızın her zaman çalışır kalması için PM2 gibi bir süreç yöneticisi kullanmalısınız.

Aynı anda birden fazla görev çalıştırabilir miyim?

Evet, istediğiniz kadar cron.schedule veya scheduleJob tanımlayabilirsiniz. Ancak çok fazla görev performansı düşürebilir.

Görevlerin çalıştığını nasıl test ederim?

Test ortamında zamanı hızlandırmak yerine, görevlerinizi küçük bir fonksiyon olarak ayırıp bu fonksiyonu bir API endpoint'i üzerinden manuel tetikleyerek test edebilirsiniz.

Hangi kütüphaneyi seçmeliyim?

Basit ve cron sözdizimi ile çalışmak istiyorsanız node-cron, daha karmaşık tarihsel planlamalar ve nesne tabanlı kurallar için node-schedule tercih edilmelidir.

Yasal Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Uygulamanızdaki veri güvenliği ve sunucu kaynak yönetimi tamamen geliştiricinin sorumluluğundadır. Kritik veritabanı işlemlerinde mutlaka yedekleme stratejileri uygulayın.

Zamanlanmış Görevlerde Hata Ayıklama ve Loglama Stratejileri

Zamanlanmış görevler arka planda çalıştığı için, bir hata oluştuğunda bunu fark etmek oldukça zordur. Standart console.log kullanımı, görevleriniz karmaşıklaştığında yetersiz kalacaktır. Profesyonel bir uygulamada, görevlerin başarı durumunu ve hata detaylarını merkezi bir loglama sistemine aktarmanız hayati önem taşır.

Görevlerinizi izlenebilir kılmak için Winston veya Pino gibi kütüphaneler kullanarak, her görev tetiklendiğinde bir "job_id" ile log kaydı oluşturmalısınız.

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'cron-jobs.log' })
  ]
});

// Görev içinde hata yönetimi
cron.schedule('0 * * * *', async () => {
  const jobId = Math.random().toString(36).substring(7);
  try {
    logger.info({ message: 'Görev başladı', jobId });
    // İş mantığı buraya gelecek
    await performTask();
    logger.info({ message: 'Görev başarıyla tamamlandı', jobId });
  } catch (error) {
    logger.error({ message: 'Görev başarısız oldu', jobId, error: error.message });
  }
});

Zamanlanmış Görevlerde Performans Optimizasyonu

Node.js tek iş parçacıklı (single-threaded) bir yapıya sahip olduğu için, ağır hesaplama gerektiren (CPU-intensive) görevler ana uygulama döngüsünü (Event Loop) bloklayabilir. Bu durum, sunucunuzun gelen HTTP isteklerine yanıt verememesine neden olur.

İleri İpuçları ve En İyi Uygulamalar

• Worker Threads Kullanımı: Eğer göreviniz uzun süren bir veri işleme süreciyse, ana iş parçacığını meşgul etmemek için worker_threads modülünü kullanın.
• Zaman Aşımı (Timeout) Yönetimi: Her görevin bir maksimum çalışma süresi olmalıdır. Sonsuz döngüye giren bir görev, sunucu kaynaklarını tüketebilir.
• Veritabanı Bağlantıları: Görevleriniz için ayrı bir veritabanı bağlantı havuzu (connection pool) kullanmayı düşünün.

Aşağıdaki örnekte, worker_threads kullanarak ana iş parçacığını bloklamadan nasıl ağır bir işlem yürütebileceğinizi görebilirsiniz:

const { Worker } = require('worker_threads');

function runHeavyTask() {
  return new Promise((resolve, reject) => {
    const worker = new Worker('./heavy-task-worker.js');
    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`));
    });
  });
}

// Cron içinde kullanımı
cron.schedule('0 2 * * *', async () => {
  console.log('Ağır görev başlatılıyor...');
  await runHeavyTask();
  console.log('Ağır görev tamamlandı.');
});

Bu yöntemle, uygulamanızın ana akışı aksamadan, arka planda yüksek performans gerektiren veri analizleri veya raporlama işlemlerini güvenle gerçekleştirebilirsiniz.

Sonuç

Node.js ile zamanlanmış görev çalıştırmak, uygulamalarınızı otomatize etmek ve verimliliği artırmak için güçlü bir yoldur. node-cron veya node-schedule kullanarak ihtiyaçlarınıza uygun çözümler geliştirebilirsiniz. Unutmayın, iyi bir zamanlanmış görev sistemi; izlenebilir, hata yönetimi yapılmış ve sistem kaynaklarını verimli kullanan yapıdır.

Bir sonraki adım olarak, zamanlanmış görevlerinizi Redis tabanlı kuyruk sistemleri olan BullMQ ile birleştirerek, görevlerin ölçeklenebilirliğini ve hata toleransını artırmayı araştırmanızı öneririm.