Node.js http.request(url[, options][, callback])用法及代码示例

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

参数

• url <string> | <URL>
• options <Object>
  • agent http.Agent|<boolean>控件http.Agent行为。可能的值：
    • undefined(默认)：为此主机和端口使用 http.globalAgent 。
    • Agent 对象：显式使用传入的 Agent 。
    • false ：导致使用具有默认值的新 Agent。
  • auth <string> 基本身份验证 ('user:password') 以计算授权标头。
  • createConnection <Function> 在不使用 agent 选项时生成用于请求的套接字/流的函数。这可用于避免创建自定义 Agent 类只是为了覆盖默认 createConnection 函数。有关详细信息，请参阅 agent.createConnection() 。任何 Duplex 流都是有效的返回值。
  • defaultPort <number> 协议的默认端口。 默认： agent.defaultPort 如果使用 Agent，否则 undefined 。
  • family <number> 解析 host 或 hostname 时使用的 IP 地址系列。有效值为 4 或 6 。未指定时，将使用 IP v4 和 v6。
  • headers <Object> 包含请求标头的对象。
  • hints <number>可选的dns.lookup() 提示.
  • host <string> 向其发出请求的服务器的域名或 IP 地址。 默认： 'localhost' 。
  • hostname <string> host 的别名。为了支持 url.parse() ，如果同时指定了 host 和 hostname，则将使用 hostname。
  • insecureHTTPParser <boolean> 使用不安全的 HTTP 解析器，在 true 时接受无效的 HTTP 标头。应避免使用不安全的解析器。有关详细信息，请参阅 --insecure-http-parser 。 默认： false
  • localAddress <string> 为网络连接绑定的本地接口。
  • localPort <number> 要连接的本地端口。
  • lookup <Function> 自定义查找函数。 默认： dns.lookup() 。
  • maxHeaderSize <number> 对于从服务器接收到的响应，可选择覆盖 --max-http-header-size 的值(响应标头的最大长度，以字节为单位)。 默认： 16384 (16 KiB)。
  • method <string> 指定 HTTP 请求方法的字符串。 默认： 'GET' 。
  • path <string> 请求路径。如果有的话，应该包括查询字符串。例如： '/index.html?page=12' 。当请求路径包含非法字符时会抛出异常。目前，只有空格被拒绝，但将来可能会改变。 默认： '/' 。
  • port <number> 远程服务器的端口。 默认： defaultPort 如果设置，否则 80 。
  • protocol <string> 要使用的协议。 默认： 'http:' 。
  • setHost <boolean> ：指定是否自动添加 Host 标头。默认为 true 。
  • socketPath <string> Unix 域套接字。如果指定了 host 或 port 之一，则不能使用，因为它们指定了 TCP 套接字。
  • timeout <number> ：一个数字，以毫秒为单位指定套接字超时。这将在套接字连接之前设置超时。
  • signal <AbortSignal> ：一个AbortSignal，可用于中止正在进行的请求。
• callback <Function>
• 返回： <http.ClientRequest>

还支持 socket.connect() 中的options。

Node.js 为每个服务器维护多个连接以发出 HTTP 请求。此函数允许透明地发出请求。

url 可以是字符串或 URL 对象。如果 url 是一个字符串，它会被自动解析为 new URL() 。如果是 URL 对象，会自动转换为普通的options对象。

如果同时指定url 和options，则合并对象，优先使用options 属性。

可选的 callback 参数将被添加为 'response' 事件的一次性侦听器。

http.request() 返回 http.ClientRequest 类的实例。 ClientRequest 实例是可写流。如果需要通过 POST 请求上传文件，则写入 ClientRequest 对象。

const http = require('node:http');

const postData = JSON.stringify({
  'msg': 'Hello World!'
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    '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();

在示例中调用了 req.end()。对于http.request()，必须始终调用req.end() 来表示请求的结束——即使没有数据写入请求正文。

如果在请求期间遇到任何错误(包括 DNS 解析、TCP 级别错误或实际 HTTP 解析错误)，则会在返回的请求对象上发出 'error' 事件。与所有 'error' 事件一样，如果未注册任何侦听器，则会引发错误。

有一些特殊的标题需要注意。

• 发送 'Connection: keep-alive' 将通知 Node.js 与服务器的连接应该持续到下一个请求。

• 发送 'Content-Length' 标头将禁用默认的分块编码。

• 发送 'Expect' 标头将立即发送请求标头。通常，在发送'Expect: 100-continue' 时，应同时设置超时和'continue' 事件的侦听器。有关详细信息，请参阅 RFC 2616 第 8.2.3 节。

• 发送 Authorization 标头将覆盖使用 auth 选项来计算基本身份验证。

使用 URL 作为 options 的示例：

const options = new URL('http://abc:[email protected]');

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

在成功的请求中，将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 'data' 任意次数，在 res 对象上(如果响应正文为空，则根本不会发出 'data'，例如，在大多数重定向中)
  • 'end' 在 res 对象上
• 'close'

在连接错误的情况下，将发出以下事件：

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

如果在收到响应之前连接过早关闭，将按以下顺序发出以下事件：

• 'socket'
• 'error' 带有错误消息 'Error: socket hang up' 和代码 'ECONNRESET'
• 'close'

在收到响应后过早关闭连接的情况下，将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 'data' 任意次数，在 res 对象上
• (此处关闭连接)
• 'aborted' 在 res 对象上
• res 对象上的 'error' 带有错误消息 'Error: aborted' 和代码 'ECONNRESET' 。
• 'close'
• 'close' 在 res 对象上

如果在分配套接字之前调用req.destroy()，则将按以下顺序发出以下事件：

• (这里调用req.destroy())
• 'error' 带有错误消息 'Error: socket hang up' 和代码 'ECONNRESET'
• 'close'

如果在连接成功之前调用req.destroy()，则会按以下顺序发出以下事件：

• 'socket'
• (这里调用req.destroy())
• 'error' 带有错误消息 'Error: socket hang up' 和代码 'ECONNRESET'
• 'close'

如果在收到响应后调用req.destroy()，则会按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 'data' 任意次数，在 res 对象上
• (这里调用req.destroy())
• 'aborted' 在 res 对象上
• res 对象上的 'error' 带有错误消息 'Error: aborted' 和代码 'ECONNRESET' 。
• 'close'
• 'close' 在 res 对象上

如果在分配套接字之前调用req.abort()，则将按以下顺序发出以下事件：

• (这里调用req.abort())
• 'abort'
• 'close'

如果在连接成功之前调用req.abort()，则会按以下顺序发出以下事件：

• 'socket'
• (这里调用req.abort())
• 'abort'
• 'error' 带有错误消息 'Error: socket hang up' 和代码 'ECONNRESET'
• 'close'

如果在收到响应后调用req.abort()，则会按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 'data' 任意次数，在 res 对象上
• (这里调用req.abort())
• 'abort'
• 'aborted' 在 res 对象上
• res 对象上的 'error' 带有错误消息 'Error: aborted' 和代码 'ECONNRESET' 。
• 'close'
• 'close' 在 res 对象上

设置 timeout 选项或使用 setTimeout() 函数不会中止请求或执行任何操作，除了添加 'timeout' 事件。

传递 AbortSignal 然后在相应的 AbortController 上调用 abort 的行为与在请求本身上调用 .destroy() 的方式相同。