SuperAgent 使用指南：轻量级 HTTP 客户端库详解

SuperAgent 使用指南：轻量级 HTTP 客户端库详解

superagent Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs. 项目地址: https://gitcode.com/gh_mirrors/sup/superagent

什么是 SuperAgent

SuperAgent 是一个轻量级、渐进式的 AJAX API 库，专为灵活性、可读性和低学习曲线而设计。它既可以在浏览器环境中使用，也可以在 Node.js 环境中运行，是目前最受欢迎的 HTTP 客户端库之一。

基本用法

发起请求

SuperAgent 采用链式调用的方式发起 HTTP 请求，基本语法非常直观：

const request = require('superagent');

request
  .get('/api/users')  // 指定请求方法(GET)和路径
  .query({ name: 'John' })  // 添加查询参数
  .then(res => {  // 处理成功响应
    console.log(res.body);
  })
  .catch(err => {  // 处理错误
    console.error(err);
  });

支持多种 HTTP 方法

SuperAgent 支持所有常见的 HTTP 方法：

request.get('/user')     // GET 请求
request.post('/user')    // POST 请求
request.put('/user')     // PUT 请求
request.patch('/user')   // PATCH 请求
request.delete('/user')  // DELETE 请求

请求配置详解

设置请求头

可以通过 .set() 方法设置请求头：

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

也可以传递一个对象来批量设置：

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

发送请求体数据

对于 POST、PUT 等需要请求体的方法，可以使用 .send()：

// 发送 JSON 数据
request
  .post('/user')
  .send({ name: 'John', age: 30 })
  
// 发送表单数据
request
  .post('/login')
  .type('form')
  .send({ username: 'admin', password: '123456' })

处理查询参数

对于 GET 请求，可以通过 .query() 添加查询参数：

request
  .get('/search')
  .query({ query: 'Manny', page: 2 })

响应处理

响应数据结构

SuperAgent 的响应对象包含丰富的信息：

request.get('/user').then(res => {
  console.log(res.body);    // 解析后的响应体
  console.log(res.headers); // 响应头
  console.log(res.status);  // 状态码
  
  // 状态相关标志
  console.log(res.ok);       // 2xx 状态码时为 true
  console.log(res.clientError); // 4xx 状态码时为 true
  console.log(res.serverError); // 5xx 状态码时为 true
});

错误处理

SuperAgent 提供了多种错误处理方式：

// 使用 catch
request.get('/user')
  .then(res => { /* 成功处理 */ })
  .catch(err => { /* 错误处理 */ });

// 使用回调函数
request.get('/user').end((err, res) => {
  if (err) {
    // 处理错误
  } else {
    // 处理响应
  }
});

高级功能

超时设置

可以设置请求超时时间：

request
  .get('/slow-response')
  .timeout({
    response: 5000,  // 等待服务器开始响应的时间
    deadline: 10000  // 整个请求完成的时间限制
  })

自动重试

对于临时性失败，可以设置自动重试：

request
  .get('/unstable-api')
  .retry(3)  // 最多重试3次

HTTP/2 支持

可以强制使用 HTTP/2 协议：

request
  .get('https://example.com')
  .http2()

文件上传

在 Node.js 环境中支持文件上传：

request
  .post('/upload')
  .attach('image', 'path/to/image.jpg')

浏览器与 Node.js 差异

SuperAgent 在浏览器和 Node.js 环境中有一些行为差异：

1. CORS 处理：浏览器中跨域请求需要服务器支持 CORS
2. 响应缓冲：Node.js 中默认不缓冲非文本响应以节省内存
3. 文件上传：Node.js 中使用 attach()，浏览器中使用 FormData

最佳实践

1. 统一错误处理：建议在所有请求上添加 .catch() 处理
2. 设置超时：特别是对于生产环境的关键请求
3. 合理使用重试：仅对幂等请求使用重试功能
4. 类型安全：明确设置 Content-Type 和 Accept 头部
5. 环境适配：根据运行环境调整配置（浏览器/Node.js）

SuperAgent 的简洁 API 设计和强大功能使其成为处理 HTTP 请求的理想选择。无论是简单的数据获取还是复杂的 API 交互，它都能提供优雅的解决方案。

superagent Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs. 项目地址: https://gitcode.com/gh_mirrors/sup/superagent