Node.js Deprecation Uyarıları: DEP Kodları ve Bayraklar

Bir uyarı mesajını okumak

Aşağıdaki CommonJS betiği, belgelerde DEP0044 koduyla kullanımdan kaldırılmış util.isArray() fonksiyonunu çağırıyor. Program sorunsuz çalışıp bitiyor, ama stderr'e iki satır daha düşüyor.

// eski.cjs
const util = require('node:util');

console.log(util.isArray([1, 2]));
console.log('program devam ediyor');

// $ node eski.cjs
// çıktı: true
// çıktı: program devam ediyor
// çıktı (stderr): (node:PID) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
// çıktı (stderr): (Use `node --trace-deprecation ...` to show where the warning was created)

Mesajın parçaları şöyle: (node:PID) uyarıyı üreten sürecin kimliğidir ve her çalıştırmada değişir. Köşeli parantez içindeki DEP0044, uyarının code değeridir. Ardından gelen DeprecationWarning, uyarının türü yani name alanıdır. Geri kalanı açıklamadır ve çoğu zaman yerine kullanılacak API'yi de söyler. İkinci satır, uyarının hangi satırdan geldiğini görmek için bir bayrak önerir.

Dikkat ederseniz uyarı, console.log çıktılarından sonra görünüyor. Bunun iki nedeni var: uyarılar stdout yerine stderr'e yazılır, ayrıca denememizde uyarı senkron kod bittikten sonra yazdırıldı. Bu yüzden terminalde uyarının yeri, onu tetikleyen satırın yeri hakkında bir ipucu vermez; kaynağı bulmak için aşağıda anlatacağımız --trace-deprecation bayrağını kullanın.

Dört kullanımdan kaldırma türü

Belgeler her maddenin başına bir Type satırı koyar. Bu satır, uyarının ne zaman ve kime gösterileceğini belirler. Node.js dört tür kullanır ve bir madde zamanla bir türden diğerine geçebilir.

Listede iki ek durum da görürsünüz. "Deprecation revoked" kaldırma kararının geri alındığını gösterir; belgeye göre bu durumda madde kodu değişmez, yalnızca açıklama güncellenir. Örneğin eski URL API'sini kapsayan DEP0116 bu türdedir. Pending deprecation ise varsayılan olarak kapalı olan, ancak --pending-deprecation bayrağı veya NODE_PENDING_DEPRECATION=1 ortam değişkeniyle açılan bir erken uyarı mekanizmasıdır.

Bir maddenin geçmişi YAML bloğunda tutulur. Örneğin DEP0063 v8.0.0 ile belgede, v25.0.0 ile çalışma zamanında kullanımdan kaldırıldı ve v26.0.0 ile End-of-Life oldu. Bu sıra size bir zaman çizelgesi verir: Runtime aşamasında uyarı aldığınız bir API'yi ertelemeden değiştirmek, End-of-Life geldiğinde kodun kırılmasını önler. v26 ile değişen maddelerin listesini Node.js 26 yenilikleri yazısında topladık.

DEP kodunu belgede bulmak

Kodu öğrendikten sonra yapmanız gereken, nodejs.org/api/deprecations.html sayfasında o kodu aramaktır. Her madde aynı düzende yazılır: başlıkta kod ve konu, ardından sürüm geçmişi, Type satırı ve bir açıklama. Açıklama çoğu zaman alternatifi verir; DEP0005 için Buffer.alloc(), Buffer.allocUnsafe() ve Buffer.from() seçenekleri listelenir. Bazı maddelerde belge otomatik bir geçiş tarifi de gösterir; DEP0044 için önerilen komut npx codemod@latest @nodejs/util-is biçimindedir. Bu tür araçları çalıştırmadan önce değişiklikleri sürüm kontrolünde inceleyebileceğiniz bir dalda olun.

DEP0190 özellikle önemlidir: belgeye göre shell: true ile birlikte verilen argümanlar kaçışlanmaz, yalnızca boşlukla birleştirilir ve bu durum kabuk enjeksiyonuna yol açabilir. Güvenli alt süreç kullanımı için child_process: exec ve spawn, url.parse() yerine WHATWG URL kullanımı için URL ve URLSearchParams yazısına bakın.

