Node.js v11.14.0 文档


目录

http(HTTP)#

中英对照提交修改

稳定性: 2 - 稳定

要使用 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 类#

查看v10.x中文文档

An Agent is responsible for managing connection persistence and reuse for HTTP clients. It maintains a queue of pending requests for a given host and port, reusing a single socket connection for each until the queue is empty, at which time the socket is either destroyed or put into a pool where it is kept to be used again for requests to the same host and port. Whether it is destroyed or pooled depends on the keepAlive option.

Pooled connections have TCP Keep-Alive enabled for them, but servers may still close idle connections, in which case they will be removed from the pool and a new connection will be made when a new HTTP request is made for that host and port. Servers may also refuse to allow multiple requests over the same connection, in which case the connection will have to be remade for every request and cannot be pooled. The Agent will still make the requests to that server, but each one will occur over a new connection.

When a connection is closed by the client or the server, it is removed from the pool. Any unused sockets in the pool will be unrefed so as not to keep the Node.js process running when there are no outstanding requests. (see socket.unref()).

It is good practice, to destroy() an Agent instance when it is no longer in use, because unused sockets consume OS resources.

Sockets are removed from an agent when the socket emits either a 'close' event or an 'agentRemove' event. When intending to keep one HTTP request open for a long time without keeping it in the agent, something like the following may be done:

http.get(options, (res) => {
  // Do stuff
}).on('socket', (socket) => {
  socket.emit('agentRemove');
});

An agent may also be used for an individual request. By providing {agent: false} as an option to the http.get() or http.request() functions, a one-time use Agent with default options will be used for the client connection.

agent:false:

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false  // Create a new agent just for this one request
}, (res) => {
  // Do stuff with response
});

new Agent([options])#

查看v10.x中文文档

  • options <Object> Set of configurable options to set on the agent. Can have the following fields:

    • keepAlive <boolean> Keep sockets around even when there are no outstanding requests, so they can be used for future requests without having to reestablish a TCP connection. Not to be confused with the keep-alive value of the Connection header. The Connection: keep-alive header is always sent when using an agent except when the Connection header is explicitly specified or when the keepAlive and maxSockets options are respectively set to false and Infinity, in which case Connection: close will be used. Default: false.
    • keepAliveMsecs <number> When using the keepAlive option, specifies the initial delay for TCP Keep-Alive packets. Ignored when the keepAlive option is false or undefined. Default: 1000.
    • maxSockets <number> Maximum number of sockets to allow per host. Each request will use a new socket until the maximum is reached. Default: Infinity.
    • maxFreeSockets <number> Maximum number of sockets to leave open in a free state. Only relevant if keepAlive is set to true. Default: 256.
    • timeout <number> Socket timeout in milliseconds. This will set the timeout when the socket is created.

options in socket.connect() are also supported.

The default http.globalAgent that is used by http.request() has all of these values set to their respective defaults.

To configure any of them, a custom http.Agent instance must be created.

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

agent.createConnection(options[, callback])#

中英对照提交修改

生成用于 HTTP 请求的套接字或流。

默认情况下,此函数与 net.createConnection() 相同。 但是,如果需要更大的灵活性,自定义代理可能会覆盖此方法。

可以通过以下两种方式之一提供套接字或流:通过从此函数返回套接字或流,或者通过将套接字或流传给 callback

callback 的参数是 (err, stream)

agent.keepSocketAlive(socket)#

中英对照提交修改

socket 与请求分离并且可以由 Agent 保留时调用。 默认行为是:

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true;

此方法可以由特定的 Agent 子类重写。 如果此方法返回一个假值,则将销毁套接字而不是将其保留以用于下一个请求。

agent.reuseSocket(socket, request)#

中英对照提交修改

由于 keep-alive 选项而在持久化后将 socket 附加到 request 时调用。 默认行为是:

socket.ref();

此方法可以由特定的 Agent 子类重写。

agent.destroy()#

中英对照提交修改

销毁代理当前使用的所有套接字。

通常没有必要这样做。 但是,如果使用启用了 keepAlive 的代理,则最好在代理不再使用时显式关闭代理。 否则,在服务器终止套接字之前,套接字可能会挂起很长时间。

agent.freeSockets#

中英对照提交修改

一个对象,其中包含当启用 keepAlive 时代理正在等待使用的套接字数组。 不要修改。

agent.getName(options)#

