SuperAgent HTTP 请求库快速上手指南

2.1 浏览器环境安装

# 使用 npm
npm install superagent
# 使用 yarn
yarn add superagent
# 使用 CDN
<script src="https://cdn.jsdelivr.net/npm/superagent"></script>

2.2 Node.js 环境安装

# Node.js 环境下安装
npm install superagent

2.3 基本引入方式

// ES6 模块引入
import request from 'superagent';

// CommonJS 引入
const request = require('superagent');

// 浏览器中直接使用全局变量
// window.superagent 或直接使用 request

3. 基础用法详解

3.1 GET 请求

// 最简单的 GET 请求
request.get('/api/users').end((err, res) => {
  if(err) {
    console.error('请求出错了:', err);
    return;
  }
  console.log('响应数据:', res.body);
});

// 带查询参数的 GET 请求
request.get('/api/users')
  .query({page: 1, limit: 10})
  .query({sort: 'name'})
  .end((err, res) => {
    // 处理响应
  });

// 使用 Promise 方式
request.get('/api/users')
  .then(res => {
    console.log(res.body);
  })
  .catch(err => {
    console.error(err);
  });

3.2 POST 请求

// 发送 JSON 数据
request.post('/api/users')
  .send({name: 'User', email: '[email protected]'})
  .set('Content-Type', 'application/json')
  .end((err, res) => {
    // 处理响应
  });

// 发送表单数据
request.post('/api/users')
  .type('form')
  .send({name: 'User', email: '[email protected]'})
  .end((err, res) => {
    // 处理响应
  });

// 上传文件
request.post('/api/upload')
  .attach('avatar', '/path/to/avatar.jpg')
  .field('name', 'User')
  .end((err, res) => {
    // 处理响应
  });

3.3 其他 HTTP 方法

// PUT 请求
request.put('/api/users/123').send({name: 'New User'}).end(callback);

// DELETE 请求
request.del('/api/users/123').end(callback);

// PATCH 请求
request.patch('/api/users/123').send({age: 19}).end(callback);

4. 高级功能与配置

4.1 请求头设置

// 设置单个请求头
request.get('/api/users')
  .set('Authorization', 'Bearer token123')
  .set('X-Custom-Header', 'custom-value')
  .end(callback);

// 批量设置请求头
request.get('/api/users')
  .set({'Authorization': 'Bearer token123', 'Content-Type': 'application/json', 'X-API-Key': 'your-api-key'})
  .end(callback);

4.2 查询参数处理

// 方式一：链式添加
request.get('/api/search')
  .query({q: 'javascript'})
  .query({page: 1})
  .query({limit: 20})
  .end(callback);

// 方式二：一次性添加
request.get('/api/search')
  .query({q: 'javascript', page: 1, limit: 20})
  .end(callback);

// 方式三：字符串形式
request.get('/api/search')
  .query('q=javascript&page=1&limit=20')
  .end(callback);

4.3 超时设置

// 设置超时时间（毫秒）
request.get('/api/users')
  .timeout(5000) // 5 秒超时
  .end((err, res) => {
    if(err && err.timeout) {
      console.log('请求超时了！');
    }
  });

// 更精细的超时控制
request.get('/api/users')
  .timeout({response: 5000, deadline: 60000})
  .end(callback);

5. 异常处理与错误捕获

5.1 错误类型分类

5.2 错误处理最佳实践

request.get('/api/users').end((err, res) => {
  // 优先处理错误
  if(err) {
    if(err.timeout) {
      console.log('请求超时，请检查网络连接');
    } else if(err.crossDomain) {
      console.log('跨域请求被阻止');
    } else if(err.abort) {
      console.log('请求被取消');
    } else {
      console.log('其他错误:', err.message);
    }
    return;
  }
  // 处理成功响应
  if(res.status === 200) {
    console.log('请求成功:', res.body);
  } else {
    console.log('服务器返回错误状态:', res.status);
  }
});

6. 流程图解析 SuperAgent 工作机制

