SuperAgent：现代JavaScript应用的HTTP客户端利器-代码聚汇网

SuperAgent：现代JavaScript应用的HTTP客户端利器

张少轶·2026-08-12·阅读 24 GEO检测（免费）

SuperAgentHTTP客户端JavaScript

|难度：普通|阅读约 57 分钟

1. SuperAgent 是什么？为什么开发者需要它？

SuperAgent 是一个轻量级、灵活的 HTTP 客户端库，专为现代 JavaScript 应用设计。它最初由 TJ Holowaychuk（Express.js 的创建者）开发，现在已成为 Node.js 和浏览器环境中处理 HTTP 请求的事实标准之一。

我在多个生产项目中深度使用过 SuperAgent，它最打动我的地方在于其优雅的链式 API 设计。与原生 fetch 或 axios 相比，SuperAgent 的 API 更加直观和富有表现力。比如一个简单的 POST 请求，用 SuperAgent 可以这样写：

javascript复制request
  .post('/api/pets')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('Accept', 'application/json')
  .then(res => {
     console.log(res.body);
  });

这种流畅的接口设计让代码可读性大幅提升，特别是在处理复杂请求时优势更加明显。我在维护一个大型电商后台时，曾经对比过三种 HTTP 客户端：

原生 fetch：需要手动处理 JSON 转换、错误处理等琐事
axios：功能全面但配置对象较为冗长
SuperAgent：链式调用让业务逻辑一目了然

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与基础安装

2.1 浏览器端集成

对于前端项目，最简单的引入方式是直接使用 CDN：

html复制<script src="https://cdn.jsdelivr.net/npm/superagent"></script>

但在实际生产环境中，我强烈建议通过 npm 安装并与你的构建工具集成：

bash复制npm install superagent
# 或者
yarn add superagent

注意：如果你使用 TypeScript，还需要安装类型定义文件：
bash复制npm install @types/superagent -D

2.2 Node.js 环境配置

在服务端使用时，除了基础安装外，还需要注意几个关键点：

如果你需要处理 HTTPS 请求，确保系统已安装最新 OpenSSL
对于代理环境，SuperAgent 支持通过 .proxy() 方法配置
在生产环境中，建议配置默认超时时间：

javascript复制const request = require('superagent');
request.timeout({
  response: 5000,  // 5秒服务器响应超时
  deadline: 60000, // 1分钟整体超时
});

我在部署一个金融系统时曾遇到过一个棘手问题：某些批量请求在没有超时设置的情况下会无限期挂起。通过合理配置 timeout 和 deadline，系统稳定性得到了显著提升。

3. 核心 API 实战指南

3.1 请求方法大全

SuperAgent 支持所有 HTTP 方法，每种方法都有对应的语法糖：

javascript复制// GET 请求的多种形式
request('GET', '/search').then(...);
request.get('/search').then(...);

// 带查询参数的 GET
request.get('/search')
  .query({ q: 'JavaScript' })
  .query({ page: 2 })
  
// POST 请求
request.post('/api')
  .send({ name: 'John' })
  
// PUT/DELETE 等
request.put('/api/thing')
request.del('/api/thing')

实际项目中，我发现 .query() 方法有个隐藏技巧：可以接受 URLSearchParams 对象，这在处理复杂查询时特别有用：

javascript复制const params = new URLSearchParams();
params.append('q', 'React');
params.append('page', '1');
request.get('/search')
  .query(params)

3.2 请求头与内容类型处理

设置请求头是 API 交互中的常见需求，SuperAgent 提供了多种方式：

javascript复制// 单个设置
request.get('/')
  .set('API-Key', 'foobar')
  .set('Accept', 'application/json')

// 批量设置
request.get('/')
  .set({
    'API-Key': 'foobar',
    'Accept': 'application/json'
  })

内容类型（Content-Type）的处理值得特别注意。SuperAgent 能自动根据发送的数据类型设置合适的 Content-Type：

javascript复制// 自动设置为 application/json
request.post('/')
  .send({ name: 'John' })

// 自动设置为 application/x-www-form-urlencoded
request.post('/')
  .send('name=John')

// 手动覆盖
request.post('/')
  .type('text/plain')
  .send('plain text')

我在对接一个老式 SOAP 服务时，发现必须显式设置 .type('text/xml') 才能正常工作，这是很多开发者容易忽略的细节。

3.3 响应处理进阶技巧

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

