- curl
- method: String
- data: Object
- content: String|Buffer
- files: Mixed
- stream: ReadStream
- writeStream: WriteStream
- consumeWriteStream: Boolean
- method: String
- contentType: String
- dataType: String
- fixJSONCtlChars: Boolean
- headers: Object
- timeout: Number|Array
- agent: HttpAgent
- httpsAgent: HttpsAgent
- auth: String
- gzip: Boolean
- timing: Boolean
发送http请求
curl
# http客户端
const url = "https://api.wrdan.com/ip";
const options = {
method: 'GET',
data: {
url: 'https://www.baidu.com',
},
dataType: 'json',
timeout: 15000,
};
const result = await this.app.curl(url, options);
method: String
设置请求方法,默认是 GET。 支持 GET、POST、PUT、DELETE、PATCH 等所有 HTTP 方法。
data: Object
需要发送的请求数据,根据 method 自动选择正确的数据处理方式。
- GET,HEAD:通过 querystring.stringify(data) 处理后拼接到 url 的 query 参数上。
- POST,PUT 和 DELETE 等:需要根据 contentType 做进一步判断处理。
- contentType = json:通过 JSON.stringify(data) 处理,并设置为 body 发送。
- 其他:通过 querystring.stringify(data) 处理,并设置为 body 发送。
// GET + data
ctx.curl(url, {
data: { foo: 'bar' },
});
// POST + data
ctx.curl(url, {
method: 'POST',
data: { foo: 'bar' },
});
// POST + JSON + data
ctx.curl(url, {
method: 'POST',
contentType: 'json',
data: { foo: 'bar' },
});
content: String|Buffer
发送请求正文,如果设置了此参数,那么会直接忽略 data 参数。
app.curl(url, {
method: 'POST',
// 直接发送原始 xml 数据,不需要 HttpClient 做特殊处理
content: '<xml><hello>world</hello></xml>',
headers: {
'content-type': 'text/html',
},
});
files: Mixed
文件上传,支持格式: String | ReadStream | Buffer | Array | Object。
app.curl(url, {
method: 'POST',
files: '/path/to/read',
data: {
foo: 'other fields',
},
});
多文件上传:
app.curl(url, {
method: 'POST',
files: {
file1: '/path/to/read',
file2: fs.createReadStream(__filename),
file3: Buffer.from('mock file content'),
},
data: {
foo: 'other fields',
},
});
stream: ReadStream
设置发送请求正文的可读数据流,默认是 null。 一旦设置了此参数,HttpClient 将会忽略 data 和 content。
ctx.curl(url, {
method: 'POST',
stream: fs.createReadStream('/path/to/read'),
});
writeStream: WriteStream
设置接受响应数据的可写数据流,默认是 null。 一旦设置此参数,那么返回值 result.data 将会被设置为 null, 因为数据已经全部写入到 writeStream 中了。
ctx.curl(url, {
writeStream: fs.createWriteStream('/path/to/store'),
});
consumeWriteStream: Boolean
是否等待 writeStream 完全写完才算响应全部接收完毕,默认是 true。 此参数不建议修改默认值,除非我们明确知道它的副作用是可接受的, 否则很可能会导致 writeStream 数据不完整。
method: String
设置请求方法,默认是 GET。 支持 GET、POST、PUT、DELETE、PATCH
contentType: String
设置请求数据格式,默认是 undefined,HttpClient 会自动根据 data 和 content 参数自动设置。data 是 object 的时候默认设置的是 form。支持 json 格式。
如需要以 JSON 格式发送 data:
ctx.curl(url, {
method: 'POST',
data: {
foo: 'bar',
now: Date.now(),
},
contentType: 'json',
});
dataType: String
设置响应数据格式,默认不对响应数据做任何处理,直接返回原始的 buffer 格式数据。 支持 text 和 json 两种格式。
注意:设置成 json 时,如果响应数据解析失败会抛 JSONResponseFormatError 异常。
const jsonResult = await ctx.curl(url, {
dataType: 'json',
});
console.log(jsonResult.data);
const htmlResult = await ctx.curl(url, {
dataType: 'text',
});
console.log(htmlResult.data);
fixJSONCtlChars: Boolean
是否自动过滤响应数据中的特殊控制字符 (U+0000 ~ U+001F),默认是 false。 通常一些 CGI 系统返回的 JSON 数据会包含这些特殊控制字符,通过此参数可以自动过滤掉它们。
ctx.curl(url, {
fixJSONCtlChars: true,
dataType: 'json',
});
headers: Object
自定义请求头。
ctx.curl(url, {
headers: {
'x-foo': 'bar',
},
});
timeout: Number|Array
请求超时时间,默认是 [ 5000, 5000 ],即创建连接超时是 5 秒,接收响应超时是 5 秒。
ctx.curl(url, {
// 创建连接超时 3 秒,接收响应超时 3 秒
timeout: 3000,
});
ctx.curl(url, {
// 创建连接超时 1 秒,接收响应超时 30 秒,用于响应比较大的场景
timeout: [1000, 30000],
});
agent: HttpAgent
允许通过此参数覆盖默认的 HttpAgent,如果你不想开启 KeepAlive,可以设置此参数为 false。
ctx.curl(url, {
agent: false,
});
httpsAgent: HttpsAgent
允许通过此参数覆盖默认的 HttpsAgent,如果你不想开启 KeepAlive,可以设置此参数为 false。
ctx.curl(url, {
httpsAgent: false,
});
auth: String
简单登录授权(Basic Authentication)参数,将以明文方式将登录信息以 Authorization 请求头发送出去。
ctx.curl(url, {
// 参数必须按照 `user:password` 格式设置
auth: 'foo:bar',
});
gzip: Boolean
是否支持 gzip 响应格式,默认为 false。 开启 gzip 之后,HttpClient 将自动设置 Accept-Encoding: gzip 请求头, 并且会自动解压带 Content-Encoding: gzip 响应头的数据。
ctx.curl(url, {
gzip: true,
});
timing: Boolean
是否开启请求各阶段的时间测量,默认为 false。 开启 timing 之后,可以通过 result.res.timing 拿到这次 HTTP 请求各阶段的时间测量值(单位是毫秒), 通过这些测量值,我们可以非常方便地定位到这次请求最慢的环境发生在那个阶段,效果如同 Chrome network timing 的作用。
timing 各阶段测量值解析:
- queuing:分配 socket 耗时
- dnslookup:DNS 查询耗时
- connected:socket 三次握手连接成功耗时
- requestSent:请求数据完整发送完毕耗时
- waiting:收到第一个字节的响应数据耗时
- contentDownload:全部响应数据接收完毕耗时
const result = await ctx.curl(url, {
timing: true,
});
console.log(result.res.timing);
// {
// "queuing":29,
// "dnslookup":37,
// "connected":370,
// "requestSent":1001,
// "waiting":1833,
// "contentDownload":3416
// }