开发手册 欢迎您！
软件开发者资料库

工具集 | Node.js

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境。Node.js 使用了一个事件驱动、非阻塞式 I/O 的模型，使其轻量又高效。Node.js 的包管理器 npm，是全球最大的开源库生态系统。

Node.js v8.x 中文文档

util (实用工具)#

稳定性: 2 - 稳定的

util 模块主要用于支持 Node.js 内部 API 的需求。大部分实用工具也可用于应用程序与模块开发者。它可以通过以下方式使用：

const util = require('util');

util.callbackify(original)#

新增于: v8.2.0
  • original async 异步函数
  • Returns: 传统回调函数

将 async 异步函数(或者一个返回值为 Promise 的函数)转换成遵循异常优先的回调风格的函数，例如将 (err, value) => ... 回调作为最后一个参数。在回调函数中, 第一个参数 err 为 Promise rejected 的原因 (如果 Promise 状态为 resolved , err为 null ),第二个参数则是 Promise 状态为 resolved 时的返回值.

例如 :

const util = require('util');async function fn() {  return 'hello world';}const callbackFunction = util.callbackify(fn);callbackFunction((err, ret) => {  if (err) throw err;  console.log(ret);});

将会打印出:

hello world

注意:

  • 回调函数是异步执行的, 并且有异常堆栈错误追踪. 如果回调函数抛出一个异常, 进程会触发一个 'uncaughtException' 异常, 如果没有被捕获, 进程将会退出.

  • null 在回调函数中作为一个参数有其特殊的意义, 如果回调函数的首个参数为 Promise rejected 的原因且带有返回值, 且值可以转换成布尔值 false, 这个值会被封装在 Error 对象里, 可以通过属性 reason 获取.

    function fn() {  return Promise.reject(null);}const callbackFunction = util.callbackify(fn);callbackFunction((err, ret) => {  // When the Promise was rejected with `null` it is wrapped with an Error and  // the original value is stored in `reason`.  err && err.hasOwnProperty('reason') && err.reason === null;  // true});

util.debuglog(section)#

新增于: v0.11.3
  • section 一个字符串，指定要为应用的哪些部分创建 debuglog 函数。debuglog 函数要为哪些应用创建。
  • 返回: 日志函数

util.debuglog() 方法用于创建一个函数，基于 NODE_DEBUG 环境变量的存在与否有条件地写入调试信息到 stderr。如果 section 名称在环境变量的值中，则返回的函数类似于 console.error()。否则，返回的函数是一个空操作。

例子：

const util = require('util');const debuglog = util.debuglog('foo');debuglog('hello from foo [%d]', 123);

如果程序在环境中运行时带上 NODE_DEBUG=foo，则输出类似如下： 

FOO 3245: hello from foo [123]

其中 3245 是进程 id。如果运行时没带上环境变量集合，则不会打印任何东西。

NODE_DEBUG 环境变量中可指定多个由逗号分隔的 section 名称。例如：NODE_DEBUG=fs,net,tls。

util.deprecate(function, string)#

新增于: v0.8.0

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

const util = require('util');exports.puts = util.deprecate(function() {  for (let i = 0, len = arguments.length; i < len; ++i) {    process.stdout.write(arguments[i] + '\n');  }}, 'util.puts: 使用 console.log 代替');

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

如果使用了 --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。

util.format(format[, ...args])#

版本历史
版本变更
v8.4.0

The %o and %O specifiers are supported now.

v0.5.3

新增于: v0.5.3

  • format 一个类似 printf 的格式字符串。

util.format() 方法返回一个格式化后的字符串，使用第一个参数作为一个类似 printf 的格式。

第一个参数是一个字符串，包含零个或多个占位符。每个占位符会被对应参数转换后的值所替换。支持的占位符有：

  • %s - 字符串。
  • %d - 数值（整数或浮点数）。
  • %i - Integer.
  • %f - Floating point value.
  • %j - JSON。如果参数包含循环引用，则用字符串 '[Circular]' 替换。
  • %o - Object. A string representation of an objectwith generic JavaScript object formatting.Similar to util.inspect() with options { showHidden: true, depth: 4, showProxy: true }.This will show the full object including non-enumerable symbols and properties.
  • %O - Object. A string representation of an objectwith generic JavaScript object formatting.Similar to util.inspect() without options.This will show the full object not including non-enumerable symbols and properties.
  • %% - 单个百分号（'%'）。不消耗参数。

如果占位符没有对应的参数，则占位符不被替换。

util.format('%s:%s', 'foo');// 返回: 'foo:%s'

如果传入 util.format() 方法的参数比占位符的数量多，则多出的参数会被强制转换为字符串，然后拼接到返回的字符串，参数之间用一个空格分隔。Excessive arguments whosetypeof is 'object' or 'symbol' (except null) will be transformed byutil.inspect().

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

如果第一个参数不是一个字符串，则 util.format() 返回一个所有参数用空格分隔并连在一起的字符串。每个参数都使用 util.inspect() 转换为一个字符串。

util.format(1, 2, 3); // '1 2 3'

If only one argument is passed to util.format(), it is returned as it iswithout any formatting.

util.format('%% %s'); // '%% %s'

util.inherits(constructor, superConstructor)#

版本历史
版本变更
v5.0.0

The constructor parameter can refer to an ES6 class now.

v0.3.0

新增于: v0.3.0

注意，不建议使用 util.inherits()。请使用 ES6 的 class 和 extends 关键词获得语言层面的继承支持。注意，这两种方式是语义上不兼容的。

  • constructor
  • superConstructor

从一个构造函数中继承原型方法到另一个。constructor 的原型会被设置到一个从 superConstructor 创建的新对象上。

superConstructor 可通过 constructor.super_ 属性访问。

const util = require('util');const EventEmitter = require('events');function MyStream() {  EventEmitter.call(this);}util.inherits(MyStream, EventEmitter);MyStream.prototype.write = function(data) {  this.emit('data', data);};const stream = new MyStream();console.log(stream instanceof EventEmitter); // trueconsole.log(MyStream.super_ === EventEmitter); // truestream.on('data', (data) => {  console.log(`接收的数据："${data}"`);});stream.write('运作良好！'); // 接收的数据："运作良好！"

例子：使用 ES6 的 class 和 extends：

const EventEmitter = require('events');class MyStream extends EventEmitter {  write(data) {    this.emit('data', data);  }}const stream = new MyStream();stream.on('data', (data) => {  console.log(`接收的数据："${data}"`);});stream.write('使用 ES6');

util.inspect(object[, options])#

版本历史
版本变更
v6.6.0

Custom inspection functions can now return this.

v6.3.0

The breakLength option is supported now.

v6.1.0

The maxArrayLength option is supported now; in particular, long arrays are truncated by default.

v6.1.0

The showProxy option is supported now.

v0.3.0

新增于: v0.3.0