Node.js Öğrenme Rehberi: Çalışma Ortamı ve API Yol Haritası

Bu rehber nasıl kullanılır?

Sıfırdan başlıyorsanız başlıkları yukarıdan aşağıya izleyin. Her başlık bir öncekinin üzerine kurulur: komut satırını ve process nesnesini bilmeden yazılan bir dosya işleme betiği çabuk karmaşıklaşır; olay döngüsünü anlamadan stream ve HTTP konuları da havada kalır. Belirli bir sorunu çözmek için geldiyseniz doğrudan ilgili başlığa geçebilirsiniz; her yazı kendi içinde tamamdır ve gerektiğinde serideki diğer yazılara bağlantı verir.

Node.js belgelerinde her özelliğin bir kararlılık etiketi vardır: 0 kullanımdan kaldırılmış, 1 deneysel (1.0 erken geliştirme, 1.1 aktif geliştirme, 1.2 sürüm adayı), 2 kararlı, 3 eski (legacy). Serideki yazılar deneysel bir özelliği anlatırken bunu ve gereken bayrağı açıkça belirtir. Örneğin node:sqlite 1.2 sürüm adayı, tek çalıştırılabilir dosya (SEA) özelliği ise 1.1 aktif geliştirme aşamasındadır. Bu etiketler sürümden sürüme değişebileceği için kendi kullandığınız sürümün belgesine bakma alışkanlığı edinin.

1. Başlangıç ve komut satırı

İlk adım Node.js'i kurmak ve node komutunu tanımaktır. Bu bölüm, bir betiği nasıl çalıştıracağınızı, programa nasıl argüman vereceğinizi, ayarları ortam değişkenleriyle nasıl taşıyacağınızı ve terminale nasıl düzgün çıktı yazacağınızı öğretir.

• Node.js kurulumu ve sürüm yöneticileri: Resmî indirme sayfasını, LTS ile Current ayrımının process.release ile nasıl görüldüğünü ve nvm, fnm gibi sürüm yöneticilerini anlatır. Sürüm değiştirince yerel eklentilerin neden bozulduğunu da açıklar.
• node komutuyla betik çalıştırma: node dosya.js, -e, -p, --check, shebang, --watch ve node --run ile package.json betiklerini çalıştırmayı gösterir.
• Node.js REPL kullanımı: Etkileşimli ortamın nokta komutlarını, _ değişkenini, üst düzey await'i ve node:repl ile özel REPL kurmayı öğretir.
• process.argv ve çıkış kodları: Komut satırı argümanlarını util.parseArgs ile ayrıştırmayı, process.exit ile exitCode farkını ve Node.js çıkış kodlarını anlatır.
• --env-file ve process.env: Ortam değişkenlerini ve ek paket olmadan .env dosyası yüklemeyi; --env-file, loadEnvFile ve parseEnv farklarını açıklar.
• console ve util.styleText: console metotlarını, stdout ile stderr ayrımını, biçim belirteçlerini ve terminalde renkli çıktıyı gösterir.

2. Modüller ve paketler

Node.js'te iki modül sistemi birlikte yaşar ve projelerin önemli bir kısmındaki kafa karışıklığı buradan çıkar. Bu bölüm, modüllerin nasıl yüklendiğini, package.json alanlarının ne işe yaradığını ve hemen her projede kullanılan temel yardımcı modülleri ele alır.