中英对照提交修改

  • options <Object> 一组选项,为生成名称提供信息。

    • host <string> 请求发送至的服务器的域名或 IP 地址。
    • port <number> 远程服务器的端口。
    • localAddress <string> 为网络连接绑定的本地接口。
    • family <integer> 如果不等于 undefined,则必须为 4 或 6。
  • 返回: <string>

获取一组请求选项的唯一名称,以判定一个连接是否可以被重用。 对于 HTTP 代理,这返回 host:port:localAddresshost:port:localAddress:family。 对于 HTTPS 代理,该名称包括 CA、证书、密码、以及其他可判定套接字可重用性的 HTTPS/TLS 特有的选项。

agent.maxFreeSockets#

中英对照提交修改

默认设置为 256。 对于启用了 keepAlive 的代理,这将设置在空闲状态下保持打开的最大套接字数。

agent.maxSockets#

中英对照提交修改

默认情况下设置为 Infinity。 决定代理可以为每个来源打开多少并发套接字。 来源是 agent.getName() 的返回值。

agent.requests#

中英对照提交修改

一个对象,包含尚未分配给套接字的请求队列。 不要修改。

agent.sockets#

中英对照提交修改

一个对象,包含当前代理正在使用的套接字数组。 不要修改。

http.ClientRequest 类#

中英对照提交修改

此对象由 http.request() 内部创建并返回。 它表示正在进行的请求,且其请求头已进入队列。 请求头仍然可以使用 setHeader(name, value)getHeader(name)removeHeader(name) 改变。 实际的请求头将与第一个数据块一起发送,或者当调用 request.end() 时发送。

要获得响应,则为请求对象添加 'response' 事件监听器。 当接收到响应头时,将、则会从请求对象触发 'response' 事件。 'response' 事件执行时有一个参数,该参数是 http.IncomingMessage 的实例。

'response' 事件期间,可以添加监听器到响应对象,比如监听 'data' 事件。

如果没有添加 'response' 事件处理函数,则响应将被完全丢弃。 如果添加了 'response' 事件处理函数,则必须消费完响应对象中的数据,每当有 'readable' 事件时调用 response.read()、或添加 'data' 事件处理函数、或通过调用 .resume() 方法。 在消费完数据之前,不会触发 'end' 事件。 此外,在读取数据之前,它将占用内存,最终可能导致进程内存不足的错误。

Node.js 不检查 Content-Length 和已传输的主体的长度是否相等。

请求继承自,且额外实现以下内容:

'abort' 事件#

中英对照提交修改

当请求被客户端中止时触发。 此事件仅在第一次调用 abort() 时触发。

'connect' 事件#

查看v10.x中文文档

Emitted each time a server responds to a request with a CONNECT method. If this event is not being listened for, clients receiving a CONNECT method will have their connections closed.

A client and server pair demonstrating how to listen for the 'connect' event:

const http = require('http');
const net = require('net');
const url = require('url');

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, cltSocket, head) => {
  // connect to an origin server
  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);
  });
});

// now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  const options = {
    port: 1337,
    host: '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('got connected!');

    // Make a request over an HTTP tunnel
    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' 事件#

中英对照提交修改

当服务器发送 100 Continue HTTP 响应时触发,通常是因为请求包含 Expect: 100-continue。 这是客户端应发送请求主体的指令。

'information' 事件#

查看v10.x中文文档

Emitted when the server sends a 1xx response (excluding 101 Upgrade). The listeners of this event will receive an object containing the status code.

const http = require('http');

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request'
};

// Make a request
const req = http.request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});

101 Upgrade statuses do not fire this event due to their break from the traditional HTTP request/response chain, such as web sockets, in-place TLS upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the 'upgrade' event instead.

'response' 事件#

中英对照提交修改

当收到此请求的响应时触发。 此事件仅触发一次。

'socket' 事件#

中英对照提交修改

将套接字分配给此请求后触发。

'timeout' 事件#

中英对照提交修改

当底层套接字因不活动而超时时触发。 这只会通知套接字已空闲。 必须手动中止请求。

另请参见:request.setTimeout()

'upgrade' 事件#

中英对照提交修改

每次服务器响应升级请求时发出。 如果未监听此事件且响应状态码为 101 Switching Protocols,则接收升级响应头的客户端将关闭其连接。

客户端服务器对,演示如何监听 'upgrade' 事件。

const http = require('http');

// 创建 HTTP 服务器。
const srv = http.createServer( (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('响应内容');
});
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,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket'
    }
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('接收到响应');
    socket.end();
    process.exit(0);
  });
});

