API 废弃系统

相关源文件

• benchmark/es/spread-assign.js
• benchmark/misc/util-extend-vs-object-assign.js
• benchmark/util/get-callsite.js
• doc/api/deprecations.md
• doc/api/process.md
• doc/api/util.md
• lib/internal/bootstrap/node.js
• lib/internal/process/per_thread.js
• lib/internal/util.js
• lib/util.js
• src/node_process_methods.cc
• src/node_util.cc
• test/fixtures/get-call-sites.js
• test/fixtures/tls-connect.js
• test/fixtures/typescript/ts/test-get-callsite-explicit.ts
• test/fixtures/typescript/ts/test-get-callsite.ts
• test/parallel/test-process-ref-unref.js
• test/parallel/test-util-getcallsite.js
• test/parallel/test-util-getcallsites.js
• test/parallel/test-util-styletext.js
• test/parallel/test-util.js

本文档描述了 Node.js 的 API 弃用系统，该系统用于标记 API 为已弃用、通知开发者已弃用的用法，并管理已弃用功能最终的移除。Node.js 采用系统化的方法来沟通 API 弃用，在保持向后兼容性的同时，为开发者提供清晰的迁移路径。

弃用类型和机制

Node.js 使用四种不同的弃用类型，每种类型都有不同的行为和对代码的影响。

弃用类型	描述	警告行为
仅文档化	仅在 API 文档中体现	无运行时警告
应用程序	适用于非 node_modules 的代码	首次使用时打印警告到 stderr
运行时	适用于所有代码	适用于所有代码（包括 node_modules）的警告
生命周期结束	功能已移除或即将移除	通常会导致运行时错误

在使用 --pending-deprecation 标志（或设置了 NODE_PENDING_DEPRECATION=1 环境变量）时，某些仅文档化的弃用可能会发出警告。

来源： lib/internal/util.js97-195 lib/util.js228-328

警告机制

util.deprecate() 函数是弃用系统的核心，它包装一个函数，并在该函数首次调用时发出警告。

来源： lib/util.js228-328 lib/internal/util.js154-195

util.deprecate() 函数接受三个参数：

• 被弃用的函数
• 警告消息
• 可选的弃用代码（例如 'DEP0001'）

当一个函数被标记为弃用时：

1. 它被包装在一个新函数中，该函数保留了其原始行为。
2. 第一次调用包装后的函数时，会发出弃用警告。
3. 警告包含提供的消息，如果适用，还包含弃用代码。
4. 原始函数会以保留所有参数和上下文的方式执行。

来源： lib/util.js228-328 lib/internal/util.js154-195

控制弃用警告

Node.js 提供了多个命令行标志和进程属性来控制如何处理弃用警告。

标志/属性	描述
--no-deprecation / process.noDeprecation = true	静默所有弃用警告
--throw-deprecation / process.throwDeprecation = true	将弃用作为警告而不是错误抛出
--trace-deprecation / process.traceDeprecation = true	显示带有弃用警告的堆栈跟踪
--pending-deprecation / NODE_PENDING_DEPRECATION=1	显示待定弃用的警告
--no-warnings	静默所有进程警告（包括弃用警告）

这些标志允许开发者控制其应用程序中弃用警告的可见性和影响。

来源： lib/util.js310-327 lib/internal/util.js97-127

弃用警告实现

弃用警告系统的实现主要在两个文件中：

1. lib/internal/util.js - 包含弃用机制的内部实现。
2. lib/util.js - 提供弃用系统的公共 API。

该系统会跟踪哪些弃用代码已经被警告过，以避免重复警告。

来源： lib/internal/util.js98-100 lib/internal/util.js104-127 lib/util.js228-328

当调用已弃用的函数时，系统会：

1. 检查是否禁用了弃用警告。
2. 如果弃用有代码，则检查该代码是否已被警告过。
3. 如果需要，使用 process.emitWarning() 发出警告。
4. 记录已发出警告。
5. 调用原始函数。

来源： lib/internal/util.js154-195 lib/util.js264-269

进程警告事件

弃用警告利用 Node.js 的警告系统，该系统会在 `process` 对象上发出 'warning' 事件。

来源： lib/internal/process/warning.js (代码提及暗示), doc/api/process.md587-706

弃用的警告对象包含：

• name: 'DeprecationWarning'
• message: 提供的弃用消息
• code: 弃用代码（如果提供）
• stack: 堆栈跟踪信息（使用 --trace-deprecation 时）

这使得应用程序可以以编程方式监控和处理弃用警告。

来源： doc/api/process.md587-706

使用弃用系统

可以使用 util.deprecate() 函数来标记你自己的函数为已弃用。

使用弃用系统的最佳实践：

1. 提供一个清晰的消息，解释 API 被弃用的原因。
2. 建议一个替代的 API 来替换。
3. 为每个弃用使用唯一的弃用代码。
4. 考虑为你的用例选择合适的弃用类型。

来源： lib/util.js248-262

弃用代码

Node.js 使用标准的弃用代码格式，以 'DEP' 开头，后跟一个四位数字（例如 'DEP0001'）。每个代码对应一个特定的已弃用 API 或功能。

弃用代码及其状态的完整列表维护在 Node.js 文档中。每个条目包含：

• 受影响的 API
• 何时被弃用
• 弃用原因
• 应使用什么替代
• 当前状态

代码绝不重复使用，即使弃用被撤销。

来源： doc/api/deprecations.md43-48 doc/api/deprecations.md52-1105

撤销弃用

偶尔，如果计划的移除被重新考虑，弃用可能会被撤销。在这种情况下：

1. 文档会更新以反映更改。
2. 弃用标识符不会被修改或重用。
3. API 继续按原样运行。

此过程可确保清晰度，同时保持弃用系统的完整性。

来源： doc/api/deprecations.md44-48

与 Node.js 内部机制集成

弃用系统已集成到 Node.js 的核心功能中。

在 Node.js 初始化期间，弃用系统会设置为尊重命令行标志和进程属性，确保它从执行开始就能正确运行。

来源： lib/internal/bootstrap/node.js341-342 lib/internal/util.js129-152

性能考量

弃用系统旨在最大程度地减少性能影响：

1. 每个弃用代码只发出一次警告。
2. 包装后的函数在首次调用后几乎没有额外的开销。
3. 通过标志禁用警告时，性能影响微乎其微。

这种设计确保了即使大量使用已弃用的 API，也不会显著影响应用程序的性能。

来源： lib/internal/util.js98-127 lib/util.js266-268