• CommonJS ve ESM farkı: Node.js'teki iki modül sistemini, .mjs ve .cjs uzantılarını, "type" alanını ve require(esm) ile birlikte çalışmayı anlatır.
• require ve module.exports: CommonJS'in ayrıntılarını; module.exports ile exports farkını, modül önbelleğini, çözümleme algoritmasını ve döngüsel bağımlılıkları açıklar.
• package.json exports ve imports: "main", "exports", koşullu dışa aktarımlar, # ile başlayan "imports" takma adları ve "engines" alanını öğretir.
• __dirname ve import.meta: ESM'de __dirname yokken import.meta.dirname, filename, url ve import.meta.resolve ile aynı bilgiyi almayı gösterir.
• path modülü: path.join, resolve, basename, extname, parse ve POSIX ile Windows yol farklarını anlatır.
• URL ve URLSearchParams: WHATWG URL API'sini, sorgu parametreleriyle çalışmayı ve dosya yolu ile URL arasında dönüşümü öğretir.
• os modülü ve sistem bilgisi: İşlemci, bellek, satır sonu karakteri, ev ve geçici klasör gibi sistem bilgilerini okumayı gösterir.

3. Dosya sistemi

Betiklerin çoğu bir noktada dosya okur ya da yazar. Bu bölüm node:fs modülünü parçalara ayırarak anlatır ve aynı işi yapmanın callback, senkron ve Promise tabanlı üç yolunu karşılaştırır.

• Dosya okuma: readFile: readFile, readFileSync ve fs.promises ile dosya okumayı, kodlama seçimini ve büyük dosyalarda stream'e geçmeyi anlatır.
• Dosya yazma: writeFile ve appendFile: writeFile ve appendFile ile yazmayı, w, a, wx gibi bayrakları ve güvenli yazma desenlerini öğretir.
• Klasör işlemleri: mkdir, readdir, rm: Klasör oluşturma, listeleme, silme, kopyalama, geçici klasör açma ve fs.glob ile desen eşlemeyi gösterir.
• fs.stat ve dosya var mı kontrolü: stat, lstat, access ve existsSync farkını, bir dosyanın varlığını kontrol etmenin doğru yolunu açıklar.
• fs.watch ile dosya izleme: fs.watch, fs.watchFile ve Promise tabanlı izlemeyi, platformlar arası davranış farklarıyla birlikte anlatır.
• fs promises, callback ve sync farkı: Üç API biçimini, FileHandle ve dosya tanımlayıcılarını karşılaştırır; hangi durumda hangisinin seçileceğini gösterir.

4. Asenkron çalışma ve olaylar

Node.js'in gücü, giriş-çıkış beklerken iş parçacığını bloklamayan olay tabanlı modelinden gelir. Bu bölüm dilin Promise ve async yapılarını değil, Node.js'e özgü parçaları anlatır; dil tarafı için Promise, async/await ve JavaScript event loop yazılarına bakın.

• EventEmitter kullanımı: on, once, off ve emit metotlarını, özel 'error' olayını ve dinleyici sınırlarını anlatır.
• process.nextTick ve setImmediate farkı: Node.js olay döngüsünün fazlarını ve nextTick, setImmediate, setTimeout(0) arasındaki sıralamayı açıklar.
• Zamanlayıcılar: setTimeout ve setInterval: Timeout nesnesinin ref, unref ve refresh metotlarını ve timers/promises API'sini öğretir.
• AbortController ile iptal ve zaman aşımı: AbortSignal.timeout ve AbortSignal.any ile dosya, zamanlayıcı, olay ve fetch işlemlerini iptal etmeyi gösterir.
• AsyncLocalStorage ile istek bağlamı: Bir isteğe ait bilgiyi asenkron çağrılar boyunca taşımayı ve async_hooks'un neden önerilmediğini anlatır.
• util.promisify ve inspect: Callback tabanlı fonksiyonları Promise'e çevirmeyi, inspect, format, types ve isDeepStrictEqual yardımcılarını öğretir.

5. Buffer, stream ve HTTP

İkili veri, akışlar ve ağ, Node.js'i sunucu tarafında güçlü kılan katmandır. Bu bölümü sırayla okumanızı öneririz: Buffer'ı bilmeden stream, stream'i bilmeden HTTP sunucusunun gövde okuma kısmı tam anlaşılmaz.

