NoAxios 使用文档

Node.js 轻量级 HTTP 客户端库，提供现代化特性支持，灵感来自 Axios 但更轻量化

---

目录

1. 功能特性
2. 安装使用
3. 快速上手
4. 配置选项
5. 请求方法
6. 拦截器
7. 错误处理
8. 代理配置
9. 重试机制
10. 流式处理
11. 响应处理

---

功能特性

• ✅ HTTP/HTTPS 双协议支持
• 🛡 智能代理服务器配置
• 🔁 自动重试与指数退避策略
• 🎯 精准的请求超时控制
• 🔀 自动处理重定向链路
• 🧩 可扩展的拦截器系统
• 📦 智能响应数据解析
• 🌊 流式请求/响应支持

---

安装使用

npm install no-axios

// ESM
import { NoAxios } from 'no-axios'

// CommonJS
const { NoAxios } = require('no-axios')

---

快速上手

基础示例

const client = new NoAxios({
  baseURL: 'https://api.example.com/v1'
})

// GET 请求
const res = await client.get('/users', {
  params: { page: 2 },
  headers: { 'X-API-Key': 'your-key' }
})

// POST 请求
await client.post('/users', {
  name: 'Alice',
  age: 28
}, {
  headers: { 'Content-Type': 'application/json' }
})

---

配置选项

核心配置参数

参数	类型	默认值	说明
url	string	''	请求路径（可绝对或相对路径）
baseURL	string	''	基础 URL（自动与 url 拼接）
method	string	'GET'	HTTP 方法 (GET/POST/PUT/DELETE 等)
params	object	{}	URL 查询参数对象
paramsSerializer	function	URLSearchParams 序列化	自定义查询参数序列化函数
data	any	undefined	请求体数据（支持对象/字符串/Buffer/流）
headers	object	{ 'user-agent': ... }	请求头配置
timeout	number	5000	请求超时时间（毫秒）
maxRedirects	number	5	最大重定向次数
maxRetries	number	3	最大重试次数
proxy	object/string	null	代理配置（支持 http/https/socks）
responseType	string	'auto'	响应类型（json/text/buffer/stream/auto）

---

请求方法

快捷方法

// GET
client.get(url[, config])

// POST
client.post(url[, data[, config]])

// PUT
client.put(url[, data[, config]])

// DELETE
client.delete(url[, config])

完整请求示例

const response = await client.request({
  method: 'PATCH',
  url: '/users/123',
  data: { name: 'Bob' },
  params: { track: true },
  headers: { 'X-Trace-ID': 'abc123' },
  timeout: 10000
})

---

拦截器

请求拦截器

// 添加请求拦截器
client.addRequestInterceptor(config => {
  // 修改配置示例：添加认证头
  config.headers.Authorization = `Bearer ${getToken()}`
  return config
})

响应拦截器

// 添加响应拦截器
client.addResponseInterceptor(response => {
  // 统一处理错误状态码
  if (response.status >= 400) {
    throw new Error(`业务错误: ${response.data?.message}`)
  }
  return response
})

---

错误处理

错误类型

try {
  await client.get('/invalid-url')
} catch (error) {
  if (error instanceof NoAxiosHttpError) {
    console.error('HTTP错误:', error.status)
  } 
  if (error instanceof NoAxiosNetworkError) {
    console.error('网络错误:', error.message)
  }
}

错误对象属性

属性	类型	说明
status	number	HTTP 状态码
data	any	响应体数据
headers	object	响应头信息
config	object	请求配置
request	object	请求基本信息 {method, url}

---

代理配置

基础代理设置

// 全局代理配置
const client = new NoAxios({
  proxy: 'http://proxy.example.com:8080'
})

// 请求级代理覆盖
await client.get('https://api.example.com', {
  proxy: 'socks5://user:pass@socks.example.com:1080'
})

高级代理配置

// 完整代理配置对象
const proxyConfig = {
  protocol: 'https:',
  hostname: 'proxy.example.com',
  port: 443,
  auth: {
    username: 'user',
    password: 'pass'
  }
}

await client.post('/data', { ... }, { proxy: proxyConfig })

---

重试机制

配置参数

参数	类型	默认值	说明
maxRetries	number	3	最大重试次数
retryDelay	number	1000	初始重试延迟（毫秒）
retryFactor	number	2	退避系数（延迟倍数）
maxRetryDelay	number	30000	最大重试延迟时间（毫秒）
shouldRetry	function	内置策略	判断是否重试的函数

自定义重试策略

const client = new NoAxios({
  shouldRetry: (error, retryCount) => {
    // 仅在网络错误或5xx错误时重试
    return error instanceof NoAxiosNetworkError || 
      (error.status >= 500 && retryCount < 2)
  }
})

---

流式处理

上传文件流

const fs = require('fs')

// 创建可读流
const fileStream = fs.createReadStream('./large-file.zip')

await client.put('/uploads', fileStream, {
  headers: {
    'Content-Type': 'application/zip',
    'X-Filename': 'archive.zip'
  }
})

下载流式响应

const response = await client.get('/video.mp4', {
  responseType: 'stream'
})

// 处理数据流
response.data.pipe(fs.createWriteStream('video.mp4'))

---

响应处理

自动数据解析

根据 Content-Type 自动转换：

• application/json → JavaScript 对象
• text/* → 字符串
• 其他 → Buffer

手动指定类型

// 强制返回 Buffer
const res = await client.get('/image.png', {
  responseType: 'buffer'
})

// 流式响应
const resStream = await client.get('/live-feed', {
  responseType: 'stream'
})

---

最佳实践

URL 配置技巧

// 基础 URL + 路径拼接
const apiClient = new NoAxios({
  baseURL: 'https://api.example.com/v2'
})

// 实际请求 URL: https://api.example.com/v2/users?active=true
apiClient.get('/users', {
  params: { active: true }
})

// 绝对 URL 覆盖
apiClient.get('https://backup.example.com/data')

配置继承

const baseConfig = {
  timeout: 10000,
  headers: { 'X-App-Version': '1.0.0' }
}

const userClient = new NoAxios(baseConfig)

// 请求级配置合并
userClient.post('/login', { ... }, {
  timeout: 15000, // 覆盖超时为15秒
  headers: { 'X-Request-ID': '123' } // 合并头部
})