Node.js v12.4.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])#

中英对照提交修改

  • options <Object> 要在代理上设置的可配置选项集。可以包含以下字段:

    • keepAlive <boolean> 即使没有未完成的请求,也要保持套接字,这样它们就可以被用于将来的请求而无需重新建立 TCP 连接。默认值: false
    • keepAliveMsecs <number> 当使用 keepAlive 选项时,指定用于 TCP Keep-Alive 数据包的[初始延迟][initial delay]。当 keepAlive 选项为 falseundefined 时则忽略。默认值: 1000
    • maxSockets <number> 每个主机允许的套接字的最大数量。默认值: Infinity
    • maxFreeSockets <number> 在空闲状态下保持打开的套接字的最大数量。仅当 keepAlive 被设置为 true 时才相关。默认值: 256
    • timeout <number> 套接字的超时时间,以毫秒为单位。这会在套接字被连接之后设置超时时间。

socket.connect() 中的 options 也受支持。

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

中英对照提交修改

生成用于 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' 事件#

查看v10.x中文文档

Emitted each time a server responds to a request with an upgrade. If this event is not being listened for and the response status code is 101 Switching Protocols, clients receiving an upgrade header will have their connections closed.

A client server pair demonstrating how to listen for the 'upgrade' event.

const http = require('http');

// Create an HTTP server
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); // echo back
});

// Now that server is running
srv.listen(1337, '127.0.0.1', () => {

  // make a request
  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('got upgraded!');
    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)#

查看v10.x中文文档

Reads out a header on the request. Note that the name is case insensitive. The type of the return value depends on the arguments provided to 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' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[]

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

中英对照提交修改

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

request.socket#

查看v10.x中文文档

Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. The socket may also be accessed via request.connection.

const http = require('http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});

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' 事件#

查看v10.x中文文档

If a client connection emits an 'error' event, it will be forwarded here. Listener of this event is responsible for closing/destroying the underlying socket. For example, one may wish to more gracefully close the socket with a custom HTTP response instead of abruptly severing the connection.

Default behavior is to try close the socket with a HTTP '400 Bad Request', or a HTTP '431 Request Header Fields Too Large' in the case of a HPE_HEADER_OVERFLOW error. If the socket is not writable it is immediately destroyed.

socket is the net.Socket object that the error originated from.

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

When the 'clientError' event occurs, there is no request or response object, so any HTTP response sent, including response headers and payload, must be written directly to the socket object. Care must be taken to ensure the response is a properly formatted HTTP response message.

err is an instance of Error with two extra columns:

  • bytesParsed: the bytes count of request packet that Node.js may have parsed correctly;
  • rawPacket: the raw packet of current request.

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

查看v10.x中文文档

Sets the timeout value for sockets, and emits a 'timeout' event on the Server object, passing the socket as an argument, if a timeout occurs.

If there is a 'timeout' event listener on the Server object, then it will be called with the timed-out socket as an argument.

By default, the Server's timeout value is 2 minutes, and sockets are destroyed automatically if they time out. However, if a callback is assigned to the Server's 'timeout' event, timeouts must be handled explicitly.

To change the default timeout use the --http-server-default-timeout flag.

server.timeout#

查看v10.x中文文档

  • <number> Timeout in milliseconds. Default: 120000 (2 minutes).

The number of milliseconds of inactivity before a socket is presumed to have timed out.

A value of 0 will disable the timeout behavior on incoming connections.

The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections.

To change the default timeout use the --http-server-default-timeout flag.

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

中英对照提交修改

此方法向服务器发出信号,表明已发送所有响应头和主体,该服务器应该视为此消息已完成。 必须在每个响应上调用此 response.end() 方法。

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

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

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

中英对照提交修改

返回新建的 http.Server 实例。

requestListener 是一个自动添加到 'request' 事件的函数。

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.