• Buffer kullanımı: Buffer.from ve alloc ile ikili veri oluşturmayı, utf8, base64 ve hex kodlamalarını ve Uint8Array ilişkisini anlatır.
• Stream nedir: Readable ve Writable: Okunabilir, yazılabilir, çift yönlü ve dönüştürücü akışları, olaylarını ve async iterator ile okumayı öğretir.
• stream.pipeline ve backpressure: Akışları güvenle birbirine bağlamayı, geri basıncı ve highWaterMark ayarını; pipe ile pipeline farkını açıklar.
• http modülü ile sunucu: Çatı kullanmadan node:http ile sunucu kurmayı, istek gövdesini okumayı ve durum kodlarını göstermeyi anlatır.
• fetch ile HTTP isteği: Global fetch ile GET ve JSON gövdeli POST isteği göndermeyi, zaman aşımı eklemeyi ve yanıt gövdesini akış olarak okumayı öğretir.
• zlib ile gzip ve brotli sıkıştırma: gzip, deflate, brotli ve zstd sıkıştırmayı stream ve Promise biçimleriyle, HTTP yanıtı örneğiyle birlikte gösterir.

6. Süreçler, ağ ve kriptografi

Bu bölüm Node.js'in işletim sistemiyle konuştuğu noktaları kapsar: başka programları çalıştırmak, CPU yoğun işleri ayrı thread'e taşımak, TCP bağlantıları kurmak, kullanıcıdan girdi almak ve verileri özetlemek ya da şifrelemek.

• child_process: exec ve spawn: exec, execFile, spawn ve fork farkını, Windows'taki .bat ve .cmd uyarısını ve kabuk güvenliğini anlatır.
• worker_threads kullanımı: Worker, parentPort, workerData, MessageChannel ve SharedArrayBuffer ile CPU yoğun işleri thread'lere dağıtmayı öğretir.
• net modülü ile TCP sunucu: net.createServer ve net.connect ile ham TCP bağlantıları, soket olayları ve IPC kanallarını anlatır.
• readline ile kullanıcı girdisi: readline/promises ile terminalden soru sormayı ve bir dosyayı satır satır okumayı gösterir.
• crypto: hash, HMAC ve randomUUID: createHash, hash(), createHmac, randomBytes, randomUUID ve zamanlamaya dayanıklı karşılaştırmayı öğretir.
• crypto ile AES-GCM şifreleme: AES-256-GCM ile şifreleme ve çözmeyi, IV ile doğrulama etiketinin rolünü ve scrypt ile anahtar türetmeyi anlatır. Parola saklama ayrı bir konudur: parola hashleme.

7. Araçlar: test, hata ayıklama, sqlite, izinler, paketleme

Node.js artık bir test çalıştırıcısı, hata ayıklayıcı, yerleşik SQLite modülü, izin modeli ve tek dosya paketleme gibi araçlarla birlikte gelir. Bu bölüm bu araçları kurulum gerektirmeden kullanmayı öğretir.

• node:test ile test yazma: test, describe ve it ile test yazmayı, node --test ile çalıştırmayı, hook'ları, filtrelemeyi ve raporlayıcıları anlatır.
• Mock ve kod kapsamı: mock.fn, mock.method, sahte zamanlayıcılar ve modül taklidi ile kod kapsamı raporu almayı gösterir.
• --inspect ve DevTools ile debug: --inspect ve --inspect-brk ile Chrome DevTools'a bağlanmayı, node inspect ve VS Code ile hata ayıklamayı öğretir.
• node:sqlite modülü: DatabaseSync ile veritabanı açmayı, hazırlanmış ifadeleri ve işlemleri anlatır; modülün sürüm adayı kararlılık etiketini açıklar. SQLite'ın kendisi için SQLite nedir.
• Permission model ve izinler: --permission ile dosya sistemi, alt süreç ve diğer erişimleri kısıtlamayı ve process.permission.has ile kontrol etmeyi gösterir.
• Tek çalıştırılabilir dosya (SEA): Bir Node.js uygulamasını tek bir çalıştırılabilir dosyaya paketlemeyi, yapılandırma dosyasını ve sınırları anlatır.

