Node.js v8.x 中文文档


目录

net (网络)#

稳定性: 2 - 稳定

net 模块提供了创建基于流的 TCP 或 IPC 服务器(net.createServer())和客户端(net.createConnection()) 的异步网络 API。

通过以下方式引入:

const net = require('net');

IPC Support#

net 模块在 Windows 上支持命名管道 IPC,在其他操作系统上支持 UNIX 域套接字。

Identifying paths for IPC connections#

net.connect(), net.createConnection(), server.listen()socket.connect() 使用一个 path 参数来识别 IPC 端点。

在 UNIX 上,本地域也称为 UNIX 域。参数 path 是文件系统路径名。它被从 sizeof(sockaddr_un.sun_path) - 1 处被截断,其长度因操作系统不同而在 91 至 107 字节之间变化。典型值在 Linux 上为 107,在 macOS 上为 103。该路径受到与创建文件相同的命名约定和权限检查。它将在文件系统中可见,并且将持续到取消链接的时候。

在 Windows 上,本地域通过命名管道实现。路径必须是以 \\?\pipe\\\.\pipe\ 为入口。路径允许任何字符,但后面的字符可能会对管道名称进行一些处理,例如解析 .. 序列。尽管如此,管道空间是平面的。管道不会持续,当最后一次引用关闭时,管道就会被删除。不要忘了 JavaScript 字符串转义需要使用双反斜杠指定路径,例如:

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl'));

net.Server 类#

这个类用于创建 TCP 或 IPC server。

new net.Server([options][, connectionListener])#

  • 返回: <net.Server>

查看 net.createServer([options][, connectionListener]).

net.Server is an EventEmitter实现了以下事件:

'close' 事件#

当server关闭的时候触发. 注意,如果connections存在, 直到所有的connections结束才会触发这个事件

'connection' 事件#

当一个新的connection建立的时候触发. socket 是一个 net.Socket的实例对象.

'error' 事件#

当错误出现的时候触发. 不同与 net.Socket, 'close' 事件不会在这个事件触发后继续触发 除非 server.close() 是手动调用. 在 server.listen()中的例子.

'listening' 事件#

当服务被绑定后调用 server.listen().

server.address()#

如果在IP socket上监听,则返回绑定的ip地址, 地址族和操作系统报告的服务端口 在找到操作系统分配的地址时,找到指定的端口是有用的.返回一个有 port, family, 和 address 属性: { port: 12346, family: 'IPv4', address: '127.0.0.1' }的对象

对于在管道或UNIX域套接字上侦听的server,该名称将返回为字符串

例子:

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // handle errors here
  throw err;
});

// grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});

只有到了 'listening' 事件被触发时候.才可以调用 server.address()

server.close([callback])#

  • 返回: <net.Server>

停止 server接受建立新的connections并保持已经存在的connections.此功能是异步的,当所有的connections关闭同时server响应 'close'事件的时候,server将会最终关闭. 一旦'close'发生将会调用可选的回调函数. 与该事件不同, 如果服务器在关闭时未打开,则将使用错误作为唯一参数。

返回 server

server.connections#

Stability: 0 - Deprecated: Use server.getConnections() instead.

The number of concurrent connections on the server.

This becomes null when sending a socket to a child with child_process.fork(). To poll forks and get current number of active connections use asynchronous server.getConnections() instead.

server.getConnections(callback)#

  • Returns <net.Server>

异步获取服务器的当前并发连接数。当 socket 被传递给子进程时工作。

回调函数的两个参数是 err 和 count。

server.listen()#

为 connections 启动一个 server 监听. 一个 net.Server 可以是一个 TCP 或者 一个 IPC server,这取决于它监听什么。

可能的参数:

这个函数是异步的。当 server 开始监听,'listening' 事件会触发。最后一个参数 callback 将会被添加为'listening' 事件的监听器。

所有的 listen() 方法可以传入一个 backlog 参数来指定待连接队列的最大长度。 实际长度将通过 OS 的 sysctl 设置, 例如 linux 里的 tcp_max_syn_backlogsomaxconn。 这个参数的默认值是511 (不是512)

说明

  • 所有的 net.Socket 都被设置为 SO_REUSEADDR (详见 socket(7))

  • server.listen() 方法可能会被调用多次。每个后续的调用都将使用其提供的选项重新打开服务器。

监听时,其中一个最常见的错误是 EADDRINUSE。这是因为另一个 server 已经监听了该请求中的 port / path / handle。 处理这种情况的一种方法是在一定时间后重试:

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

server.listen(handle[, backlog][, callback])#

启动一个服务器,监听已经绑定到端口、UNIX 域套接字或 Windows 命名管道的给定句柄上的连接。