request.abort()#

中英对照提交修改

将请求标记为中止。 调用此方法将导致响应中剩余的数据被丢弃并且套接字被销毁。

request.aborted#

查看v10.x中文文档

The request.aborted property will be true if the request has been aborted.

request.connection#

中英对照提交修改

请参阅 request.socket

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

中英对照提交修改

完成发送请求。 如果部分请求主体还未发送,则将它们刷新到流中。 如果请求被分块,则发送终止符 '0\r\n\r\n'

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

如果指定了 callback,则当请求流完成时将调用它。

request.finished#

中英对照提交修改

如果调用了 request.end(),则 request.finished 属性将为 true。 如果请求是通过 http.get() 发起的,则会自动调用 request.end()

request.flushHeaders()#

中英对照提交修改

刷新请求头。

出于效率原因,Node.js 通常会缓冲请求头,直到调用 request.end() 或写入第一个请求数据块。 然后,它尝试将请求头和数据打包到单个 TCP 数据包中。

这通常是期望的(它节省了 TCP 往返),但是可能很晚才发送第一个数据。 request.flushHeaders() 绕过优化并启动请求。

request.getHeader(name)#

中英对照提交修改

读取请求中的一个请求头。 注意,该名称不区分大小写。 返回值的类型取决于提供给 request.setHeader() 的参数。

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// contentType 是 'text/html'。
const contentLength = request.getHeader('Content-Length');
// contentLength 的类型为数值。
const cookie = request.getHeader('Cookie');
// cookie 的类型为字符串数组。

request.maxHeadersCount#

中英对照提交修改

限制最大响应头数。 如果设置为 0,则不会应用任何限制。

request.path#

暂无中英对照

request.removeHeader(name)#

中英对照提交修改

移除已定义到请求头对象中的请求头。

request.removeHeader('Content-Type');

request.setHeader(name, value)#

中英对照提交修改

为请求头对象设置单个请求头的值。 如果此请求头已存在于待发送的请求头中,则其值将被替换。 这里可以使用字符串数组来发送具有相同名称的多个请求头。 非字符串值将被原样保存。 因此 request.getHeader() 可能会返回非字符串值。 但是非字符串值将转换为字符串以进行网络传输。

request.setHeader('Content-Type', 'application/json');

或:

request.setHeader('Cookie', ['type=ninja', 'language=javascript']);

request.setNoDelay([noDelay])#

中英对照提交修改

一旦将套接字分配给此请求并且连接了套接字,就会调用 socket.setNoDelay()

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

中英对照提交修改

一旦将套接字分配给此请求并连接了套接字,就会调用 socket.setKeepAlive()

request.setTimeout(timeout[, callback])#

查看v10.x中文文档

  • timeout <number> Milliseconds before a request times out.
  • callback <Function> Optional function to be called when a timeout occurs. Same as binding to the 'timeout' event.
  • Returns: <http.ClientRequest>

Once a socket is assigned to this request and is connected socket.setTimeout() will be called.

request.socket#

中英对照提交修改

指向底层套接字。 通常用户无需访问此属性。 特别是,由于协议解析器附加到套接字的方式,套接字将不会触发 'readable' 事件。 也可以通过 request.connection 访问 socket

const http = require('http');
const options = {
  host: 'nodejs.cn',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`您的 IP 地址是 ${ip},源端口是 ${port}`);
  // 使用响应对象。
});

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

中英对照提交修改

发送一个请求主体的数据块。 通过多次调用此方法,可以将请求主体发送到服务器,在这种情况下,建议在创建请求时使用 ['Transfer-Encoding', 'chunked'] 请求头行。

encoding 参数是可选的,仅当 chunk 是字符串时才适用。 默认为 'utf8'

callback 参数是可选的,当刷新此数据块时调用,但仅当数据块非空时才会调用。

如果将整个数据成功刷新到内核缓冲区,则返回 true。 如果全部或部分数据在用户内存中排队,则返回 false。 当缓冲区再次空闲时,则触发 'drain' 事件。

当使用空字符串或 buffer 调用 write 函数时,则什么也不做且等待更多输入。

http.Server 类#

中英对照提交修改

此类继承自 net.Server 并具有以下额外的事件:

'checkContinue' 事件#

中英对照提交修改

每次收到 HTTP Expect: 100-continue 的请求时都会触发。 如果未监听此事件,服务器将自动响应 100 Continue