8. Sürüm ve sık hatalar

Son bölüm, bir sürüm yükseltirken ya da beklenmedik bir hata mesajıyla karşılaştığınızda başvuracağınız yazıları toplar. Hata kodlarıyla arama yapan okurlar için her yazı ilgili kodları başlıkta ve örneklerde gösterir.

• Node.js 26 yenilikleri: Belgelerde v26 sürümleriyle eklendiği ya da değiştiği kayıtlı olan API'leri ve kullanımdan kaldırma maddelerini derler.
• Deprecation uyarıları ve DEP kodları: DeprecationWarning mesajlarını, DEP kodlarını, kaldırma türlerini ve --throw-deprecation gibi bayrakları açıklar.
• NODE_OPTIONS ve CLI bayrakları: NODE_OPTIONS, bellek sınırı, kaynak haritaları, yapılandırma dosyası ve yığın izi uzunluğu gibi sık kullanılan ayarları anlatır.
• ERR_MODULE_NOT_FOUND ve hata kodları: ERR_MODULE_NOT_FOUND, ERR_REQUIRE_ESM ve ERR_INVALID_ARG_TYPE gibi Node.js hata kodlarını ve error.code ile ayırt etmeyi öğretir.
• EADDRINUSE, ENOENT ve sistem hataları: EADDRINUSE, ENOENT, EACCES, ECONNREFUSED gibi işletim sistemi hatalarının nedenlerini ve çözümlerini anlatır.
• uncaughtException ve unhandledRejection: Yakalanmamış hata ve reddedilmiş Promise olaylarını, --unhandled-rejections modlarını ve hata sınıflarını açıklar.

Önerilen çalışma planı

Seriyi yalnızca okumak yerine her yazıdaki örnekleri kendi makinenizde çalıştırmanızı öneririz. Yazılardaki örnekler yerleşik modüllerle yazıldı; hiçbirini çalıştırmak için npm paketi kurmanız gerekmez. Örnekleri .mjs uzantılı dosyalara kaydedip node dosya.mjs ile çalıştırabilirsiniz; CommonJS'i anlatan yazılarda .cjs kullanılır.

Bir uygulamayı sunucuya taşıma aşamasına geldiğinizde Dockerfile yazma rehberi ve systemd servis dosyası yazıları işinize yarar. Express tabanlı bir API yazıyorsanız Express middleware deseni, Jest ile test yazıyorsanız Jest unit testing rehberi, gerçek zamanlı iletişim için WebSocket ve SSE karşılaştırması yazısına bakabilirsiniz.

Sık Sorulan Sorular

Node.js öğrenmek için ne kadar JavaScript bilmem gerekir?

Değişkenler, fonksiyonlar, nesneler ve diziler gibi temellerin yanında Promise ve async/await'i bilmeniz yeterli bir başlangıçtır. Bu konuları JavaScript öğrenme rehberinde sırayla bulabilirsiniz.

Hangi Node.js sürümünü kullanmalıyım?

Seri Node.js v26.13.0 belgelerine göre yazıldı. Üretim için LTS hattı önerilir; ayrıntılar ve sürüm doğrulama yöntemleri kurulum yazısında.

TypeScript ile yazıyorum, bu seri işime yarar mı?

Evet. Anlatılan API'ler TypeScript'te de aynıdır. TypeScript dosyalarını Node.js'te çalıştırmayı TypeScript ile Node.js yazısında anlattık.

Yazılar hangi işletim sisteminde denendi?

Örnekler Windows üzerinde Node.js v26.13.0 ile çalıştırıldı. Yol ayırıcıları, sinyaller ve dosya izleme gibi platforma göre değişen davranışlar yazılarda belgelere dayanarak ayrıca belirtilir; çıktılardaki yerel yollar Linux biçiminde kısaltıldı.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Node.js nedir · JavaScript öğrenme rehberi · TypeScript öğrenme rehberi · Node.js REST API · cluster ve PM2