javascript复制request.get('/')
  .then(response => {
    // HTTP 状态码
    console.log(response.status);
    
    // 响应头
    console.log(response.header);
    
    // 响应体（自动根据 Content-Type 解析）
    console.log(response.body);
    
    // 原始文本
    console.log(response.text);
    
    // 对于二进制数据
    console.log(response.body);
  });

在处理大型 JSON 响应时，我发现一个性能优化点：如果只需要响应中的部分数据，可以直接访问 response.body 而不必调用 JSON.parse(response.text)，因为 SuperAgent 已经完成了这个解析工作。

4. 高级功能与实战场景

4.1 文件上传实现

文件上传是 Web 开发中的常见需求，SuperAgent 提供了简洁的 API：

javascript复制request.post('/upload')
  .attach('image', 'path/to/image.jpg')
  .field('caption', 'Vacation photo')
  .then(...);

在实际项目中，我经常需要处理上传进度显示。SuperAgent 的 .on('progress') 事件非常实用：

javascript复制const req = request.post('/upload')
  .attach('file', file)
  .on('progress', event => {
    console.log(`进度: ${Math.round(event.percent)}%`);
  });

重要提示：在浏览器环境中，文件上传需要确保 FormData API 可用。对于 IE10+ 的兼容性需求，可能需要引入 polyfill。

4.2 认证与安全实践

现代 Web 应用通常需要处理各种认证方式。以下是一些常见场景的实现：

Bearer Token 认证：

javascript复制request.get('/protected')
  .set('Authorization', `Bearer ${token}`)

基本认证：

javascript复制request.get('/protected')
  .auth('username', 'password')

Cookie 处理：

javascript复制// 发送 Cookie
request.get('/')
  .withCredentials()

// 接收 Cookie
const agent = request.agent();
agent.post('/login')
  .send({ user, pass })
  .then(() => {
    // 后续请求会自动携带 Cookie
    agent.get('/profile')
  })

在金融项目中，我们实现了 JWT 自动刷新的机制。通过 SuperAgent 的拦截器（interceptor）可以优雅地实现：

javascript复制const agent = request.agent();

// 请求拦截器
agent.use(req => {
  const token = getToken();
  if (token) {
    req.set('Authorization', `Bearer ${token}`);
  }
});

// 响应拦截器
agent.use(req => {
  req.on('response', res => {
    if (res.status === 401) {
      return refreshToken().then(newToken => {
        storeToken(newToken);
        return req.retry();
      });
    }
  });
});

4.3 错误处理最佳实践

SuperAgent 的错误处理有几个层级需要注意：

javascript复制request.get('/')
  .then(
    successHandler,
    errorHandler // 捕获网络错误和 4xx/5xx 响应
  );

// 更精细的错误处理
request.get('/')
  .then(response => {
    // 业务逻辑错误
    if (response.body.code !== 0) {
      throw new BusinessError(response.body.message);
    }
    return response.body.data;
  })
  .catch(err => {
    if (err.status === 404) {
      // 处理 404
    } else if (err.response) {
      // 服务器返回了错误响应
      console.log(err.response.body);
    } else {
      // 网络或其它错误
      console.log(err.message);
    }
  });

在日志系统中，我发现将完整的错误上下文记录下来对调试非常有帮助：

javascript复制.catch(err => {
  logError({
    message: err.message,
    status: err.status,
    method: err.method,
    url: err.url,
    stack: err.stack,
    response: err.response ? {
      status: err.response.status,
      body: err.response.body,
      text: err.response.text
    } : null
  });
});

5. 性能优化与调试技巧

5.1 连接池管理

在 Node.js 服务端应用中，合理配置 HTTP 连接池可以显著提升性能：

javascript复制const agent = request.agent()
  .use(request => {
    // 启用 keep-alive
    request.keepAlive(true);
    // 连接池配置
    request.agent(new http.Agent({
      keepAlive: true,
      maxSockets: 100,
      maxFreeSockets: 10,
      timeout: 60000
    }));
  });

在负载测试中，我发现合理的连接池配置可以将 QPS 提升 3-5 倍。特别是在微服务架构中，服务间通信频繁时效果更加明显。

5.2 请求重试策略

对于不稳定的网络环境，实现智能重试机制很有必要：

javascript复制const retry = require('superagent-retry')(request, {
  retries: 3,
  delay: 1000,
  onlyRetryOn: ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND']
});

retry.get('http://unstable-api.com')
  .then(...);

在移动端应用中，我还实现了指数退避算法来优化重试逻辑：