处理此事件时,如果客户端应继续发送请求主体,则调用 response.writeContinue(),如果客户端不应继续发送请求主体,则生成适当的 HTTP 响应(例如 400 Bad Request)。

请注意,在触发和处理此事件时,不会触发 'request' 事件。

'checkExpectation' 事件#

中英对照提交修改

每次收到带有 HTTP Expect 请求头的请求时触发,其中值不是 100-continue。 如果未监听此事件,则服务器将根据需要自动响应 417 Expectation Failed

请注意,在触发和处理此事件时,不会触发 'request' 事件。

'clientError' 事件#

中英对照提交修改

如果客户端连接触发 'error' 事件,则会在此处转发。 此事件的监听器负责关闭或销毁底层套接字。 例如,用户可能希望使用自定义 HTTP 响应更优雅地关闭套接字,而不是突然切断连接。

默认行为是尽可能使用 HTTP 400 Bad Request 响应关闭套接字,否则立即销毁套接字。

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' 事件发生时,没有 requestresponse 对象,因此必须将发送的任何 HTTP 响应(包括响应头和有效负载)直接写入 socket 对象。 必须注意确保响应是格式正确的 HTTP 响应消息。

errError 实例,有以下两个额外的部分:

  • bytesParsed: Node.js 可能正确解析的请求包的字节数。
  • rawPacket: 当前请求的原始数据包。

'close' 事件#

中英对照提交修改

当服务器关闭时触发。

'connect' 事件#

中英对照提交修改

每次客户端请求 HTTP CONNECT 方法时触发。 如果未监听此事件,则请求 CONNECT 方法的客户端将关闭其连接。

触发此事件后,请求的套接字将没有 'data' 事件监听器,这意味着它需要绑定才能处理发送到该套接字上的服务器的数据。

'connection' 事件#

查看v10.x中文文档

This event is emitted when a new TCP stream is established. socket is typically an object of type net.Socket. Usually users will not want to access this event. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. The socket can also be accessed at request.connection.

This event can also be explicitly emitted by users to inject connections into the HTTP server. In that case, any Duplex stream can be passed.

If socket.setTimeout() is called here, the timeout will be replaced with server.keepAliveTimeout when the socket has served a request (if server.keepAliveTimeout is non-zero).

'request' 事件#

中英对照提交修改

每次有请求时都会触发。 注意,每个连接可能有多个请求(在 HTTP Keep-Alive 连接的情况下)。

'upgrade' 事件#

中英对照提交修改

每次客户端请求 HTTP 升级时发出。 监听此事件是可选的,客户端无法坚持更改协议。

触发此事件后,请求的套接字将没有 'data' 事件监听器,这意味着它需要绑定才能处理发送到该套接字上的服务器的数据。

server.close([callback])#

中英对照提交修改

停止服务器接受新连接。 请参见 net.Server.close()

server.headersTimeout#

查看v10.x中文文档

Limit the amount of time the parser will wait to receive the complete HTTP headers.

In case of inactivity, the rules defined in server.timeout apply. However, that inactivity based timeout would still allow the connection to be kept open if the headers are being sent very slowly (by default, up to a byte per 2 minutes). In order to prevent this, whenever header data arrives an additional check is made that more than server.headersTimeout milliseconds has not passed since the connection was established. If the check fails, a 'timeout' event is emitted on the server object, and (by default) the socket is destroyed. See server.timeout for more information on how timeout behavior can be customized.

server.listen()#

中英对照提交修改

启动 HTTP 服务器监听连接。 此方法与 net.Server 中的 server.listen() 相同。

server.listening#

中英对照提交修改

  • <boolean> 表明服务器是否正在监听连接。

server.maxHeadersCount#

中英对照提交修改

限制最大传入请求头数。 如果设置为 0,则不会应用任何限制。

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

中英对照提交修改

设置套接字的超时值,并在服务器对象上触发 'timeout' 事件,如果发生超时,则将套接字作为参数传入。

如果服务器对象上有 'timeout' 事件监听器,则将使用超时的套接字作为参数调用它。

默认情况下,服务器的超时值为 2 分钟,如果超时,套接字会自动销毁。 但是,如果将回调分配给服务器的 'timeout' 事件,则必须显式处理超时。

server.timeout#

中英对照提交修改

  • <number> 超时时间(以毫秒为单位)。默认值: 120000(2 分钟)。

认定套接字超时的不活动毫秒数。

值为 0 将禁用传入连接的超时行为。

套接字超时逻辑在连接时设置,因此更改此值仅影响到服务器的新连接,而不影响任何现有连接。

