Node.js v11.5.0 API参考文档

Node.js®是基于Chrome的V8 JavaScript引擎构建的JavaScript运行时。

• 关于文档
• 用法和示例

断言测试

assert模块提供了一组简单的断言测试，可用于测试不变量。

存在strict和legacy模式，但建议仅使用strict模式。

有关使用的相等比较的更多信息，请参阅MDN关于相等比较和相同性的指南。

• assert.AssertionError类
• strict模式
• legacy模式
• assert(value[, message])
• assert.deepEqual(actual, expected[, message])
• assert.deepStrictEqual(actual, expected[, message])
• assert.doesNotReject(asyncFn, error)
• assert.doesNotThrow(fn, error)
• assert.equal(actual, expected[, message])
• assert.fail([message])
• assert.fail(actual, expected[, message[, operator[, stackStartFn]]]) 弃用
• assert.ifError(value)
• assert.notDeepEqual(actual, expected[, message])
• assert.notDeepStrictEqual(actual, expected[, message])
• assert.notEqual(actual, expected[, message])
• assert.notStrictEqual(actual, expected[, message])
• assert.ok(value[, message])
• assert.rejects(asyncFn, error)
• assert.strictEqual(actual, expected[, message])
• assert.throws(fn, error)

异步钩子

async_hooks模块提供了一个API来注册回调，跟踪Node.js应用程序内部创建的异步资源的生命周期，它可以使用以下方式访问：

const async_hooks = require('async_hooks');

异步资源表示具有关联回调的对象，可以多次调用此回调，例如，net.createServer()中的'connection'事件，或者只是fs.open()中的一次。在调用回调之前，也可以关闭资源，AsyncHook没有明确区分这些不同的情况，但会将它们表示为资源的抽象概念。

如果使用Worker，则每个线程都有一个独立的async_hooks接口，每个线程将使用一组新的异步ID。

• Public API
• Promise执行跟踪
• JavaScript Embedder API

Buffer

在引入TypedArray之前，JavaScript语言没有用于读取或操作二进制数据流的机制，Buffer类是作为Node.js API的一部分引入的，用于在TCP流、文件系统操作和其他上下文中与八位字节流进行交互。

Buffer类的实例类似于整数数组，但对应于V8堆外部的固定大小的原始内存分配，Buffer的大小在创建时建立，无法更改。

Buffer类在全局作用域内，因此不太可能需要使用require('buffer').Buffer。

// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);

// Creates a Buffer of length 10, filled with 0x1.
const buf2 = Buffer.alloc(10, 1);

// Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using either fill() or write().
const buf3 = Buffer.allocUnsafe(10);

// Creates a Buffer containing [0x1, 0x2, 0x3].
const buf4 = Buffer.from([1, 2, 3]);

// Creates a Buffer containing UTF-8 bytes [0x74, 0xc3, 0xa9, 0x73, 0x74].
const buf5 = Buffer.from('tést');

// Creates a Buffer containing Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
const buf6 = Buffer.from('tést', 'latin1');

• Buffer.from()，Buffer.alloc()和Buffer.allocUnsafe()
• 缓冲区和字符编码
• 缓冲区和TypedArray
• 缓冲区和迭代
• Buffer类
• buffer.INSPECT_MAX_BYTES
• buffer.kMaxLength
• buffer.transcode(source, fromEnc, toEnc)
• SlowBuffer类 弃用
• Buffer常量

C++扩展库

Node.js扩展库是动态链接的共享对象，用C++ 编写，可以使用require()函数加载到Node.js中，就像它们是普通的Node.js模块一样使用，它们主要用于提供Node.js中运行的JavaScript与C/C++库之间的接口。

目前，实现扩展库的方法相当复杂，涉及多个组件和API的知识：

• V8：Node.js目前用来提供JavaScript实现的C++库，V8提供了创建对象、调用函数等的机制，V8的API大多记录在v8.h头文件（Node.js源代码树中的deps/v8/include/v8.h）中，该文件也可在线获取。
• libuv：实现Node.js事件循环的C库，它工作线程和平台的所有异步行为，它还可以作为跨平台的抽象库，为所有主要操作系统提供简单的类似POSIX访问，以及许多常见的系统任务，例如与文件系统、sockets、定时器和系统事件的交互。libuv还提供类似并行线程的线程抽象，可用于驱动需要超越标准事件循环的更复杂的异步扩展库。鼓励扩展库作者考虑如何通过libuv将工作卸载到非阻塞系统操作，工作线程或libuv线程的自定义使用来避免使用I/O或其他时间密集型任务阻止事件循环。
• 内部Node.js库，Node.js本身导出了扩展库可以使用的许多C++ API - 其中最重要的是node::ObjectWrap类。
• Node.js包括许多其他静态链接库，包括OpenSSL，这些其他库位于Node.js源代码树的deps/目录中，Node.js只故意重新导出libuv、OpenSSL、V8和zlib symbols，并且可以通过扩展库在不同的范围内使用，有关其他信息，请参阅链接到Node.js自己的依赖项。

以下所有示例均可供下载，可用作扩展库的起点。

• Hello world
• Node.js原生抽象
• N-API
• 扩展库示例

C/C++插件 - N-API

N-API（在字母中发音为N，后跟API）是用于构建原生扩展库的API，它独立于底层JavaScript运行时（前V8），并作为Node.js本身的一部分进行维护，此API将是跨Node.js版本的应用程序二进制接口（ABI）稳定版，它旨在将扩展库与底层JavaScript引擎中的更改隔离开来，并允许为一个主要版本编译的模块在Node.js的后续主要版本上运行而无需重新编译，ABI稳定性指南提供了更深入的解释。

使用与C++扩展库一节中概述的相同方法/工具构建/打包扩展库，唯一的区别是原生代码使用的API集，不使用V8或Node.js原生抽象API，而是使用N-API中可用的功能。

N-API公开的API通常用于创建和操作JavaScript值，概念和操作通常映射到ECMA262语言规范中指定的想法，API具有以下属性：