quick-fy

quick-fy 是一个轻量级、可扩展的基于 fetch 的 HTTP 请求库，适用于浏览器和 Node.js 环境。

特性

• 基于原生 fetch API
• 支持请求和响应拦截器
• 提供全局钩子函数（onSuccess, onError, onComplete）
• 中间件（Middleware）洋葱模型，支持网络层拦截和修改
• 插件（Addon）系统，可打包复用 middleware + 拦截器
• 内置常用中间件：logger、retry、timeout、body、params
• 内置常用插件：headers
• 支持自定义元数据传递
• 类型安全，使用 TypeScript 编写

安装

npm install quick-fy

快速开始

import { createFy, fy } from 'quick-fy'

// 使用默认 fy 实例
const data = await fy.get('https://api.example.com/users')

// 创建自定义实例
const api = createFy({
  baseURL: 'https://api.example.com',
})

const users = await api.get<User[]>('/users')
const user = await api.post<User>('/users', {}, { meta: { data: { name: 'Alice' } } })

内置中间件

logger - 请求日志

记录请求和响应信息，包含耗时统计。

import { createFy } from 'quick-fy'
import { logger } from 'quick-fy/middlewares/logger'

const fy = createFy()
fy.use(logger())

// 输出示例:
// → GET https://api.example.com/users
// ← GET https://api.example.com/users 200 (123ms)

自定义回调：

fy.use(logger({
  onRequest: (method, url) => console.log(`Sending ${method} ${url}`),
  onResponse: (method, url, status, duration) => console.log(`${status} in ${duration}ms`),
  onError: (method, url, error, duration) => console.error(`Failed: ${error.message}`),
}))

| 选项 | 类型 | 默认行为 | |------|------|---------| | onRequest | (method, url) => void | 打印 → METHOD URL | | onResponse | (method, url, status, duration) => void | 打印 ← METHOD URL STATUS (durationms) | | onError | (method, url, error, duration) => void | 打印 ✗ METHOD URL message (durationms) |

retry - 自动重试

请求失败时自动重试，默认仅重试网络错误（TypeError）。

import { retry } from 'quick-fy/middlewares/retry'

fy.use(retry())

// 自定义配置
fy.use(retry({
  retries: 5,
  delay: 2000,
  shouldRetry: (error, attempt) => attempt < 3,
}))

| 选项 | 类型 | 默认值 | |------|------|--------| | retries | number | 3 | | delay | number (ms) | 1000 | | shouldRetry | (error, attempt) => boolean | 仅 TypeError 时重试 |

timeout - 请求超时

使用 AbortController 实现请求超时控制。

import { timeout, TimeoutError } from 'quick-fy/middlewares/timeout'

fy.use(timeout({ timeout: 5000 }))

try {
  await fy.get('/slow-api')
}
catch (error) {
  if (error instanceof TimeoutError) {
    console.log('请求超时')
  }
}

| 选项 | 类型 | 说明 | |------|------|------| | timeout | number (ms) | 必填，超时时间 |

body - JSON 请求体

自动将 meta.data 序列化为 JSON 请求体。

import { body } from 'quick-fy/middlewares/body'

fy.use(body())

await fy.post('/users', {}, { data: { name: 'Alice', age: 25 } })
// 自动设置 Content-Type: application/json 并序列化 body

params - 查询参数

自动将 meta.params 序列化为 URL 查询字符串。

import { params } from 'quick-fy/middlewares/params'

fy.use(params())

await fy.get('/users', {}, { params: { page: 1, size: 20 } })
// 实际请求: /users?page=1&size=20

内置插件

headers - 默认请求头

为所有请求添加默认 headers，不会覆盖已存在的同名 header。

import { headers } from 'quick-fy/addons/headers'

const fy = createFy({
  addons: [
    headers({
      headers: {
        'Authorization': 'Bearer token123',
        'X-App-Version': '1.0.0',
      },
    }),
  ],
})

Middleware

Middleware 作用于 fetch 调用的网络层，采用洋葱模型（onion model）执行。每个 middleware 接收 next 并返回新的处理函数，可以在请求前后添加逻辑。