server.keepAliveTimeout#

中英对照提交修改

  • <number> 超时时间(以毫秒为单位)。默认值: 5000(5 秒)。

服务器在完成写入最后一个响应之后,在销毁套接字之前需要等待其他传入数据的非活动毫秒数。 如果服务器在保持活动超时被触发之前接收到新数据,它将重置常规非活动超时,即 server.timeout

值为 0 将禁用传入连接上的保持活动超时行为。 值为 0 使得 http 服务器的行为与 8.0.0 之前的 Node.js 版本类似,后者没有保持活动超时。

套接字超时逻辑在连接时设置,因此更改此值仅影响到服务器的新连接,而不影响任何现有连接。

http.ServerResponse 类#

中英对照提交修改

此对象由 HTTP 服务器在内部创建,而不是由用户创建。 它作为第二个参数传给 'request' 事件。

响应继承自,并额外实现以下内容:

'close' 事件#

查看v10.x中文文档

Indicates that the underlying connection was terminated.

'finish' 事件#

中英对照提交修改

响应发送后触发。 更具体地说,当响应头和主体的最后一段已经切换到操作系统以通过网络传输时,触发该事件。 这并不意味着客户端已收到任何信息。

response.addTrailers(headers)#

中英对照提交修改

此方法将 HTTP 尾部响应头(一种在消息末尾的响应头)添加到响应中。

只有在使用分块编码进行响应时才会发出尾部响应头; 如果不是(例如,如果请求是 HTTP/1.0),它们将被静默丢弃。

请注意,HTTP 需要发送 Trailer 响应头才能发出尾部响应头,并在其值中包含响应头字段列表。 例如:

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

尝试设置包含无效字符的响应头字段名称或值将导致抛出 TypeError

response.connection#

中英对照提交修改

参阅 response.socket

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

查看v10.x中文文档

This method signals to the server that all of the response headers and body have been sent; that server should consider this message complete. The method, response.end(), MUST be called on each response.

If data is specified, it is similar in effect to calling response.write(data, encoding) followed by response.end(callback).

If callback is specified, it will be called when the response stream is finished.

response.finished#

中英对照提交修改

布尔值,表明响应是否已完成。 默认为 false。 在 response.end() 执行之后,该值将为 true

response.getHeader(name)#

中英对照提交修改

读出已排队但未发送到客户端的响应头。 请注意,该名称不区分大小写。 返回值的类型取决于提供给 response.setHeader() 的参数。

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType 是 'text/html'。
const contentLength = response.getHeader('Content-Length');
// contentLength 的类型为数值。
const setCookie = response.getHeader('set-cookie');
// setCookie 的类型为字符串数组。

response.getHeaderNames()#

中英对照提交修改

返回一个数组,其中包含当前传出的响应头的唯一名称。 所有响应头名称都是小写的。

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie']

response.getHeaders()#

中英对照提交修改

返回当前传出的响应头的浅拷贝。 由于使用浅拷贝,因此可以更改数组的值而无需额外调用各种与响应头相关的 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)#

中英对照提交修改

如果当前在传出的响应头中设置了由 name 标识的响应头,则返回 true。 请注意,响应头名称匹配不区分大小写。

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

response.headersSent#

中英对照提交修改

布尔值(只读)。 如果已发送响应头,则为 true,否则为 false

response.removeHeader(name)#

中英对照提交修改

移除排队等待中的隐式发送的响应头。

response.removeHeader('Content-Encoding');

response.sendDate#

中英对照提交修改

如果为 true,则 Date 响应头将自动生成并在响应中发送(如果响应头中尚不存在)。 默认为 true

这应该仅在测试时才禁用,HTTP 响应需要 Date 响应头。

response.setHeader(name, value)#

查看v10.x中文文档

Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Non-string values will be stored without modification. Therefore, response.getHeader() may return non-string values. However, the non-string values will be converted to strings for network transmission.

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

or

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

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

// Returns 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');
});

If response.writeHead() method is called and this method has not been called, it will directly write the supplied header values onto the network channel without caching internally, and the response.getHeader() on the header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use response.setHeader() instead of response.writeHead().

response.setTimeout(msecs[, callback])#

中英对照提交修改

将套接字的超时值设置为 msecs。 如果提供了回调,则会将其作为监听器添加到响应对象上的 'timeout' 事件中。

如果没有 'timeout' 监听器添加到请求、响应、或服务器,则套接字在超时时将被销毁。 如果有回调处理函数分配给请求、响应、或服务器的 'timeout' 事件,则必须显式处理超时的套接字。

