SuperAgent使用文档

2018-09-20 本文已影响9人 _shen

本篇文档是参考SuperAgent英文文档翻译整理成的。前段时间，在一个爬虫项目中用到了SuperAgent，因为遇到了一些坑，就详细的查阅了一下官方的文档，为了便于其他朋友查阅参考，我便对翻译的文档进行了简要整理。后期，我还会针对SuperAgent使用中遇到的一些问题进行完善，并附于文末Issue章节。同时也欢迎大家分享自己在使用SuperAgent过程中遇到的一些问题和解决方法。

1 简介

SuperAgent是一个轻量级、灵活的、易读的、低学习曲线的客户端请求代理模块，使用在NodeJS环境中。

官方文档：http://visionmedia.github.io/superagent

使用示例：

var request = require('superagent')

request
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('Accept', 'application/json')
  .then(res => {
     alert('yay got ' + JSON.stringify(res.body));
  });

在后面的讲解中我们都使用request表示superagent对象，代码中也省略如下部分：

var request = require('superagent')

2 请求

通过调用request对象then()或end()方法，或使用await关键字，发送一个请求。

request
  .get('/search')
  .then(res => {
     // res.body, res.headers, res.status
  })
  .catch(err => {
     // err.message, err.response
  });

请求的方法类型（DELETE，HEAD，PATCH，POST和PUT）可以通过如下字符串来指定：

// 指定使用GET方法
request('GET', '/search')
  .then(function (response) {
    // success

  },  function (error) {
    // failure

});

也可以使用end()方法

request('GET', '/search')
  .end(function(error, response){
    if (response.ok) {
    }
});

可以使用完整的URLs，由于同源策略的原因，这需要服务器实现了跨域访问。

request
  .get('https://example.com/search')
  .then(res => {

  });

除了上述使用的GET方法外，也可以使用DELETE，HEAD，PATCH，POST和PUT方法，只需要简单地更改一下方法的名称。

request
  .head('/favicon.ico')
  .then(response => {

  });

在旧版本IE浏览器中delete是系统的关键字，为了兼容这一点，可以调用del()方法来避免冲突。

request
  .del('/book/1')
  .end(function(response){

  });

request默认使用GET方法发送请求，可以简写成如下：

request('/search', (error, response) => {

 });

3 HTTP/2

如果要使用HTTP/2协议发送请求，可以调用http2()方法。目前还暂不支持对服务器 HTTP/2能力的检测。

const request = require('superagent');
const res = await request
  .get('https://example.com/h2')
  .http2();

4 设置头部字段

报文header字段设置通过调用set()方法。

request
  .get('/search')
  .set('API-Key', 'foobar')
  .set('Accept', 'application/json')
  .then(callback);

你也可以传递一个对象来设置多个字段：

request
  .get('/search')
  .set({
     'API-Key': 'foobar',
     ' Accept': 'application/json' 
    })
  .then(callback);

5 GET请求

当我们使用GET请求传递查询字符串的时候，可以使用query()方法，同时传递一个对象作为参数，下面的代码将产生一个URL为/search?query=Manny&range=1..5&order=desc请求：

request
  .get('/search')
  .query({ query: 'Manny' })
  .query({ range: '1..5' })
  .query({ order: 'desc' })
  .then(response => {

  });

或者传递一个对象

request
  .get('/search')
  .query({
    query: 'Manny',
    range: '1..5',
    order: 'desc'
  })
  .then(response => {

  });

query()也接受一个字符串作为参数

request
  .get('/querystring')
  .query('search=Manny&range=1..5')
  .then(response => {

  })

参数拼接字符&也可以用下面的方式替代：

request
  .get('/querystring')
  .query('search=Manny')
  .query('range=1..5')
  .then(response => {

  });

6 HEAD请求

query()方法也可以用于HEAD请求，下面的代码将会产生一个URL为 /users?email=joe@smith.com的请求：

request
  .head('/users')
  .query({
    email: 'joe@smith.com'
  })
  .then(response => {

  });

7 POST / PUT请求

一个典型的JSON POST请求的代码实现如下，设置相应的Content-type头字段，再写入数据。在这个例子里，仅使用JSON字符串:

request.post('/user')
  .set('Content-Type', 'application/json')
  .send('{"name":"tj","pet":"tobi"}')
  .then(callback)

JSON成为通用的数据格式后，request对象默认Content-type类型就是application/json，因此代码就可以简化为：

request.post('/user')
  .send('{"name":"tj","pet":"tobi"}')
  .then(callback)

也可以多次调用send()方法完成

request.post('/user')
  .send({ name: 'tj' })
  .send({ pet: 'tobi' })
  .then(callback

默认情况下，发送字符串时Content-type会被设置为application/x-www-form-urlencoded，多次调用send()方法会使用&连接起来，下面的代码中最终结果为：name=tj&pet=tobi

request.post('/user')
  .send('name=tj')
  .send('pet=tobi')
  .then(callback);

SuperAgent请求的数据格式是可以扩展的，不过默认支持“form”和“json”两种格式，想要以application/x-www-form-urlencoded格式发送数据的话，则可以调用type()方法并传入'form'参数，这里默认的参数是“json”。下面的请求中，POST请求体为name=tj&pet=tobi。

request.post('/user')
  .type('form')
  .send({ name: 'tj' })
  .send({ pet: 'tobi' })
  .then(callback)

支持发送FormData对象。下面的例子中发送id="myForm"的<form>表单数据：

request.post('/user')
  .send(new FormData(document.getElementById('myForm')))
  .then(callback)

提示：FormData类型其实是在XMLHttpRequest 2级定义的，它是为序列化表以及创建与表单格式相同的数据（当然是用于XHR传输）提供便利。

8 Content-Type设置

通常使用set()方法

request.post('/user')
  .set('Content-Type', 'application/json')

简便的方法是调用.type()方法，传递一个规范的MIME名称，包括type/subtype，或者一个简单的后缀就像xml，json，png这样。例如:

request.post('/user')
  .type('application/json')

request.post('/user')
  .type('json')

request.post('/user')
  .type('png')

9 序列化请求体

SuperAgent会自动序列化JSON和表单数据，你也可以为其他类型设置自动序列化：

request.serialize['application/xml'] = function (obj) {
    return 'string generated from obj';
};

// going forward, all requests with a Content-type of
// 'application/xml' will be automatically serialized

If you want to send the payload in a custom format, you can replace the built-in serialization with the .serialize() method on a per-request basis:
如果你希望以自定义格式发送数据，可以通过.serialize()方法为每个请求设置相应的序列化方法，以替换内置序列化方法：

request
    .post('/user')
    .send({foo: 'bar'})
    .serialize(obj => {
        return 'string generated from obj';
    });

10 重发请求

当给定retry()方法时，SuperAgent将自动重试请求，如果它们以短暂的方式失败或者可能由于因特网连接不正常而失败。

这个方法有两个可选参数：重试次数（默认值3）和回调函数。它在每次重发之前调用回调(error, res)。回调可以返回true/false，以决定是否要重发请求。

request
  .get('https://example.com/search')
  .retry(2) // or:
  .retry(2, callback)
  .then(finished);

需要注意的是：应该只对HTTP等幂请求使用retry()方法（即，到达服务器的多个请求不会导致不希望的副作用，如重复购买，否则会产生多个订单）。

11 设置Accept

与type()方法一样，这里可以调用accept()方法来设置Accept接受类型，这个值将会被request.types所引用，支持传递一个规范的MIME名称，包括type/subtype，或者一个简单的后缀：xml，json，``png等。例如:

request.get('/user')
  .accept('application/json')

request.get('/user')
  .accept('json')

request.post('/user')
  .accept('png')

Facebook和接收JSON：如果你是在调用Facebook的API，确保请求头中Accept: application/json 。否则，Facebook 将返回Content-Type: text/javascript; charset=UTF-8响应， SuperAgent将不会解析这个响应，读取响应体会得到undefined。你需要在请求对象request加上request.accept('json')或者request.header('Accept', 'application/json')代码。

12 查询字符串

调用.query()方法可以自动生成查询字符串，比如向URL为?format=json&dest=/login发送一个post请求：

request
  .post('/')
  .query({ format: 'json' })
  .query({ dest: '/login' })
  .send({ post: 'data', here: 'wahoo' })
  .then(callback);

默认情况下，查询字符串的拼装是没有特定的顺序。调用sortQuery()方法将默认按照ASCII码顺序进行，你也可以传递一个比较函数来指定排序规则，比较函数需要传递两个参数（在回调过程中会自动传递进两个参数，这两个参数就是用于比较的查询字符串），返回值是正整数、负整数或者0。

// 选择默认排序
request.get('/user')
  .query('name=Nick')
  .query('search=Manny')
  .sortQuery()
  .then(callback)

// 客制化的排序函数
request.get('/user')
  .query('name=Nick')
  .query('search=Manny')
  .sortQuery((a, b) => a.length - b.length)
  .then(callback)

上述客制化的排序函数中，a和b实际上就是sortQuery()回调过程中传递进去的两个查询字符串，按照查询字符串长度来排序的，长度大的排在前面。

13 TLS选项

在Node.js中使用SuperAgent，支持对HTTPS请求的下列配置：

ca()：将CA证书设置为信任
cert()：设置客户端证书链
key(): 设置客户端私钥
pfx(): 设置客户端PFX或PKCS12编码的私钥和证书链

更多信息可以查看：https.request 官方文档.

var key = fs.readFileSync('key.pem'),
    cert = fs.readFileSync('cert.pem');

request
  .post('/client-auth')
  .key(key)
  .cert(cert)
  .then(callback);

var ca = fs.readFileSync('ca.cert.pem');

request
  .post('https://localhost/private-ca-server')
  .ca(ca)
  .then(res => {});

14 解析响应体

SuperAgent 可以解析常用的响应体，目前支持application/x-www-form-urlencoded，application/json，和multipart/form-data格式。如下代码，你也可以对其它类型的响应体设置相应的解析方法：

// 浏览器端使用SuperAgent
request.parse['application/xml'] = function (str) {
    return {'object': 'parsed from str'};
};

// Node中使用SuperAgent
request.parse['application/xml'] = function (res, cb) {

    // 解析响应内容，设置响应体代码

    cb(null, res);
};

// 自动解析响应体

通过调用buffer(true)和parse(fn)的配合，你可以设置一个定制的解析器（定制的解析器优先于内置解析器）。如果没有启用响应缓冲（buffer(false)），那么响应事件的触发将不会等待主体解析器完成，因此响应体将不可用。

14.1 JSON/Urlencoded

response.body是解析后的内容对象，比如对于一个请求响应'{"user":{"name":"tobi"}}'字符串，response.body.user.name会返回"tobi"。同样的，与x-www-form-urlencoded格式的"user[name]=tobi"解析后值也是一样，只支持嵌套的一个层次，如果需要更复杂的数据，请使用JSON格式。

数组会以重复键名的方式进行发送，send({color: ['red','blue']})会发送"color=red&color=blue"。如果你希望数组键的名称包含"[]"，则需要自己添加，SuperAgent是不会自动添加。

14.2 Multipart

Node客户端通过Formidable模块来支持multipart/form-data类型，当解析一个multipart响应时，response.files属性就可以用。假设一个请求响应得到下面的数据：

--whoop
Content-Disposition: attachment; name="image"; filename="tobi.png"
Content-Type: image/png

... data here ...
--whoop
Content-Disposition: form-data; name="name"
Content-Type: text/plain

Tobi
--whoop--

你可以获取到res.body.name名为’Tobi’，res.files.image为一个file对象，包括一个磁盘文件路径、文件名称，还有其它的文件属性。

14.3 Binary

在浏览器中可以使用responseType('blob')来请求处理二进制格式的响应体。在Node.js中运行此API是不必要的。此方法的支持参数值为：

'blob'：会被传递为XmlHTTPRequest的responseType属性。
'arraybuffer'：会被传递为XmlHTTPRequest的responseType属性。

req.get('/binary.data')
  .responseType('blob')
  .then(res => {
    // res.body will be a browser native Blob type here
  });

更多的信息可以查看：xhr.responseType 文档.

15 响应对象属性

SuperAgent请求得到响应后，响应对象的属性主要有：

text：未解析前的响应内容，字符串类型。一般只在mime类型能够匹配"text/"，"json"，"x-www-form-urlencoding"的情况下，这个属性才会有效，默认为nodejs客户端提供；
body：响应数据解析后的对象，对象类型。
header：解析之后的响应头数据，数组类型。
type：响应报文的Content-Type值，字符串类型。
charset：响应的字符集，字符串类型。
status：响应状态标识。
statusCode：响应的状态码，数整数类型。如：200、302、404、500等。

15.1 text

response.text包含未解析前的响应内容，一般只在mime类型能够匹配"text/"，"json"，"x-www-form-urlencoding"的情况下，这个属性才会有效，默认为nodejs客户端提供，这是出于节省内存的考虑。因为缓冲大数据量的文本（如multipart文件或图像）的效率非常低。要强制缓冲，请参阅“响应缓冲”部分。

15.2 body

与SuperAgent请求数据自动序列化一样，响应数据也会自动的解析，当为一个Content-Type定义一个解析器后，就能自动解析，默认解析包含application/json和application/x-www-form-urlencoded，可以通过response.body来访问解析对象.

15.3 header fields

response.header包含解析之后的响应头数据，字段值都是Node处理成小写字母形式，如response.header['content-length']。

15.4 Content-Type

Content-Type响应头字段是一个特列，服务器提供response.type来访问它，默认response.charset是空的（如果有的话，则为指定类型），例如Content-Type值为"text/html; charset=utf8"，则response.type为text/html,response.charset为"utf8"。

15.5 status

响应状态标识可以用来判断请求是否成功，除此之外，可以用SuperAgent来构建理想的RESTful服务器，这些标识目前定义为:

var type = status / 100 | 0;

// status / class
res.status = status;
res.statusType = type;

// basics
res.info = 1 == type;
res.ok = 2 == type;
res.clientError = 4 == type;
res.serverError = 5 == type;
res.error = 4 == type || 5 == type;

// sugar
res.accepted = 202 == status;
res.noContent = 204 == status || 1223 == status;
res.badRequest = 400 == status;
res.unauthorized = 401 == status;
res.notAcceptable = 406 == status;
res.notFound = 404 == status;
res.forbidden = 403 == status;

16.中止请求

可以通过req.abort()来中止请求。

17.请求超时

有时网络和服务器会“卡住”，并且在接受请求后从不响应。设置超时以避免请求永远等待。

req.timeout({deadline:ms}) 或 req.timeout(ms)： ms是大于0的毫秒数。为整个请求设置一个截止时间（包括所有上传、重定向、服务器处理时间）完成。如果在那个时间内没有得到完整的响应，请求将被中止。
req.timeout({response:ms})：设置等待第一个字节从服务器到达的最大时间，但不限制整个下载可以消耗多长时间。响应超时应该比服务器响应的时间长至少几秒钟，因为它还包括进行DNS查找、TCP/IP和TLS连接的时间，以及上传请求数据的时间。

你应该同时使用deadline和response超时。通过这种方式，你可以通过较短的response超时来快速检测无响应网络，并且使用较长的deadline来在缓慢但可靠的网络上提供一个合适的时间。注意，这两个计时器都限制了上传文件的上传时间。如果上传文件，则使用长时间超时。

request
  .get('/big-file?network=slow')
  .timeout({
    response: 5000,  // Wait 5 seconds for the server to start sending,
    deadline: 60000, // but allow 1 minute for the file to finish loading.
  })
  .then(res => {
      /* responded in time */
    }, err => {
      if (err.timeout) { /* timed out! */ } else { /* other error */ }
  });

超时错误会提供一个timeout属性。

18.认证

Node和浏览器中都可以通过auth()方法来完成认证。

request
  .get('http://local')
  .auth('tobi', 'learnboost')
  .then(callback);

nodejs客户端也可以通过传递一个像下面这样的URL：

request.get('http://tobi:learnboost@local').then(callback);

默认在浏览器中只使用基本的认证方式，你也可以添加{type:'auto'}，以启用浏览器中内置的所有方法（摘要、NTLM等）：

request.auth('digest', 'secret', {type:'auto'})

19.跟随重定向

默认是向上跟随5个重定向，可以通过调用.res.redirects(n)来设置个数:

request
  .get('/some.png')
  .redirects(2)
  .then(callback);

20.全局状态代理

20.1 保存cookies

在Node SuperAgent中，默认情况下不保存cookie，但是可以使用.agent()方法创建一个含有cookie的SuperAgent副本。每个副本都有一个单独的cookie数据。

const agent = request.agent();
agent
  .post('/login')
  .then(() => {
    return agent.get('/cookied-page');
  });

在浏览器中，cookie由浏览器自动管理，因此.agent()不会格式化处理cookies。

20.2 多请求的默认选项

使用agent进行的多个请求中，agent调用的常规方法也将默认用于agent的后续所有的请求中。这些常规方法包括：use, on, once, set, query, type, accept, auth, withCredentials, sortQuery, retry, ok, redirects, timeout, buffer, serialize, parse, ca, key, pfx, cert。

const agent = request.agent()
  .use(plugin)
  .auth(shared);

await agent.get('/with-plugin-and-auth');
await agent.get('/also-with-plugin-and-auth');

21.管道数据

在nodejs客户端中，可以使用一个请求流来传输数据。需要注意的是：用pipe()取代了end()和then()方法。

下面是将文件内容作为请求进行管道传输例子：

const request = require('superagent');
const fs = require('fs');

const stream = fs.createReadStream('path/to/my.json');
const req = request.post('/somewhere');
req.type('json');
stream.pipe(req);

注意，在管道传输到请求时，superagent使用分块传输编码发送管道数据，这不是所有服务器（例如Python WSGI服务器）都支持的。

下面是输送一个响应流到文件的管道传输例子：

const stream = fs.createWriteStream('path/to/my.json');
const req = request.get('/some.json');
req.pipe(stream);

不能将管道、回调或promise混合在一起使用，不能尝试对end()或response对象进行管道操作（pipe()），如下所示：

// 不能做下面的操作
const stream = getAWritableStream();
const req = request
  .get('/some.json')
  // BAD: this pipes garbage to the stream and fails in unexpected ways
  .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
const req = request
  .get('/some.json')
  .end()
  // BAD: this is also unsupported, .pipe calls .end for you.
  .pipe(nope_its_too_late);

22.Multipart/form-data请求

superagen提供了attach() 和 field()方法用于构建multipart/form-data请求。

当你使用了field()或者attach()，你就不能使用 send()方法，你也不能设置 Content-Type （superagen会自动设置纠正后的type）。

22.1 附件

可以使用attach(name, [file], [options])进行文件发送。你可以通过多次调用attach()附加多个文件。attach()的参数说明如下：

name：文件名
file：文件路径字符串，或Blob/Buffer对象。
options ：（可选）字符串或自定义文件名或{filename: string}对象。在Node中也支持{contentType: 'mime/type'}。在浏览器中创建一个具有适当类型的Blob。

request
  .post('/upload')
  .attach('image1', 'path/to/felix.jpeg')
  .attach('image2', imageBuffer, 'luna.jpeg')
  .field('caption', 'My cats')
  .then(callback);

22.2 字段值

与HTML中表单的字段类似，你可以调用field(name,value)方法来设置字段，假设你想上传一个图片的并附带自己的名称和邮箱，那么你可以像下面这样:

 request
   .post('/upload')
   .field('user[name]', 'Tobi')
   .field('user[email]', 'tobi@learnboost.com')
   .field('friends[]', ['loki', 'jane'])
   .attach('image', 'path/to/tobi.png')
   .then(callback);

23.压缩

NodeJS客户端本身就提供压缩响应内容，所以你不需要做任何其它处理。

24.响应缓冲

为了强制缓冲response.text这样未解析前的响应内容（一般只在mime类型能够匹配"text/"，"json"，"x-www-form-urlencoding"的情况下才进行缓冲），可以调用buffer()方法，想取消默认的文本缓冲响应像text/plain, text/html这样的，可以调用buffer(false)方法。

// 强制缓冲
request
  .get('/userinfo')
  .buffer(true)
  .then(callback)

// 取消缓冲
request
  .get('/userinfo')
  .buffer(false)
  .then(callback)

当缓冲response.buffered标识有效了，那么就可以在一个回调函数里处理缓冲和未缓冲的响应.

25.跨域资源共享(CORS)

出于安全原因，浏览器将阻止跨源请求，除非服务器使用CORS头进行选择。浏览器还将做出额外的选项请求，以检查服务器允许的HTTP头和方法。更多信息可参阅：CORS.

withCredentials()方法可以激活发送原始cookie的能力，不过只有在Access-Control-Allow-Origin不是一个通配符(*)，并且Access-Control-Allow-Credentials为’true’的情况下才行。

request
  .get('https://api.example.com:4001/')
  .withCredentials()
  .then(res => {
    assert.equal(200, res.status);
    assert.equal('tobi', res.text);
  })

26.错误处理

回调函数总是会传递两个参数：error 错误和response 响应。如果没有发生错误，第一个参数将为null。

request
 .post('/upload')
 .attach('image', 'path/to/tobi.png')
 .then(response => {

 });

你可以加入监听错误的代码，错误产生之后会执行监听代码。

request
  .post('/upload')
  .attach('image', 'path/to/tobi.png')
  .on('error', handle)
  .then(response => {

  });

注意：
superagent默认情况下，对响应4xx和5xx的认为不是错误，例如当响应返回一个500或者403的时候，这些状态信息可以通过response.error，response.status和其它的响应属性来查看。

不产生响应的网络故障、超时和其他错误将不包含response.error，response.status属性。

如果希望处理404个或其他HTTP错误响应，可以查询error.status属性。当发生HTTP错误（4xx或5xx响应）时，response.error属性是error对象，这可以用来作以下检查：

if (error && error.status === 404) {
  alert('oh no ' + response.body.message);
}
else if (error) {
  // all other error types we handle generically
}

或者，可以使用ok(callback)方法来判断响应是否是错误。对ok()的回调得到响应，如果响应成功，则返回true。

request.get('/404')
  .ok(res => res.status < 500)
  .then(response => {
    // reads 404 page as a successful response
  })

27.进度跟踪

superagent在大型文件的上传和下载过程中触发progress事件。

request.post(url)
  .attach('field_name', file)
  .on('progress', event => {
    /* the event is:
    {
      direction: "upload" or "download"
      percent: 0 to 100 // may be missing if file size is unknown
      total: // total file size, may be missing
      loaded: // bytes downloaded or uploaded so far
    } */
  })
  .then()

event属性包括：

direction： upload 或 download
percent：0 到 100 ，文件大小未知的话为无效
total：文件总大小，可能为无效
loaded：已经下载或上传的字节数

28.Promise和Generator支持

SuperAgent的请求是一个“thenable”对象，它与JavaScript承诺和异步/等待语法兼容。

如果你正在使用promises，那么就不要再调用end()或pipe()方法。任何使用then()或者await操作都会禁用所有其他使用请求的方式。

像CO或类似KOA这样的Web框架，可以在superagent使用yield：

const req = request
  .get('http://local')
  .auth('tobi', 'learnboost');
const res = yield req;

请注意，superagent期望全局promises对象存在。在Internet Explorer或Node.js 0.10中需要使用polyfill组件。

29.浏览器和Node版本

SuperAgent有两个实现：一个是用于web浏览器（使用XHR）的版本，另一个是用于Node.JS (使用核心的http模块)版本。

30.3XX处理

HTTP 3XX是重定向报文，superagent默认会自动跟踪下去，我们也不能使用redirect(0)的方法来禁止重定向，因此需要使用原生的http来处理。

request.post({
  url: '/login',
}, function (err, res, body) {
  if (!err && (res.statusCode == 301 || res.statusCode == 302)) {
    // 登录成功后服务端返回重定位报文
    cookie += ';' + res.headers['set-cookie']
    res1.redirect('listall')
  } else if (res.statusCode == 200) {
    // 登录失败服务端会返回200
    // ...
  } else {
    // 其他错误信息处理
    console.log(err)
  }
})