http client

send an http request

usage

curl

# http client
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);

options：

method: String

set the request method. The default value is GET. Supports all HTTP methods, such as GET, POST, PUT, DELETE, and PATCH.

data: Object

the request data to be sent, according method automatically select the correct data processing method.

1. GET,HEAD: use querystring.stringify(data) to process and splice it to the query parameter of the url.
2. POST,PUT, and DELETE: further judgment is required based on contentType.
   1. contentType = json: it is processed by JSON.stringify(data) and set to body.
   2. others: use querystring.stringify(data) to process and set it to 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

the body of the request. If this parameter is set, it will be ignored. Data parameter.

app.curl(url, {
  method: 'POST',
  // 直接发送原始 xml 数据，不需要 HttpClient 做特殊处理
  content: '<xml><hello>world</hello></xml>',
  headers: {
    'content-type': 'text/html',
  },
});

files: Mixed

file upload. Supported format: String | ReadStream | Buffer | Array | Object.

app.curl(url, {
  method: 'POST',
  files: '/path/to/read',
  data: {
    foo: 'other fields',
  },
});

Upload multiple files:

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

set the readable data stream of the request body. The default value is null . Once this parameter is set, the HttpClient is ignored. Data and content .

ctx.curl(url, {
  method: 'POST',
  stream: fs.createReadStream('/path/to/read'),
});

writeStream: WriteStream

set the writable data stream that accepts response data. The default value is null . Once this parameter is set, the return value result.data will be set null because all data has been written writeStream yes.

ctx.curl(url, {
  writeStream: fs.createWriteStream('/path/to/store'),
});

consumeWriteStream: Boolean

wait writeStream the response is received only after it is completely written. The default value is true . This parameter does not recommend modifying the default value unless we clearly know that its side effects are acceptable writeStream the data is incomplete.

method: String

Set the request method. The default value is GET . Supported GET, POST, PUT, DELETE, PATCH

contentType: String

set the request data format. The default value is undefined , the HttpClient is automatically based on data and content parameters are automatically set. Data when it is an object, the default setting is form . Supported JSON the format.
Send in JSON format data :

ctx.curl(url, {
  method: 'POST',
  data: {
    foo: 'bar',
    now: Date.now(),
  },
  contentType: 'json',
});

dataType: String

set the response data format. By default, the original buffer data is directly returned without processing the response data. Supported text and JSON two formats.
Note: set JSON if the response data fails to be parsed JSONResponseFormatError an error occurred.

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

specifies whether to automatically filter special control characters (U +0000 ~ U + 001F) in response data. The default value is false . Usually, JSON data returned by some CGI systems contains these special control characters, which can be automatically filtered out.。

ctx.curl(url, {
  fixJSONCtlChars: true,
  dataType: 'json',
});

headers: Object

ustom request headers.

ctx.curl(url, {
  headers: {
    'x-foo': 'bar',
  },
});

timeout: Number|Array

the request timeout period. Default value: [5000, 5000] , that is, the connection creation timeout is 5 seconds, and the response timeout is 5 seconds.

ctx.curl(url, {
  // 创建连接超时 3 秒，接收响应超时 3 秒
  timeout: 3000,
});
ctx.curl(url, {
  // 创建连接超时 1 秒，接收响应超时 30 秒，用于响应比较大的场景
  timeout: [1000, 30000],
});

agent: HttpAgent

this parameter is allowed to overwrite the default HttpAgent. If you do not want to enable KeepAlive, you can set this parameter false .

ctx.curl(url, {
  agent: false,
});

httpsAgent: HttpsAgent

this parameter is allowed to overwrite the default HttpsAgent. If you do not want to enable KeepAlive, you can set this parameter false .

ctx.curl(url, {
  httpsAgent: false,
});

auth: String

simple logon authorization (Basic Authentication) parameter, the login information will be in plaintext Authorization request the hair to be sent out.

ctx.curl(url, {
  // 参数必须按照 `user:password` 格式设置
  auth: 'foo:bar',
});

gzip: Boolean

indicates whether gzip response format is supported. Default value: false . After gzip is enabled, the HttpClient is automatically set. Accept-Encoding: gzip the request header is automatically decompressed. Content-Encoding: gzip the response header data.

ctx.curl(url, {
  gzip: true,
});

timing: Boolean

whether to enable time measurement for each phase of the request. The default value is false . After timing is enabled, you can result.res.timing get the time measurements (in milliseconds) of each stage of the HTTP request. Through these measurements, we can easily locate the stage in which the slowest environment of the request occurs, and the effect is as Chrome network timing.

Analysis of measured values in each stage of timing:

• queuing：allocate socket time
• dnslookup：DNS query time
• connected：socket three-way handshake connection time
• requestSent：the time consumed when the request data is completely sent.
• waiting：The time taken to receive the first byte of response data.
• contentDownload：It takes time to receive all response data.

  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
  // }