response.socket#

中英对照提交修改

指向底层的套接字。 通常用户不需要访问此属性。 特别是,由于协议解析器附加到套接字的方式,套接字将不会触发 'readable' 事件。 在调用 response.end() 之后,此属性将为空。 也可以通过 response.connection 访问 socket

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

response.statusCode#

中英对照提交修改

当使用隐式的响应头时(没有显式地调用 response.writeHead()),此属性控制在刷新响应头时将发送到客户端的状态码。

response.statusCode = 404;

响应头发送到客户端后,此属性表示已发送的状态码。

response.statusMessage#

中英对照提交修改

当使用隐式的响应头时(没有显式地调用 response.writeHead()),此属性控制在刷新响应头时将发送到客户端的状态消息。 如果保留为 undefined,则将使用状态码的标准消息。

response.statusMessage = 'Not found';

响应头发送到客户端后,此属性表示已发送的状态消息。

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

中英对照提交修改

如果调用此方法并且尚未调用 response.writeHead(),则将切换到隐式响应头模式并刷新隐式响应头。

这会发送一块响应主体。 可以多次调用该方法以提供连续的响应主体片段。

注意,在 http 模块中,当请求是 HEAD 请求时,则省略响应主体。 同样地, 204304 响应不得包含消息主体。

chunk 可以是字符串或 buffer。 如果 chunk 是一个字符串,则第二个参数指定如何将其编码为字节流。 当刷新此数据块时将调用 callback

这是原始的 HTTP 主体,与可能使用的更高级别的多部分主体编码无关。

第一次调用 response.write() 时,它会将缓冲的响应头信息和主体的第一个数据块发送给客户端。 第二次调用 response.write() 时,Node.js 假定数据将被流式传输,并分别发送新数据。 也就是说,响应被缓冲到主体的第一个数据块。

如果将整个数据成功刷新到内核缓冲区,则返回 true。 如果全部或部分数据在用户内存中排队,则返回 false。 当缓冲区再次空闲时,则触发 'drain' 事件。

response.writeContinue()#

中英对照提交修改

向客户端发送 HTTP/1.1 100 Continue 消息,表示应发送请求主体。 请参阅 Server 上的 'checkContinue' 事件。

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

查看v10.x中文文档

Sends a response header to the request. The status code is a 3-digit HTTP status code, like 404. The last argument, headers, are the response headers. Optionally one can give a human-readable statusMessage as the second argument.

Returns a reference to the ServerResponse, so that calls can be chained.

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

This method must only be called once on a message and it must be called before response.end() is called.

If response.write() or response.end() are called before calling this, the implicit/mutable headers will be calculated and call this function.

When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

If this method is called and response.setHeader() has not been called, it will directly write the supplied header values onto the network channel without caching internally, and the response.getHeader() on the header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use response.setHeader() instead.

// Returns 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');
});

Note that Content-Length is given in bytes not characters. The above example works because the string 'hello world' contains only single byte characters. If the body contains higher coded characters then Buffer.byteLength() should be used to determine the number of bytes in a given encoding. And Node.js does not check whether Content-Length and the length of the body which has been transmitted are equal or not.

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

response.writeProcessing()#

中英对照提交修改

向客户端发送 HTTP/1.1 102 处理消息,表明可以发送请求主体。

http.IncomingMessage 类#

中英对照提交修改

IncomingMessage 对象由 http.Serverhttp.ClientRequest 创建,并分别作为第一个参数传给 'request''response' 事件。 它可用于访问响应状态、消息头、以及数据。

它实现了可读流接口,还有以下额外的事件、方法、以及属性。

'aborted' 事件#

中英对照提交修改

当请求中止时触发。

'close' 事件#

查看v10.x中文文档

Indicates that the underlying connection was closed.

message.aborted#

中英对照提交修改

如果请求已中止,则 message.aborted 属性为 true

message.complete#

中英对照提交修改

如果已收到并成功解析完整的 HTTP 消息,则 message.complete 属性将为 true

此属性可用于判断客户端或服务器在连接终止之前是否完全传输消息:

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST'
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        '消息仍在发送时终止了连接');
  });
});

message.destroy([error])#

中英对照提交修改

在接收 IncomingMessage 的套接字上调用 destroy()。 如果提供了 error,则会触发 'error' 事件,并将 error 作为参数传递给事件上的任何监听器。

message.headers#