javascript复制function backoff(retries) {
  return Math.min(1000 * Math.pow(2, retries), 30000);
}

request.get('/')
  .retry(3, (err, res, retries) => {
    return new Promise(resolve => {
      setTimeout(() => resolve(), backoff(retries));
    });
  });

5.3 调试与日志记录

开发阶段，启用详细日志可以快速定位问题：

javascript复制request.get('/')
  .on('request', req => {
    console.log('发出请求:', req.method, req.url);
  })
  .on('response', res => {
    console.log('收到响应:', res.status, res.type);
  })
  .on('redirect', res => {
    console.log('重定向到:', res.headers.location);
  });

对于生产环境，我建议使用结构化日志：

javascript复制const winston = require('winston');
const logger = winston.createLogger({...});

request.get('/')
  .use(req => {
    const start = Date.now();
    req.on('response', res => {
      logger.info({
        duration: Date.now() - start,
        method: req.method,
        url: req.url,
        status: res.status,
        length: res.header['content-length']
      });
    });
  });

6. 与前端框架的集成实践

6.1 React 中的使用模式

在 React 组件中，最佳实践是将 SuperAgent 请求封装到服务模块中：

javascript复制// apiService.js
export const getProducts = () => {
  return request.get('/api/products')
    .then(res => res.body);
};

// ProductList.jsx
import { useEffect, useState } from 'react';
import { getProducts } from './apiService';

function ProductList() {
  const [products, setProducts] = useState([]);
  
  useEffect(() => {
    getProducts()
      .then(data => setProducts(data))
      .catch(err => console.error(err));
  }, []);
  
  return (...);
}

在大型项目中，我通常会创建一个完整的 API 客户端类：

javascript复制class ApiClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
    this.agent = request.agent();
  }
  
  get(path) {
    return this.agent.get(`${this.baseURL}${path}`)
      .then(res => res.body);
  }
  
  // 其他方法...
}

// 使用上下文提供全局实例
const ApiContext = React.createContext();
export const useApi = () => useContext(ApiContext);

// 在根组件中
function App() {
  const api = new ApiClient(process.env.API_URL);
  
  return (
    <ApiContext.Provider value={api}>
      {/* 子组件 */}
    </ApiContext.Provider>
  );
}

6.2 Vue 集成方案

在 Vue 中，可以将 SuperAgent 挂载到 Vue 原型上：

javascript复制// main.js
import Vue from 'vue';
import request from 'superagent';

Vue.prototype.$http = request;

// 组件中使用
export default {
  methods: {
    fetchData() {
      this.$http.get('/api/data')
        .then(res => {
          this.data = res.body;
        });
    }
  }
}

更模块化的做法是使用 Vue 的插件系统：

javascript复制// httpPlugin.js
export default {
  install(Vue, options) {
    const agent = request.agent()
      .use(req => {
        req.set('X-Requested-With', 'XMLHttpRequest');
        if (options.baseURL) {
          req.url = options.baseURL + req.url;
        }
      });
    
    Vue.prototype.$http = agent;
    Vue.prototype.$upload = (url, file) => {
      return agent.post(url)
        .attach('file', file);
    };
  }
};

// main.js
Vue.use(httpPlugin, {
  baseURL: process.env.VUE_APP_API_URL
});

6.3 与状态管理集成

在 Redux 应用中，处理异步请求通常使用 redux-thunk 或 redux-saga：

javascript复制// 使用 redux-thunk
const fetchProducts = () => (dispatch) => {
  dispatch({ type: 'PRODUCTS_REQUEST' });
  
  return request.get('/api/products')
    .then(res => {
      dispatch({
        type: 'PRODUCTS_SUCCESS',
        payload: res.body
      });
    })
    .catch(err => {
      dispatch({
        type: 'PRODUCTS_FAILURE',
        error: err.message
      });
    });
};

// 在组件中
dispatch(fetchProducts());

对于更复杂的场景，redux-saga 提供了更强大的控制流：

javascript复制import { call, put, takeLatest } from 'redux-saga/effects';

function* fetchProductsSaga() {
  try {
    const response = yield call(request.get, '/api/products');
    yield put({
      type: 'PRODUCTS_SUCCESS',
      payload: response.body
    });
  } catch (err) {
    yield put({
      type: 'PRODUCTS_FAILURE',
      error: err.message
    });
  }
}

export default function* rootSaga() {
  yield takeLatest('PRODUCTS_REQUEST', fetchProductsSaga);
}

