deprecation 弃用
Node.js API 可能由于以下任何原因而被弃用:
- 该 API 的使用是不安全的。
- 改进的替代 API 可用。
- 预计在未来的主要版本中会对 API 进行重大更改。
Node.js 使用了三种弃用:
- 仅文档
- 运行时
- 生命结束
仅文档弃用是仅在 Node.js API 文档中表达的弃用。
这些在运行 Node.js 时不会产生副作用。
某些仅文档的弃用在使用 --pending-deprecation
标志(或其替代的 NODE_PENDING_DEPRECATION=1
环境变量)启动时会触发运行时警告,类似于下面的运行时弃用。
支持该标志的仅文档弃用在弃用的 API 列表中明确标记为此类。
默认情况下,运行时弃用将生成进程警告,该警告将在第一次使用弃用的 API 时打印到 stderr
。
当使用 --throw-deprecation
命令行标志时,运行时弃用将导致抛出错误。
当特性已经或即将从 Node.js 中删除时,使用生命结束的弃用。
Node.js APIs might be deprecated for any of the following reasons:
- Use of the API is unsafe.
- An improved alternative API is available.
- Breaking changes to the API are expected in a future major release.
Node.js uses three kinds of Deprecations:
- Documentation-only
- Runtime
- End-of-Life
A Documentation-only deprecation is one that is expressed only within the
Node.js API docs. These generate no side-effects while running Node.js.
Some Documentation-only deprecations trigger a runtime warning when launched
with --pending-deprecation
flag (or its alternative,
NODE_PENDING_DEPRECATION=1
environment variable), similarly to Runtime
deprecations below. Documentation-only deprecations that support that flag
are explicitly labeled as such in the
list of Deprecated APIs.
A Runtime deprecation will, by default, generate a process warning that will
be printed to stderr
the first time the deprecated API is used. When the
--throw-deprecation
command-line flag is used, a Runtime deprecation will
cause an error to be thrown.
An End-of-Life deprecation is used when functionality is or will soon be removed from Node.js.