util.deprecate(fn, msg[, code])


  • fn <Function> The function that is being deprecated.
  • msg <string> A warning message to display when the deprecated function is invoked.
  • code <string> A deprecation code. See the list of deprecated APIs for a list of codes.
  • Returns: <Function> The deprecated function wrapped to emit a warning.

util.deprecate() 方法会包装给定的 function 或类,并标记为废弃的。

const util = require('util');

exports.obsoleteFunction = util.deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');

当被调用时, util.deprecate() 会返回一个函数,这个函数会使用 process.on('warning') 事件触发一个 DeprecationWarning。 默认情况下,警告只在首次被调用时才会被触发并打印到 stderr。 警告被触发之后,被包装的 function 会被调用。

const util = require('util');

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // emits a deprecation warning with code DEP0001
fn2(); // does not emit a deprecation warning because it has the same code

如果使用了 --no-deprecation--no-warnings 命令行标记,或 process.noDeprecation 属性在首次废弃警告之前被设为 true,则 util.deprecate() 方法什么也不做。

如果设置了 --trace-deprecation--trace-warnings 命令行标记,或 process.traceDeprecation 属性被设为 true,则废弃的函数首次被调用时会把警告与堆栈追踪打印到 stderr

如果设置了 --throw-deprecation 命令行标记,或 process.throwDeprecation 属性被设为 true,则当废弃的函数被调用时会抛出一个异常。

--throw-deprecation 命令行标记和 process.throwDeprecation 属性优先于 --trace-deprecationprocess.traceDeprecation

  • fn <Function> The function that is being deprecated.
  • msg <string> A warning message to display when the deprecated function is invoked.
  • code <string> A deprecation code. See the list of deprecated APIs for a list of codes.
  • Returns: <Function> The deprecated function wrapped to emit a warning.

The util.deprecate() method wraps fn (which may be a function or class) in such a way that it is marked as deprecated.

const util = require('util');

exports.obsoleteFunction = util.deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');

When called, util.deprecate() will return a function that will emit a DeprecationWarning using the 'warning' event. The warning will be emitted and printed to stderr the first time the returned function is called. After the warning is emitted, the wrapped function is called without emitting a warning.

If the same optional code is supplied in multiple calls to util.deprecate(), the warning will be emitted only once for that code.

const util = require('util');

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // emits a deprecation warning with code DEP0001
fn2(); // does not emit a deprecation warning because it has the same code

If either the --no-deprecation or --no-warnings command line flags are used, or if the process.noDeprecation property is set to true prior to the first deprecation warning, the util.deprecate() method does nothing.

If the --trace-deprecation or --trace-warnings command line flags are set, or the process.traceDeprecation property is set to true, a warning and a stack trace are printed to stderr the first time the deprecated function is called.

If the --throw-deprecation command line flag is set, or the process.throwDeprecation property is set to true, then an exception will be thrown when the deprecated function is called.

The --throw-deprecation command line flag and process.throwDeprecation property take precedence over --trace-deprecation and process.traceDeprecation.