7. 常见问题与解决方案

7.1 CORS 问题排查

跨域问题是前端开发中的常见障碍。SuperAgent 处理 CORS 需要注意：

javascript复制// 启用跨域凭证
request.get('https://api.other.com')
  .withCredentials()
  .then(...);

如果遇到 CORS 错误，检查点包括：

服务端是否正确设置了 Access-Control-Allow-Origin
是否需要在预检请求中处理 OPTIONS 方法
自定义头是否在 Access-Control-Allow-Headers 中声明

我在实际项目中发现，开发环境经常需要配置代理来绕过 CORS 限制。一个实用的 webpack 代理配置：

javascript复制// webpack.config.js
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  }
};

7.2 处理 502/504 网关错误

网关错误通常表示后端服务不可用或超时。SuperAgent 中可以通过以下方式增强稳定性：

javascript复制request.get('/')
  .retry(2) // 重试2次
  .timeout({
    response: 5000,  // 等待服务器响应时间
    deadline: 30000  // 整个请求超时时间
  })
  .then(...)
  .catch(err => {
    if (err.status === 502) {
      // 显示友好的错误信息
      showNotification('服务暂时不可用，请稍后重试');
    }
  });

对于关键业务接口，我建议实现熔断机制：

javascript复制class CircuitBreaker {
  constructor(request, options) {
    this.state = 'CLOSED';
    this.failureCount = 0;
    this.request = request;
    this.options = options;
  }
  
  async call() {
    if (this.state === 'OPEN') {
      throw new Error('Circuit breaker is open');
    }
    
    try {
      const res = await this.request;
      this.reset();
      return res;
    } catch (err) {
      this.failureCount++;
      if (this.failureCount >= this.options.threshold) {
        this.state = 'OPEN';
        setTimeout(() => {
          this.state = 'HALF-OPEN';
        }, this.options.timeout);
      }
      throw err;
    }
  }
  
  reset() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
}

// 使用示例
const breaker = new CircuitBreaker(
  request.get('/api'),
  { threshold: 3, timeout: 10000 }
);

breaker.call().then(...).catch(...);

7.3 内容类型解析问题

当服务端返回的内容类型与实际内容不匹配时，可以强制指定解析方式：

javascript复制request.get('/csv-data')
  .parse((res, callback) => {
    // 自定义解析逻辑
    res.text = '';
    res.setEncoding('utf8');
    res.on('data', chunk => {
      res.text += chunk;
    });
    res.on('end', () => {
      callback(null, parseCSV(res.text));
    });
  })
  .then(data => {
    // 这里得到的是 parseCSV 的结果
  });

在处理非标准 JSON 响应时，我曾经遇到过这样的案例：

javascript复制// 服务端返回: )]}'\n{"status":"ok","data":[...]}
request.get('/legacy-api')
  .parse((res, callback) => {
    res.text = '';
    res.on('data', chunk => res.text += chunk);
    res.on('end', () => {
      try {
        const json = JSON.parse(res.text.replace(/^\)\]\}'\n/, ''));
        callback(null, json);
      } catch (err) {
        callback(err);
      }
    });
  });

8. 测试策略与 Mock 方案

8.1 单元测试中的 HTTP 请求模拟

使用 nock 可以方便地模拟 HTTP 请求：

javascript复制const nock = require('nock');
const request = require('superagent');

describe('API 测试', () => {
  it('应该成功获取用户数据', async () => {
    nock('http://api.example.com')
      .get('/users/1')
      .reply(200, { id: 1, name: 'John' });
    
    const res = await request.get('http://api.example.com/users/1');
    expect(res.body).toEqual({ id: 1, name: 'John' });
  });
});

对于更复杂的场景，我建议使用专门的 mock 服务：

javascript复制// 使用 msw (Mock Service Worker)
import { setupWorker, rest } from 'msw';

const worker = setupWorker(
  rest.get('/api/user', (req, res, ctx) => {
    return res(
      ctx.delay(150),
      ctx.json({ id: 1, name: 'Mock User' })
    );
  })
);

beforeAll(() => worker.start());
afterAll(() => worker.stop());

test('获取模拟用户', async () => {
  const res = await request.get('/api/user');
  expect(res.body).toEqual({ id: 1, name: 'Mock User' });
});

8.2 端到端测试集成

在 Cypress 测试中使用 SuperAgent：