中英对照提交修改

请求或响应的消息头对象。

消息头的名称和值的键值对。 消息头的名称都是小写的。

// 打印类似以下:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers);

原始消息头中的重复项会按以下方式处理,具体取决于消息头的名称:

  • 重复的 ageauthorizationcontent-lengthcontent-typeetagexpiresfromhostif-modified-sinceif-unmodified-sincelast-modifiedlocationmax-forwardsproxy-authorizationrefererretry-afteruser-agent 会被丢弃。
  • set-cookie 始终是一个数组。重复项都会添加到数组中。
  • 对于重复的 cookie 消息头,其值会使用与 '; ' 连接到一起。
  • 对于所有其他消息头,其值会使用 ', ' 连接到一起。

message.httpVersion#

中英对照提交修改

在服务器请求的情况下,表示客户端发送的 HTTP 版本。 在客户端响应的情况下,表示连接到的服务器的 HTTP 版本。 可能是 '1.1''1.0'

另外, message.httpVersionMajor 是第一个整数, message.httpVersionMinor 是第二个整数。

message.method#

中英对照提交修改

仅对从 http.Server 获取的请求有效。

请求方法为字符串。 只读。 示例:'GET''DELETE'

message.rawHeaders#

中英对照提交修改

原始请求头/响应头的列表,与接收到的完全一致。

请注意,键和值位于同一列表中。 它不是元组列表。 因此,偶数偏移是键值,奇数偏移是关联的值。

消息头名称不是小写的,并且不会合并重复项。

// 打印类似于:
//
// [ 'user-agent',
//   '这是无效的,因为只能有一个值',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders);

message.rawTrailers#

中英对照提交修改

原始的请求/响应的尾部消息头的键和值,与接收到的完全一致。 仅在 'end' 事件中填充。

message.setTimeout(msecs, callback)#

中英对照提交修改

调用 message.connection.setTimeout(msecs, callback)

message.socket#

中英对照提交修改

与连接关联的 net.Socket 对象。

通过 HTTPS 的支持,使用 request.socket.getPeerCertificate() 获取客户端的身份验证详细信息。

message.statusCode#

中英对照提交修改

仅对从 http.ClientRequest 获取的响应有效。

3 位 HTTP 响应状态码。 例如 404

message.statusMessage#

中英对照提交修改

仅对从 http.ClientRequest 获取的响应有效。

HTTP 响应状态消息(原因短语)。 例如 OKInternal Server Error

message.trailers#

中英对照提交修改

请求/响应的尾部消息头对象。 仅在 'end' 事件中填充。

message.url#

中英对照提交修改

仅对从 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 函数,或者可以将 true 作为第二个参数传递给 require('url').parse

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

中英对照提交修改

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

http.STATUS_CODES#

中英对照提交修改

所有标准 HTTP 响应状态码的集合,以及每个状态码的简短描述。 例如, http.STATUS_CODES[404] === 'Not Found'

http.createServer([options][, requestlistener])#

查看v10.x中文文档

  • options <Object>

    • IncomingMessage <http.IncomingMessage> Specifies the IncomingMessage class to be used. Useful for extending the original IncomingMessage. Default: IncomingMessage.
    • ServerResponse <http.ServerResponse> Specifies the ServerResponse class to be used. Useful for extending the original ServerResponse. Default: ServerResponse.
  • requestListener <Function>

  • Returns: <http.Server>

Returns a new instance of http.Server.

The requestListener is a function which is automatically added to the 'request' event.

http.get(options[, callback])#

http.get(url[, options][, callback])#

查看v10.x中文文档

Since most requests are GET requests without bodies, Node.js provides this convenience method. The only difference between this method and http.request() is that it sets the method to GET and calls req.end() automatically. Note that the callback must take care to consume the response data for reasons stated in http.ClientRequest section.

The callback is invoked with a single argument that is an instance of http.IncomingMessage.