句柄对象可以是服务器、套接字(任何具有底层 _handle 成员的东西),也可以是具有 fd 成员的对象,该成员是一个有效的文件描述符。

注意:在Windows上不支持在文件描述符上进行监听。

server.listen(options[, callback])#

如果指定了 port 参数,该方法的行为跟 server.listen([port][, hostname][, backlog][, callback]) 一样。否则,如果指定了 path 参数,该方法的行为与 server.listen(path[, backlog][, callback]) 一致。如果没有 port 或者 path 参数,则会跑出一个错误。

如果 exclusivefalse(默认),则集群的所有进程将使用相同的底层句柄,允许共享连接处理任务。如果 exclusivetrue,则句柄不会被共享,如果尝试端口共享将导致错误。监听独立端口的例子如下。

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

server.listen(path[, backlog][, callback])#

启动一个 IPC 服务器监听给定 path 的连接。

server.listen([port][, host][, backlog][, callback])#

启动一个TCP服务监听输入的porthost

如果port省略或是0,系统会随意分配一个在'listening'事件触发后能被server.address().port检索的无用端口。

如果host省略,如果IPv6可用,服务器将会接收基于unspecified IPv6 address (::)的连接,否则接收基于unspecified IPv4 address (0.0.0.0)的连接

注意: 在大多数的系统, 监听unspecified IPv6 address (::)可能导致net.Server也监听unspecified IPv4 address (0.0.0.0).

server.listening#

一个布尔值, 表明 server 是否正在监听连接

server.maxConnections#

设置该属性使得当 server 连接数过多时拒绝连接。

一旦将一个 socket 发送给 child_process.fork() 生成的子进程,就不推荐使用该选项。

server.ref()#

  • Returns: <net.Server>

unref 相反,在一个已经调用 unref 的 server 中调用 ref,如果 server 是仅存的 server,则程序不会退出(默认)。对一个已经调用 ref 的 server 再次调用 ref 将不会再有效果。

server.unref()#

  • Returns: <net.Server>

如果这个server在事件系统中是唯一有效的,那么对server调用unref将允许程序退出。如果这个server已经调用过unref那么再次调用将不会再有效果。

net.Socket 类#

这个类是 TCP 或 UNIX Socket 的抽象(在Windows上使用命名管道,而UNIX使用域套接字)。一个net.Socket也是一个duplex stream,所以它能被读或写,并且它也是一个EventEmitter

net.Socket可以被用户创建并直接与server通信。举个例子,它是通过net.createConnection()返回的,所以用户可以使用它来与server通信。

当一个连接被接收时,它也能被Node.js创建并传递给用户。比如,它是通过监听在一个net.Server上的'connection'事件触发而获得的,那么用户可以使用它来与客户端通信。

new net.Socket([options])#

创建一个 socket 对象。

  • options <Object> 可用选项有:
    • fd: <number> 如果指定了该参数,则使用一个给定的文件描述符包装一个已存在的 socket,否则将创建一个新的 socket。
    • allowHalfOpen <boolean> 指示是否允许半打开的 TCP 连接。详情查看 net.createServer()'end' 事件。默认是 false
    • readable <boolean> 当传递了 fd 时允许读取 socket,否则忽略。默认 false
    • writable <boolean> 当传递了 fd 时允许写入 socket,否则忽略。默认 false
  • Returns: <net.Socket>

新创建的 socket 可以是 TCP socket 也可以是 IPC 端点流,取决于它连接 connect() 到什么。

'close' 事件#

  • had_error <boolean> 如果 socket 有传输错误就为 true。

一旦 socket 完全关闭就发出该事件。参数 had_error 是 boolean 类型,表明 socket 被关闭是否取决于传输错误。

'connect' 事件#

当一个 socket 连接成功建立的时候触发该事件。 查看 net.createConnection()

'data' 事件#

当接收到数据的时触发该事件。data 参数是一个 BufferString。数据编码由 socket.setEncoding() 设置。(在 Readable Stream 章节查看更多信息。)

注意当 Socket 发送 data 事件的时候,如果没有监听者数据将会丢失

'drain' 事件#

当写入缓冲区变为空时触发。可以用来做上传节流。

也可以查看:socket.write() 的返回值

'end' 事件#

当 socket 的另一端发送一个 FIN 包的时候触发,从而结束 socket 的可读端。

默认情况下(allowHalfOpenfalse),socket 将发送一个 FIN 数据包,并且一旦写出它的等待写入队列就销毁它的文件描述符。当然,如果 allowHalfOpentrue,socket 就不会自动结束 end() 它的写入端,允许用户写入任意数量的数据。用户必须调用 end() 显示地结束这个连接(例如发送一个 FIN 数据包。)