+------------------+
| 开始请求构建     |
+------------------+
| v
+------------------+
| 设置请求方法     |
| (GET/POST/PUT 等)|
+------------------+
| v
+------------------+
| 设置请求 URL     |
+------------------+
| v
+------------------+
| 添加请求头       |
+------------------+
| v
+------------------+
| 设置请求体数据   |
+------------------+
| v
+------------------+
| 设置查询参数     |
+------------------+
| v
+------------------+
| 发送网络请求     |
+------------------+
| v
+------------------+
| 等待服务器响应   |
+------------------+
| v
+------------------+
| 处理响应数据     |
+------------------+
| v
+------------------+
| 执行回调函数     |
+------------------+

7. 常见错误与解决方案

7.1 忘记调用 .end()

问题：写了半天请求，忘了调用 .end()，结果没有返回。

// 错误示例 - 忘记调用 end()
request.get('/api/users'); // 这样永远不会发送请求！

// 正确做法
request.get('/api/users').end((err, res) => {
  // 处理响应
});

7.2 混淆 .send() 和 .field()

问题：上传文件时用错了方法，导致文件变成了字符串。

// 错误用法
request.post('/api/upload').send('file', fileInput.files[0]); // 错了！应该用 field 或 attach

// 正确用法
request.post('/api/upload')
  .field('name', 'User') // 普通字段用 field
  .attach('file', fileInput.files[0]) // 文件用 attach
  .end(callback);

7.3 跨域请求不设置 CORS

问题：前端写得好好的，一调接口就报跨域错误。

// 前端正确处理跨域
request.get('http://api.example.com/users')
  .withCredentials() // 需要携带 cookies 时
  .end(callback);

// 后端需要配置 CORS 头
// Access-Control-Allow-Origin: *
// Access-Control-Allow-Credentials: true

7.4 Promise 和 Callback 混用

问题：代码写得混乱，挑战可读性极限。

// 错误混用
request.get('/api/users')
  .end((err, res) => {}) // Callback 风格
  .then(res => {});      // 又想用 Promise 风格

// 统一使用一种风格
// Callback 风格
request.get('/api/users').end(callback);

// Promise 风格
request.get('/api/users').then(res => {}).catch(err => {});

7.5 请求头设置 Content-Type 错误

问题：JSON 当表单发，表单当 JSON 发。

// 发送 JSON 数据
request.post('/api/users')
  .set('Content-Type', 'application/json')
  .send({name: 'User'});

// 发送表单数据
request.post('/api/users')
  .type('form') // 或者 .set('Content-Type', 'application/x-www-form-urlencoded')
  .send({name: 'User'});

7.6 忽略 HTTPS 证书验证

问题：生产环境还用自签名证书，又不配置忽略验证。

// Node.js 环境下忽略证书验证（仅用于开发环境）
request.get('https://self-signed.badssl.com/')
  .ca(null) // 忽略证书验证
  .end(callback);

// 或者设置环境变量
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

7.7 文件上传路径错误

问题：文件路径写错，怪封装不好。

// 浏览器环境下正确上传文件
const fileInput = document.getElementById('fileInput');
request.post('/api/upload')
  .attach('file', fileInput.files[0]) // 使用 File 对象
  .end(callback);

// Node.js 环境下上传文件
request.post('/api/upload')
  .attach('file', '/path/to/file.txt') // 使用文件路径
  .end(callback);

7.8 查询参数编码问题

问题：中文参数不编码就直接发送，服务器收到乱码。

// SuperAgent 会自动处理编码
request.get('/api/search')
  .query({q: '用户的博客'}) // 自动编码为 UTF-8
  .end(callback);

// 手动编码（不推荐）
request.get('/api/search')
  .query({q: encodeURIComponent('用户的博客')})
  .end(callback);

7.9 并发请求处理不当

问题：一口气发几百个请求，服务器被打挂。

// 错误做法：无限制并发
const urls = ['/api/data1', '/api/data2'];
const promises = urls.map(url => request.get(url));
Promise.all(promises).then(results => {
  // 可能导致服务器压力过大
});

// 正确做法：限制并发数
async function limitedRequest(urls, limit = 5) {
  const results = [];
  for(let i = 0; i < urls.length; i += limit) {
    const batch = urls.slice(i, i + limit);
    const batchPromises = batch.map(url => request.get(url));
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
  }
  return results;
}