Uyarıları yöneten bayraklar

Node.js uyarı davranışını değiştiren birkaç komut satırı bayrağı sunar. Hepsi NODE_OPTIONS içinde de kullanılabilir; ortam değişkeniyle bayrak verme ayrıntıları NODE_OPTIONS ve CLI bayrakları yazısında.

--trace-deprecation, "bu uyarı nereden geliyor" sorusunun cevabıdır. Aynı betiği bu bayrakla çalıştırdığımızda uyarının altına yığın izi eklenir ve ilk satır sizi doğrudan sorunlu çağrıya götürür.

$ node --trace-deprecation eski.cjs
true
program devam ediyor
(node:PID) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
    at Object.<anonymous> (/home/kullanici/proje/eski.cjs:3:18)
    at Module._compile (node:internal/modules/cjs/loader:1968:14)
    ...

Çıktıyı kısalttık; dosya yolunu da kendi bilgisayarımızdaki geçici klasör yerine nötr bir yolla değiştirdik. eski.cjs:3:18 kısmı 3. satırın 18. sütununu gösterir. Bir bağımlılıktan gelen uyarılarda yığın izinin ilk satırı node_modules içindeki bir dosyayı gösterecektir; bu durumda sorunu çözmek için o paketin güncel sürümüne bakmanız gerekir.

--throw-deprecation ise uyarıyı bir hataya dönüştürür. CI ortamında, kullanımdan kaldırılmış bir API'ye yeni bir bağımlılık eklenmesini engellemek için kullanışlıdır.

$ node --throw-deprecation eski.cjs
true
program devam ediyor
node:internal/process/warning:176
        throw warning;
        ^

DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
    at Object.<anonymous> (/home/kullanici/proje/eski.cjs:3:18)
    ...
  code: 'DEP0044'
}

Node.js v26.13.0
$ echo $?
1

Burada ince bir ayrıntı var: denememizde hata, util.isArray() çağrısının olduğu anda değil, senkron kod bittikten sonra fırlatıldı; bu yüzden "program devam ediyor" satırı hatadan önce yazıldı. Yani bu bayrak çağrıyı try/catch ile yakalanabilir bir hataya çevirmez, süreci 1 koduyla sonlandırır. Hata bir yakalanmamış istisna gibi davranır; bu konuyu uncaughtException ve unhandledRejection yazısında ele aldık.

--disable-warning v26.7.0 ile kararlı hâle geldi ve en hassas susturma yöntemidir. node --disable-warning=DEP0044 eski.cjs çalıştırıldığında yalnızca bu koddaki uyarı kaybolur, diğer kullanımdan kaldırmalar ve deneysel özellik uyarıları görünmeye devam eder. Bir türü tümüyle kapatmak isterseniz kod yerine tür adı verebilirsiniz; belgeye göre Node.js çekirdeğinin uyarı türleri DeprecationWarning ve ExperimentalWarning şeklindedir.

node_modules içindeki kod ve --pending-deprecation

Application türündeki maddeler, uyarıyı yalnızca kendi kodunuzda gösterir. DEP0005 bunun en bilinen örneğidir: projenizdeki bir dosyada new Buffer() kullanırsanız uyarı alırsınız, ama aynı çağrı bir bağımlılığın içindeyse varsayılan olarak sessiz kalınır. --pending-deprecation verildiğinde ise uyarı, kullanımın nerede olduğuna bakılmaksızın gösterilir.

// buf.cjs
const b = new Buffer(4);
console.log(b.length);

// $ node buf.cjs
// çıktı: 4
// çıktı (stderr): (node:PID) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
// çıktı (stderr): (Use `node --trace-deprecation ...` to show where the warning was created)

Bağımlılıklarınızın hangi eski API'leri kullandığını merak ediyorsanız test paketinizi bir kez --pending-deprecation --trace-deprecation ile çalıştırmak iyi bir başlangıçtır. Böylece hem belgede bekleyen maddeleri hem de node_modules içindeki kullanımları görürsünüz.

Uyarıları kod içinden yakalamak

Her süreç uyarısı process nesnesinde bir 'warning' olayı tetikler. Dinleyici name, message, stack ve kullanımdan kaldırmalarda code alanı olan bir nesne alır. Uyarıları kendi log sisteminize göndermek istediğinizde bu olayı kullanabilirsiniz.

