@newaifree-tool/request-fetch-imp

request-fetch-imp 是基于原生 fetch 的 Requestor 实现包。

它适合不想引入 axios、或者运行环境更偏向标准 fetch API 的项目。

安装

pnpm add @newaifree-tool/request-fetch-imp @newaifree-tool/request-core

基础用法

import { FetchRequestor } from "@newaifree-tool/request-fetch-imp";

const requestor = new FetchRequestor({
  baseURL: "https://api.example.com",
  timeout: 10_000,
  withCredentials: true,
});

const response = await requestor.get<User[]>("/users", {
  params: { page: 1, pageSize: 20 },
});

console.log(response.data);

POST 请求

const response = await requestor.post<User>(
  "/users",
  {
    name: "Tom",
    age: 18,
  },
);

普通对象会自动序列化为 JSON，并设置 Content-Type: application/json。

FormData、Blob、URLSearchParams 会直接传给 fetch，不会被 JSON 序列化。

请求参数

params 会被拼接到 URL 查询字符串：

await requestor.get("/users", {
  params: {
    keyword: "tom",
    roles: ["admin", "user"],
  },
});

最终请求类似：

/users?keyword=tom&roles=admin&roles=user

添加拦截器

requestor.interceptors.request.use((config) => {
  config.headers = {
    ...config.headers,
    Authorization: `Bearer ${accessToken}`,
  };

  return config;
});

requestor.interceptors.response.use((response) => {
  return response;
});

requestor.interceptors.error.use((error) => {
  throw error;
});

拦截器应该注册在 FetchRequestor 实例上。createXxxRequestor 包装器只负责缓存、重试、幂等等能力。

超时和取消

FetchRequestor 内部使用 AbortController 实现超时控制。

const controller = new AbortController();

const promise = requestor.get("/users", {
  signal: controller.signal,
  timeout: 5_000,
});

controller.abort();

await promise;

非 2xx 响应

fetch 原生不会因为 4xx/5xx 自动抛错，但 FetchRequestor 会把非 2xx 响应转换为错误，并进入错误拦截器。

requestor.interceptors.error.use((error) => {
  const status = error?.response?.status;

  if (status === 401) {
    // 处理登录过期。
  }

  throw error;
});

和 request-core 能力组合

import {
  createRetryRequestor,
  createCacheRequestor,
  createIdempotentRequestor,
} from "@newaifree-tool/request-core";
import { FetchRequestor } from "@newaifree-tool/request-fetch-imp";

const baseRequestor = new FetchRequestor({
  baseURL: "https://api.example.com",
});

let requestor = baseRequestor;
requestor = createRetryRequestor(requestor, { maxCount: 3 });
requestor = createCacheRequestor(requestor, { duration: 30_000 });
requestor = createIdempotentRequestor(requestor, { mode: "concurrent" });

和 request-bus 组合

import { createBus, defineEndpoint } from "@newaifree-tool/request-bus";
import { FetchRequestor } from "@newaifree-tool/request-fetch-imp";

interface User {
  id: number;
  name: string;
}

const requestor = new FetchRequestor({
  baseURL: "https://api.example.com",
});

const bus = createBus({ requestor });

const userApi = bus.createApiService({
  listUsers: defineEndpoint<User[]>({
    path: "/users",
    method: "GET",
    cache: true,
  }),
});

const users = await userApi.listUsers();

适用场景

• 不想引入 axios。
• 浏览器或 Node 18+ 环境可直接使用 fetch。
• 希望用统一 Requestor 契约接入 request-core 和 request-bus。