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() 的方式相同。