// uyari.mjs
import util from 'node:util';

process.on('warning', (w) => {
  console.log('uyarı yakalandı:', w.name, w.code);
});

util.isArray([]);
util.isArray([]); // aynı kod ikinci kez uyarı üretmez

// çıktı (stderr): (node:PID) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.
// çıktı (stderr): (Use `node --trace-deprecation ...` to show where the warning was created)
// çıktı: uyarı yakalandı: DeprecationWarning DEP0044

Dinleyici eklemek varsayılan stderr çıktısını kapatmaz; ikisi birlikte çalışır. Belge, yalnızca kendi dinleyicinizin çalışmasını istiyorsanız --no-warnings kullanmayı gösteriyor: bu bayrak varsayılan çıktıyı susturur ama 'warning' olayı yine tetiklenir. Aynı kodun ikinci çağrısının uyarı üretmediğine de dikkat edin; Node.js her kullanımdan kaldırma kodunu süreç başına bir kez bildirir.

Bayrakların durumunu çalışma anında okumak için üç özellik vardır: process.noDeprecation, process.throwDeprecation ve process.traceDeprecation. Denememizde bayrak verilmediğinde bu özellikler false değil undefined döndü, bu yüzden kontrolü katı eşitlikle değil doğruluk değeriyle yapın.

// bayrak.mjs
console.log('noDeprecation:', process.noDeprecation);
console.log('throwDeprecation:', process.throwDeprecation);
console.log('traceDeprecation:', process.traceDeprecation);

// $ node --no-deprecation bayrak.mjs
// çıktı: noDeprecation: true
// çıktı: throwDeprecation: undefined
// çıktı: traceDeprecation: undefined

Kendi kütüphanenizde util.deprecate kullanmak

Bir paket yayımlıyorsanız eski bir fonksiyonu hemen silmek yerine önce uyarı vermek kullanıcılarınıza geçiş süresi tanır. util.deprecate(fn, mesaj, kod) verilen fonksiyonu sarar ve ilk çağrıda bir DeprecationWarning yayar, sonraki çağrılarda yalnızca fonksiyonu çalıştırır. Aynı kod birden fazla deprecate çağrısında kullanılırsa uyarı o kod için bir kez gösterilir.

// ozel.mjs
import { deprecate } from 'node:util';

const eskiTopla = deprecate(
  (a, b) => a + b,
  'eskiTopla() kullanımdan kaldırılacak, topla() kullanın.',
  'UYG001',
);

console.log(eskiTopla(2, 3));
console.log(eskiTopla(4, 5));

// çıktı: 5
// çıktı: 9
// çıktı (stderr): (node:PID) [UYG001] DeprecationWarning: eskiTopla() kullanımdan kaldırılacak, topla() kullanın.
// çıktı (stderr): (Use `node --trace-deprecation ...` to show where the warning was created)

Kendi kodlarınız için DEP öneki kullanmayın; DEP kodları Node.js çekirdeğine aittir ve listede başka bir anlam taşır. Bu tür uyarılar da aynı bayraklara uyar: --no-deprecation veya --no-warnings verildiğinde ya da ilk uyarıdan önce process.noDeprecation değeri true yapıldığında util.deprecate() hiçbir şey yapmaz. Daha genel bir uyarı için process.emitWarning() fonksiyonunu kullanabilirsiniz; belgeye göre --*-deprecation bayrakları yalnızca adı DeprecationWarning olan uyarıları etkiler. util modülünün diğer araçları için util.promisify ve util.inspect yazısına bakın.

Bir projede kullanımdan kaldırmaları adım adım temizlemek

Büyük bir kod tabanında uyarılarla tek tek uğraşmak yerine düzenli bir akış izlemek işinizi kolaylaştırır. Önce mevcut durumu görün: test paketinizi ya da uygulamanızı --trace-deprecation ve gerekirse --pending-deprecation ile bir kez çalıştırın, çıkan uyarıları --redirect-warnings=uyarilar.log ile bir dosyada toplayın. Belgeye göre bu dosya yoksa oluşturulur, varsa sonuna eklenir; göreli bir yol verirseniz --diagnostic-dir ile belirlenen dizine yazılır.