7.10 忽略错误处理

问题：错误处理全靠意念，出错了就当没看见。

// 错误做法：忽略错误
request.get('/api/users').end((err, res) => {
  console.log(res.body); // 如果 err 存在，这里会报错
});

// 正确做法：先处理错误
request.get('/api/users').end((err, res) => {
  if(err) {
    console.error('请求失败:', err);
    return;
  }
  console.log(res.body);
});

8. SuperAgent 方法速查表

8.1 HTTP 方法相关

8.2 请求配置相关

8.3 文件上传相关

9. 实战案例：构建完整的 API 客户端

9.1 基础 API 客户端封装

class ApiClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }

  // 通用请求方法
  request(method, url, data = null, options = {}) {
    const req = request[method.toLowerCase()](`${this.baseUrl}${url}`);
    
    // 设置请求头
    if(options.headers) { req.set(options.headers); }
    
    // 设置查询参数
    if(options.query) { req.query(options.query); }
    
    // 设置请求体数据
    if(data) { req.send(data); }
    
    // 设置超时
    if(options.timeout) { req.timeout(options.timeout); }
    
    return new Promise((resolve, reject) => {
      req.end((err, res) => {
        if(err) {
          reject(err);
        } else {
          resolve(res);
        }
      });
    });
  }

  // GET 请求
  get(url, options = {}) {
    return this.request('GET', url, null, options);
  }

  // POST 请求
  post(url, data, options = {}) {
    return this.request('POST', url, data, options);
  }

  // PUT 请求
  put(url, data, options = {}) {
    return this.request('PUT', url, data, options);
  }

  // DELETE 请求
  delete(url, options = {}) {
    return this.request('DELETE', url, null, options);
  }
}

// 使用示例
const api = new ApiClient('https://api.example.com');

// GET 请求
api.get('/users', {query: {page: 1, limit: 10}, timeout: 5000})
  .then(res => {
    console.log('用户列表:', res.body);
  })
  .catch(err => {
    console.error('获取用户列表失败:', err);
  });

// POST 请求
api.post('/users', {name: 'User', email: '[email protected]'}, {headers: {'Authorization': 'Bearer token123'}})
  .then(res => {
    console.log('创建用户成功:', res.body);
  })
  .catch(err => {
    console.error('创建用户失败:', err);
  });

9.2 带拦截器的高级客户端

class AdvancedApiClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.requestInterceptors = [];
    this.responseInterceptors = [];
  }

  // 添加请求拦截器
  useRequestInterceptor(interceptor) {
    this.requestInterceptors.push(interceptor);
  }

  // 添加响应拦截器
  useResponseInterceptor(interceptor) {
    this.responseInterceptors.push(interceptor);
  }

  // 执行请求拦截器
  async runRequestInterceptors(config) {
    let interceptedConfig = {...config};
    for(const interceptor of this.requestInterceptors) {
      interceptedConfig = await interceptor(interceptedConfig);
    }
    return interceptedConfig;
  }

  // 执行响应拦截器
  async runResponseInterceptors(response) {
    let interceptedResponse = response;
    for(const interceptor of this.responseInterceptors) {
      interceptedResponse = await interceptor(interceptedResponse);
    }
    return interceptedResponse;
  }

  // 核心请求方法
  async request(method, url, data = null, options = {}) {
    // 构建请求配置
    let config = { method, url: `${this.baseUrl}${url}`, data, options };
    
    // 执行请求拦截器
    config = await this.runRequestInterceptors(config);
    
    // 发送请求
    const req = request[config.method.toLowerCase()](config.url);
    
    // 应用配置
    if(config.options.headers) { req.set(config.options.headers); }
    if(config.options.query) { req.query(config.options.query); }
    if(config.data) { req.send(config.data); }
    if(config.options.timeout) { req.timeout(config.options.timeout); }
    
    try {
      const res = await new Promise((resolve, reject) => {
        req.end((err, response) => {
          if(err) reject(err);
          else resolve(response);
        });
      });
      
      // 执行响应拦截器
      const finalResponse = await this.runResponseInterceptors(res);
      return finalResponse;
    } catch(error) {
      throw error;
    }
  }

  // 便捷方法
  get(url, options = {}) { return this.request('GET', url, null, options); }
  post(url, data, options = {}) { return this.request('POST', url, data, options); }
  put(url, data, options = {}) { return this.request('PUT', url, data, options); }
  delete(url, options = {}) { return this.request('DELETE', url, null, options); }
}

