@newaifree-tool/request-core

request-core 是请求库的核心能力包，只定义请求契约和通用请求能力，不绑定 axios、fetch 或任何业务协议。

它适合被底层请求实现包和业务 API 层复用。

安装

pnpm add @newaifree-tool/request-core

核心职责

• 定义统一的 Requestor、RequestConfig、Response 类型。
• 提供 BaseRequestor，让 axios/fetch 等实现复用 HTTP 便捷方法和拦截器能力。
• 提供通用能力包装函数：缓存、重试、并发控制、幂等。
• 提供依赖注入辅助方法：injectRequestor、useRequestor。

request-core 不负责真实 HTTP 请求，也不负责业务接口定义。

实现一个 Requestor

底层实现包通常继承 BaseRequestor，只需要实现 request 方法。

import {
  BaseRequestor,
  RequestConfig,
  Response,
} from "@newaifree-tool/request-core";

class CustomRequestor extends BaseRequestor {
  async request<T>(config: RequestConfig): Promise<Response<T>> {
    const finalConfig = await this.runRequestInterceptors(config);

    // 这里接入真实请求实现，例如 axios、fetch 或公司内部网络库。
    const response: Response<T> = {
      data: {} as T,
      status: 200,
      statusText: "OK",
      headers: {},
      config: finalConfig,
      toPlain() {
        return {
          data: this.data,
          status: this.status,
          statusText: this.statusText,
          headers: this.headers,
        };
      },
    };

    return this.runResponseInterceptors(response);
  }
}

添加拦截器

拦截器应该注册在基础请求器上，例如 AxiosRequestor 或 FetchRequestor。

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

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

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

组合通用请求能力

createXxxRequestor 只负责自己的能力，不提供新的拦截器入口。

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

let requestor = baseRequestor;

requestor = createRetryRequestor(requestor, {
  maxCount: 3,
});

requestor = createCacheRequestor(requestor, {
  duration: 60_000,
});

requestor = createIdempotentRequestor(requestor, {
  mode: "concurrent",
});

推荐顺序：

baseRequestor -> retry -> cache -> concurrency -> idempotent

这样最外层的幂等能力会先拦住重复请求，避免重复请求继续进入缓存、重试和真实网络层。

缓存

import { createCacheRequestor } from "@newaifree-tool/request-core";

const cachedRequestor = createCacheRequestor(requestor, {
  duration: 30_000,
});

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

缓存适合 GET 查询类接口，例如字典、配置、列表查询。

重试

import { createRetryRequestor } from "@newaifree-tool/request-core";

const retryRequestor = createRetryRequestor(requestor, {
  maxCount: 3,
  delay: 500,
});

const response = await retryRequestor.get<User>("/users/1");

重试适合网络抖动、读接口或明确可重试的写接口。支付、下单等接口需要谨慎开启。

幂等

import { createIdempotentRequestor } from "@newaifree-tool/request-core";

const idempotentRequestor = createIdempotentRequestor(requestor, {
  mode: "concurrent",
});

await idempotentRequestor.post<Order>("/orders", {
  skuId: 1,
  count: 2,
});

concurrent 模式只合并同一时间正在进行的相同请求，请求完成后下次会重新发送。

persistent 模式会缓存首次响应，相同请求后续直接返回首次结果。

前端幂等只能减少重复提交，不能替代服务端幂等。关键业务仍应依赖后端幂等 key。

并发控制

import { createConcurrencyRequestor } from "@newaifree-tool/request-core";

const concurrencyRequestor = createConcurrencyRequestor(requestor, {
  maxConcurrent: 5,
});

并发控制适合限制同一请求器的最大同时请求数量，避免瞬时请求过多。