İkinci adımda uyarıları kaynağa göre ayırın. Yığın izinin ilk satırı kendi dosyalarınızı gösteriyorsa düzeltme sizdedir: belgede maddenin önerdiği alternatife geçin. node_modules içini gösteriyorsa paketin daha yeni bir sürümünün sorunu çözüp çözmediğine bakın. Üçüncü adımda türleri önceliklendirin: Runtime ve Application türleri bir sonraki ana sürümde End-of-Life olabileceği için önce bunları ele alın, Documentation-only maddeleri yeni kod yazarken dikkate alın.

Son adımda geri dönüşü engelleyin. Temizlik bittikten sonra CI komutunuza --throw-deprecation eklerseniz, birisi kullanımdan kaldırılmış bir API'yi yeniden kullandığında derleme başarısız olur. Bu bayrağı yerel geliştirmede açmak zorunda değilsiniz; NODE_OPTIONS ile yalnızca CI ortamında vermek de yeterlidir. Yükseltme sırasında karşılaştığınız yeni uyarıları geçici olarak susturmanız gerekirse, kod bazlı --disable-warning kullanın ve bunu bir iş kaydına bağlayın ki susturma kalıcı hâle gelmesin.

Sık yapılan hatalar

Her şeyi --no-warnings ile kapatmak. Bu bayrak yalnızca kullanımdan kaldırmaları değil, deneysel özellik ve bellek sızıntısı belirtisi olabilecek MaxListenersExceededWarning gibi uyarıları da gizler. Belirli bir uyarıyı susturmak gerekiyorsa --disable-warning=DEPxxxx kullanın.

Uyarının yerini çıktı sırasından tahmin etmek. Uyarılar stderr'e ve gecikmeli yazıldığı için terminaldeki konumu yanıltıcıdır. Kaynağı her zaman --trace-deprecation ile bulun.

--throw-deprecation hatasını try/catch ile yakalamaya çalışmak. Denememizde hata çağrının olduğu satırda değil, senkron kod bittikten sonra fırlatıldı; çağrının etrafındaki try/catch bunu yakalamaz.

Bağımlılıktaki uyarıyı kendi kodunuzda aramak. Yığın izinin ilk satırı node_modules içini gösteriyorsa çözüm, paketi güncellemek ya da paketin sorun kaydına bakmaktır; kendi kodunuzda değişiklik gerekmez.

End-of-Life maddeleri "sadece uyarı" sanmak. End-of-Life aşamasındaki API'ler çoğu zaman artık çalışmaz. Eski bir rehberdeki kodu kopyaladığınızda aldığınız hata bir TypeError veya ERR_* kodu olarak görünebilir; hata kodlarını ERR_MODULE_NOT_FOUND ve hata kodları yazısında anlattık.

Sık Sorulan Sorular

DeprecationWarning programımı durdurur mu?

Hayır. Uyarı stderr'e yazılır ve program çalışmaya devam eder. Yalnızca --throw-deprecation verilmişse ya da process.throwDeprecation doğru bir değere ayarlanmışsa uyarı hataya dönüşür.

Uyarıyı yalnızca üretimde gizlemek doğru mu?

Üretim loglarını kirletmemek için belirli bir kodu --disable-warning ile susturmak kabul edilebilir, ama asıl çözüm kodu güncellemektir. Geliştirme ve CI ortamında uyarıları açık bırakın, hatta --throw-deprecation ile hataya çevirin.

Bir kodun ne zaman kaldırılacağını nereden öğrenirim?

Belgeler kesin bir tarih vermez; maddenin geçmişindeki türler size gidişatı gösterir. End-of-Life kaydı bulunan bir madde ya kaldırılmıştır ya da yakında kaldırılacaktır.

Kullanımdan kaldırılmış bir API geri gelebilir mi?

Evet, nadiren olur. Belgeler bu durumda maddeyi "Deprecation revoked" olarak işaretler ve kodu değiştirmez; örneğin DEP0116 eski URL API'si için böyle bir geçmişe sahiptir.

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 öğrenme rehberi · Node.js 26 yenilikleri · NODE_OPTIONS ve CLI bayrakları · Node.js hata kodları · uncaughtException ve unhandledRejection