javascript复制describe('API 测试', () => {
  it('应该创建新资源', () => {
    cy.wrap(
      request.post('http://localhost:3000/api/resources')
        .send({ name: 'Test' })
        .then(res => res.body)
    ).should('have.property', 'id');
  });
});

对于需要登录状态的测试，可以复用 agent 保持会话：

javascript复制describe('认证测试', () => {
  let agent;
  
  before(() => {
    agent = request.agent();
    return agent.post('http://localhost:3000/login')
      .send({ username: 'test', password: 'test' });
  });
  
  it('应该访问受保护路由', () => {
    return agent.get('http://localhost:3000/protected')
      .then(res => {
        expect(res.status).to.equal(200);
      });
  });
});

9. 性能对比与替代方案

9.1 与 Fetch API 的对比

虽然现代浏览器原生支持 fetch，但 SuperAgent 在以下场景更具优势：

更简洁的错误处理：

javascript复制// fetch 需要检查 response.ok
fetch('/api')
  .then(res => {
    if (!res.ok) throw new Error(res.statusText);
    return res.json();
  })

// SuperAgent 自动处理
request.get('/api')
  .then(res => res.body)

更灵活的请求构建：

javascript复制// fetch 需要手动构建 URLSearchParams
const params = new URLSearchParams({ page: 1, limit: 10 });
fetch(`/api?${params}`)

// SuperAgent 更直观
request.get('/api')
  .query({ page: 1, limit: 10 })

上传进度支持：

javascript复制// fetch 没有原生进度事件
// SuperAgent 提供进度回调
request.post('/upload')
  .attach('file', file)
  .on('progress', event => {
    console.log(event.percent);
  })

9.2 与 Axios 的对比

Axios 是另一个流行的 HTTP 客户端，与 SuperAgent 的主要区别：

特性	SuperAgent	Axios
API 风格	链式调用	配置对象
浏览器支持	所有现代浏览器	所有现代浏览器
Node.js 支持	是	是
拦截器	通过插件实现	内置
取消请求	通过插件实现	内置 CancelToken
自动转换 JSON	是	是
上传进度	支持	支持
体积	~6KB (min+gzip)	~4KB (min+gzip)

选择建议：

如果你喜欢链式 API 和更灵活的请求构建方式，选择 SuperAgent
如果你需要内置的拦截器和取消请求功能，选择 Axios

10. 实际项目经验分享

10.1 电商平台中的实践

在一个大型电商平台中，我们使用 SuperAgent 处理了以下场景：

商品搜索：构建复杂的查询参数

javascript复制const buildSearchQuery = (filters) => {
  return request.get('/api/search')
    .query({ q: filters.keyword })
    .query({ sort: filters.sortBy })
    .query({ 
      price: `${filters.minPrice}-${filters.maxPrice}` 
    })
    .query({ 
      attributes: filters.attributes.join(',') 
    });
};

购物车批量操作：

javascript复制request.post('/api/cart/batch')
  .send({
    add: itemsToAdd,
    remove: itemsToRemove,
    update: itemsToUpdate
  })
  .then(res => {
    // 处理部分成功的情况
    if (res.body.partialSuccess) {
      showPartialSuccessAlert(res.body.results);
    }
  });

支付状态轮询：

javascript复制function pollPaymentStatus(orderId, timeout = 30000) {
  const start = Date.now();
  
  function check() {
    return request.get(`/api/orders/${orderId}/status`)
      .then(res => {
        if (res.body.status === 'completed') return res.body;
        if (Date.now() - start > timeout) {
          throw new Error('Polling timeout');
        }
        return new Promise(resolve => {
          setTimeout(() => resolve(check()), 1000);
        });
      });
  }
  
  return check();
}

10.2 微服务架构中的使用

在基于微服务的后台系统中，我们实现了以下模式：

服务发现集成：

javascript复制const serviceDiscovery = require('./discovery');

async function callService(serviceName, path, options = {}) {
  const instance = await serviceDiscovery.getInstance(serviceName);
  return request[options.method || 'get'](
    `http://${instance.host}:${instance.port}${path}`
  )
    .set('X-Request-ID', generateRequestId())
    .set('X-Service-Caller', 'web-api')
    .query(options.query || {})
    .send(options.body || {});
}

分布式追踪：

javascript复制const cls = require('cls-hooked');
const namespace = cls.createNamespace('app');

request.use(req => {
  const traceId = namespace.get('traceId');
  if (traceId) {
    req.set('X-Trace-ID', traceId);
  }
});

