util.deprecate(fn, msg[, code])
fn
<Function> 被弃用的函数。msg
<string> 调用弃用的函数时显示的警告消息。code
<string> 弃用代码。 有关代码的列表,请参阅弃用的 API 列表。- 返回: <Function> 弃用的函数被封装以触发警告。
util.deprecate()
方法以标记为已弃用的方式封装 fn
(可能是函数或类)。
const util = require('util');
exports.obsoleteFunction = util.deprecate(() => {
// 在这里做点事情。
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
当调用时,util.deprecate()
将返回将使用 'warning'
事件触发 DeprecationWarning
的函数。
第一次调用返回的函数时,警告将触发并打印到 stderr
。
触发警告后,将调用封装的函数而不触发警告。
如果在多次调用 util.deprecate()
时提供了相同的可选 code
,则该 code
只会触发一次警告。
const util = require('util');
const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // 使用代码 DEP0001 触发弃用警告
fn2(); // 不触发弃用警告,因为它具有相同的代码
如果使用 --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-deprecation
和 process.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
.