专栏名称: qize

前端交互开发工程师

[翻译] SuperAgent 中文使用指南(v3.8.0)

qize · 掘金 · 前端 · 2018-01-22 08:36

正文

版本: v3.8.0
SuperAgent 英文使用指南

SuperAgent

SuperAgent是轻量级渐进式ajax API，相比于现有的请求API，它更加灵活，可读，且学习成本低。同样它也适用于Node.js！

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

测试文档

以下测试文档是由 Mocha's "doc" 记录生成的，直接反映了测试套件。这提供了额外的文档来源。

基础请求

请求可以通过调用 request 对象的适当方法来启动，然后调用 .then() (or .end() or await ) 来发送请求，例如一个简单的GET请求:

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

HTTP 方法也可以使用字符串:

request('GET', '/search').then(success, failure);

旧的回调依旧可以使用。将 .then() 替换成 .end() ：

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

可以使用绝对URL。在Web浏览器中，绝对URL只在服务器实现 CORS 的情况下才起作用。

 request
   .get('http://example.com/search')
   .then(function(res) {

   });

Node 客户端支持向 Unix域套接字发送请求:

 // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
 //          Use `%2F` as `/` in SOCKET_PATH
 request
   .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search')
   .then(res => {

   });

DELETE , HEAD , PATCH , POST , 和 PUT 请求方法依旧可以使用, 只需要修改一下方法名即可：

request
  .head('/favicon.ico')
  .then(function(res) {

  });

DELETE 也可以被称为 .del() 与旧的IE兼容，其中 delete 是一个保留字。

HTTP 方法默认是 GET ，所以下面的写法也是可以的:

 request('/search', function(err, res){

 });

设置 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);

`GET` 请求

.query() 方法接受对象，当与 GET 方法一起使用时，将形成一个查询字符串。以下将拼接成 / search？query = Manny＆range = 1..5＆order = desc 这样的一个查询字符串。

 request
   .get('/search')
   .query({ query: 'Manny' })
   .query({ range: '1..5' })
   .query({ order: 'desc' })
   .then(function(res) {

   });

或者用一个对象包裹:

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

  });

.query() 方法同样可以接收字符串的形式:

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

    });

或者如下这样:

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

    });

`HEAD` 请求

对于 HEAD 请求你依旧可以使用 .query() 方法。下面的 .query() 参数将会拼接成 /[email protected] 。

  request
    .head('/users')
    .query({ email: '[email protected]' })
    .then(function(res) {

    });

`POST` / `PUT` 请求

一个典型的JSON POST 请求可能看起来有点像下面这样，我们适当地设置 Content-Type 头字段，并“写”一些数据，在这种情况下，只是一个JSON字符串。

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

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 ，多个调用将与 ＆ 连接在一起，这里生成 name = tj＆pet = tobi ：

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

SuperAgent 格式是可扩展的，但默认支持 "json" 和 "form"。要以 application / x-www-form-urlencoded 方式发送数据，只需使用 "form" 调用 .type() ，默认为“json”。这个请求将 POST 的 body拼接成“名称= tj＆pet = tobi"。

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

发送一个 FormData 格式的数据也是支持的。以下示例将 POST 标识为 id =“myForm” 的HTML表单的内容。

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

设置 `Content-Type`

.set() 方法也是经常使用的:

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

作为一个简短方式， .type() 方法也是可用的，它接受规范化的 MIME 类型名称完整的类型/子类型，或简单的扩展名称，如“xml”，“json”，“png”:

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

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

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

序列化请求正文

SuperAgent会自动序列化JSON和表单。如果要以自定义格式发送有效内容，则可以使用 .serialize() 方法替换内置序列化。

重试请求

当给定 .retry() 方法时，SuperAgent 会自动重试请求，如果它们以短暂的失败或可能是由于Internet连接造成的。

此方法有两个可选参数：重试次数（默认值3）和回调。它在每次重试之前调用 callback(err，res) 。回调可能返回 true / false 来控制请求是否被重试（但总是应用最大重试次数）。

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

仅对幂等的请求使用 .retry() 。

设置 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 和 Accept JSON

如果你正在调用 Facebook 的API，请确保在您的请求中发送 "Accept:application/json" 头。如果你不这样做，Facebook 会用 Content-Type：text / javascript; charset = UTF-8 ，SuperAgent 将不会解析，因此 res.body 将是未定义的。你可以用 req.accept('json') 或 req.header('Accept'，'application / json') 来做到这一点。有关详细信息，请参见 issues1078 。

查询字符串

req.query(obj) 是一个可以用来建立一个查询字符串的方法。例如，在 POST 上填充 ？format = json＆dest = / login ：

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

默认情况下，查询字符串不会以任何特定的顺序组装的。 asciibetically-sorted 排序的查询字符串可以用 req.sortQuery() 来启用。你也可以用 req.sortQuery(myComparisonFn) 提供一个自定义的排序比较函数。比较函数应该带2个参数并返回一个负/零/正整数。

 // default order
 request.get('/user')
   .query('name=Nick')
   .query('search=Manny')
   .sortQuery()
   .then(callback)

 // customized sort function
 request.get('/user')
   .query('name=Nick')
   .query('search=Manny')
   .sortQuery(function(a, b){
     return a.length - b.length;
   })
   .then(callback)

TLS 选项

在 Node.js 中，SuperAgent 支持配置 HTTPS 请求的方法：

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

更多信息，请看 Node.js https.request docs .

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 => {});

解析响应主体

SuperAgent 将为你解析已知的响应主体数据，目前支持 application / x-www-form-urlencoded ， application / json 和 multipart / form-data 。

您可以使用 .buffer(true).parse(fn) 方法设置自定义解析器（优先于内置解析器）。如果没有启用响应缓冲 ( .buffer（false） ），那么 response 事件将不会等待 body 解析完成，所以 response.body 将不可用。

JSON / Urlencoded

例如，如果请求用JSON字符串 “{”user“：{”name“：”tobi“}}” 响应，那么 res.body.user.name 就是解析对象就是“tobi”。同样，“user [name] = tobi”的x-www-form-urlencoded值也会产生相同的结果。只支持一个嵌套级别。如果您需要更复杂的数据，请发送JSON。

通过重复key发送数组。 .send({color：['red'，'blue']}) 发送 color = red＆color = blue 。如果你想让数组 key 在它们的名字中包含 [] ，你必须自己添加它，因为SuperAgent不会自动添加它。

Multipart

Node客户端通过 Formidable 模块支持 multipart / form-data 。当解析多部分响应时，对象 res.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”对象。

二进制

在浏览器中，你可以使用 .responseType('blob') 来请求处理二进制响应主体。在 node.js 中运行时，此API不是必要的。这个方法支持的参数值是

blob 传递给 XmlHTTPRequest responseType 属性
arraybuffer' 传递给 XmlHTTPRequest responseType` 属性

req.get('/binary.data')
  .responseType('blob')
  .end(function (error, res) {
    // res.body will be a browser native Blob type here
  });

更多内容请看 Mozilla Developer Network xhr.responseType docs 。

响应属性

响应对象设置了许多有用的标志和属性，包括响应文本，解析的响应主体，标题字段，状态标志等等。

响应文本

res.text 属性包含未解析的响应正文字符串。此属性始终为客户端API提供，并且仅当默认情况下mime类型与节点默认匹配“text / ”，“ / json”或“x-www-form-urlencoded”时。其原因是为了节省内存，因为诸如多部分文件或图像的大型文本的缓存文本是非常低效的。要强制缓存请参阅 “缓存响应” 部分。