网络

稳定性: 3 - 稳定

net模块提供了异步网络封装，该Node.js模块包含了创建服务器/客户端的方法（调用 streams），你可以通过调用 require('net') 包含这个模块，访问方法如下所示：

const net = require('net');

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

创建一个TCP服务器。参数connectionListener自动给'connection'事件创建监听器。

options包含有以下默认值：

{
  allowHalfOpen: false,
  pauseOnConnect: false
}

如果allowHalfOpen=true，当另一端socket发送FIN包时，socket不会自动发送FIN包。socket变为不可读，但仍可写。你需要显式的调用end()方法。更多信息参见'end'事件。

如果pauseOnConnect=true，当连接到来的时候相关联的socket将会暂停。它允许在初始进程不读取数据情况下，让连接在进程间传递。调用resume()从暂停的socket里读取数据。

下面是一个监听8124端口连接的应答服务器的例子：

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

使用telnet来测试：

telnet localhost 8124

要监听socket t/tmp/echo.sock，仅需要改倒数第三行代码，如下所示：

server.listen('/tmp/echo.sock', function() { //'listening' listener

使用nc连接到一个UNIX domain socket服务器：

nc -U /tmp/echo.sock

net.connect(options[, connectionListener])

net.createConnection(options[, connectionListener])

工厂方法，返回一个新的'net.Socket'，并连接到指定的地址和端口。

当socket建立的时候，将会触发'connect'事件。

和'net.Socket'有相同的方法。

对于TCP sockets，参数options因为下列参数的对象：

• port: 客户端连接到Port的端口（必须）。

• host: 客户端要连接到得主机。默认'localhost'.

• localAddress: 网络连接绑定的本地接口。

• localPort: 网络连接绑定的本地端口。

• family : IP栈版本。默认4。

对于本地域socket，参数options因为下列参数的对象：

• path: 客户端连接到得路径(必须).

通用选项:

• 如果allowHalfOpen=true， 当另一端socket发送FIN包时socket不会自动发送FIN包。socket变为不可读，但仍可写。你需要显式的调用end()方法。更多信息参见'end'事件。

  connectListener参数将会作为监听器添加到'connect'事件上。

下面是一个用上述方法应答服务器的客户端例子：

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

要连接到socket/tmp/echo.sock，仅需将第二行代码改为如下的内容：

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

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

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

创建一个到端口port和主机host的TCP连接。如果忽略主机host，则假定为'localhost'。参数connectListener将会作为监听器添加到'connect'事件。

这是工厂方法，返回一个新的'net.Socket'。

net.connect(path[, connectListener])

net.createConnection(path[, connectListener])

创建到path的unix socket连接。参数connectListener将会作为监听器添加到'connect'事件上。

这是工厂方法，返回一个新的'net.Socket'。

Class: net.Server

这个类用来创建一个TCP或本地服务器。

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

开始接受指定端口port和主机host的连接。如果忽略主机host， 服务器将会接受任何IPv4地址(INADDR_ANY)的直接连接。端口为0，则会分配一个随机端口。

积压量（Backlog）为连接等待队列的最大长度。实际长度由您的操作系统通过 sysctl 设定，比如 linux 上的tcp_max_syn_backlog 和 somaxconn。这个参数默认值是511(不是512)。

这是异步函数。当服务器被绑定时会触发'listening'事件。最后一个参数callback将会作为'listening'事件的监听器。

有些用户会遇到EADDRINUSE错误，它表示另外一个服务器已经运行在所请求的端口上。处理这个情况的办法是等一段事件再重试：

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

(注意：Node中的所有socket已设置了SO_REUSEADDR)

server.listen(path[, callback])

• path {String}
• callback {Function}

启动一个本地socket服务器，监听指定path的连接。

这是异步函数。绑定服务器后，会触发'listening'事件。最后一个参数callback将会作为'listening'事件的监听器。

UNIX上，本地域通常默认为UNIX域。参数path是文件系统路径，就和创建文件时一样，它也遵从命名规则和权限检查，并且在文件系统里可见，并持续到关闭关联。

Windows上，本地域通过命名管道实现。路径必须是以\\?\pipe\或\\.\pipe\入口。任意字符串都可以，不过之后进行相同的管道命名处理，比如解决..序列。管道命名空间是平的。管道不会一直持久，当最后一个引用关闭的时候，管道将会移除。不要忘记javascript字符字符串转义要求路径使用双反斜杠，比如：

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

server.listen(handle[, callback])

• handle {Object}

• callback {Function}

  handle 对象可以设置成server或socket（任意以下划线_handle开头的类），或者是{fd: <n>}对象。

这将是服务器用指定的句柄接收连接，前提是文件描述符或句柄已经绑定到端口或域socket。

Windows不支持监听文件句柄。

这是异步函数。当服务器已经被绑定，将会触发'listening'事件。最后一个参数callback将会作为'listening'事件的监听器。

server.listen(options[, callback])

• options {Object} - 必须有。支持以下属性：
  • port {Number} - 可选。
  • host {String} - 可选。
  • backlog {Number} - 可选。
  • path {String} - 可选。
  • exclusive {Boolean} - 可选。
• callback {Function} - 可选。

options的属性：端口port，主机host，和backlog，以及可选参数callback函数，他们在一起调用server.listen(port, [host], [backlog], [callback])。还有，参数path可以用来指定UNIX socket。

如果参数exclusive是false（默认值），集群进程将会使用同一个句柄，允许连接共享。当参数exclusive是true时，句柄不会共享，如果共享端口会返回错误。监听独家端口例子如下：

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

server.close([callback])

服务器停止接收新的连接，保持现有连接。这是异步函数，当所有连接结束的时候服务器会关闭，并会触发'close'事件。你可以传一个回调函数来监听'close' 事件。如果存在，将会调用回调函数，错误（如果有）作为唯一参数。

server.address()

操作系统返回绑定的地址，协议族名和服务器端口。查找哪个端口已经被系统绑定时，非常有用。返回的对象有3个属性，比如：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

例如：

var server = net.createServer(function (socket) {
  socket.end("goodbye\n");
});

// grab a random port.
server.listen(function() {
  address = server.address();
  console.log("opened server on %j", address);
});

在'listening'事件触发前，不要调用server.address()。

server.unref()

如果这是事件系统中唯一一个活动的服务器，调用unref将允许程序退出。如果服务器已被unref，则再次调用unref并不会产生影响。

server.ref()

与unref相反，如果这是唯一的服务器，在之前被unref了的服务器上调用ref将不会让程序退出（默认行为）。如果服务器已经被ref，则再次调用ref并不会产生影响。

server.maxConnections

设置这个选项后，当服务器连接数超过数量时拒绝新连接。

一旦已经用child_process.fork()方法将socket发送给子进程， 就不推荐使用这个选项。

server.connections

已经抛弃这个函数。请用server.getConnections()代替。服务器上当前连接的数量。

当调用child_process.fork()发送一个socket给子进程时，它将变为null。 要轮询子进程来获取当前活动连接的数量，请用server.getConnections代替。

server.getConnections(callback)

异步获取服务器当前活跃连接的数量。当socket发送给子进程后才有效；

回调函数有2个参数err和count。

net.Server是事件分发器EventEmitter， 有以下事件:

事件： 'listening'

当服务器调用server.listen绑定后会触发。

事件：'connection'

• {Socket object} 连接对象

当新连接创建后会被触发。socket是net.Socket实例。

事件： 'close'

服务器关闭时会触发。注意，如果存在连接，这个事件不会被触发直到所有的连接关闭。

事件： 'error'

• {Error Object}

发生错误时触发。'close'事件将被下列事件直接调用。请查看server.listen例子。

Class: net.Socket

这个对象是TCP或UNIX Socket的抽象。net.Socket实例实现了一个双工流接口。他们可以在用户创建客户端（使用connect()）时使用，或者由Node创建它们，并通过connection服务器事件传递给用户。

new net.Socket([options])

构造一个新的socket对象。

options对象有以下默认值：

{ fd: null
  allowHalfOpen: false,
  readable: false,
  writable: false
}

参数fd允许你指定一个存在的文件描述符。将readable和（或）writable设为true，允许在这个socket上读和（或）写（注意，仅在参数fd有效时）。关于allowHalfOpen，参见createServer()和'end'事件。

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

socket.connect(path[, connectListener])

使用传入的socket打开一个连接。如果指定了端口port和主机host，TCP socket将打开socket。如果忽略参数host，则默认为localhost。如果指定了 path，socket将会被指定路径的unix socket打开。

通常情况不需要使用这个函数，比如使用net.createConnection打开socket。只有你实现了自己的socket时才会用到。

这是异步函数。当'connect'事件被触发时，socket已经建立。如果这是问题连接，'connect'事件不会被触发，将会抛出'error'事件。

参数connectListener将会作为监听器添加到'connect'事件。

socket.bufferSize

socket.bufferSize是net.Socket的一个属性，用于socket.write()。它能够帮助用户获取更快的运行速度。计算机不能一直处于写入大量数据状态--网络连接可能太慢。Node在内部会将排队数据写入到socket，并在网络可用时发送。（内部实现：轮询socket的文件描述符直到变为可写）。

这种内部缓冲的缺点是会增加内存使用量。这个属性表示当前准备写的缓冲字符数。（字符的数量等于准备写入的字节的数量，但是缓冲区可能包含字符串，这些字符串是惰性编码的，所以准确的字节数还无法知道）。

遇到很大增长很快的bufferSize时，用户可用尝试用pause()和resume()来控制字符流。

socket.setEncoding([encoding])

设置socket的编码为可读流。更多信息参见stream.setEncoding()

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

在socket上发送数据。第二个参数指定了字符串的编码，默认是UTF8编码。

如果所有数据成功刷新到内核缓冲区，返回true。如果数据全部或部分在用户内存里，返回false。当缓冲区为空的时候会触发'drain'。

当数据最终被完整写入的的时候，可选的callback参数会被执行，但不一定会马上执行。

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

半关闭socket。例如，它发送一个FIN包。可能服务器仍在发送数据。

如果参数data不为空，等同于调用socket.write(data, encoding)后再调用socket.end()。

socket.destroy()

确保没有I/O活动在这个套接字上。只有在错误发生情况下才需要。（处理错误等等）。

socket.pause()

暂停读取数据。就是说，不会再触发data事件。对于控制上传非常有用。

socket.resume()

调用pause()后想恢复读取数据。

socket.setTimeout(timeout[, callback])

socket闲置时间超过timeout毫秒后 ，将socket设置为超时。

触发空闲超时事件时，socket将会收到'timeout'事件，但是连接不会被断开。用户必须手动调用end()或destroy()这个socket。

如果timeout= 0，那么现有的闲置超时会被禁用

可选的callback参数将会被添加成为'timeout'事件的一次性监听器。

socket.setNoDelay([noDelay])

禁用纳格（Nagle）算法。默认情况下TCP连接使用纳格算法，在发送前他们会缓冲数据。将noDelay设置为true将会在调用socket.write()时立即发送数据。noDelay默认值为true。

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

禁用/启用长连接功能，并在发送第一个在闲置socket上的长连接 probe 之前，可选地设定初始延时。默认为false。

设定initialDelay（毫秒），来设定收到的最后一个数据包和第一个长连接probe之间的延时。将initialDelay设为0，将会保留默认（或者之前）的值。默认值为0。

socket.address()

操作系统返回绑定的地址，协议族名和服务器端口。返回的对象有3个属性，比如{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

socket.unref()

如果这是事件系统中唯一一个活动的服务器，调用unref将允许程序退出。如果服务器已被unref，则再次调用unref并不会产生影响。

socket.ref()

与unref相反，如果这是唯一的服务器，在之前被unref了的服务器上调用ref将不会让程序退出（默认行为）。如果服务器已经被ref，则再次调用ref并不会产生影响。

socket.remoteAddress

远程的IP地址字符串，例如：'74.125.127.100'或者'2001:4860:a005::68'。

socket.remoteFamily

远程IP协议族字符串，比如'IPv4'或者'IPv6'。

socket.remotePort

远程端口，数字表示，例如：80或者21。

socket.localAddress

网络连接绑定的本地接口远程客户端正在连接的本地IP地址，字符串表示。例如，如果你在监听'0.0.0.0'而客户端连接在'192.168.1.1'，这个值就会是 '192.168.1.1'。

socket.localPort

本地端口地址，数字表示。例如：80或者21。

socket.bytesRead

接收到得字节数。

socket.bytesWritten

发送的字节数。

net.Socket是事件分发器EventEmitter的实例， 有以下事件：

事件： 'lookup'

在解析域名后，但在连接前，触发这个事件。对UNIX sokcet不适用。

• err {Error | Null} 错误对象。参见dns.lookup().
• address {String} IP地址。
• family {String | Null} 地址类型。参见dns.lookup().

事件： 'connect'

当成功建立socket连接时触发。参见connect()。

事件： 'data'

• {Buffer object}

当接收到数据时触发。参数data可以是Buffer或String。使用socket.setEncoding()设定数据编码。(更多信息参见Readable Stream)。

当Socket触发一个'data'事件时，如果没有监听器，数据将会丢失。

事件： 'end'

当socket另一端发送FIN包时，触发该事件。

默认情况下(allowHalfOpen == false)，一旦socket将队列里的数据写完毕，socket将会销毁它的文件描述符。如果allowHalfOpen == true，socket不会从它这边自动调用end()，使的用户可以随意写入数据，而让用户端自己调用end()。

事件： 'timeout'

当socket空闲超时时触发，仅是表明socket已经空闲。用户必须手动关闭连接。

参见：socket.setTimeout()

事件： 'drain'

当写缓存为空得时候触发。可用来控制上传。

参见：socket.write()的返回值。

事件： 'error'

• {Error object}

错误发生时触发。以下事件将会直接触发'close'事件。

事件： 'close'

• had_error {Boolean} 如果socket传输错误，为true

当socket完全关闭时触发。参数had_error是boolean，它表示是否因为传输错误导致socket关闭。

net.isIP(input)

测试是否输入的为IP地址。字符串无效时返回0。IPV4情况下返回4，IPV6情况下返回6.

net.isIPv4(input)

如果输入的地址为IPV4，返回true，否则返回false。

net.isIPv6(input)

如果输入的地址为IPV6，返回true，否则返回false。