@seaart/request

基于 Axios 的框架无关 JSON HTTP 请求内核。它负责 Axios 实例、请求配置预处理、动态请求头、相同请求取消、业务状态码与响应钩子；不依赖 Vue、Nuxt、Pinia 或 UI 组件。

上传直传、SSE、登录跳转、Token 存储、业务弹窗和埋点不属于本包职责，应由上层协议包或业务项目处理。

安装

axios 是 peer dependency，接入项目需要自行安装：

pnpm add @seaart/request axios

使用

import { createRequestClient } from '@seaart/request';

export const request = createRequestClient({
  baseURL: 'https://api.example.com',
  timeout: 30_000,
  withCredentials: true,
  getHeaders: () => ({ Authorization: getAccessToken() }),
  onBusinessError: (error) => reportBusinessError(error.status),
  onHttpError: (error) => reportHttpError(error),
});

const result = await request<{ items: Array<{ id: string }> }>({
  url: '/api/v1/items',
  method: 'POST',
  data: { page: 1, pageSize: 20 },
});

客户端参数

createRequestClient(options) 返回一个可调用的 RequestClient。除下表配置外，创建后仍可访问 Axios 的 request.defaults 与 request.interceptors。

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | axiosInstance | AxiosInstance | 否 | 新建实例 | 注入已有 Axios 实例；传入后由调用方管理其默认配置。 | | baseURL | string | 否 | - | API 基础地址。请求级 config.baseURL 优先。 | | timeout | number | 否 | Axios 默认值 | 默认超时毫秒数；可被请求级 customConfig.timeout 覆盖。 | | withCredentials | boolean | 否 | Axios 默认值 | 是否携带跨域 Cookie。 | | headers | Record<string, string> | 否 | - | Axios 实例默认请求头。 | | successCodes | number[] | 否 | [10000, 10404, 500401] | 返回存在 status 时的默认业务成功码。 | | prepareConfig | (config) => config \| void | 否 | - | 请求发送前修改 URL、baseURL、凭据等配置；支持异步。 | | getHeaders | (config) => headers | 否 | - | 每次请求动态获取请求头；支持异步。 | | isSuccess | (data, response) => boolean | 否 | - | 完全覆盖默认业务成功码判断。 | | onResponse | (response, data) => void | 否 | - | 收到响应后、业务状态判断前执行；适合读取响应头。 | | onBusinessError | (error, response) => void | 否 | - | 业务状态码失败时执行，随后请求会 reject ApiBusinessError。 | | onHttpError | (error) => void | 否 | - | 网络、超时、取消和非 2xx HTTP 错误时执行。 |

请求参数

调用参数兼容 Axios 的 AxiosRequestConfig，常用字段如下：

| 参数 | 类型 | 说明 | | --- | --- | --- | | url | string | 请求路径或完整 URL。 | | method | string | HTTP 方法。 | | data | unknown | 请求体。 | | params | unknown | URL query 参数。 | | headers | Record<string, string> | 单次请求头。 | | signal | AbortSignal | 调用方取消信号，会与内部取消信号合并。 | | baseURL | string | 覆盖实例级 API 基础地址。 | | customConfig | RequestCustomConfig | 本包附加配置，见下表。 |

customConfig：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | headers | Record<string, string \| number \| boolean> | - | 在动态请求头后合并的业务头。 | | timeout | number | - | 单次请求超时，单位毫秒。 | | dedupe | boolean | true | 同一 method、URL、params、data 的前一个未完成请求会被取消；上传、轮询和并发提交应设为 false。 | | needHeaders | boolean | false | 成功业务响应中附加 Axios 响应头。 |

返回值与错误

后端返回包含 status 时，默认成功码为 10000、10404、500401，成功时原样返回业务响应：

{
  status: { code: 10000, msg: 'ok' },
  data: { /* 业务数据 */ },
}

不存在 status 的第三方/CDN JSON 响应会原样返回，不会进行业务码判定。业务失败会 reject ApiBusinessError，可通过 error.status 获取 code 与 msg；网络或 Axios 错误保持原错误对象。

取消与并发

const config = { url: '/api/v1/items', method: 'POST', data: { page: 1 } };

request(config);
request.cancelPending(config); // 取消该配置对应的请求
request.cancelPending(); // 取消当前实例的全部内部请求

请求去重只作用于同一 RequestClient 实例，不影响其他实例或浏览器 Tab。

扩展示例

const request = createRequestClient({
  prepareConfig: async (config) => {
    if (isServerRequest()) config.baseURL = await resolveServerApiBaseURL();
    return config;
  },
  getHeaders: () => ({
    'X-Request-Id': crypto.randomUUID(),
    'Accept-Language': getLocale(),
  }),
  isSuccess: (data) => data.status?.code === 0,
});

SeaArt Web 的标准请求头、多语言、SSR Cookie/IP 透传和 Token 刷新策略，请使用 @seaart/request-seaart。

测试与构建

pnpm --filter @seaart/request typecheck
pnpm --filter @seaart/request test
pnpm --filter @seaart/request build

License

UNLICENSED