clienthttp2session.request(headers[, options])

新增于: v8.4.0

  • headers <HTTP/2 Headers Object>

  • options <Object>

    • endStream <boolean> 如果 Http2Stream _可写_端最初应该关闭（例如发送不应期待有效负载正文的 GET 请求时），则为 true。
    • exclusive <boolean> 当 true 和 parent 标识父流时，创建的流将成为父流的唯一直接依赖项，所有其他现有依赖项都成为新创建流的依赖项。 默认值: false。
    • parent <number> 指定新创建的流所依赖的流的数字标识符。
    • weight <number> 指定流相对于具有相同 parent 的其他流的相对依赖性。 该值为 1 到 256（含）之间的数字。
    • waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送完最后的 DATA 帧后触发 'wantTrailers' 事件。
    • signal <AbortSignal> 可用于中止正在进行的请求的中止信号。

  • 返回: <ClientHttp2Stream>

仅对于 HTTP/2 客户端 Http2Session 实例，http2session.request() 创建并返回 Http2Stream 实例，该实例可用于向连接的服务器发送 HTTP/2 请求。

当第一次创建 ClientHttp2Session 时，套接字可能尚未连接。 如果在此期间调用 clienthttp2session.request()，则实际的请求将被推迟到套接字准备就绪。 如果在实际的请求执行之前关闭了 session，则抛出 ERR_HTTP2_GOAWAY_SESSION。

此方法仅在 http2session.type 等于 http2.constants.NGHTTP2_SESSION_CLIENT 时可用。

const http2 = require('node:http2');
const clientSession = http2.connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = http2.constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});

当设置了 options.waitForTrailers 选项时，在将要发送的最后一块有效负载数据排队后立即触发 'wantTrailers' 事件。 然后可以调用 http2stream.sendTrailers() 方法将尾随标头发送到对等方。

当设置了 options.waitForTrailers，则传输完最后的 DATA 帧时，Http2Stream 不会自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

当 options.signal 设置为 AbortSignal，然后调用相应 AbortController 上的 abort 时，则请求将使用 AbortError 错误触发 'error' 事件。

:method 和 :path 伪标头在 headers 中没有指定，它们分别默认为：

  • :method = 'GET'
  • :path = /
Added in: v8.4.0

  • headers <HTTP/2 Headers Object>

  • options <Object>

    • endStream <boolean> true if the Http2Stream writable side should be closed initially, such as when sending a GET request that should not expect a payload body.
    • exclusive <boolean> When true and parent identifies a parent Stream, the created stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of the newly created stream. Default: false.
    • parent <number> Specifies the numeric identifier of a stream the newly created stream is dependent on.
    • weight <number> Specifies the relative dependency of a stream in relation to other streams with the same parent. The value is a number between 1 and 256 (inclusive).
    • waitForTrailers <boolean> When true, the Http2Stream will emit the 'wantTrailers' event after the final DATA frame has been sent.
    • signal <AbortSignal> An AbortSignal that may be used to abort an ongoing request.

  • Returns: <ClientHttp2Stream>

For HTTP/2 Client Http2Session instances only, the http2session.request() creates and returns an Http2Stream instance that can be used to send an HTTP/2 request to the connected server.

When a ClientHttp2Session is first created, the socket may not yet be connected. if clienthttp2session.request() is called during this time, the actual request will be deferred until the socket is ready to go. If the session is closed before the actual request be executed, an ERR_HTTP2_GOAWAY_SESSION is thrown.

This method is only available if http2session.type is equal to http2.constants.NGHTTP2_SESSION_CLIENT.

const http2 = require('node:http2');
const clientSession = http2.connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = http2.constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});

When the options.waitForTrailers option is set, the 'wantTrailers' event is emitted immediately after queuing the last chunk of payload data to be sent. The http2stream.sendTrailers() method can then be called to send trailing headers to the peer.

When options.waitForTrailers is set, the Http2Stream will not automatically close when the final DATA frame is transmitted. User code must call either http2stream.sendTrailers() or http2stream.close() to close the Http2Stream.

When options.signal is set with an AbortSignal and then abort on the corresponding AbortController is called, the request will emit an 'error' event with an AbortError error.

The :method and :path pseudo-headers are not specified within headers, they respectively default to:

  • :method = 'GET'
  • :path = /