iota-fetch

一个基于 axios 的二次封装请求库，提供统一的 get/post/delete/put/patch 调用方式，并内置请求队列能力（可按 key 中断单个请求或中断全部请求）。支持自定义 axios 默认配置、请求/响应拦截器，以及可选的 loading 显示/隐藏钩子。

安装

npm i iota-fetch axios

本项目本身依赖 axios，如果你在业务工程里已安装 axios，可按你的依赖管理策略处理（避免重复安装/版本冲突）。

快速开始

import { createFetch } from "iota-fetch";

const fetch = createFetch({
  requestConfig: {
    baseURL: "https://api.example.com",
    headers: {
      "Content-Type": "application/json;charset=utf-8",
    },
  },
});

// GET：第二个参数会作为 query params
const list = await fetch.get("/items", { page: 1, pageSize: 10 });

// POST：第二个参数会作为 body data
const created = await fetch.post("/items", { name: "foo" });

API

createFetch(options)

创建一个包含 get/post/delete/put/patch 的请求对象。

参数 options

• requestConfig: CreateAxiosDefaults
  • axios 实例默认配置（如 baseURL、timeout、headers 等）
• requestIntercept?: () => { onFulfilled, onRejected }
  • 请求拦截器工厂函数（内部会 instance.interceptors.request.use(...)）
• responseIntercept?: () => { onFulfilled, onRejected }
  • 响应拦截器工厂函数（内部会 instance.interceptors.response.use(...)）
• loading?: { show(): void; hide(): void }
  • 传入后可配合单次请求的 config.loading 控制显示/隐藏

返回值

返回 fetch 对象：

• fetch.get(url, data?, config?)
• fetch.delete(url, data?, config?)
• fetch.post(url, data?, config?)
• fetch.put(url, data?, config?)
• fetch.patch(url, data?, config?)

其中：

• url: string
• data?: any
• config?: AxiosRequestConfig & { loading?: boolean }

行为规则：

• get/delete：data 会被放到 params
• post/put/patch：data 会被放到 data
• 返回值：默认 Promise<R>，内部 resolve(res.data)

拦截器示例

import type { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from "axios";
import { createFetch } from "iota-fetch";

const fetch = createFetch({
  requestConfig: { baseURL: "https://api.example.com" },
  requestIntercept: () => ({
    onFulfilled: (config: InternalAxiosRequestConfig) => {
      config.headers.set("X-Token", "your-token");
      return config;
    },
    onRejected: (error: AxiosError) => Promise.reject(error),
  }),
  responseIntercept: () => ({
    onFulfilled: (resp: AxiosResponse) => resp,
    onRejected: (error: AxiosError) => Promise.reject(error),
  }),
});

Loading 示例

import { createFetch } from "iota-fetch";

const loading = {
  show: () => console.log("loading show"),
  hide: () => console.log("loading hide"),
};

const fetch = createFetch({
  requestConfig: { baseURL: "https://api.example.com" },
  loading,
});

// 只有当 config.loading 为 true 才会触发 show/hide
await fetch.get("/items", { page: 1 }, { loading: true });

请求队列与取消请求

包对外导出 requestQueue，内部用 AbortController 管理请求。

import { requestQueue } from "iota-fetch";

// 获取当前队列（Map<key, AbortController>）
const q = requestQueue.getQueue();

key 规则

key 默认由以下规则生成：

1. 基础部分：method + "-" + url
2. 数据部分：如果存在 data，则对其进行以下处理：
   • 递归排序对象键
   • 清洗数据（过滤 undefined 和函数）
   • 将处理后的数据转换为 JSON 字符串
   • 使用 MD5 生成哈希值
3. 最终 key：基础部分 + "-" + MD5哈希值

这样处理的好处是：

• 相同的请求参数（无论顺序如何）会生成相同的 key
• 避免了复杂参数导致 key 过长的问题
• 提高了 key 的唯一性和安全性

你也可以手动生成：

const key = requestQueue.createKey("get", "/items", { page: 1 });

示例：

// 以下两个请求会生成相同的 key
const key1 = requestQueue.createKey("get", "/items", { page: 1, size: 10 });
const key2 = requestQueue.createKey("get", "/items", { size: 10, page: 1 });

// 输出示例："get-/items-5f4dcc3b5aa765d61d8327deb882cf99"

中断单个请求

requestQueue.abortive(key);

中断所有请求

requestQueue.removeResAll();

同 key 自动取消旧请求（内置行为）

当发起新请求时，如果队列里已存在同一个 key，会先取消旧请求再登记新请求（避免相同请求并发造成的覆盖与浪费）。

注意：是否算“同一个请求”取决于 key（包含 method/url/data 的 JSON 字符串）。

开发与构建

# 构建产物到 lib/（CJS + ESM + d.ts）
npm run build

# 开发模式（watch + 本地静态服务 + livereload）
npm run start

# 自动发布脚本（检查代码更新、npm 登录状态、版本管理）
npm run release

构建输出（默认）：

• lib/bundle.cjs.js
• lib/bundle.esm.js
• lib/main.d.ts

发布流程

1. 运行 npm run release 启动发布流程
2. 脚本会检查代码是否有更新
3. 检查 npm 是否登录
4. 显示当前版本和仓库版本
5. 选择版本升级类型（小版本/中版本/大版本）
6. 执行构建和发布
7. 显示远程包的最新版本

版本管理

• 小版本：修复 bug，向后兼容
• 中版本：添加新功能，向后兼容
• 大版本：不向后兼容的变更