@saplingjs/axios-http-client

一个基于 Axios 的 TypeScript HTTP 客户端。它不绑定 Vue、React、Nuxt 或任何 UI 框架，专注处理业务项目里最常见的请求问题：取消、搜索竞态、重试、统一错误模型，以及日志/监控等插件扩展。

特性

• 提供 GET、POST、PUT、PATCH、DELETE 等类型安全方法。
• 通过 requestKey 支持应用层取消同一逻辑请求。
• 支持“后发优先”：旧响应即使晚到，也不能覆盖新数据。
• 支持全局静默取消或全局提示，并允许单次请求单独处理取消。
• 统一 HTTP、网络、超时、取消、过期响应五类错误。
• 仅对幂等方法默认重试，也支持自定义重试次数、间隔和条件。
• hooks 和插件可用于 Token 注入、日志、监控、链路追踪和错误上报。
• 同时提供 ESM、CommonJS 和 TypeScript 声明文件。

安装

pnpm add @saplingjs/axios-http-client
# 或 npm install @saplingjs/axios-http-client

要求 Node.js >= 20。

快速开始

import { createClient } from "@saplingjs/axios-http-client";

const api = createClient({
  baseURL: "https://api.example.com",
  timeout: 10_000,
});

type User = { id: string; name: string };

const user = await api.get<User>("/users/u_1");

搜索时取消上一次请求，并防止竞态覆盖

为同一业务动作设置稳定的 requestKey。用户连续输入时，新的请求会中断旧请求；即使底层网络无法及时中断，旧响应也会被标记为过期，不能再影响最新数据。

const users = await api.get<User[]>("/users", {
  params: { keyword },
  requestKey: "user-search",
  supersede: "cancel-previous-and-discard-stale",
});

只想淘汰晚到响应、但不主动中止旧网络请求时，使用 discard-stale。

取消策略

默认取消是静默的；全局配置 notify 后，客户端级 onCancel 会触发。单次请求可以覆盖全局策略，并提供自己的 onCancel。

const api = createClient({
  cancelHandling: "notify",
  hooks: {
    onCancel: ({ request }) => {
      console.info(`已取消：${request.requestKey}`);
    },
  },
});

const task = api.get("/reports", { requestKey: "report" });
api.cancel("report", "manual");

await task;

await api.get("/download", {
  requestKey: "download",
  cancelHandling: "silent",
  onCancel: () => {
    console.info("下载由当前页面自行处理取消");
  },
});

重试与错误处理

默认只会重试可安全重复执行的幂等请求。错误可通过 kind 区分：http、network、timeout、cancelled、stale。

try {
  await api.get("/health", {
    retry: {
      retries: 2,
      delay: (attempt) => attempt * 500,
    },
  });
} catch (error) {
  const httpError = error as { kind: string; status?: number };
  if (httpError.kind === "cancelled") {
    // 取消通常不需要提示。
  }
}

插件

插件适合接入日志、监控和链路追踪，不会让业务代码依赖具体平台。

api.use({
  name: "请求日志",
  onRequest: ({ request }) => console.info("发送", request.url),
  onSuccess: ({ request }) => console.info("成功", request.url),
  onError: ({ error }) => console.error("失败", error?.kind),
});

文档与开发

• 使用指南和示例：docs
• 自动生成的 API 文档：执行 pnpm docs:api
• 本地文档站：执行 pnpm docs:dev

pnpm install
pnpm check
pnpm test
pnpm typecheck
pnpm build
pnpm docs:build

发布维护

发布前执行 npm pack 或 npm publish --dry-run 检查实际产物。npm 已发布版本不可覆盖；修复发布 0.0.x，新增兼容能力发布 0.x.0。

许可证

MIT