断路器模式实现：

javascript复制class ServiceClient {
  constructor(serviceName) {
    this.serviceName = serviceName;
    this.state = 'CLOSED';
    this.failures = 0;
  }
  
  async request(path) {
    if (this.state === 'OPEN') {
      throw new Error('Circuit breaker open');
    }
    
    try {
      const res = await callService(this.serviceName, path);
      this.reset();
      return res;
    } catch (err) {
      this.failures++;
      if (this.failures >= 3) {
        this.state = 'OPEN';
        setTimeout(() => {
          this.state = 'HALF-OPEN';
        }, 10000);
      }
      throw err;
    }
  }
  
  reset() {
    this.failures = 0;
    this.state = 'CLOSED';
  }
}

10.3 移动应用中的优化技巧

在 React Native 项目中，我们针对移动网络特性做了以下优化：

请求压缩：

javascript复制request.post('/api')
  .send(data)
  .set('Accept-Encoding', 'gzip')
  .compress()

离线缓存：

javascript复制const cache = new Map();

function cachedRequest(url) {
  if (cache.has(url)) {
    const { data, timestamp } = cache.get(url);
    if (Date.now() - timestamp < CACHE_TTL) {
      return Promise.resolve(data);
    }
  }
  
  return request.get(url)
    .then(res => {
      cache.set(url, {
        data: res.body,
        timestamp: Date.now()
      });
      return res.body;
    })
    .catch(err => {
      if (cache.has(url)) {
        return cache.get(url).data;
      }
      throw err;
    });
}

弱网适应：

javascript复制import { NetInfo } from 'react-native';

request.use(req => {
  return NetInfo.fetch().then(state => {
    if (!state.isConnected) {
      throw new Error('No network connection');
    }
    if (state.type === 'cellular') {
      req.timeout(30000); // 移动网络增加超时
    }
    return req;
  });
});

11. 插件生态系统

SuperAgent 的强大之处在于其可扩展性，以下是几个常用插件：

11.1 superagent-prefix

为所有请求添加统一前缀：

javascript复制const prefix = require('superagent-prefix')('/api/v1');

request.get('/users')
  .use(prefix)
  // 实际请求 /api/v1/users

11.2 superagent-promise-plugin

提供更完善的 Promise 支持：

javascript复制const request = require('superagent');
require('superagent-promise-plugin')(request);

request.get('/')
  .then(res => ...)
  .catch(err => ...)
  .finally(() => ...);

11.3 superagent-mock

创建模拟响应：

javascript复制const mockConfig = [
  {
    pattern: '/users/(\\d+)',
    fixtures: (match) => {
      return { id: match[1], name: 'Mock User' };
    },
    get: (match, data) => ({ body: data })
  }
];

const mock = require('superagent-mock')(request, mockConfig);

request.get('/users/123')
  .then(res => {
    console.log(res.body); // { id: '123', name: 'Mock User' }
  });

11.4 自定义插件开发

创建一个记录请求耗时的插件：

javascript复制function timingPlugin() {
  return req => {
    const start = Date.now();
    
    req.on('response', res => {
      res.time = Date.now() - start;
    });
    
    req.on('error', err => {
      err.time = Date.now() - start;
    });
  };
}

// 使用插件
request.get('/')
  .use(timingPlugin())
  .then(res => {
    console.log(`请求耗时: ${res.time}ms`);
  });

12. 未来展望与升级建议

虽然 SuperAgent 已经非常成熟，但在以下方面仍有改进空间：

TypeScript 支持：官方类型定义可以更加完善
Tree Shaking：减小浏览器端打包体积
更现代的 Promise 链：支持 async/await 模式
内置重试逻辑：提供更灵活的重试策略

对于新项目，我建议采用以下架构：

javascript复制// httpClient.js
import request from 'superagent';
import prefix from 'superagent-prefix';
import retry from 'superagent-retry';

const apiClient = request
  .agent()
  .use(prefix(process.env.API_BASE_URL))
  .use(retry({ retries: 2 }))
  .use(req => {
    req.set('Accept', 'application/json');
    if (store.getState().auth.token) {
      req.set('Authorization', `Bearer ${store.getState().auth.token}`);
    }
  });

export default {
  get: path => apiClient.get(path).then(res => res.body),
  post: (path, data) => apiClient.post(path).send(data).then(res => res.body),
  // 其他方法...
};

这种封装方式提供了统一的配置入口，同时保持了 SuperAgent 的灵活性。