// 使用示例
const advancedApi = new AdvancedApiClient('https://api.example.com');

// 添加请求拦截器 - 自动添加认证头
advancedApi.useRequestInterceptor(async(config) => {
  const token = localStorage.getItem('authToken');
  if(token) {
    config.options.headers = {...config.options.headers, 'Authorization': `Bearer ${token}`};
  }
  return config;
});

// 添加响应拦截器 - 统一处理错误
advancedApi.useResponseInterceptor(async(response) => {
  if(response.status >= 400) {
    throw new Error(`请求失败：${response.status}${response.text}`);
  }
  return response;
});

// 使用
advancedApi.get('/users')
  .then(res => {
    console.log('用户列表:', res.body);
  })
  .catch(err => {
    console.error('请求出错:', err.message);
  });

10. 性能优化与最佳实践

10.1 请求缓存策略

class CachedApiClient {
  constructor() {
    this.cache = new Map();
  }

  // 带缓存的 GET 请求
  async getCached(url, options = {}) {
    const cacheKey = `${url}?${JSON.stringify(options.query || {})}`;
    const cacheTimeout = options.cacheTimeout || 300000; // 5 分钟默认
    
    // 检查缓存
    if(this.cache.has(cacheKey)) {
      const cached = this.cache.get(cacheKey);
      if(Date.now() - cached.timestamp < cacheTimeout) {
        return cached.data;
      }
    }
    
    // 发送请求
    const res = await request.get(url).query(options.query || {});
    const data = res.body;
    
    // 存入缓存
    this.cache.set(cacheKey, { data, timestamp: Date.now() });
    return data;
  }

  // 清除缓存
  clearCache(url) {
    if(url) {
      // 清除特定 URL 的缓存
      for(const key of this.cache.keys()) {
        if(key.startsWith(url)) {
          this.cache.delete(key);
        }
      }
    } else {
      // 清除所有缓存
      this.cache.clear();
    }
  }
}

// 使用示例
const cachedApi = new CachedApiClient();

// 第一次请求，会发送网络请求
cachedApi.getCached('/api/users', {query: {page: 1}}).then(data => console.log('第一次:', data));

// 短时间内再次请求，会使用缓存
setTimeout(() => {
  cachedApi.getCached('/api/users', {query: {page: 1}}).then(data => console.log('使用缓存:', data));
}, 1000);

10.2 请求队列管理

class RequestQueue {
  constructor(concurrency = 3) {
    this.concurrency = concurrency;
    this.running = 0;
    this.queue = [];
  }

  // 添加请求到队列
  add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  // 处理队列
  async process() {
    if(this.running >= this.concurrency || this.queue.length === 0) {
      return;
    }
    this.running++;
    const { requestFn, resolve, reject } = this.queue.shift();
    try {
      const result = await requestFn();
      resolve(result);
    } catch(error) {
      reject(error);
    } finally {
      this.running--;
      this.process(); // 处理下一个请求
    }
  }
}

// 使用示例
const queue = new RequestQueue(2); // 最多并发 2 个请求
const urls = ['/api/data1', '/api/data2', '/api/data3', '/api/data4', '/api/data5'];

// 所有请求都会通过队列管理并发
Promise.all(
  urls.map(url => queue.add(() => request.get(url).then(res => res.body)))
).then(results => {
  console.log('所有请求完成:', results);
});

10.3 最佳实践总结

总结

SuperAgent 是一个优秀的 HTTP 客户端库，链式调用的设计让代码简洁优雅，功能强大且兼容性强，既能在浏览器中使用，也能在 Node.js 中运行。建议开发者遵循规范，妥善处理错误与性能优化，充分利用其特性提升开发效率。