http.request(url[, options][, callback])
url
<string> | <URL>options
<Object>agent
<http.Agent> | <boolean> 控制Agent
的行为。 可能的值:undefined
(默认): 为此主机和端口使用http.globalAgent
。Agent
对象: 显式使用传入的Agent
。false
: 使用具有默认值的新Agent
。
auth
<string> 基本身份验证,即'user:password'
计算授权标头。createConnection
<Function> 当不使用agent
选项时,生成用于请求的套接字/流的函数。 这可用于避免创建自定义Agent
类只是为了覆盖默认的createConnection
函数。 有关详细信息,请参阅agent.createConnection()
。 任何Duplex
流都是有效的返回值。defaultPort
<number> 协议的默认端口。 默认值: 如果使用Agent
则为agent.defaultPort
,否则为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 (16KB).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>: 可用于中止正在进行的请求的中止信号。
callback
<Function>- 返回: <http.ClientRequest>
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('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}`);
});
// 将数据写入请求正文
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 节。 -
发送授权标头将覆盖使用
auth
选项来计算基本身份验证。
使用 URL
作为 options
的示例:
const options = new URL('http://abc:xyz@example.com');
const req = http.request(options, (res) => {
// ...
});
在成功的请求中,将按以下顺序触发以下事件:
'socket'
'response'
res
对象上的'data'
,任意次数(如果响应正文为空,则根本不会触发'data'
,例如,在大多数重定向中)res
对象上的'end'
'close'
在连接错误的情况下,将触发以下事件:
'socket'
'error'
'close'
在收到响应之前过早关闭连接的情况下,将按以下顺序触发以下事件:
'socket'
- 使用具有消息
'Error: socket hang up'
和代码'ECONNRESET'
的错误的'error'
'close'
在收到响应之后过早关闭连接的情况下,将按以下顺序触发以下事件:
'socket'
'response'
res
对象上的'data'
,任意次数
- (在此处关闭连接)
res
对象上的'aborted'
'close'
res
对象上的'close'
如果在分配套接字之前调用 req.destroy()
,则将按以下顺序触发以下事件:
- (在此处调用
req.destroy()
) - 使用具有消息
'Error: socket hang up'
和代码'ECONNRESET'
的错误的'error'
'close'
如果在连接成功之前调用 req.destroy()
,则将按以下顺序触发以下事件:
'socket'
- (在此处调用
req.destroy()
) - 使用具有消息
'Error: socket hang up'
和代码'ECONNRESET'
的错误的'error'
'close'
如果在收到响应之后调用 req.destroy()
,则将按以下顺序触发以下事件:
'socket'
'response'
res
对象上的'data'
,任意次数
- (在此处调用
req.destroy()
) res
对象上的'aborted'
'close'
res
对象上的'close'
如果在分配套接字之前调用 req.abort()
,则将按以下顺序触发以下事件:
- (在此处调用
req.abort()
) 'abort'
'close'
如果在连接成功之前调用 req.abort()
,则将按以下顺序触发以下事件:
'socket'
- (在此处调用
req.abort()
) 'abort'
- 使用具有消息
'Error: socket hang up'
和代码'ECONNRESET'
的错误的'error'
'close'
如果在收到响应之后调用 req.abort()
,则将按以下顺序触发以下事件:
'socket'
'response'
res
对象上的'data'
,任意次数
- (在此处调用
req.abort()
) 'abort'
res
对象上的'aborted'
'close'
res
对象上的'close'
设置 timeout
选项或使用 setTimeout()
函数将不会中止请求或执行除添加 'timeout'
事件外的任何操作。
传入 AbortSignal
然后在相应的 AbortController
上调用 abort
,与在请求本身上调用 .destroy()
的行为相同。
url
<string> | <URL>options
<Object>agent
<http.Agent> | <boolean> ControlsAgent
behavior. Possible values:undefined
(default): usehttp.globalAgent
for this host and port.Agent
object: explicitly use the passed inAgent
.false
: causes a newAgent
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 theagent
option is not used. This can be used to avoid creating a customAgent
class just to override the defaultcreateConnection
function. Seeagent.createConnection()
for more details. AnyDuplex
stream is a valid return value.defaultPort
<number> Default port for the protocol. Default:agent.defaultPort
if anAgent
is used, elseundefined
.family
<number> IP address family to use when resolvinghost
orhostname
. Valid values are4
or6
. When unspecified, both IP v4 and v6 will be used.headers
<Object> An object containing request headers.hints
<number> Optionaldns.lookup()
hints.host
<string> A domain name or IP address of the server to issue the request to. Default:'localhost'
.hostname
<string> Alias forhost
. To supporturl.parse()
,hostname
will be used if bothhost
andhostname
are specified.insecureHTTPParser
<boolean> Use an insecure HTTP parser that accepts invalid HTTP headers whentrue
. Using the insecure parser should be avoided. See--insecure-http-parser
for more information. Default:false
localAddress
<string> Local interface to bind for network connections.localPort
<number> Local port to connect from.lookup
<Function> Custom lookup function. Default:dns.lookup()
.maxHeaderSize
<number> Optionally overrides the value of--max-http-header-size
for requests received from the server, i.e. the maximum length of response headers in bytes. Default: 16384 (16KB).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, else80
.protocol
<string> Protocol to use. Default:'http:'
.setHost
<boolean>: Specifies whether or not to automatically add theHost
header. Defaults totrue
.socketPath
<string> Unix Domain Socket (cannot be used if one ofhost
orport
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.signal
<AbortSignal>: An AbortSignal that may be used to abort an ongoing request.
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 http = require('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();
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 theres
object ('data'
will not be emitted at all if the response body is empty, for instance, in most redirects)'end'
on theres
object
'close'
In the case of a connection error, the following events will be emitted:
'socket'
'error'
'close'
In the case of a premature connection close before the response is received, the following events will be emitted in the following order:
'socket'
'error'
with an error with message'Error: socket hang up'
and code'ECONNRESET'
'close'
In the case of a premature connection close after the response is received, the following events will be emitted in the following order:
'socket'
'response'
'data'
any number of times, on theres
object
- (connection closed here)
'aborted'
on theres
object'close'
'close'
on theres
object
If req.destroy()
is called before a socket is assigned, the following
events will be emitted in the following order:
- (
req.destroy()
called here) 'error'
with an error with message'Error: socket hang up'
and code'ECONNRESET'
'close'
If req.destroy()
is called before the connection succeeds, the following
events will be emitted in the following order:
'socket'
- (
req.destroy()
called here) 'error'
with an error with message'Error: socket hang up'
and code'ECONNRESET'
'close'
If req.destroy()
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 theres
object
- (
req.destroy()
called here) 'aborted'
on theres
object'close'
'close'
on theres
object
If req.abort()
is called before a socket is assigned, the following
events will be emitted in the following order:
- (
req.abort()
called here) 'abort'
'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 theres
object
- (
req.abort()
called here) 'abort'
'aborted'
on theres
object'close'
'close'
on theres
object
Setting the timeout
option or using the setTimeout()
function will
not abort the request or do anything besides add a 'timeout'
event.
Passing an AbortSignal
and then calling abort
on the corresponding
AbortController
will behave the same way as calling .destroy()
on the
request itself.