'error' 事件#

当错误发生时触发。'close' 事件也会紧接着该事件被触发。

'lookup' 事件#

在找到主机之后创建连接之前触发。不可用于 UNIX socket。

'timeout' 事件#

当 socket 超时的时候触发。该事件只是用来通知 socket 已经闲置。用户必须手动关闭。

也可以查看:socket.setTimeout()

socket.address()#

返回操作系统报告的 socket 的地址、地址族和端口。返回的对象有三个属性,例如: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize#

net.Socket 具有该属性,socket.write() 工作时需要。它可以帮助用户快速启动和运行。计算机(处理速度)不能总是跟上 socket 的写入速度 - 网络连接可能太慢了。 Node.js 内部将维护一个写入 socket 的数据队列,并在可能的时候将数据发送出去。(内部实现是对 socket 的文件描述符进行轮训其是否是可写状态。)

使用内部缓冲的结果是可能造成内存的增长。此属性显示当前即将被写入的缓冲的字符数。(字符串的数目大致等于即将被写入的字节,但缓冲可能包含字符串,而字符串是惰性编码的,所以实际的字节数是不知道的。)

对处理大量或持续增长的 bufferSize 有经验的用户应该注意使用 socket.pause() and socket.resume() 对他们程序中的数据流进行节流。

socket.bytesRead#

接收的字节数量。

socket.bytesWritten#

发送的字节数量。

socket.connect()#

在给定的套接字上启动一个连接。

可能的签名:

该方法是异步的。当连接建立了的时候,'connect' 事件将会被触发。如果连接过程中有问题,'error' 事件将会代替 'connect' 事件被触发,并将错误信息传递给 'error' 监听器。 最后一个参数 connectListener,如果指定了,将会被添加为 'connect' 事件的。

socket.connect(options[, connectListener])#

在给定的 socket 上初始化一个连接。通常该方法是不需要的,应该使用 net.createConnection() 来创建和打开 socket。一般只在实现一个自定义的 Socket 的时候使用该方法。

For TCP connections, available options are:

对于 TCP 连接可能的 options 有:

对于 IPC 连接可能的 options 有:

返回 socket.

socket.connect(path[, connectListener])#

在给定的 socket 上初始化 IPC

相当使用 { path: path } 作为 options 调用 socket.connect(options[, connectListener]) 方法的别名。

返回 socket

socket.connect(port[, host][, connectListener])#

在给定的 socket 上初始化一个 TCP 连接。

使用 {port: port, host: host} 作为 options 调用 socket.connect(options[, connectListener]) 方法的别名。

返回 socket

socket.connecting#

如果为 truesocket.connect(options[, connectListener]) 被调用但还未结束。当发送 connect 事件或调用 socket.connect(options[, connectListener]) 的回调函数的时候会被设置为 false

socket.destroy([exception])#

确保在该 socket 上不再有 I/O 活动。仅在出现错误的时候才需要(如解析错误等)。

如果制定了 exception,则将会触发一个 'error' 事件,任何监听器都将接收到 exception 作为一个参数。

socket.destroyed#

一个布尔值,用来指示连接是否已经被销毁。一旦连接被销毁就不能再使用它传输任何数据。

socket.end([data][, encoding])#

半关闭 socket。例如发送一个 FIN 包。服务端仍可以发送数据。

如果指定了 data,则相当于调用 socket.write(data, encoding) 之后再调用 socket.end()

socket.localAddress#

远程客户端连接的本地 IP 地址字符串。例如,一个服务端正在连接到 '0.0.0.0',客户端连接到的是 '192.168.1.1',则 socket.localAddress 的值是 '192.168.1.1'

socket.localPort#

The numeric representation of the local port. For example, 80 or 21.

socket.pause()#

Pauses the reading of data. That is, 'data' events will not be emitted. Useful to throttle back an upload.

socket.ref()#

Opposite of unref, calling ref on a previously unrefd socket will not let the program exit if it's the only socket left (the default behavior). If the socket is refd calling ref again will have no effect.

socket.remoteAddress#

The string representation of the remote IP address. For example, '74.125.127.100' or '2001:4860:a005::68'. Value may be undefined if the socket is destroyed (for example, if the client disconnected).

socket.remoteFamily#

The string representation of the remote IP family. 'IPv4' or 'IPv6'.

socket.remotePort#

The numeric representation of the remote port. For example, 80 or 21.

socket.resume()#

Resumes reading after a call to socket.pause().

socket.setEncoding([encoding])#

