官网：详细文档

options 参数详解

由于 HTTP 请求的复杂性，导致 httpclient.request(url, options) 的 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 发送。 ```typescript // 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’ }, });

  1. <a name="b02La"></a>
  2. ### <br />dataAsQueryString: Boolean
  3. 如果设置了 dataAsQueryString=true，那么即使在 POST 情况下， 也会强制将 options.data 以 querystring.stringify 处理之后拼接到 url 的 query 参数上。<br />可以很好地解决以 stream 发送数据，且额外的请求参数以 url query 形式传递的应用场景
  4. ```typescript
  5. ctx.curl(url, {
  6.   method: 'POST',
  7.   dataAsQueryString: true,
  8.   data: {
  9.     // 一般来说都是 access token 之类的权限验证参数
  10.     accessToken: 'some access token value',
  11.   },
  12.   stream: myFileStream,
  13. });


content: String|Buffer

发送请求正文，如果设置了此参数，那么会直接忽略 data 参数。

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


files: Mixed

文件上传，支持格式： String | ReadStream | Buffer | Array | Object。

  1. ctx.curl(url, {
  2.   method: 'POST',
  3.   files: '/path/to/read',
  4.   data: {
  5.     foo: 'other fields',
  6.   },
  7. });
  1. ctx.curl(url, {
  2.   method: 'POST',
  3.   files: {
  4.     file1: '/path/to/read',
  5.     file2: fs.createReadStream(__filename),
  6.     file3: Buffer.from('mock file content'),
  7.   },
  8.   data: {
  9.     foo: 'other fields',
  10.   },
  11. });

stream: ReadStream

设置发送请求正文的可读数据流，默认是 null。 一旦设置了此参数，HttpClient 将会忽略 data 和 content。

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

contentType: String

设置请求数据格式，默认是 undefined，HttpClient 会自动根据 data 和 content 参数自动设置。data 是 object 的时候默认设置的是 form。支持 json 格式。
如需要以 JSON 格式发送 data：

  1. ctx.curl(url, {
  2.   method: 'POST',
  3.   data: {
  4.     foo: 'bar',
  5.     now: Date.now(),
  6.   },
  7.   contentType: 'json',
  8. });

dataType: String

设置响应数据格式，默认不对响应数据做任何处理，直接返回原始的 buffer 格式数据。 支持 text 和 json 两种格式。
注意：设置成 json 时，如果响应数据解析失败会抛 JSONResponseFormatError 异常。

  1. const jsonResult = await ctx.curl(url, {
  2.   dataType: 'json',
  3. });
  4. console.log(jsonResult.data);
  6. const htmlResult = await ctx.curl(url, {
  7.   dataType: 'text',
  8. });
  9. console.log(htmlResult.data);

beforeRequest: Function(options)

HttpClient 在请求正式发送之前，会尝试调用 beforeRequest 钩子，允许我们在这里对请求参数做最后一次修改。

  1. ctx.curl(url, {
  2.   beforeRequest: (options) => {
  3.     // 例如我们可以设置全局请求 id，方便日志跟踪
  4.     options.headers['x-request-id'] = uuid.v1();
  5.   },
  6. });