http模塊

 

 

- 穩定的

要使用 HTTP 服務器與客戶端，須要 require('http')。

Node.js 中的 HTTP 接口被設計成支持協議的許多特性。 好比，大塊編碼的消息。 這些接口不緩衝完整的請求或響應，用戶可以以流的形式處理數據。

HTTP 消息頭由一個對象表示，例如：

{ 'content-length': '123', 'content-type': 'text/plain', 'connection': 'keep-alive', 'host': 'mysite.com', 'accept': '*/*' } 

鍵名是小寫的，鍵值不能修改。

爲了支持各類可能的 HTTP 應用，Node.js 的 HTTP API 是很是底層的。 它只涉及流處理與消息解析。 它把一個消息解析成消息頭和消息主體，但不解析具體的消息頭或消息主體。

查看 message.headers 瞭解如何處理重複的消息頭。

接收到的原始消息頭保存在 rawHeaders 屬性中，它是一個 [key, value, key2, value2, ...] 數組。 例如，上面的消息頭對象有一個相似如下的 rawHeaders 列表：

[ 'ConTent-Length', '123456', 'content-LENGTH', '123', 'content-type', 'text/plain', 'CONNECTION', 'keep-alive', 'Host', 'mysite.com', 'accepT', '*/*' ] 

http.Agent 類

 

 

Agent 負責爲 HTTP 客戶端管理鏈接的持續與複用。 它爲一個給定的主機與端口維護着一個等待請求的隊列，且爲每一個請求重複使用一個單一的 socket 鏈接直到隊列爲空，此時 socket 會被銷燬或被放入一個鏈接池中，在鏈接池中等待被有着相同主機與端口的請求再次使用。 是否被銷燬或被放入鏈接池取決於 keepAlive 選項。

鏈接池中的鏈接的 TCP Keep-Alive 是開啓的，但服務器仍然可能關閉閒置的鏈接，在這種狀況下，這些鏈接會被移出鏈接池，且當一個新的 HTTP 請求被建立時再爲指定的主機與端口建立一個新的鏈接。 服務器也可能拒絕容許同一鏈接上有多個請求，在這種狀況下，鏈接會爲每一個請求從新建立，且不能被放入鏈接池。 Agent 仍然會建立請求到服務器，但每一個請求會出如今一個新的鏈接。

但一個鏈接被客戶端或服務器關閉時，它會被移出鏈接池。 鏈接池中任何未被使用的 socket 會被釋放，從而使 Node.js 進程在沒有請求時不用保持運行。 （查看 socket.unref()）。

當 Agent 實例再也不被使用時，建議 destroy() 它，由於未被使用的 socket 也會消耗操做系統資源。

當 socket 觸發 'close' 事件或 'agentRemove' 事件時，它會被移出代理池。 當打算長時間保持打開一個 HTTP 請求且不想它留着鏈接池中，則能夠以下處理：