Set the encoding for the socket as a Readable Stream. See stream.setEncoding() for more information.

socket.setKeepAlive([enable][, initialDelay])#

Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. enable defaults to false.

Set initialDelay (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Setting 0 for initialDelay will leave the value unchanged from the default (or previous) setting. Defaults to 0.

socket.setNoDelay([noDelay])#

Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off. Setting true for noDelay will immediately fire off data each time socket.write() is called. noDelay defaults to true.

socket.setTimeout(timeout[, callback])#

Sets the socket to timeout after timeout milliseconds of inactivity on the socket. By default net.Socket do not have a timeout.

When an idle timeout is triggered the socket will receive a 'timeout' event but the connection will not be severed. The user must manually call socket.end() or socket.destroy() to end the connection.

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
});

If timeout is 0, then the existing idle timeout is disabled.

The optional callback parameter will be added as a one time listener for the 'timeout' event.

socket.unref()#

Calling unref on a socket will allow the program to exit if this is the only active socket in the event system. If the socket is already unrefd calling unref again will have no effect.

socket.write(data[, encoding][, callback])#

Sends data on the socket. The second parameter specifies the encoding in the case of a string--it defaults to UTF8 encoding.

Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in user memory. 'drain' will be emitted when the buffer is again free.

The optional callback parameter will be executed when the data is finally written out - this may not be immediately.

net.connect()#

Aliases to net.createConnection().

Possible signatures:

net.connect(options[, connectListener])#

Alias to net.createConnection(options[, connectListener]).

net.connect(path[, connectListener])#

Alias to net.createConnection(path[, connectListener]).

net.connect(port[, host][, connectListener])#

Alias to net.createConnection(port[, host][, connectListener]).

net.createConnection()#

A factory function, which creates a new net.Socket, immediately initiates connection with socket.connect(), then returns the net.Socket that starts the connection.

When the connection is established, a 'connect' event will be emitted on the returned socket. The last parameter connectListener, if supplied, will be added as a listener for the 'connect' event once.

Possible signatures:

Note: The net.connect() function is an alias to this function.

net.createConnection(options[, connectListener])#

For available options, see new net.Socket([options]) and socket.connect(options[, connectListener]).

Additional options:

Following is an example of a client of the echo server described in the net.createServer() section:

const net = require('net');
const client = net.createConnection({ port: 8124 }, () => {
  //'connect' listener
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});

To connect on the socket /tmp/echo.sock the second line would just be changed to

const client = net.createConnection({ path: '/tmp/echo.sock' });

net.createConnection(path[, connectListener])#

Initiates an IPC connection.

This function creates a new net.Socket with all options set to default, immediately initiates connection with socket.connect(path[, connectListener]), then returns the net.Socket that starts the connection.

net.createConnection(port[, host][, connectListener])#

Initiates a TCP connection.

This function creates a new net.Socket with all options set to default, immediately initiates connection with socket.connect(port[, host][, connectListener]), then returns the net.Socket that starts the connection.

net.createServer([options][, connectionListener])#

Creates a new TCP or IPC server.

  • options <Object>
    • allowHalfOpen <boolean> Indicates whether half-opened TCP connections are allowed. Default: false
    • pauseOnConnect <boolean> Indicates whether the socket should be paused on incoming connections. Default: false
  • connectionListener <Function> Automatically set as a listener for the 'connection' event.
  • Returns: <net.Server>

If allowHalfOpen is set to true, when the other end of the socket sends a FIN packet, the server will only send a FIN packet back when socket.end() is explicitly called, until then the connection is half-closed (non-readable but still writable). See 'end' event and RFC 1122 (section 4.2.2.13) for more information.

If pauseOnConnect is set to true, then the socket associated with each incoming connection will be paused, and no data will be read from its handle. This allows connections to be passed between processes without any data being read by the original process. To begin reading data from a paused socket, call socket.resume().

The server can be a TCP server or a IPC server, depending on what it listen() to.

Here is an example of an TCP echo server which listens for connections on port 8124:

const net = require('net');
const server = net.createServer((c) => {
  // 'connection' listener
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});

Test this by using telnet:

$ telnet localhost 8124

To listen on the socket /tmp/echo.sock the third line from the last would just be changed to

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});

Use nc to connect to a UNIX domain socket server:

$ nc -U /tmp/echo.sock

net.isIP(input)#

测试 input 是否是 IP 地址。无效的字符串则返回 0,IPv4 地址则返回 4,IPv6的地址则返回 6。

net.isIPv4(input)#

如果 input 是 IPv4 地址则返回 true,否则返回 false。

net.isIPv6(input)#

如果 input 是 IPv6 地址则返回 true,否则返回 false。