import type { Middleware } from 'quick-fy'

// 自定义中间件
const rewriteUrl: Middleware = next => async (url, config, meta) => {
  return next(url.replace('api/v1', 'api/v2'), config, meta)
}

const fy = createFy()
fy.use(rewriteUrl)

中间件按注册顺序执行，形成洋葱模型：

A-before → B-before → fetch → B-after → A-after

调用 fy.clearMiddlewares() 可以移除所有中间件。

Addon

Addon 是 middleware 和拦截器的打包复用单元。一个 addon 是带有 install 方法的对象，install 接收完整的 FyInstance，可以注入 middleware、拦截器等能力。

import type { FyAddon } from 'quick-fy'

const myAddon: FyAddon = {
  install(fy) {
    fy.use(someMiddleware)
    fy.addBeforeInterceptor((method) => {
      return { ...method, meta: { ...method.meta, retries: 3 } }
    })
  }
}

// 注册方式
const fy = createFy({ addons: [myAddon] })
// 或动态注册
fy.useAddon(myAddon)

拦截器

拦截器作用于请求/响应的数据层。

const fy = createFy()

// 请求拦截器 - 在请求发送前修改请求
fy.addBeforeInterceptor((method) => {
  console.log('请求:', method.url)
  return method
})

// 响应拦截器 - 在响应返回前修改响应
fy.addAfterInterceptor((response) => {
  console.log('响应状态:', response.status)
  return response
})

// 清除拦截器
fy.clearBeforeInterceptors()
fy.clearAfterInterceptors()

三者关系

| 层级 | 能力 | 作用范围 | |------|------|---------| | Middleware | 网络层拦截，操作 url/config/meta，返回 Response | fetch 调用层 | | Interceptor | 请求/响应数据层，修改 Method 或 Response | beforeRequest / afterInterceptor | | Addon | 打包容器，组合 middleware + interceptor | 通过 install 注册到实例 |

API 参考

createFy(options)

创建一个新的 fy 实例。

| 字段 | 类型 | 说明 | |------|------|------| | baseURL | string | 基础 URL，非 http 开头的请求会自动拼接 | | beforeRequest | RequestInterceptor | 请求前拦截器 | | responded | RespondedHook | 全局响应钩子（onSuccess, onError, onComplete） | | middlewares | Middleware[] | 中间件数组 | | addons | FyAddon[] | 插件数组 |

FyInstance 方法

| 方法 | 说明 | |------|------| | request<T>(url, init?, meta?) | 发送请求 | | get<T>(url, init?, meta?) | GET 请求 | | post<T>(url, init?, meta?) | POST 请求 | | put<T>(url, init?, meta?) | PUT 请求 | | delete<T>(url, init?, meta?) | DELETE 请求 | | patch<T>(url, init?, meta?) | PATCH 请求 | | addBeforeInterceptor(interceptor) | 添加请求前拦截器 | | addAfterInterceptor(interceptor) | 添加响应后拦截器 | | clearBeforeInterceptors() | 清除所有请求前拦截器 | | clearAfterInterceptors() | 清除所有响应后拦截器 | | use(middleware) | 添加中间件 | | clearMiddlewares() | 清除所有中间件 | | useAddon(addon) | 动态注册插件 |

Meta 字段

通过第三个参数 meta 传递请求元数据：

| 字段 | 类型 | 说明 | |------|------|------| | responseType | 'json' \| 'text' \| 'blob' \| 'arraybuffer' | 指定响应数据类型 | | data | any | 请求体数据（需配合 body 中间件） | | params | Record<string, string \| number \| boolean> | 查询参数（需配合 params 中间件） |

FyError

请求失败时抛出，包含以下字段：

| 字段 | 类型 | 说明 | |------|------|------| | message | string | 错误信息 | | status | number | HTTP 状态码 | | response | Response | 原始 Response 对象 | | method | Method | 请求方法信息 |

许可证

MIT License © 2024-PRESENT XiaDeYu