Node.js v8.7.0 文档


目录

net (网络)#

查看英文版 / 查看英文md文件 / 编辑中文md文件

稳定性: 2 - 稳定

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

通过以下方式引入:

const net = require('net');

IPC Support#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

Identifying paths for IPC connections#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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 类#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • 返回: <net.Server>

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

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

'close' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

'connection' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

'error' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

'listening' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

server.address()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

如果在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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • 返回: <net.Server>

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

返回 server

server.connections#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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)#

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • Returns <net.Server>

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

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

server.listen()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

为 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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

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

server.listen(options[, callback])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

如果指定了 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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

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

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

server.listening#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

server.maxConnections#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

一旦将一个套接字发送给[child process.fork()][]生成的子进程, 不推荐使用该选项。

server.ref()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • Returns: <net.Server>

对应的是unref,如果server是唯一的,那么在unref之前调用ref将不会让程序退出(这是默认行为)。如果server已经调用过ref再次调用ref将不会再有效果。

server.unref()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • Returns: <net.Server>

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

net.Socket 类#

查看英文版 / 查看英文md文件 / 编辑中文md文件

这个类是 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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Creates a new socket object.

  • options <Object> Available options are:
    • fd: <number> If specified, wrap around an existing socket with the given file descriptor, otherwise a new socket will be created.
    • allowHalfOpen <boolean> Indicates whether half-opened TCP connections are allowed. See net.createServer() and the 'end' event for details. Defaults to false.
    • readable <boolean> Allow reads on the socket when an fd is passed, otherwise ignored. Defaults to false.
    • writable <boolean> Allow writes on the socket when an fd is passed, otherwise ignored. Defaults to false.
  • Returns: <net.Socket>

The newly created socket can be either a TCP socket or a streaming IPC endpoint, depending on what it connect() to.

'close' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

  • had_error <boolean> true if the socket had a transmission error.

Emitted once the socket is fully closed. The argument had_error is a boolean which says if the socket was closed due to a transmission error.

'connect' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted when a socket connection is successfully established. See net.createConnection().

'data' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted when data is received. The argument data will be a Buffer or String. Encoding of data is set by socket.setEncoding(). (See the Readable Stream section for more information.)

Note that the data will be lost if there is no listener when a Socket emits a 'data' event.

'drain' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted when the write buffer becomes empty. Can be used to throttle uploads.

See also: the return values of socket.write()

'end' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted when the other end of the socket sends a FIN packet, thus ending the readable side of the socket.

By default (allowHalfOpen is false) the socket will send a FIN packet back and destroy its file descriptor once it has written out its pending write queue. However, if allowHalfOpen is set to true, the socket will not automatically end() its writable side, allowing the user to write arbitrary amounts of data. The user must call end() explicitly to close the connection (i.e. sending a FIN packet back).

'error' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted when an error occurs. The 'close' event will be called directly following this event.

'lookup' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted after resolving the hostname but before connecting. Not applicable to UNIX sockets.

'timeout' 事件#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Emitted if the socket times out from inactivity. This is only to notify that the socket has been idle. The user must manually close the connection.

See also: socket.setTimeout()

socket.address()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Returns the bound address, the address family name and port of the socket as reported by the operating system. Returns an object with three properties, e.g. { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize#

查看英文版 / 查看英文md文件 / 编辑中文md文件

net.Socket has the property that socket.write() always works. This is to help users get up and running quickly. The computer cannot always keep up with the amount of data that is written to a socket - the network connection simply might be too slow. Node.js will internally queue up the data written to a socket and send it out over the wire when it is possible. (Internally it is polling on the socket's file descriptor for being writable).

The consequence of this internal buffering is that memory may grow. This property shows the number of characters currently buffered to be written. (Number of characters is approximately equal to the number of bytes to be written, but the buffer may contain strings, and the strings are lazily encoded, so the exact number of bytes is not known.)

Users who experience large or growing bufferSize should attempt to "throttle" the data flows in their program with socket.pause() and socket.resume().

socket.bytesRead#

查看英文版 / 查看英文md文件 / 编辑中文md文件

The amount of received bytes.

socket.bytesWritten#

查看英文版 / 查看英文md文件 / 编辑中文md文件

The amount of bytes sent.

socket.connect()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Initiate a connection on a given socket.

Possible signatures:

This function is asynchronous. When the connection is established, the 'connect' event will be emitted. If there is a problem connecting, instead of a 'connect' event, an 'error' event will be emitted with the error passed to the 'error' listener. The last parameter connectListener, if supplied, will be added as a listener for the 'connect' event once.

socket.connect(options[, connectListener])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Initiate a connection on a given socket. Normally this method is not needed, the socket should be created and opened with net.createConnection(). Use this only when implementing a custom Socket.

For TCP connections, available options are:

  • port <number> Required. Port the socket should connect to.
  • host <string> Host the socket should connect to. Defaults to 'localhost'.
  • localAddress <string> Local address the socket should connect from.
  • localPort <number> Local port the socket should connect from.
  • family <number>: Version of IP stack, can be either 4 or 6. Defaults to 4.
  • hints <number> Optional dns.lookup() hints.
  • lookup <Function> Custom lookup function. Defaults to dns.lookup().

For IPC connections, available options are:

Returns socket.

socket.connect(path[, connectListener])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Initiate an IPC connection on the given socket.

Alias to socket.connect(options[, connectListener]) called with { path: path } as options.

Returns socket.

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

Initiate a TCP connection on the given socket.

Alias to socket.connect(options[, connectListener]) called with {port: port, host: host} as options.

Returns socket.

socket.connecting#

查看英文版 / 查看英文md文件 / 编辑中文md文件

If true - socket.connect(options[, connectListener]) was called and haven't yet finished. Will be set to false before emitting connect event and/or calling socket.connect(options[, connectListener])'s callback.

socket.destroy([exception])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Ensures that no more I/O activity happens on this socket. Only necessary in case of errors (parse error or so).

If exception is specified, an 'error' event will be emitted and any listeners for that event will receive exception as an argument.

socket.destroyed#

查看英文版 / 查看英文md文件 / 编辑中文md文件

A Boolean value that indicates if the connection is destroyed or not. Once a connection is destroyed no further data can be transferred using it.

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

Half-closes the socket. i.e., it sends a FIN packet. It is possible the server will still send some data.

If data is specified, it is equivalent to calling socket.write(data, encoding) followed by socket.end().

socket.localAddress#

查看英文版 / 查看英文md文件 / 编辑中文md文件

The string representation of the local IP address the remote client is connecting on. For example, in a server listening on '0.0.0.0', if a client connects on '192.168.1.1', the value of socket.localAddress would be '192.168.1.1'.

socket.localPort#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

socket.pause()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

socket.ref()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

socket.remotePort#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

socket.resume()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

socket.setEncoding([encoding])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Aliases to net.createConnection().

Possible signatures:

net.connect(options[, connectListener])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

net.connect(path[, connectListener])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

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

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

net.createConnection()#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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])#

查看英文版 / 查看英文md文件 / 编辑中文md文件

Creates a new TCP or IPC server.

  • options <Object>
    • allowHalfOpen <boolean> Default to false. Indicates whether half-opened TCP connections are allowed.
    • pauseOnConnect <boolean> Default to false. Indicates whether the socket should be paused on incoming connections.
  • 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)#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

net.isIPv4(input)#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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

net.isIPv6(input)#

查看英文版 / 查看英文md文件 / 编辑中文md文件

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