JSON fetching example:

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('Request Failed.\n' +
                      `Status Code: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Invalid content-type.\n' +
                      `Expected application/json but received ${contentType}`);
  }
  if (error) {
    console.error(error.message);
    // Consume response data to free up memory
    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(`Got error: ${e.message}`);
});

http.globalAgent#

中英对照提交修改

Agent 的全局实例,作为所有 HTTP 客户端请求的默认值。

http.maxHeaderSize#

查看v10.x中文文档

Read-only property specifying the maximum allowed size of HTTP headers in bytes. Defaults to 8KB. Configurable using the --max-http-header-size CLI option.

http.request(options[, callback])#

http.request(url[, options][, callback])#

查看v10.x中文文档

  • url <string> | <URL>
  • options <Object>

    • agent <http.Agent> | <boolean> Controls Agent behavior. Possible values:

      • undefined (default): use http.globalAgent for this host and port.
      • Agent object: explicitly use the passed in Agent.
      • false: causes a new Agent with default values to be used.
    • auth <string> Basic authentication i.e. 'user:password' to compute an Authorization header.
    • createConnection <Function> A function that produces a socket/stream to use for the request when the agent option is not used. This can be used to avoid creating a custom Agent class just to override the default createConnection function. See agent.createConnection() for more details. Any Duplex stream is a valid return value.
    • defaultPort <number> Default port for the protocol. Default: agent.defaultPort if an Agent is used, else undefined.
    • family <number> IP address family to use when resolving host or hostname. Valid values are 4 or 6. When unspecified, both IP v4 and v6 will be used.
    • headers <Object> An object containing request headers.
    • host <string> A domain name or IP address of the server to issue the request to. Default: 'localhost'.
    • hostname <string> Alias for host. To support url.parse(), hostname will be used if both host and hostname are specified.
    • localAddress <string> Local interface to bind for network connections.
    • method <string> A string specifying the HTTP request method. Default: 'GET'.
    • path <string> Request path. Should include query string if any. E.G. '/index.html?page=12'. An exception is thrown when the request path contains illegal characters. Currently, only spaces are rejected but that may change in the future. Default: '/'.
    • port <number> Port of remote server. Default: defaultPort if set, else 80.
    • protocol <string> Protocol to use. Default: 'http:'.
    • setHost <boolean>: Specifies whether or not to automatically add the Host header. Defaults to true.
    • socketPath <string> Unix Domain Socket (cannot be used if one of host or port is specified, those specify a TCP Socket).
    • timeout <number>: A number specifying the socket timeout in milliseconds. This will set the timeout before the socket is connected.
  • callback <Function>
  • Returns: <http.ClientRequest>

Node.js maintains several connections per server to make HTTP requests. This function allows one to transparently issue requests.

url can be a string or a URL object. If url is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

If both url and options are specified, the objects are merged, with the options properties taking precedence.

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

http.request() returns an instance of the http.ClientRequest class. The ClientRequest instance is a writable stream. If one needs to upload a file with a POST request, then write to the ClientRequest object.

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(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// write data to request body
req.write(postData);
req.end();

Note that in the example req.end() was called. With http.request() one must always call req.end() to signify the end of the request - even if there is no data being written to the request body.

If any error is encountered during the request (be that with DNS resolution, TCP level errors, or actual HTTP parse errors) an 'error' event is emitted on the returned request object. As with all 'error' events, if no listeners are registered the error will be thrown.

There are a few special headers that should be noted.

  • Sending a 'Connection: keep-alive' will notify Node.js that the connection to the server should be persisted until the next request.

  • Sending a 'Content-Length' header will disable the default chunked encoding.

  • Sending an 'Expect' header will immediately send the request headers. Usually, when sending 'Expect: 100-continue', both a timeout and a listener for the 'continue' event should be set. See RFC 2616 Section 8.2.3 for more information.

  • Sending an Authorization header will override using the auth option to compute basic authentication.

Example using a URL as options:

const options = new URL('http://abc:xyz@example.com');

const req = http.request(options, (res) => {
  // ...
});

In a successful request, the following events will be emitted in the following order:

  • 'socket'
  • 'response'

    • 'data' any number of times, on the res object ('data' will not be emitted at all if the response body is empty, for instance, in most redirects)
    • 'end' on the res object
  • 'close'

In the case of a connection error, the following events will be emitted:

  • 'socket'
  • 'error'
  • 'close'

If req.abort() is called before the connection succeeds, the following events will be emitted in the following order:

  • 'socket'
  • (req.abort() called here)
  • 'abort'
  • 'error' with an error with message 'Error: socket hang up' and code 'ECONNRESET'
  • 'close'

If req.abort() is called after the response is received, the following events will be emitted in the following order:

  • 'socket'
  • 'response'

    • 'data' any number of times, on the res object
  • (req.abort() called here)
  • 'abort'
  • 'aborted' on the res object
  • 'close'
  • 'end' on the res object
  • 'close' on the res object

Note that setting the timeout option or using the setTimeout() function will not abort the request or do anything besides add a 'timeout' event.