# net
~~~
穩(wěn)定度: 3 - 穩(wěn)定
~~~
The `net` module provides you with an asynchronous network wrapper. It contains methods for creating both servers and clients (called streams). You can include this module with `require('net');`
### net.createServer([options], [connectionListener])
創(chuàng)建一個(gè)新的 TCP 服務(wù)器。參數(shù) `connectionListener` 會(huì)被自動(dòng)作為 ['connection'](#) 事件的監(jiān)聽(tīng)器。
`options` 是一個(gè)包含下列缺省值的對(duì)象：
~~~
{ allowHalfOpen: false
}
~~~
如果允許半開(kāi)連接 `allowHalfOpen` 被設(shè)置為 `true`，則當(dāng)另一端的套接字發(fā)送 FIN 報(bào)文時(shí)套接字并不會(huì)自動(dòng)發(fā)送 FIN 報(bào)文。套接字會(huì)變?yōu)椴豢勺x，但仍然可寫。您應(yīng)當(dāng)明確地調(diào)用 `end()` 方法。詳見(jiàn) ['end'](#) 事件。
下面是一個(gè)監(jiān)聽(tīng) 8124 端口連接的應(yīng)答服務(wù)器的例子：
~~~
var net = require('net');
var server = net.createServer(function(c) { // 'connection' 監(jiān)聽(tīng)器
console.log('服務(wù)器已連接');
c.on('end', function() {
console.log('服務(wù)器已斷開(kāi)');
});
c.write('hello\r\n');
c.pipe(c);
});
server.listen(8124, function() { // 'listening' 監(jiān)聽(tīng)器
console.log('服務(wù)器已綁定');
});
~~~
使用 `telnet` 測(cè)試：
~~~
telnet localhost 8124
~~~
要監(jiān)聽(tīng)套接字 `/tmp/echo.sock` 僅需更改倒數(shù)第三行代碼：
~~~
server.listen('/tmp/echo.sock', function() { // 'listening' 監(jiān)聽(tīng)器
~~~
使用 `nc` 連接到一個(gè) UNIX domain 套接字服務(wù)器：
~~~
nc -U /tmp/echo.sock
~~~
### net.connect(options, [connectionListener])
### net.createConnection(options, [connectionListener])
構(gòu)建一個(gè)新的套接字對(duì)象并打開(kāi)所給位置的套接字。當(dāng)套接字就緒時(shí)會(huì)觸發(fā) ['connect'](#) 事件。
對(duì)于 TCP 套接字，選項(xiàng) `options` 參數(shù)應(yīng)為一個(gè)指定下列參數(shù)的對(duì)象：
- `port`：客戶端連接到的端口（必須）
- `host`：客戶端連接到的主機(jī)，缺省為 `'localhost'`
- `localAddress`：網(wǎng)絡(luò)連接綁定的本地接口
- `family`：IP 棧版本，缺省為 `4`
對(duì)于 UNIX domain 套接字，選項(xiàng) `options` 參數(shù)應(yīng)當(dāng)為一個(gè)指定下列參數(shù)的對(duì)象：
- `path`：客戶端連接到的路徑（必須）
通用選項(xiàng)：
- `allowHalfOpen`：允許半開(kāi)連接，如果被設(shè)置為 `true`，則當(dāng)另一端的套接字發(fā)送 FIN 報(bào)文時(shí)套接字并不會(huì)自動(dòng)發(fā)送 FIN 報(bào)文。缺省為 `false`。詳見(jiàn) ['end'](#) 事件。
`connectListener` 用于 ['connect'](#) 事件的監(jiān)聽(tīng)器
下面是一個(gè)上述應(yīng)答服務(wù)器的客戶端的例子：
~~~
var net = require('net');
var client = net.connect({port: 8124},
function() { //'connect' 監(jiān)聽(tīng)器
console.log('client connected');
client.write('world!\r\n');
});
client.on('data', function(data) {
console.log(data.toString());
client.end();
});
client.on('end', function() {
console.log('客戶端斷開(kāi)連接');
});
~~~
要連接到套接字 `/tmp/echo.sock`，僅需將第二行改為
~~~
var client = net.connect({path: '/tmp/echo.sock'},
~~~
### net.connect(port, [host], [connectListener])
### net.createConnection(port, [host], [connectListener])
創(chuàng)建一個(gè) `host` 主機(jī) `port` 端口的 TCP 連接。如果省略 `host` 則假定為 `'localhost'`。`connectListener` 參數(shù)會(huì)被用作 ['connect'](#) 事件的監(jiān)聽(tīng)器。
### net.connect(path, [connectListener])
### net.createConnection(path, [connectListener])
創(chuàng)建一個(gè)到路徑 `path` 的 UNIX 套接字連接。`connectListener` 參數(shù)會(huì)被用作 ['connect'](#) 事件的監(jiān)聽(tīng)器。
### 類: net.Server
該類用于創(chuàng)建一個(gè) TCP 或 UNIX 服務(wù)器。服務(wù)器本質(zhì)上是一個(gè)可監(jiān)聽(tīng)傳入連接的 `net.Socket`。
### server.listen(port, [host], [backlog], [callback])
在指定端口 `port` 和主機(jī) `host` 上開(kāi)始接受連接。如果省略 `host` 則服務(wù)器會(huì)接受來(lái)自所有 IPv4 地址（`INADDR_ANY`）的連接；端口為 0 則會(huì)使用分隨機(jī)分配的端口。
積壓量 `backlog` 為連接等待隊(duì)列的最大長(zhǎng)度。實(shí)際長(zhǎng)度由您的操作系統(tǒng)通過(guò) sysctl 設(shè)置決定，比如 Linux 上的 `tcp_max_syn_backlog` 和 `somaxconn`。該參數(shù)缺省值為 511（不是 512）。
這是一個(gè)異步函數(shù)。當(dāng)服務(wù)器已被綁定時(shí)會(huì)觸發(fā) ['listening'](#) 事件。最后一個(gè)參數(shù) `callback` 會(huì)被用作 ['listening'](#) 事件的監(jiān)聽(tīng)器。
有些用戶會(huì)遇到的情況是遇到 'EADDINUSE' 錯(cuò)誤。這表示另一個(gè)服務(wù)器已經(jīng)運(yùn)行在所請(qǐng)求的端口上。一個(gè)處理這種情況的方法是等待一段時(shí)間再重試
~~~
server.on('error', function (e) {
if (e.code == 'EADDRINUSE') {
console.log('地址被占用，重試中...');
setTimeout(function () {
server.close();
server.listen(PORT, HOST);
}, 1000);
}
});
~~~
（注意：Node 中的所有套接字已設(shè)置了 `SO_REUSEADDR`）
### server.listen(path, [callback])
啟動(dòng)一個(gè) UNIX 套接字服務(wù)器在所給路徑 `path` 上監(jiān)聽(tīng)連接。
這是一個(gè)異步函數(shù)。當(dāng)服務(wù)器已被綁定時(shí)會(huì)觸發(fā) ['listening'](#) 事件。最后一個(gè)參數(shù) `callback` 會(huì)被用作 ['listening'](#) 事件的監(jiān)聽(tīng)器。
### server.listen(handle, [callback])
- `handle`處理器 {Object}
- `callback`回調(diào)函數(shù) {Function}
`handle` 變量可以被設(shè)置為server 或者 socket(任一以下劃線開(kāi)頭的成員 `_handle`), 或者一個(gè) `{fd: <n>}` 對(duì)象
這將使服務(wù)器用指定的句柄接受連接，但它假設(shè)文件描述符或者句柄已經(jīng)被綁定在特定的端口或者域名套接字。
Windows 不支持監(jiān)聽(tīng)一個(gè)文件描述符。
這是一個(gè)異步函數(shù)。當(dāng)服務(wù)器已被綁定時(shí)會(huì)觸發(fā) ['listening'](#) 事件。最后一個(gè)參數(shù) `callback` 會(huì)被用作 ['listening'](#) 事件的監(jiān)聽(tīng)器。
### server.close([callback])
用于停止服務(wù)器接受新連接，但保持已存在的連接。這是一個(gè)異步函數(shù)， 服務(wù)器將在所有的連接都結(jié)束后關(guān)閉，并且服務(wù)器發(fā)送 `'close'`事件 你可以有選擇的傳入回調(diào)函數(shù)來(lái)監(jiān)聽(tīng) `'close'`事件。
### server.address()
返回操作系統(tǒng)報(bào)告的綁定的地址，協(xié)議族和端口。 對(duì)查找操作系統(tǒng)分配的地址哪個(gè)端口已被分配非常有用， 如. `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
實(shí)例：
~~~
// 獲得隨機(jī)端口
server.listen(function() {
address = server.address();
console.log("opened server on %j", address);
});
~~~
在 `'listening'` 事件發(fā)生前請(qǐng)勿調(diào)用 `server.address()`。
### server.unref()
如果這是事件系統(tǒng)中唯一一個(gè)活動(dòng)的服務(wù)器，調(diào)用 `unref` 將允許程序退出。如果服務(wù)器已被 `unref`，則再次調(diào)用 `unref` 并不會(huì)產(chǎn)生影響。
### server.ref()
與 `unref` 相反，如果這是僅剩的服務(wù)器，在一個(gè)之前被 `unref` 了的服務(wù)器上調(diào)用 `ref` 將不會(huì)讓程序退出（缺省行為）。如果服務(wù)器已經(jīng)被 `ref`，則再次調(diào)用 `ref` 并不會(huì)產(chǎn)生影響。
### server.maxConnections
設(shè)置這個(gè)選項(xiàng)能在當(dāng)服務(wù)器連接數(shù)超過(guò)數(shù)量時(shí)拒絕連接。
這個(gè)選項(xiàng)不推薦使用在套接字已經(jīng)用 `child_process.fork()`發(fā)送給子進(jìn)程。
### server.connections
這個(gè)函數(shù)已被 **廢棄**; 請(qǐng)用 [server.getConnections()][] 代替. 服務(wù)器的當(dāng)前活動(dòng)連接的數(shù)量。
當(dāng)用`child_process.fork()`發(fā)送一個(gè)套接字給子進(jìn)程時(shí)，它將是 `null` 。 要輪詢子進(jìn)程來(lái)獲取當(dāng)前活動(dòng)的連接請(qǐng)用 `server.getConnections` 代替.
`net.Server` 是一個(gè)包含下列事件的 [EventEmitter](#) :
### server.getConnections(callback)
異步獲取服務(wù)器當(dāng)前活躍的連接數(shù). 用于套接字唄發(fā)送給子進(jìn)程。
回調(diào)函數(shù)需要兩個(gè)參數(shù) `err` 和 `count`.
### 事件: 'listening'
在服務(wù)器調(diào)用 `server.listen`綁定后觸發(fā)。
### 事件: 'connection'
- {Socket object} 連接對(duì)象
在一個(gè)新連接被創(chuàng)建時(shí)觸發(fā)。 `socket` 是一個(gè)`net.Socket`的實(shí)例。
### 事件: 'close'
當(dāng)服務(wù)被關(guān)閉時(shí)觸發(fā). 注意：如果當(dāng)前仍有活動(dòng)連接，他個(gè)事件將等到所有連接都結(jié)束后才觸發(fā)。
### 事件: 'error'
- {Error Object}
當(dāng)一個(gè)錯(cuò)誤發(fā)生時(shí)觸發(fā)。 `'close'` 事件將直接被下列時(shí)間調(diào)用。 請(qǐng)查看討論 `server.listen`的例子。
### 類: net.Socket
這個(gè)對(duì)象是一個(gè)TCP或UNIX套接字的抽象。 `net.Socket` 實(shí)例實(shí)現(xiàn)了一個(gè)雙工流接口。 他們可以被用戶使用在客戶端(使用 `connect()`) 或者它們可以由 Node創(chuàng)建，并通過(guò) `'connection'`服務(wù)器事件傳遞給用戶。
### new net.Socket([options])
構(gòu)造一個(gè)新的套接字對(duì)象。
`options` 是一個(gè)包含下列缺省值的對(duì)象：
~~~
{ fd: null
type: null
allowHalfOpen: false
}
~~~
`fd` 允許你指定一個(gè)存在的文件描述符和套接字。 `type` 指定一個(gè)優(yōu)先的協(xié)議。 他可以是 `'tcp4'`, `'tcp6'`, 或 `'unix'`. 關(guān)于 `allowHalfOpen`, 參見(jiàn) `createServer()` 和 `'end'` 事件。
### socket.connect(port, [host], [connectListener])
### socket.connect(path, [connectListener])
使用傳入的套接字打開(kāi)一個(gè)連接 如果 `port` 和 `host` 都被傳入， 那么套接字將會(huì)被已TCP套接字打開(kāi)，如果 `host` 被省略, 默認(rèn)為`localhost` . 如果 `path` 被傳入, 套接字將會(huì)被已指定路徑UNIX套接字打開(kāi)。
一般情況下這個(gè)函數(shù)是不需要使用, 比如用 `net.createConnection` 打開(kāi)套接字. 只有在您實(shí)現(xiàn)了自定義套接字時(shí)候才需要。
這是一個(gè)異步函數(shù)。 當(dāng) ['connect'](#) 觸發(fā)了的套接字是established狀態(tài) .或者在連接的時(shí)候出現(xiàn)了一個(gè)問(wèn)題, `'connect'` 事件不會(huì)被觸發(fā)， 而 `'error'` 事件會(huì)觸發(fā)并發(fā)送異常信息。
`connectListener` 用于 ['connect'](#) 事件的監(jiān)聽(tīng)器
### socket.bufferSize
是一個(gè)`net.Socket` 的屬性，用于 `socket.write()` . 用于幫助用戶獲取更快的運(yùn)行速度。 計(jì)算機(jī)不能一直處于大量數(shù)據(jù)被寫入狀態(tài) —— 網(wǎng)絡(luò)鏈接可能會(huì)變得過(guò)慢。 Node 在內(nèi)部會(huì)排隊(duì)等候數(shù)據(jù)被寫入套接字并確保傳輸連接上的數(shù)據(jù)完好。 (內(nèi)部實(shí)現(xiàn)為：輪詢套接字的文件描述符等待它為可寫).
內(nèi)部緩沖的可能后果是內(nèi)存使用會(huì)增加。這個(gè)屬性表示了現(xiàn)在處于緩沖區(qū)等待被寫入的字符數(shù)。（字符的數(shù)目約等于要被寫入的字節(jié)數(shù)，但是緩沖區(qū)可能包含字符串，而字符串是惰性編碼的，所以確切的字節(jié)數(shù)是未知的。）
遇到數(shù)值很大或者增長(zhǎng)很快的`bufferSize`的時(shí)候，用戶應(yīng)該嘗試用`pause()`和`resume()`來(lái)控制數(shù)據(jù)流。
### socket.setEncoding([encoding])
設(shè)置套接字的編碼為一個(gè)可讀流. 更多信息請(qǐng)查看 [stream.setEncoding()](#)
### socket.write(data, [encoding], [callback])
在套接字上發(fā)送數(shù)據(jù)。第二參數(shù)指明了使用字符串時(shí)的編碼方式-默認(rèn)為UTF8編碼。
如果所有數(shù)據(jù)被成功刷新到內(nèi)核緩沖區(qū)，則返回`true`。如果所有或部分?jǐn)?shù)據(jù)在用戶內(nèi)存里還處于隊(duì)列中，則返回`false`。當(dāng)緩沖區(qū)再次被釋放時(shí)，`'drain'`事件會(huì)被分發(fā)。
當(dāng)數(shù)據(jù)最終被完整寫入時(shí)，可選的`callback`參數(shù)會(huì)被執(zhí)行 - 但不一定是馬上執(zhí)行。
### socket.end([data], [encoding])
半關(guān)閉套接字 如., 它發(fā)送一個(gè) FIN 包 .可能服務(wù)器仍在發(fā)送數(shù)據(jù)。
如果 `data`被傳入, 等同于調(diào)用 `socket.write(data, encoding)` 然后調(diào)用 `socket.end()`.
### socket.destroy()
確保沒(méi)有I/O活動(dòng)在這個(gè)套接字。 只有在錯(cuò)誤發(fā)生情況下才需要（處理錯(cuò)誤等等）。
### socket.pause()
暫停讀取數(shù)據(jù)。 `'data'` 事件不會(huì)被觸發(fā)。 對(duì)于控制上傳非常有用。
### socket.resume()
在調(diào)用 `pause()`后恢復(fù)讀操作。
### socket.setTimeout(timeout, [callback])
如果套接字超過(guò)`timeout`毫秒處于閑置狀態(tài)，則將套接字設(shè)為超時(shí)。默認(rèn)情況下`net.Socket`不存在超時(shí)。
當(dāng)一個(gè)閑置超時(shí)被觸發(fā)時(shí)，套接字會(huì)接收到一個(gè)`'timeout'`事件，但是連接將不會(huì)被斷開(kāi)。用戶必須手動(dòng)`end()`或`destroy()`這個(gè)套接字。
如果`timeout`為0，那么現(xiàn)有的閑置超時(shí)會(huì)被禁用。
可選的`callback`參數(shù)將會(huì)被添加成為`'timeout'`事件的一次性監(jiān)聽(tīng)器。
### socket.setNoDelay([noDelay])
禁用納格（Nagle）算法。默認(rèn)情況下TCP連接使用納格算法，這些連接在發(fā)送數(shù)據(jù)之前對(duì)數(shù)據(jù)進(jìn)行緩沖處理。 將`noDelay`設(shè)成`true`會(huì)在每次`socket.write()`被調(diào)用時(shí)立刻發(fā)送數(shù)據(jù)。`noDelay`默認(rèn)為`true`。
### socket.setKeepAlive([enable], [initialDelay])
禁用/啟用長(zhǎng)連接功能，并在第一個(gè)在閑置套接字上的長(zhǎng)連接probe被發(fā)送之前，可選地設(shè)定初始延時(shí)。`enable`默認(rèn)為`false`。
設(shè)定`initialDelay` (毫秒)，來(lái)設(shè)定在收到的最后一個(gè)數(shù)據(jù)包和第一個(gè)長(zhǎng)連接probe之間的延時(shí)。將initialDelay設(shè)成0會(huì)讓值保持不變(默認(rèn)值或之前所設(shè)的值)。默認(rèn)為`0`。
### socket.address()
返回 socket 綁定的IP地址, 協(xié)議類型 (family name) 以及 端口號(hào) (port). 具體是一個(gè)包含三個(gè)屬性的對(duì)象, 形如 `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
### socket.unref()
如果這是事件系統(tǒng)中唯一一個(gè)活動(dòng)的套接字，調(diào)用 `unref` 將允許程序退出。如果套接字已被 `unref`，則再次調(diào)用 `unref` 并不會(huì)產(chǎn)生影響。
### socket.ref()
與 `unref` 相反，如果這是僅剩的套接字，在一個(gè)之前被 `unref` 了的套接字上調(diào)用 `ref` 將*不會(huì)*讓程序退出（缺省行為）。如果一個(gè)套接字已經(jīng)被 `ref`，則再次調(diào)用 `ref` 并不會(huì)產(chǎn)生影響。
### socket.remoteAddress
遠(yuǎn)程IP地址的字符串表示。例如，`'74.125.127.100'`或 `'2001:4860:a005::68'`。
### socket.remotePort
遠(yuǎn)程端口的數(shù)值表示。例如，`80` 或 `21`。
### socket.localAddress
遠(yuǎn)程客戶端正在連接的本地IP地址的字符串表示。例如，如果你在監(jiān)聽(tīng)`'0.0.0.0'`而客戶端連接在`'192.168.1.1'`，這個(gè)值就會(huì)是 `'192.168.1.1'`。
### socket.localPort
本地端口的數(shù)值表示。比如`80` 或 `21`。
### socket.bytesRead
所接收的字節(jié)數(shù)。
### socket.bytesWritten
所發(fā)送的字節(jié)數(shù)。
`net.Socket`實(shí)例是帶有以下事件的[EventEmitter](#)對(duì)象：
### 事件: 'lookup'
這個(gè)事件在解析主機(jī)名之后，連接主機(jī)之前被分發(fā)。對(duì)UNIX套接字不適用。
- `err` {Error | Null} 錯(cuò)誤對(duì)象。見(jiàn)[dns.lookup()][]。
- `address` {String} IP地址。
- `family` {String | Null} 得知類型。見(jiàn)[dns.lookup()][]。
### 事件: 'connect'
該事件在一個(gè)套接字連接成功建立后被分發(fā)。見(jiàn)`connect()`。
### 事件: 'data'
- {Buffer object}
當(dāng)收到數(shù)據(jù)時(shí)被分發(fā)。`data`參數(shù)會(huì)是一個(gè)`Buffer`或`String`對(duì)象。數(shù)據(jù)的編碼方式由`socket.setEncoding()`設(shè)定。 （詳見(jiàn) [可讀流][] 章節(jié)）
請(qǐng)注意，如果一個(gè)`Socket`對(duì)象分發(fā)一個(gè)`'data'`事件時(shí)沒(méi)有任何監(jiān)聽(tīng)器存在，則 **數(shù)據(jù)會(huì)丟失**。
### 事件: 'end'
當(dāng)套接字的另一端發(fā)送FIN包時(shí)，該事件被分發(fā)。
默認(rèn)情況下 （`allowHalfOpen == false`），當(dāng)套接字完成待寫入隊(duì)列中的任務(wù)時(shí)，它會(huì)destroy文件描述符。然而，如果把`allowHalfOpen`設(shè)成`true`，那么套接字將不會(huì)從它這邊自動(dòng)調(diào)用`end()`，使得用戶可以隨意寫入數(shù)據(jù)，但同時(shí)使得用戶自己需要調(diào)用`end()`。
### 事件: 'timeout'
當(dāng)套接字因?yàn)榉腔顒?dòng)狀態(tài)而超時(shí)時(shí)該事件被分發(fā)。這只是用來(lái)表明套接字處于空閑狀態(tài)。用戶必須手動(dòng)關(guān)閉這個(gè)連接。
參閱：`socket.setTimeout()`
### 事件: 'drain'
當(dāng)寫入緩沖被清空時(shí)產(chǎn)生?？杀挥糜诳刂粕蟼髁髁俊?
參閱：`socket.write()` 的返回值
### 事件: 'error'
- {Error object}
當(dāng)一個(gè)錯(cuò)誤發(fā)生時(shí)產(chǎn)生。`'close'` 事件會(huì)緊接著該事件被觸發(fā)。
### 事件: 'close'
- `had_error` {Boolean} 如果套接字發(fā)生了傳輸錯(cuò)誤則此字段為true
當(dāng)套接字完全關(guān)閉時(shí)該事件被分發(fā)。參數(shù)`had_error`是一個(gè)布爾值，表示了套接字是否因?yàn)橐粋€(gè)傳輸錯(cuò)誤而被關(guān)閉。
### net.isIP(input)
測(cè)試 input 是否 IP 地址。無(wú)效字符串返回 0；IP 版本 4 地址返回 4；IP 版本 6 地址返回 6。
### net.isIPv4(input)
如果 input 為版本 4 地址則返回 true，否則返回 false。
### net.isIPv6(input)
如果 input 為版本 6 地址則返回 true，否則返回 false。
- 關(guān)于本文檔
- 概述
- 斷言 (assert)
- Buffer
- Addons插件
- 子進(jìn)程
- 集群
- 控制臺(tái)
- 加密（Crypto）
- 調(diào)試器
- DNS
- 域
- 事件 (Events)
- File System
- 全局對(duì)象
- HTTP
- HTTPS
- Modules
- net
- 操作系統(tǒng)
- 路徑 (Path)
- process
- punycode
- Query String
- Readline
- REPL
- Smalloc
- 流
- 字符串解碼器
- 定時(shí)器
- TLS (SSL)
- TTY
- UDP / 數(shù)據(jù)報(bào)套接字
- URL
- utils
- 執(zhí)行 JavaScript
- Zlib
- 進(jìn)度
- 感謝