http.get(options, (res) => { // 處理事情 }).on('socket', (socket) => { socket.emit('agentRemove'); }); 

代理也可被用於單獨的請求。 使用 {agent: false} 做爲 http.get() 函數或 http.request() 函數的選項，則會爲客戶端鏈接建立一個默認配置的一次性使用的 Agent。

agent:false:

http.get({ hostname: 'localhost', port: 80, path: '/', agent: false // 建立一個新的代理，只用於本次請求 }, (res) => { // 對響應進行處理 }); 

new Agent([options])

 

 

• options <Object> 代理的配置選項。有如下字段：
  • keepAlive <boolean> 保持 socket 可用即便沒有請求，以便它們可被未來的請求使用而無需從新創建一個 TCP 鏈接。默認爲 false。
  • keepAliveMsecs <number> 當使用了 keepAlive 選項時，該選項指定 TCP Keep-Alive 數據包的 初始延遲。 當 keepAlive 選項爲 false 或 undefined 時，該選項無效。 默認爲 1000。
  • maxSockets <number> 每一個主機容許的最大 socket 數量。 默認爲 Infinity。
  • maxFreeSockets <number> 在空閒狀態下容許打開的最大 socket 數量。 僅當 keepAlive 爲 true 時纔有效。 默認爲 256。

http.request() 使用的默認 http.globalAgent 的選項均爲各自的默認值。

若要配置其中任何一個，則須要建立自定義的 http.Agent 實例。

const http = require('http'); const keepAliveAgent = new http.Agent({ keepAlive: true }); options.agent = keepAliveAgent; http.request(options, onResponseCallback); 

agent.createConnection(options[, callback])

 

• options <Object> 包含鏈接詳情的選項。查看 net.createConnection() 瞭解選項的格式。
• callback <Function> 接收被建立的 socket 的回調函數。
• 返回: <net.Socket>

建立一個用於 HTTP 請求的 socket 或流。

默認狀況下，該函數相似於 net.createConnection()。 可是若是指望更大的靈活性，自定義的代理能夠重寫該方法。

socket 或流能夠經過如下兩種方式獲取：從該函數返回，或傳入 callback。

callback 有 (err, stream) 參數。

agent.keepSocketAlive(socket)

 

新增於: v8.1.0

• socket <net.Socket>

在 socket 被請求分離的時候調用, 可能被代理持續使用. 默認行爲:

socket.unref(); socket.setKeepAlive(agent.keepAliveMsecs); 

這個方法能夠被一個特定的 Agent 子類重寫. 若是這個方法返回假值, socket 會被銷燬而不是 在下一次請求時持續使用.

agent.reuseSocket(socket, request)

 

新增於: v8.1.0

• socket <net.Socket>
• request <http.ClientRequest>

因爲 keep-alive 選項被保持持久化, 在 socket 附加到 request 時調用. 默認行爲是:

socket.ref(); 

這個方法能夠被一個特定的 Agent 子類重寫.

agent.destroy()

 

 

銷燬當前正被代理使用的任何 socket。

一般不須要這麼作。 可是若是使用的代理啓用了 keepAlive，則當肯定它再也不被使用時，最好顯式地關閉代理。 不然，在服務器終止它們以前，socket 可能還會長時間保持打開。

agent.freeSockets

• <Object>

返回一個對象，包含當前正在等待被啓用了 keepAlive 的代理使用的 socket 數組。 不要修改該屬性。

agent.getName(options)

 

 

• options <Object> 爲名稱生成程序提供信息的選項。
  • host <string> 請求發送至的服務器的域名或 IP 地址。
  • port <number> 遠程服務器的端口。
  • localAddress <string> 當發送請求時，爲網絡鏈接綁定的本地接口。
• 返回: <string>

爲請求選項的集合獲取一個惟一的名稱，用來判斷一個鏈接是否能夠被複用。 對於 HTTP 代理，返回 host:port:localAddress。 對於 HTTPS 代理，名稱會包含 CA、證書、密碼、以及其餘 HTTPS/TLS 特有的用於判斷 socket 複用性的選項。

agent.maxFreeSockets

 

 

• <number>

默認爲 256。 對於已啓用 keepAlive 的代理，該屬性可設置要保留的空閒 socket 的最大數量。

agent.maxSockets

 

 

• <number>

默認爲不限制。 該屬性可設置代理爲每一個來源打開的併發 socket 的最大數量。 來源是一個 'host:port' 或 'host:port:localAddress' 組合。

agent.requests

 

 

• <Object>

返回一個對象，包含還未被分配到 socket 的請求隊列。 不要修改。

agent.sockets#

查看英文版 / 參與翻譯

新增於: v0.3.6

• <Object>

返回一個對象，包含當前正被代理使用的 socket 數組。 不要修改。

http.ClientRequest 類#

查看英文版 / 參與翻譯

新增於: v0.1.17

該對象在 http.request() 內部被建立並返回。 它表示着一個正在處理的請求，其請求頭已進入隊列。 請求頭仍可以使用 setHeader(name, value)、getHeader(name) 和 removeHeader(name) API 進行修改。 實際的請求頭會與第一個數據塊一塊兒發送或當關閉鏈接時發送。

要獲取響應，需爲 'response' 事件添加一個監聽器到請求對象上。 當響應頭被接收到時，'response' 事件會從請求對象上被觸發 。 'response' 事件被執行時帶有一個參數，該參數是一個 http.IncomingMessage 實例。

在 'response' 事件期間，能夠添加監聽器到響應對象上，好比監聽 'data' 事件。

若是沒有添加 'response' 事件處理函數，則響應會被整個丟棄。 若是添加了 'response' 事件處理函數，則必須消耗完響應對象的數據，可經過調用 response.read()、或添加一個 'data' 事件處理函數、或調用 .resume() 方法。 數據被消耗完時會觸發 'end' 事件。 在數據被讀取完以前會消耗內存，可能會形成 'process out of memory' 錯誤。

注意：Node.js 不會檢查 Content-Length 與已傳輸的請求主體的長度是否相等。

該請求實現了 可寫流 接口。 它是一個包含如下事件的 EventEmitter：

'abort' 事件#

查看英文版 / 參與翻譯

新增於: v1.4.1

當請求已被客戶端終止時觸發。 該事件僅在首次調用 abort() 時觸發。

'aborted' 事件#

查看英文版 / 參與翻譯

新增於: v0.3.8

當請求已被服務器終止且網絡 socket 已關閉時觸發。

'connect' 事件#

查看英文版 / 參與翻譯

新增於: v0.7.0

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Buffer>

每當服務器響應 CONNECT 請求時觸發。 若是該事件未被監聽，則接收到 CONNECT 方法的客戶端會關閉鏈接。

例子，用一對客戶端和服務端來演示如何監聽 'connect' 事件：

const http = require('http'); const net = require('net'); const url = require('url'); // 建立一個 HTTP 代理服務器 const proxy = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('okay'); }); proxy.on('connect', (req, cltSocket, head) => { // 鏈接到一個服務器 const srvUrl = url.parse(`http://${req.url}`); const srvSocket = net.connect(srvUrl.port, srvUrl.hostname, () => { cltSocket.write('HTTP/1.1 200 Connection Established\r\n' + 'Proxy-agent: Node.js-Proxy\r\n' + '\r\n'); srvSocket.write(head); srvSocket.pipe(cltSocket); cltSocket.pipe(srvSocket); }); }); // 代理服務器正在運行 proxy.listen(1337, '127.0.0.1', () => { // 發送一個請求到代理服務器 const options = { port: 1337, hostname: '127.0.0.1', method: 'CONNECT', path: 'www.google.com:80' }; const req = http.request(options); req.end(); req.on('connect', (res, socket, head) => { console.log('已鏈接！'); // 經過代理服務器發送一個請求 socket.write('GET / HTTP/1.1\r\n' + 'Host: www.google.com:80\r\n' + 'Connection: close\r\n' + '\r\n'); socket.on('data', (chunk) => { console.log(chunk.toString()); }); socket.on('end', () => { proxy.close(); }); }); }); 

'continue' 事件#

查看英文版 / 參與翻譯

新增於: v0.3.2

當服務器發送了一個 100 Continue 的 HTTP 響應時觸發，一般是由於請求包含 Expect: 100-continue。 這是客戶端將要發送請求主體的指令。

'response' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.0

• response <http.IncomingMessage>

當請求的響應被接收到時觸發。 該事件只觸發一次。

'socket' 事件#

查看英文版 / 參與翻譯

新增於: v0.5.3

• socket <net.Socket>

當 socket 被分配到請求後觸發。

'upgrade' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.94

• response <http.IncomingMessage>
• socket <net.Socket>
• head <Buffer>

每當服務器響應 upgrade 請求時觸發。 若是該事件未被監聽，則接收到 upgrade 請求頭的客戶端會關閉鏈接。

例子，用一對客戶端和服務端來演示如何監聽 'upgrade' 事件：

const http = require('http'); // 建立一個 HTTP 服務器 const srv = http.createServer( (req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('okay'); }); srv.on('upgrade', (req, socket, head) => { socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + 'Upgrade: WebSocket\r\n' + 'Connection: Upgrade\r\n' + '\r\n'); socket.pipe(socket); }); // 服務器正在運行 srv.listen(1337, '127.0.0.1', () => { // 發送一個請求 const options = { port: 1337, hostname: '127.0.0.1', headers: { 'Connection': 'Upgrade', 'Upgrade': 'websocket' } }; const req = http.request(options); req.end(); req.on('upgrade', (res, socket, upgradeHead) => { console.log('got upgraded!'); socket.end(); process.exit(0); }); }); 

request.abort()#

查看英文版 / 參與翻譯

新增於: v0.3.8

標記請求爲終止。 調用該方法將使響應中剩餘的數據被丟棄且 socket 被銷燬。

request.aborted#

查看英文版 / 參與翻譯

新增於: v0.11.14

若是請求已被終止，則該屬性的值爲請求被終止的時間，從 1 January 1970 00:00:00 UTC 到如今的毫秒數。

request.connection#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <net.Socket>

See request.socket

request.end([data[, encoding]][, callback])#

查看英文版 / 參與翻譯

新增於: v0.1.90

• data <string> | <Buffer>
• encoding <string>
• callback <Function>

結束髮送請求。 若是部分請求主體還未被髮送，則會刷新它們到流中。 若是請求是分塊的，則會發送終止字符 '0\r\n\r\n'。

若是指定了 data，則至關於調用 request.write(data, encoding) 以後再調用 request.end(callback)。

若是指定了 callback，則當請求流結束時會被調用。

request.flushHeaders()#

查看英文版 / 參與翻譯

新增於: v1.6.0

刷新請求頭。

出於效率的考慮，Node.js 一般會緩存請求頭直到 request.end() 被調用或第一塊請求數據被寫入。 而後 Node.js 會將請求頭和數據打包成一個單一的 TCP 數據包。

一般那是指望的（由於它節省了 TCP 往返），除非第一個數據塊很長時間以後才被髮送。 request.flushHeaders() 能夠繞過最優選擇並提早開始請求。

request.setNoDelay([noDelay])#

查看英文版 / 參與翻譯

新增於: v0.5.9

• noDelay <boolean>

一旦 socket 被分配給請求且已鏈接，socket.setNoDelay() 會被調用。

request.setSocketKeepAlive([enable][, initialDelay])#

查看英文版 / 參與翻譯

新增於: v0.5.9

• enable <boolean>
• initialDelay <number>

一旦 socket 被分配給請求且已鏈接，socket.setKeepAlive() 會被調用。

request.setTimeout(timeout[, callback])#

查看英文版 / 參與翻譯

新增於: v0.5.9

• timeout <number> 請求被認爲是超時的毫秒數。
• callback <Function> 可選的函數，當超時發生時被調用。等同於綁定到 timeout 事件。

一旦 socket 被分配給請求且已鏈接，socket.setTimeout() 會被調用。

返回 request。

request.socket#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <net.Socket>

引用底層socket。 一般用戶不想訪問此屬性。 特別地，因爲協議解析器鏈接到socket的方式，socket將不會觸發'readable'事件。 在response.end()以後，該屬性爲null。 也能夠經過request.connection來訪問socket。

例如:

const http = require('http'); const server = http.createServer((req, res) => { const ip = req.socket.remoteAddress; const port = req.socket.remotePort; res.end(`你的IP地址是${ip}，你的源端口是${port}.`); }).listen(3000); 

request.write(chunk[, encoding][, callback])#

查看英文版 / 參與翻譯

新增於: v0.1.29

• chunk <string> | <Buffer>
• encoding <string>
• callback <Function>

發送請求主體的一個數據塊。 經過屢次調用該方法，一個請求主體可被髮送到一個服務器，在這種狀況下，當建立請求時，建議使用 ['Transfer-Encoding', 'chunked'] 請求頭。

encoding 參數是可選的，僅當 chunk 是一個字符串時纔有效。默認爲 'utf8'。

callback 參數是可選的，當數據塊被刷新時調用。

返回 request。

http.Server 類#

查看英文版 / 參與翻譯

新增於: v0.1.17

該類繼承自 net.Server，且具備如下額外的事件：

'checkContinue' 事件#

查看英文版 / 參與翻譯

新增於: v0.3.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

每當接收到一個帶有 HTTP Expect: 100-continue 請求頭的請求時觸發。 若是該事件未被監聽，則服務器會自動響應 100 Continue。

處理該事件時，若是客戶端應該繼續發送請求主體，則調用 response.writeContinue()，不然生成一個適當的 HTTP 響應（例如 400 錯誤請求）。

注意，當該事件被觸發且處理後，'request' 事件不會被觸發。

'checkExpectation' 事件#

查看英文版 / 參與翻譯

新增於: v5.5.0

• request <http.ClientRequest>
• response <http.ServerResponse>

每當接收到一個帶有 HTTP Expect 請求頭（值不爲 100-continue）的請求時觸發。 若是該事件未被監聽，則服務器會自動響應 417 Expectation Failed。

注意，當該事件被觸發且處理後，'request' 事件不會被觸發。

'clientError' 事件#

查看英文版 / 參與翻譯

版本歷史

• exception <Error>
• socket <net.Socket>

若是客戶端觸發了一個 'error' 事件，則它會被傳遞到這裏。 該事件的監聽器負責關閉或銷燬底層的 socket。 例如，用戶可能但願更溫和地用 HTTP '400 Bad Request' 響應關閉 socket，而不是忽然地切斷鏈接。

默認狀況下，請求異常時會當即銷燬 socket。

socket 參數是發生錯誤的 net.Socket 對象。

const http = require('http'); const server = http.createServer((req, res) => { res.end(); }); server.on('clientError', (err, socket) => { socket.end('HTTP/1.1 400 Bad Request\r\n\r\n'); }); server.listen(8000); 

當 'clientError' 事件發生時，不會有 request 或 response 對象，因此發送的任何 HTTP 響應，包括響應頭和內容，必須被直接寫入到 socket 對象。 注意，確保響應是一個被正確格式化的 HTTP 響應消息。

'close' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.4

當服務器關閉時觸發。

'connect' 事件#

查看英文版 / 參與翻譯

新增於: v0.7.0

• request <http.IncomingMessage> HTTP 請求，同 'request' 事件。
• socket <net.Socket> 服務器與客戶端之間的網絡 socket。
• head <Buffer> 流的第一個數據包，可能爲空。

每當客戶端發送 HTTP CONNECT 請求時觸發。 若是該事件未被監聽，則發送 CONNECT 請求的客戶端會關閉鏈接。

當該事件被觸發後，請求的 socket 上沒有 'data' 事件監聽器，這意味着須要綁定 'data' 事件監聽器，用來處理 socket 上被髮送到服務器的數據。

'connection' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.0

• socket <net.Socket>

當一個新的 TCP 流被創建時觸發。 socket 是一個 net.Socket 類型的對象。 一般用戶無需訪問該事件。 注意，由於協議解析器綁定到 socket 的方式，socket 不會觸發 'readable' 事件。 socket 也能夠經過 request.connection 訪問。

'request' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

每次接收到一個請求時觸發。 注意，每一個鏈接可能有多個請求（在 HTTP keep-alive 鏈接的狀況下）。

'upgrade' 事件#

查看英文版 / 參與翻譯

新增於: v0.1.94

• request <http.IncomingMessage> HTTP 請求，同 'request' 事件。
• socket <net.Socket> 服務器與客戶端之間的網絡 socket。
• head <Buffer> 流的第一個數據包，可能爲空。

每當客戶端發送 HTTP upgrade 請求時觸發。 若是該事件未被監聽，則發送 upgrade 請求的客戶端會關閉鏈接。

當該事件被觸發後，請求的 socket 上沒有 'data' 事件監聽器，這意味着須要綁定 'data' 事件監聽器，用來處理 socket 上被髮送到服務器的數據。

server.close([callback])#

查看英文版 / 參與翻譯

新增於: v0.1.90

• callback <Function>

中止服務端接收新的鏈接。詳見 net.Server.close()。

server.listen(handle[, callback])#

查看英文版 / 參與翻譯

新增於: v0.5.10

• handle <Object>
• callback <Function>

handle 對象能夠被設爲一個服務器或 socket（任何帶有一個 _handle 成員的對象）、或一個 {fd: <n>} 對象。

該函數可讓服務器使用指定的處理程序接受鏈接，前提是文件描述符或處理程序已綁定了一個端口或域 socket。

Windows 平臺上不支持監聽文件描述符。

該函數是異步的。 callback 會被添加到 'listening' 事件的監聽器中。也可查看 net.Server.listen()。

返回 server。

注意，server.listen() 方法可能被屢次調用。 每次調用都會使用提供的選項從新打開服務器。

server.listen(path[, callback])#

查看英文版 / 參與翻譯

新增於: v0.1.90

• path <string>
• callback <Function>

啓動一個 UNIX socket 服務器，並在給定的 path 上監聽鏈接。

該函數是異步的。 callback 會被添加到 'listening' 事件的監聽器中。也可查看 net.Server.listen(path)。

注意，server.listen() 方法可能被屢次調用。 每次調用都會使用提供的選項從新打開服務器。

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

查看英文版 / 參與翻譯

新增於: v0.1.90

• port <number>
• hostname <string>
• backlog <number>
• callback <Function>

開始在指定的 port 和 hostname 上接受鏈接。 若是省略了 hostname，則當 IPv6 可用時，服務器會接受 未指定的 IPv6 地址（::）的鏈接，不然接受 未指定的 IPv4 地址（0.0.0.0）的鏈接。

請注意: 在大多數操做系統中，監聽未指定的IPv6地址unspecified IPv6 address (::)可能會致使net.Server也監聽未指定的IPv4地址unspecified IPv4 address (0.0.0.0)。

若是省略了 port 或值爲 0，則操做系統會分配一個隨機的端口，該端口可在 'listening' 事件被觸發後使用 server.address().port 獲取。

若要監聽一個 UNIX socket，則需提供文件名而不是端口和主機名。

backlog 是等待鏈接的隊列的最大長度。 實際長度由操做系統經過 sysctl 設置決定，好比 Linux 上的 tcp_max_syn_backlog 和 somaxconn。 該參數的默認值是 511（不是 512）。

該函數是異步的。 callback 會被添加到 'listening' 事件的監聽器中。也可查看 net.Server.listen(port)。

注意，server.listen() 方法可能被屢次調用。 每次調用都會使用提供的選項從新打開服務器。

server.listening#

查看英文版 / 參與翻譯

新增於: v5.7.0

• <boolean>

返回一個布爾值，表示服務器是否正在監聽鏈接。

server.maxHeadersCount#

查看英文版 / 參與翻譯

新增於: v0.7.0

• <number> 默認爲 2000。

限制請求頭的最大數量，默認爲 2000。 若是設爲 0，則沒有限制。

server.setTimeout([msecs][, callback])#

查看英文版 / 參與翻譯

新增於: v0.9.12

• msecs <number> 默認爲 120000 (2 分鐘)。
• callback <Function>

設置 socket 的超時時間。 若是發生超時，則觸發服務器對象的 'timeout' 事件，並傳入 socket 做爲一個參數。

默認狀況下，服務器的超時時間是 2 分鐘，且超時後的 socket 會被自動銷燬。 可是，若是你爲服務器的 'timeout' 事件分配了一個回調函數，則超時必須被顯式地處理。

返回 server。

server.timeout#

查看英文版 / 參與翻譯

新增於: v0.9.12

• <number> 超時時間，以毫秒爲單位。默認爲 120000 (2 分鐘)。

socket 被認定爲超時的空閒毫秒數。

值設爲 0 可禁用請求鏈接的超時行爲。

注意，socket 的超時邏輯是在鏈接上設定的，因此改變這個值隻影響服務器新建的鏈接，而不會影響任何已存在的鏈接。

server.keepAliveTimeout#

查看英文版 / 參與翻譯

新增於: v8.0.0

• <number> 超時毫秒. 默認爲 5000 (5秒).

服務器完成最後的響應以後須要等待的額外的傳入數據的活躍毫秒數, socket 才能被銷燬.
若是服務器在 keep-alive 計時已激活時接收到新的數據, 他會重置常規的非活動計時, 即server.timeout.

值爲 0 時禁用傳入鏈接 keep-alive 的超時行爲.

注意: scoket 的超時邏輯上取決於服務器鏈接, 因此改變這個值隻影響服務器的新鏈接, 不影響任何已存在的鏈接.

http.ServerResponse 類#

查看英文版 / 參與翻譯

新增於: v0.1.17

該對象在 HTTP 服務器內部被建立。 它做爲第二個參數被傳入 'request' 事件。

這個類實現了（而不是繼承自）可寫流 接口。 它是一個有如下事件的 EventEmitter：

'close' 事件#

查看英文版 / 參與翻譯

新增於: v0.6.7

當底層鏈接在 response.end() 被調用或可以刷新以前被終止時觸發。

'finish' 事件#

查看英文版 / 參與翻譯

新增於: v0.3.6

當響應已被髮送時觸發。 更具體地說，當響應頭和響應主體的最後一部分已被交給操做系統經過網絡進行傳輸時，觸發該事件。 這並不意味着客戶端已接收到任何東西。

該事件觸發後，響應對象上再也不觸發其餘事件。

response.addTrailers(headers)#

查看英文版 / 參與翻譯

新增於: v0.3.0

• headers <Object>

該方法會添加 HTTP 尾部響應頭（一種在消息尾部的響應頭）到響應。

僅當響應使用分塊編碼時，尾部響應頭纔會被髮送；不然（好比請求爲 HTTP/1.0），尾部響應頭會被丟棄。

注意，發送尾部響應頭以前，需先發送 Trailer 響應頭，並在值裏帶上尾部響應頭字段的列表。 例如：

response.writeHead(200, { 'Content-Type': 'text/plain', 'Trailer': 'Content-MD5' }); response.write(fileData); response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' }); response.end(); 

若是尾部響應頭字段的名稱或值包含無效字符，則拋出 TypeError 錯誤。

response.connection#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <net.Socket>

See response.socket.

response.end([data][, encoding][, callback])#

查看英文版 / 參與翻譯

新增於: v0.1.90

• data <string> | <Buffer>
• encoding <string>
• callback <Function>

該方法會通知服務器，全部響應頭和響應主體都已被髮送，即服務器將其視爲已完成。 每次響應都必須調用 response.end() 方法。

若是指定了 data，則至關於調用 response.write(data, encoding) 以後再調用 response.end(callback)。

若是指定了 callback，則當響應流結束時被調用。

response.finished#

查看英文版 / 參與翻譯

新增於: v0.0.2

• <boolean>

返回一個布爾值，表示響應是否已完成。 默認爲 false。 執行 response.end() 以後，該值會變爲 true。

response.getHeader(name)#

查看英文版 / 參與翻譯

新增於: v0.4.0

• name <string>
• 返回: <string>

讀取一個已入隊列但還沒有發送到客戶端的響應頭。 注意，名稱不區分大小寫。

例子：

const contentType = response.getHeader('content-type'); 

response.getHeaderNames()#

查看英文版 / 參與翻譯

新增於: v7.7.0

• Returns: <Array>

返回一個包含當前響應惟一名稱的 http 頭信息名稱數組. 名稱均爲小寫.

示例:

response.setHeader('Foo', 'bar'); response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']); const headerNames = response.getHeaderNames(); // headerNames === ['foo', 'set-cookie'] 

response.getHeaders()#

查看英文版 / 參與翻譯

新增於: v7.7.0

• Returns: <Object>

返回當前響應頭文件的淺拷貝。 因爲使用了淺拷貝，所以數組值可能會改變，無需對各類與響應頭相關的http模塊方法進行額外調用。 返回對象的鍵是響應頭名稱，值是各自的響應頭值。 全部響應頭名稱都是小寫的。

注意：response.getHeaders() 方法返回的對象不會原型繼承 JavaScript Object。 這意味着，沒有定義典型的Object方法，如obj.toString()，obj.hasOwnProperty() 和其餘方法，而且不起做用。

例子：

response.setHeader('Foo', 'bar'); response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']); const headers = response.getHeaders(); // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } 

response.hasHeader(name)#

查看英文版 / 參與翻譯

新增於: v7.7.0

• name <string>
• Returns: <boolean>

若是響應頭當前有設置 name 頭部，返回 true。請注意，名稱匹配不區分大小寫。

例子：

const hasContentType = response.hasHeader('content-type'); 

response.headersSent#

查看英文版 / 參與翻譯

新增於: v0.9.3

• <boolean>

返回一個布爾值（只讀）。 若是響應頭已被髮送則爲 true，不然爲 false。

response.removeHeader(name)#

查看英文版 / 參與翻譯

新增於: v0.4.0

• name <string>

從隱式發送的隊列中移除一個響應頭。

例子：

response.removeHeader('Content-Encoding'); 

response.sendDate#

查看英文版 / 參與翻譯

新增於: v0.7.5

• <boolean>

當爲 true 時，若是響應頭裏沒有日期響應頭，則日期響應頭會被自動生成併發送。默認爲 true。

該屬性只可在測試時被禁用，由於 HTTP 響應須要包含日期響應頭。

response.setHeader(name, value)#

查看英文版 / 參與翻譯

新增於: v0.4.0

• name <string>
• value <string> | <string[]>

爲一個隱式的響應頭設置值。 若是該響應頭已存在，則值會被覆蓋。 若是要發送多個名稱相同的響應頭，則使用字符串數組。

例子：

response.setHeader('Content-Type', 'text/html'); 

或

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); 

若是響應頭字段的名稱或值包含無效字符，則拋出 TypeError 錯誤。

response.setHeader() 設置的響應頭會與 response.writeHead() 設置的響應頭合併，且 response.writeHead() 的優先。

// 返回 content-type = text/plain const server = http.createServer((req, res) => { res.setHeader('Content-Type', 'text/html'); res.setHeader('X-Foo', 'bar'); res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('ok'); }); 

response.setTimeout(msecs[, callback])#

查看英文版 / 參與翻譯

新增於: v0.9.12

• msecs <number>
• callback <Function>

設置 socket 的超時時間爲 msecs。 若是提供了回調函數，則它會做爲監聽器被添加到響應對象的 'timeout' 事件。

若是沒有 'timeout' 監聽器被添加到請求、響應或服務器，則 socket 會在超時後被銷燬。 若是在請求、響應或服務器的 'timeout' 事件上分配了回調函數，則超時的 socket 必須被顯式地處理。

返回 response。

response.socket#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <net.Socket>

引用底層socket。 一般用戶不想訪問此屬性。 特別地，因爲協議解析器鏈接到socket的方式，socket將不會發出'readable'事件。 在response.end()以後，該屬性爲null。 也能夠經過response.connection來訪問socket。

例如:

const http = require('http'); const server = http.createServer((req, res) => { const ip = req.socket.remoteAddress; const port = req.socket.remotePort; res.end(`你的IP地址是${ip}，你的源端口是${port}.`); }).listen(3000); 

response.statusCode#

查看英文版 / 參與翻譯

新增於: v0.4.0

• <number>

當使用隱式的響應頭時（沒有顯式地調用 response.writeHead()），該屬性控制響應頭刷新時將被髮送到客戶端的狀態碼。

例子：

response.statusCode = 404; 

響應頭被髮送到客戶端後，該屬性表示被髮出的狀態碼。

response.statusMessage#

查看英文版 / 參與翻譯

新增於: v0.11.8

• <string>

當使用隱式的響應頭時（沒有顯式地調用 response.writeHead()），該屬性控制響應頭刷新時將被髮送到客戶端的狀態信息。 若是該值爲 undefined，則使用狀態碼的標準信息。

例子：

response.statusMessage = 'Not found'; 

響應頭被髮送到客戶端後，該屬性表示被髮出的狀態信息。

response.write(chunk[, encoding][, callback])#

查看英文版 / 參與翻譯

新增於: v0.1.29

• chunk <string> | <Buffer>
• encoding <string>
• callback <Function>
• 返回: <boolean>

若是該方法被調用且 response.writeHead() 沒有被調用，則它會切換到隱式響應頭模式並刷新隱式響應頭。

該方法會發送一塊響應主體。 它可被屢次調用，以便提供連續的響應主體片斷。

請注意在http模塊中，當請求是HEAD請求時，響應主體被省略。 相似地，204和304響應 不能 包括消息體。

chunk 能夠是一個字符串或一個 buffer。 若是 chunk 是一個字符串，則第二個參數指定如何將它編碼成一個字節流。 encoding默認爲 'utf8'。 當數據塊被刷新時，callback 會被調用。

注意：這是原始的 HTTP 主體，且與可能被使用的高級主體編碼無關。

response.write() 首次被調用時，會發送緩衝的響應頭信息和響應主體的第一塊數據到客戶端。 response.write() 第二次被調用時，Node.js 會以流的形式處理數據，並將它們分別發送。 也就是說，響應會被緩衝到響應主體的第一個數據塊。

若是所有數據被成功刷新到內核緩衝區，則返回 true。 若是所有或部分數據還在內存中排隊，則返回 false。 當緩衝區再次空閒時，則觸發 'drain' 事件。

response.writeContinue()#

查看英文版 / 參與翻譯

新增於: v0.3.0

發送一個 HTTP/1.1 100 Continue 消息到客戶端，表示請求主體能夠開始發送。 參閱 Server 的 'checkContinue' 事件。

response.writeHead(statusCode[, statusMessage][, headers])#

查看英文版 / 參與翻譯

版本歷史

• statusCode <number>
• statusMessage <string>
• headers <Object>

發送一個響應頭給請求。 狀態碼是一個三位數的 HTTP 狀態碼，如 404。 最後一個參數 headers 是響應頭。 第二個參數 statusMessage 是可選的狀態描述。

例子：

const body = 'hello world'; response.writeHead(200, { 'Content-Length': Buffer.byteLength(body), 'Content-Type': 'text/plain' }); 

該方法在消息中只能被調用一次，且必須在 response.end() 被調用以前調用。

若是在調用該方法以前調用 response.write() 或 response.end()，則隱式的響應頭會被處理並調用該函數。

response.setHeader() 設置的響應頭會與 response.writeHead() 設置的響應頭合併，且 response.writeHead() 的優先。

// 返回 content-type = text/plain const server = http.createServer((req, res) => { res.setHeader('Content-Type', 'text/html'); res.setHeader('X-Foo', 'bar'); res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('ok'); }); 

注意，Content-Length 是以字節（而不是字符）爲單位的。 上面的例子行得通是由於字符串 'hello world' 只包含單字節字符。 若是響應主體包含高級編碼的字符，則應使用 Buffer.byteLength() 來肯定在給定編碼中的字節數。 Node.js 不會檢查 Content-Length 與已發送的響應主體的長度是否相同。

若是響應頭字段的名稱或值包含無效字符，則拋出 TypeError 錯誤。

http.IncomingMessage 類#

查看英文版 / 參與翻譯

新增於: v0.1.17

IncomingMessage 對象由 http.Server 或 http.ClientRequest 建立，並做爲第一個參數分別遞給 'request' 和 'response' 事件。 它能夠用來訪問響應狀態、消息頭、以及數據。

它實現了 可讀流 接口，還有如下額外的事件、方法、以及屬性。

'aborted' 事件#

查看英文版 / 參與翻譯

新增於: v0.3.8

當請求已被客戶端終止且網絡 socket 已關閉時觸發。

'close' 事件#

查看英文版 / 參與翻譯

新增於: v0.4.2

當底層鏈接被關閉時觸發。 同 'end' 事件同樣，該事件每一個響應只觸發一次。

message.destroy([error])#

查看英文版 / 參與翻譯

新增於: v0.3.0

• error <Error>

調用接收到 IncomingMessage 的 socket 上的 destroy() 方法。 若是提供了 error，則觸發 'error' 事件，且把 error 做爲參數傳入事件的監聽器。

message.headers#

查看英文版 / 參與翻譯

新增於: v0.1.5

• <Object>

請求頭或響應頭的對象。

頭信息的名稱與值的鍵值對。 頭信息的名稱爲小寫。 例如：

// 輸出相似如下的東西： // // { 'user-agent': 'curl/7.22.0', // host: '127.0.0.1:8000', // accept: '*/*' } console.log(request.headers); 

原始頭信息中的重複數據會按如下方式根據頭信息名稱進行處理：

• 重複的 age 、 authorization 、 content-length 、 content-type 、 etag 、 expires 、 from 、 host 、 if-modified-since 、 if-unmodified-since 、 last-modified 、 location 、 max-forwards 、 proxy-authorization 、 referer 、 retry-after 、或 user-agent 會被丟棄。
• set-cookie 始終是一個數組。重複的會被添加到數組。
• 對於其餘頭信息，其值使用 , 拼接。

message.httpVersion#

查看英文版 / 參與翻譯

新增於: v0.1.1

• <string>

在服務器請求中，該屬性返回客戶端發送的 HTTP 版本。 在客戶端響應中，該屬性返回鏈接到的服務器的 HTTP 版本。 可能的值有 '1.1' 或 '1.0'。

message.httpVersionMajor 返回 HTTP 版本的第一個整數值，message.httpVersionMinor 返回 HTTP 版本的第二個整數值。

message.method#

查看英文版 / 參與翻譯

新增於: v0.1.1

• <string>

僅在 http.Server 返回的請求中有效。

返回一個字符串，表示請求的方法。 該屬性只讀。 例如：'GET'、'DELETE'。

message.rawHeaders#

查看英文版 / 參與翻譯

新增於: v0.11.6

• <Array>

接收到的原始的請求頭或響應頭列表。

注意，鍵和值在同一個列表中。 偶數位的是鍵，奇數位的是對應的值。

頭信息的名稱不會被轉換爲小寫，重複的也不會被合併。

// 輸出相似如下的東西： // // [ 'user-agent', // 'this is invalid because there can be only one', // 'User-Agent', // 'curl/7.22.0', // 'Host', // '127.0.0.1:8000', // 'ACCEPT', // '*/*' ] console.log(request.rawHeaders); 

message.rawTrailers#

查看英文版 / 參與翻譯

新增於: v0.11.6

• <Array>

接收到的原始的 Trailer 請求頭或響應頭的的鍵和值。 只在 'end' 事件時被賦值。

message.setTimeout(msecs, callback)#

查看英文版 / 參與翻譯

新增於: v0.5.9

• msecs <number>
• callback <Function>

調用 message.connection.setTimeout(msecs, callback)。

返回 message。

message.socket#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <net.Socket>

返回與鏈接關聯的 net.Socket 對象。

經過 HTTPS 的支持，使用 request.socket.getPeerCertificate() 獲取客戶端的認證信息。

message.statusCode#

查看英文版 / 參與翻譯

新增於: v0.1.1

• <number>

僅在 http.ClientRequest 返回的響應中有效。

返回一個三位數的 HTTP 響應狀態碼。 如 404。

message.statusMessage#

查看英文版 / 參與翻譯

新增於: v0.11.10

• <string>

僅在 http.ClientRequest 返回的響應中有效。

返回 HTTP 響應狀態消息（緣由描述）。 如 OK 或 Internal Server Error。

message.trailers#

查看英文版 / 參與翻譯

新增於: v0.3.0

• <Object>

返回 Trailer 請求頭或響應頭對象。 只在 'end' 事件時被賦值。

message.url#

查看英文版 / 參與翻譯

新增於: v0.1.90

• <string>

僅在 http.Server 返回的請求中有效。

返回請求的 URL 字符串。 僅包含實際 HTTP 請求中的 URL。 若是請求是：

GET /status?name=ryan HTTP/1.1\r\n Accept: text/plain\r\n \r\n 

則 request.url 會是：

'/status?name=ryan' 

若是想將 url 解析成各個部分，可使用 require('url').parse(request.url)。 例子：

$ node
> require('url').parse('/status?name=ryan') Url { protocol: null, slashes: null, auth: null, host: null, port: null, hostname: null, hash: null, search: '?name=ryan', query: 'name=ryan', pathname: '/status', path: '/status?name=ryan', href: '/status?name=ryan' } 

若是想從查詢字符串中提取參數，可使用 require('querystring').parse 函數、或爲 require('url').parse 的第二個參數傳入 true。 例子：

$ node
> require('url').parse('/status?name=ryan', true) Url { protocol: null, slashes: null, auth: null, host: null, port: null, hostname: null, hash: null, search: '?name=ryan', query: { name: 'ryan' }, pathname: '/status', path: '/status?name=ryan', href: '/status?name=ryan' } 

http.METHODS#

查看英文版 / 參與翻譯

新增於: v0.11.8

• <Array>

返回解析器支持的 HTTP 方法的列表。

http.STATUS_CODES#

查看英文版 / 參與翻譯

新增於: v0.1.22

• <Object>

返回標準的 HTTP 響應狀態碼的集合，以及各自的簡短描述。 例如，http.STATUS_CODES[404] === 'Not Found'。

http.createServer([requestListener])#

查看英文版 / 參與翻譯

新增於: v0.1.13

• requestListener <Function>

• 返回: <http.Server>

返回一個新建的 http.Server 實例。

requestListener 是一個函數，會被自動添加到 'request' 事件。

http.get(options[, callback])#

查看英文版 / 參與翻譯

版本歷史

• options <Object> | <string> | <URL> Accepts the same options as http.request(), with the method always set to GET. Properties that are inherited from the prototype are ignored.
• callback <Function>
• 返回: <http.ClientRequest>

由於大多數請求都是 GET 請求且不帶請求主體，因此 Node.js 提供了該便捷方法。 該方法與 http.request() 惟一的區別是它設置請求方法爲 GET 且自動調用 req.end()。 注意，響應數據必須在回調中被消耗，緣由詳見 http.ClientRequest 章節。

callback 被調用時只傳入一個參數，該參數是 http.IncomingMessage 的一個實例。

一個獲取 JSON 的例子：

http.get('http://nodejs.org/dist/index.json', (res) => { const { statusCode } = res; const contentType = res.headers['content-type']; let error; if (statusCode !== 200) { error = new Error('請求失敗。\n' + `狀態碼: ${statusCode}`); } else if (!/^application\/json/.test(contentType)) { error = new Error('無效的 content-type.\n' + `指望 application/json 但獲取的是 ${contentType}`); } if (error) { console.error(error.message); // 消耗響應數據以釋放內存 res.resume(); return; } res.setEncoding('utf8'); let rawData = ''; res.on('data', (chunk) => { rawData += chunk; }); res.on('end', () => { try { const parsedData = JSON.parse(rawData); console.log(parsedData); } catch (e) { console.error(e.message); } }); }).on('error', (e) => { console.error(`錯誤: ${e.message}`); }); 

http.globalAgent#

查看英文版 / 參與翻譯

新增於: v0.5.9

• <http.Agent>

Agent 的全局實例，做爲全部 HTTP 客戶端請求的默認 Agent。

http.request(options[, callback])#

查看英文版 / 參與翻譯

版本歷史

• options <Object> | <string> | <URL>
  • protocol <string> 使用的協議。默認爲 http:。
  • host <string> 請求發送至的服務器的域名或 IP 地址。默認爲 localhost。
  • hostname <string> host 的別名。爲了支持 url.parse()，hostname 優於 host。
  • family <number> 當解析 host 和 hostname 時使用的 IP 地址族。 有效值是 4 或 6。當未指定時，則同時使用 IP v4 和 v6。
  • port <number> 遠程服務器的端口。默認爲 80。
  • localAddress <string> 爲網絡鏈接綁定的本地接口。
  • socketPath <string> Unix 域 Socket（使用 host:port 或 socketPath）。
  • method <string> 指定 HTTP 請求方法的字符串。默認爲 'GET'。
  • path <string> 請求的路徑。默認爲 '/'。 應包括查詢字符串（若有的話）。如 '/index.html?page=12'。 當請求的路徑中包含非法字符時，會拋出異常。 目前只有空字符會被拒絕，但將來可能會變化。
  • headers <Object> 包含請求頭的對象。
  • auth <string> 基自己份驗證，如 'user:password' 用來計算 Authorization 請求頭。
  • agent <http.Agent> | <boolean> 控制 Agent 的行爲。 可能的值有：
    • undefined (默認): 對該主機和端口使用 http.globalAgent。
    • Agent 對象：顯式地使用傳入的 Agent。
    • false: 建立一個新的使用默認值的 Agent。
  • createConnection <Function> 當不使用 agent 選項時，爲請求建立一個 socket 或流。 這能夠用於避免僅僅建立一個自定義的 Agent 類來覆蓋默認的 createConnection 函數。詳見 agent.createConnection()。
  • timeout <number>: 指定 socket 超時的毫秒數。 它設置了 socket 等待鏈接的超時時間。
• callback <Function>
• 返回: <http.ClientRequest>

Node.js 爲每臺服務器維護多個鏈接來進行 HTTP 請求。 該函數容許顯式地發出請求。

options 能夠是一個對象、或字符串、或 URL 對象。 若是 options 是一個字符串，它會被自動使用 url.parse() 解析。 If it is a URL object, it will be automatically converted to an ordinary options object.

可選的 callback 參數會做爲單次監聽器被添加到 'response' 事件。

http.request() 返回一個 http.ClientRequest 類的實例。 ClientRequest 實例是一個可寫流。 若是須要經過 POST 請求上傳一個文件，則寫入到 ClientRequest 對象。

例子：

const postData = querystring.stringify({ 'msg' : 'Hello World!' }); const options = { hostname: 'www.google.com', port: 80, path: '/upload', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; const req = http.request(options, (res) => { console.log(`狀態碼: ${res.statusCode}`); console.log(`響應頭: ${JSON.stringify(res.headers)}`); res.setEncoding('utf8'); res.on('data', (chunk) => { console.log(`響應主體: ${chunk}`); }); res.on('end', () => { console.log('響應中已無數據。'); }); }); req.on('error', (e) => { console.error(`請求遇到問題: ${e.message}`); }); // 寫入數據到請求主體 req.write(postData); req.end(); 

注意，在例子中調用了 req.end()。 使用 http.request() 必須老是調用 req.end() 來代表請求的結束，即便沒有數據被寫入請求主體。

若是請求過程當中遇到任何錯誤（DNS 解析錯誤、TCP 級的錯誤、或實際的 HTTP 解析錯誤），則在返回的請求對象中會觸發 'error' 事件。 對於全部的 'error' 事件，若是沒有註冊監聽器，則拋出錯誤。

如下是須要注意的幾個特殊的請求頭。

• 發送 'Connection: keep-alive' 會通知 Node.js，服務器的鏈接應一直持續到下一個請求。

• 發送 'Content-Length' 請求頭會禁用默認的塊編碼。

• 發送 'Expect' 請求頭會當即發送請求頭。 一般狀況下，當發送 'Expect: 100-continue' 時，超時時間與 continue 事件的監聽器都須要被設置。 詳見 RFC2616 章節 8.2.3。

• 發送 Authorization 請求頭會替代 auth 選項計算基自己份驗證。

Example using a URL as options:

const { URL } = require('url'); const options = new URL('http://abc:xyz@example.com'); const req = http.request(options, (res) => { // ... });