feat: 初始化项目基础结构和配置

packages/effects/request/src/index.ts

@@ -0,0 +1,2 @@
+export * from './request-client';
+export * from 'axios';

packages/effects/request/src/request-client/index.ts

@@ -0,0 +1,3 @@
+export * from './preset-interceptors';
+export * from './request-client';
+export type * from './types';

packages/effects/request/src/request-client/modules/downloader.test.ts

@@ -0,0 +1,157 @@
+import type { AxiosRequestConfig } from 'axios';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { FileDownloader } from './downloader';
+
+describe('fileDownloader', () => {
+  let fileDownloader: FileDownloader;
+  const mockAxiosInstance = {
+    get: vi.fn(),
+  } as any;
+
+  beforeEach(() => {
+    fileDownloader = new FileDownloader(mockAxiosInstance);
+  });
+
+  it('should create an instance of FileDownloader', () => {
+    expect(fileDownloader).toBeInstanceOf(FileDownloader);
+  });
+
+  it('should download a file and return a Blob', async () => {
+    const url = 'https://example.com/file';
+    const mockBlob = new Blob(['file content'], { type: 'text/plain' });
+    const mockResponse: Blob = mockBlob;
+
+    mockAxiosInstance.get.mockResolvedValueOnce(mockResponse);
+
+    const result = await fileDownloader.download(url);
+
+    expect(result).toBeInstanceOf(Blob);
+    expect(result).toEqual(mockBlob);
+    expect(mockAxiosInstance.get).toHaveBeenCalledWith(url, {
+      method: 'GET',
+      responseType: 'blob',
+      responseReturn: 'body',
+    });
+  });
+
+  it('should merge provided config with default config', async () => {
+    const url = 'https://example.com/file';
+    const mockBlob = new Blob(['file content'], { type: 'text/plain' });
+    const mockResponse: Blob = mockBlob;
+
+    mockAxiosInstance.get.mockResolvedValueOnce(mockResponse);
+
+    const customConfig: AxiosRequestConfig = {
+      headers: { 'Custom-Header': 'value' },
+    };
+
+    const result = await fileDownloader.download(url, customConfig);
+    expect(result).toBeInstanceOf(Blob);
+    expect(result).toEqual(mockBlob);
+    expect(mockAxiosInstance.get).toHaveBeenCalledWith(url, {
+      ...customConfig,
+      method: 'GET',
+      responseType: 'blob',
+      responseReturn: 'body',
+    });
+  });
+
+  it('should handle errors gracefully', async () => {
+    const url = 'https://example.com/file';
+    mockAxiosInstance.get.mockRejectedValueOnce(new Error('Network Error'));
+    await expect(fileDownloader.download(url)).rejects.toThrow('Network Error');
+  });
+
+  it('should handle empty URL gracefully', async () => {
+    const url = '';
+    mockAxiosInstance.get.mockRejectedValueOnce(
+      new Error('Request failed with status code 404'),
+    );
+
+    await expect(fileDownloader.download(url)).rejects.toThrow(
+      'Request failed with status code 404',
+    );
+  });
+
+  it('should handle null URL gracefully', async () => {
+    const url = null as unknown as string;
+    mockAxiosInstance.get.mockRejectedValueOnce(
+      new Error('Request failed with status code 404'),
+    );
+
+    await expect(fileDownloader.download(url)).rejects.toThrow(
+      'Request failed with status code 404',
+    );
+  });
+});
+
+describe('fileDownloader use other method', () => {
+  let fileDownloader: FileDownloader;
+
+  it('should call request using get', async () => {
+    const url = 'https://example.com/file';
+    const mockBlob = new Blob(['file content'], { type: 'text/plain' });
+    const mockResponse: Blob = mockBlob;
+
+    const mockAxiosInstance = {
+      request: vi.fn(),
+    } as any;
+
+    fileDownloader = new FileDownloader(mockAxiosInstance);
+
+    mockAxiosInstance.request.mockResolvedValueOnce(mockResponse);
+
+    const result = await fileDownloader.download(url);
+
+    expect(result).toBeInstanceOf(Blob);
+    expect(result).toEqual(mockBlob);
+    expect(mockAxiosInstance.request).toHaveBeenCalledWith(url, {
+      method: 'GET',
+      responseType: 'blob',
+      responseReturn: 'body',
+    });
+  });
+
+  it('should call post', async () => {
+    const url = 'https://example.com/file';
+
+    const mockAxiosInstance = {
+      post: vi.fn(),
+    } as any;
+
+    fileDownloader = new FileDownloader(mockAxiosInstance);
+
+    const customConfig: AxiosRequestConfig = {
+      method: 'POST',
+      data: { name: 'aa' },
+    };
+
+    await fileDownloader.download(url, customConfig);
+
+    expect(mockAxiosInstance.post).toHaveBeenCalledWith(
+      url,
+      { name: 'aa' },
+      {
+        method: 'POST',
+        responseType: 'blob',
+        responseReturn: 'body',
+      },
+    );
+  });
+
+  it('should handle errors gracefully', async () => {
+    const url = 'https://example.com/file';
+    const mockAxiosInstance = {
+      post: vi.fn(),
+    } as any;
+
+    fileDownloader = new FileDownloader(mockAxiosInstance);
+    await expect(() =>
+      fileDownloader.download(url, { method: 'postt' }),
+    ).rejects.toThrow(
+      'RequestClient does not support method "POSTT". Please ensure the method is properly implemented in your RequestClient instance.',
+    );
+  });
+});

packages/effects/request/src/request-client/modules/downloader.ts

@@ -0,0 +1,60 @@
+import type { RequestClient } from '../request-client';
+import type { RequestClientConfig } from '../types';
+
+type DownloadRequestConfig = {
+  /**
+   * 定义期望获得的数据类型。
+   * raw: 原始的AxiosResponse，包括headers、status等。
+   * body: 只返回响应数据的BODY部分(Blob)
+   */
+  responseReturn?: 'body' | 'raw';
+} & Omit<RequestClientConfig, 'responseReturn'>;
+
+class FileDownloader {
+  private client: RequestClient;
+
+  constructor(client: RequestClient) {
+    this.client = client;
+  }
+  /**
+   * 下载文件
+   * @param url 文件的完整链接
+   * @param config 配置信息，可选。
+   * @returns 如果config.responseReturn为'body'，则返回Blob(默认)，否则返回RequestResponse<Blob>
+   */
+  public async download<T = Blob>(
+    url: string,
+    config?: DownloadRequestConfig,
+  ): Promise<T> {
+    const finalConfig: DownloadRequestConfig = {
+      responseReturn: 'body',
+      method: 'GET',
+      ...config,
+      responseType: 'blob',
+    };
+
+    // Prefer a generic request if available; otherwise, dispatch to method-specific calls.
+    const method = (finalConfig.method || 'GET').toUpperCase();
+    const clientAny = this.client as any;
+
+    if (typeof clientAny.request === 'function') {
+      return await clientAny.request(url, finalConfig);
+    }
+    const lower = method.toLowerCase();
+
+    if (typeof clientAny[lower] === 'function') {
+      if (['POST', 'PUT'].includes(method)) {
+        const { data, ...rest } = finalConfig as Record<string, any>;
+        return await clientAny[lower](url, data, rest);
+      }
+
+      return await clientAny[lower](url, finalConfig);
+    }
+
+    throw new Error(
+      `RequestClient does not support method "${method}". Please ensure the method is properly implemented in your RequestClient instance.`,
+    );
+  }
+}
+
+export { FileDownloader };

packages/effects/request/src/request-client/modules/interceptor.ts

@@ -0,0 +1,37 @@
+import type { AxiosInstance, AxiosResponse } from 'axios';
+
+import type { RequestInterceptorConfig, ResponseInterceptorConfig } from '../types';
+
+const defaultRequestInterceptorConfig: RequestInterceptorConfig = {
+  fulfilled: (response) => response,
+  rejected: (error) => Promise.reject(error),
+};
+
+const defaultResponseInterceptorConfig: ResponseInterceptorConfig = {
+  fulfilled: (response: AxiosResponse) => response,
+  rejected: (error) => Promise.reject(error),
+};
+
+class InterceptorManager {
+  private axiosInstance: AxiosInstance;
+
+  constructor(instance: AxiosInstance) {
+    this.axiosInstance = instance;
+  }
+
+  addRequestInterceptor({
+    fulfilled,
+    rejected,
+  }: RequestInterceptorConfig = defaultRequestInterceptorConfig) {
+    this.axiosInstance.interceptors.request.use(fulfilled, rejected);
+  }
+
+  addResponseInterceptor<T = any>({
+    fulfilled,
+    rejected,
+  }: ResponseInterceptorConfig<T> = defaultResponseInterceptorConfig) {
+    this.axiosInstance.interceptors.response.use(fulfilled, rejected);
+  }
+}
+
+export { InterceptorManager };

packages/effects/request/src/request-client/modules/sse.test.ts

@@ -0,0 +1,142 @@
+import type { RequestClient } from '../request-client';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { SSE } from './sse';
+
+// 模拟 TextDecoder
+const OriginalTextDecoder = globalThis.TextDecoder;
+
+beforeEach(() => {
+  vi.stubGlobal(
+    'TextDecoder',
+    class {
+      private decoder = new OriginalTextDecoder();
+      decode(value: Uint8Array, opts?: any) {
+        return this.decoder.decode(value, opts);
+      }
+    },
+  );
+});
+
+// 创建 fetch mock
+const createFetchMock = (chunks: string[], ok = true) => {
+  const encoder = new TextEncoder();
+  let index = 0;
+  return vi.fn().mockResolvedValue({
+    ok,
+    status: ok ? 200 : 500,
+    body: {
+      getReader: () => ({
+        read: async () => {
+          if (index < chunks.length) {
+            return { done: false, value: encoder.encode(chunks[index++]) };
+          }
+          return { done: true, value: undefined };
+        },
+      }),
+    },
+  });
+};
+
+describe('sSE', () => {
+  let client: RequestClient;
+  let sse: SSE;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    client = {
+      getBaseUrl: () => 'http://localhost',
+      instance: {
+        interceptors: {
+          request: {
+            handlers: [],
+          },
+        },
+      },
+    } as unknown as RequestClient;
+    sse = new SSE(client);
+  });
+
+  it('should call requestSSE when postSSE is used', async () => {
+    const spy = vi.spyOn(sse, 'requestSSE').mockResolvedValue(undefined);
+    await sse.postSSE('/test', { foo: 'bar' }, { headers: { a: '1' } });
+    expect(spy).toHaveBeenCalledWith(
+      '/test',
+      { foo: 'bar' },
+      {
+        headers: { a: '1' },
+        method: 'POST',
+      },
+    );
+  });
+
+  it('should throw error if fetch response not ok', async () => {
+    vi.stubGlobal('fetch', createFetchMock([], false));
+    await expect(sse.requestSSE('/bad')).rejects.toThrow(
+      'HTTP error! status: 500',
+    );
+  });
+
+  it('should trigger onMessage and onEnd callbacks', async () => {
+    const messages: string[] = [];
+    const onMessage = vi.fn((msg: string) => messages.push(msg));
+    const onEnd = vi.fn();
+
+    vi.stubGlobal('fetch', createFetchMock(['hello', ' world']));
+
+    await sse.requestSSE('/sse', undefined, { onMessage, onEnd });
+
+    expect(onMessage).toHaveBeenCalledTimes(2);
+    expect(messages.join('')).toBe('hello world');
+    // onEnd 不再带参数
+    expect(onEnd).toHaveBeenCalled();
+  });
+
+  it('should apply request interceptors', async () => {
+    const interceptor = vi.fn(async (config) => {
+      config.headers['x-test'] = 'intercepted';
+      return config;
+    });
+    (client.instance.interceptors.request as any).handlers.push({
+      fulfilled: interceptor,
+    });
+
+    // 创建 fetch mock，并挂到全局
+    const fetchMock = createFetchMock(['data']);
+    vi.stubGlobal('fetch', fetchMock);
+
+    await sse.requestSSE('/sse', undefined, {});
+
+    expect(interceptor).toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost/sse',
+      expect.objectContaining({
+        headers: expect.any(Headers),
+      }),
+    );
+
+    const calls = fetchMock.mock?.calls;
+    expect(calls).toBeDefined();
+    expect(calls?.length).toBeGreaterThan(0);
+
+    const init = calls?.[0]?.[1] as RequestInit;
+    expect(init).toBeDefined();
+
+    const headers = init?.headers as Headers;
+    expect(headers?.get('x-test')).toBe('intercepted');
+    expect(headers?.get('accept')).toBe('text/event-stream');
+  });
+
+  it('should throw error when no reader', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        body: null,
+      }),
+    );
+    await expect(sse.requestSSE('/sse')).rejects.toThrow('No reader');
+  });
+});

packages/effects/request/src/request-client/modules/sse.ts

@@ -0,0 +1,136 @@
+import type { AxiosRequestHeaders, InternalAxiosRequestConfig } from 'axios';
+
+import type { RequestClient } from '../request-client';
+import type { SseRequestOptions } from '../types';
+
+/**
+ * SSE模块
+ */
+class SSE {
+  private client: RequestClient;
+
+  constructor(client: RequestClient) {
+    this.client = client;
+  }
+
+  public async postSSE(
+    url: string,
+    data?: any,
+    requestOptions?: SseRequestOptions,
+  ) {
+    return this.requestSSE(url, data, {
+      ...requestOptions,
+      method: 'POST',
+    });
+  }
+
+  /**
+   * SSE请求方法
+   * @param url - 请求URL
+   * @param data - 请求数据
+   * @param requestOptions - SSE请求选项
+   */
+  public async requestSSE(
+    url: string,
+    data?: any,
+    requestOptions?: SseRequestOptions,
+  ) {
+    const baseUrl = this.client.getBaseUrl() || '';
+
+    let axiosConfig: InternalAxiosRequestConfig<any> = {
+      url,
+      method: (requestOptions?.method as any) ?? 'GET',
+      headers: {} as AxiosRequestHeaders,
+    };
+    const requestInterceptors = this.client.instance.interceptors
+      .request as any;
+    if (
+      requestInterceptors.handlers &&
+      requestInterceptors.handlers.length > 0
+    ) {
+      for (const handler of requestInterceptors.handlers) {
+        if (typeof handler?.fulfilled === 'function') {
+          const next = await handler.fulfilled(axiosConfig as any);
+          if (next) axiosConfig = next as InternalAxiosRequestConfig<any>;
+        }
+      }
+    }
+
+    const merged = new Headers();
+    Object.entries(
+      (axiosConfig.headers ?? {}) as Record<string, string>,
+    ).forEach(([k, v]) => merged.set(k, String(v)));
+    if (requestOptions?.headers) {
+      new Headers(requestOptions.headers).forEach((v, k) => merged.set(k, v));
+    }
+    if (!merged.has('accept')) {
+      merged.set('accept', 'text/event-stream');
+    }
+
+    let bodyInit = requestOptions?.body ?? data;
+    const ct = (merged.get('content-type') || '').toLowerCase();
+    if (
+      bodyInit &&
+      typeof bodyInit === 'object' &&
+      !ArrayBuffer.isView(bodyInit as any) &&
+      !(bodyInit instanceof ArrayBuffer) &&
+      !(bodyInit instanceof Blob) &&
+      !(bodyInit instanceof FormData) &&
+      ct.includes('application/json')
+    ) {
+      bodyInit = JSON.stringify(bodyInit);
+    }
+    const requestInit: RequestInit = {
+      ...requestOptions,
+      method: axiosConfig.method,
+      headers: merged,
+      body: bodyInit,
+    };
+
+    const response = await fetch(safeJoinUrl(baseUrl, url), requestInit);
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const reader = response.body?.getReader();
+    const decoder = new TextDecoder();
+
+    if (!reader) {
+      throw new Error('No reader');
+    }
+    let isEnd = false;
+    while (!isEnd) {
+      const { done, value } = await reader.read();
+      if (done) {
+        isEnd = true;
+        decoder.decode(new Uint8Array(0), { stream: false });
+        requestOptions?.onEnd?.();
+        reader.releaseLock?.();
+        break;
+      }
+      const content = decoder.decode(value, { stream: true });
+      requestOptions?.onMessage?.(content);
+    }
+  }
+}
+
+function safeJoinUrl(baseUrl: string | undefined, url: string): string {
+  if (!baseUrl) {
+    return url; // 没有 baseUrl，直接返回 url
+  }
+
+  // 如果 url 本身就是绝对地址，直接返回
+  if (/^https?:\/\//i.test(url)) {
+    return url;
+  }
+
+  // 如果 baseUrl 是完整 URL，就用 new URL
+  if (/^https?:\/\//i.test(baseUrl)) {
+    return new URL(url, baseUrl).toString();
+  }
+
+  // 否则，当作路径拼接
+  return `${baseUrl.replace(/\/+$/, '')}/${url.replace(/^\/+/, '')}`;
+}
+
+export { SSE };

packages/effects/request/src/request-client/modules/uploader.test.ts

@@ -0,0 +1,118 @@
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { FileUploader } from './uploader';
+
+describe('fileUploader', () => {
+  let fileUploader: FileUploader;
+  // Mock the AxiosInstance
+  const mockAxiosInstance = {
+    post: vi.fn(),
+  } as any;
+
+  beforeEach(() => {
+    fileUploader = new FileUploader(mockAxiosInstance);
+  });
+
+  it('should create an instance of FileUploader', () => {
+    expect(fileUploader).toBeInstanceOf(FileUploader);
+  });
+
+  it('should upload a file and return the response', async () => {
+    const url = 'https://example.com/upload';
+    const file = new File(['file content'], 'test.txt', { type: 'text/plain' });
+    const mockResponse: AxiosResponse = {
+      config: {} as any,
+      data: { success: true },
+      headers: {},
+      status: 200,
+      statusText: 'OK',
+    };
+
+    (
+      mockAxiosInstance.post as unknown as ReturnType<typeof vi.fn>
+    ).mockResolvedValueOnce(mockResponse);
+
+    const result = await fileUploader.upload(url, { file });
+    expect(result).toEqual(mockResponse);
+    expect(mockAxiosInstance.post).toHaveBeenCalledWith(
+      url,
+      expect.any(FormData),
+      {
+        headers: {
+          'Content-Type': 'multipart/form-data',
+        },
+      },
+    );
+  });
+
+  it('should merge provided config with default config', async () => {
+    const url = 'https://example.com/upload';
+    const file = new File(['file content'], 'test.txt', { type: 'text/plain' });
+    const mockResponse: AxiosResponse = {
+      config: {} as any,
+      data: { success: true },
+      headers: {},
+      status: 200,
+      statusText: 'OK',
+    };
+
+    (
+      mockAxiosInstance.post as unknown as ReturnType<typeof vi.fn>
+    ).mockResolvedValueOnce(mockResponse);
+
+    const customConfig: AxiosRequestConfig = {
+      headers: { 'Custom-Header': 'value' },
+    };
+
+    const result = await fileUploader.upload(url, { file }, customConfig);
+    expect(result).toEqual(mockResponse);
+    expect(mockAxiosInstance.post).toHaveBeenCalledWith(
+      url,
+      expect.any(FormData),
+      {
+        headers: {
+          'Content-Type': 'multipart/form-data',
+          'Custom-Header': 'value',
+        },
+      },
+    );
+  });
+
+  it('should handle errors gracefully', async () => {
+    const url = 'https://example.com/upload';
+    const file = new File(['file content'], 'test.txt', { type: 'text/plain' });
+    (
+      mockAxiosInstance.post as unknown as ReturnType<typeof vi.fn>
+    ).mockRejectedValueOnce(new Error('Network Error'));
+
+    await expect(fileUploader.upload(url, { file })).rejects.toThrow(
+      'Network Error',
+    );
+  });
+
+  it('should handle empty URL gracefully', async () => {
+    const url = '';
+    const file = new File(['file content'], 'test.txt', { type: 'text/plain' });
+    (
+      mockAxiosInstance.post as unknown as ReturnType<typeof vi.fn>
+    ).mockRejectedValueOnce(new Error('Request failed with status code 404'));
+
+    await expect(fileUploader.upload(url, { file })).rejects.toThrow(
+      'Request failed with status code 404',
+    );
+  });
+
+  it('should handle null URL gracefully', async () => {
+    const url = null as unknown as string;
+    const file = new File(['file content'], 'test.txt', { type: 'text/plain' });
+    (
+      mockAxiosInstance.post as unknown as ReturnType<typeof vi.fn>
+    ).mockRejectedValueOnce(new Error('Request failed with status code 404'));
+
+    await expect(fileUploader.upload(url, { file })).rejects.toThrow(
+      'Request failed with status code 404',
+    );
+  });
+});

packages/effects/request/src/request-client/modules/uploader.ts

@@ -0,0 +1,42 @@
+import type { RequestClient } from '../request-client';
+import type { RequestClientConfig } from '../types';
+
+import { isUndefined } from '@vben/utils';
+
+class FileUploader {
+  private client: RequestClient;
+
+  constructor(client: RequestClient) {
+    this.client = client;
+  }
+
+  public async upload<T = any>(
+    url: string,
+    data: Record<string, any> & { file: Blob | File },
+    config?: RequestClientConfig,
+  ): Promise<T> {
+    const formData = new FormData();
+
+    Object.entries(data).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+          !isUndefined(item) && formData.append(`${key}[${index}]`, item);
+        });
+      } else {
+        !isUndefined(value) && formData.append(key, value);
+      }
+    });
+
+    const finalConfig: RequestClientConfig = {
+      ...config,
+      headers: {
+        'Content-Type': 'multipart/form-data',
+        ...config?.headers,
+      },
+    };
+
+    return this.client.post(url, formData, finalConfig);
+  }
+}
+
+export { FileUploader };

packages/effects/request/src/request-client/preset-interceptors.ts

@@ -0,0 +1,170 @@
+import type { RequestClient } from './request-client';
+import type { MakeErrorMessageFn, ResponseInterceptorConfig } from './types';
+
+import { $t } from '@vben/locales';
+import { isFunction } from '@vben/utils';
+
+import axios from 'axios';
+
+export const defaultResponseInterceptor = ({
+  codeField = 'code',
+  dataField = 'data',
+  successCode = 0,
+}: {
+  /** 响应数据中代表访问结果的字段名 */
+  codeField: string;
+  /** 响应数据中装载实际数据的字段名，或者提供一个函数从响应数据中解析需要返回的数据 */
+  dataField: ((response: any) => any) | string;
+  /** 当codeField所指定的字段值与successCode相同时，代表接口访问成功。如果提供一个函数，则返回true代表接口访问成功 */
+  successCode: ((code: any) => boolean) | number | string;
+}): ResponseInterceptorConfig => {
+  return {
+    fulfilled: (response) => {
+      const { config, data: responseData, status } = response;
+
+      if (config.responseReturn === 'raw') {
+        return response;
+      }
+
+      if (status >= 200 && status < 400) {
+        if (config.responseReturn === 'body') {
+          return responseData;
+        } else if (
+          isFunction(successCode)
+            ? successCode(responseData[codeField])
+            : responseData[codeField] === successCode
+        ) {
+          return isFunction(dataField) ? dataField(responseData) : responseData[dataField];
+        }
+      }
+      throw Object.assign({}, response, { response });
+    },
+  };
+};
+
+export const authenticateResponseInterceptor = ({
+  client,
+  doReAuthenticate,
+  doRefreshToken,
+  enableRefreshToken,
+  formatToken,
+}: {
+  client: RequestClient;
+  doReAuthenticate: () => Promise<void>;
+  doRefreshToken: () => Promise<string>;
+  enableRefreshToken: boolean;
+  formatToken: (token: string) => null | string;
+}): ResponseInterceptorConfig => {
+  return {
+    rejected: async (error) => {
+      const { config, response } = error;
+      // 如果不是 401 错误，直接抛出异常
+      if (response?.status !== 401) {
+        throw error;
+      }
+      // 判断是否启用了 refreshToken 功能
+      // 如果没有启用或者已经是重试请求了，直接跳转到重新登录
+      if (!enableRefreshToken || config.__isRetryRequest) {
+        await doReAuthenticate();
+        throw error;
+      }
+      // 如果正在刷新 token，则将请求加入队列，等待刷新完成
+      if (client.isRefreshing) {
+        return new Promise((resolve) => {
+          client.refreshTokenQueue.push((newToken: string) => {
+            config.headers.Authorization = formatToken(newToken);
+            resolve(client.request(config.url, { ...config }));
+          });
+        });
+      }
+
+      // 标记开始刷新 token
+      client.isRefreshing = true;
+      // 标记当前请求为重试请求，避免无限循环
+      config.__isRetryRequest = true;
+
+      try {
+        const newToken = await doRefreshToken();
+
+        // 处理队列中的请求
+        client.refreshTokenQueue.forEach((callback) => callback(newToken));
+        // 清空队列
+        client.refreshTokenQueue = [];
+
+        return client.request(error.config.url, { ...error.config });
+      } catch (refreshError) {
+        // 如果刷新 token 失败，处理错误（如强制登出或跳转登录页面）
+        client.refreshTokenQueue.forEach((callback) => callback(''));
+        client.refreshTokenQueue = [];
+        console.error('Refresh token failed, please login again.');
+        await doReAuthenticate();
+
+        throw refreshError;
+      } finally {
+        client.isRefreshing = false;
+      }
+    },
+  };
+};
+
+export const errorMessageResponseInterceptor = (
+  makeErrorMessage?: MakeErrorMessageFn,
+): ResponseInterceptorConfig => {
+  return {
+    rejected: (error: any) => {
+      if (axios.isCancel(error)) {
+        return Promise.reject(error);
+      }
+
+      const err: string = error?.toString?.() ?? '';
+      let errMsg = '';
+      if (err?.includes('Network Error')) {
+        errMsg = $t('ui.fallback.http.networkError');
+      } else if (error?.message?.includes?.('timeout')) {
+        errMsg = $t('ui.fallback.http.requestTimeout');
+      }
+      if (errMsg) {
+        makeErrorMessage?.(errMsg, error);
+        return Promise.reject(error);
+      }
+
+      let errorMessage = '';
+      const status = error?.response?.status;
+
+      switch (status) {
+        case 400: {
+          errorMessage = $t('ui.fallback.http.badRequest');
+          break;
+        }
+        case 401: {
+          errorMessage = $t('ui.fallback.http.unauthorized');
+          break;
+        }
+        case 403: {
+          errorMessage = $t('ui.fallback.http.forbidden');
+          break;
+        }
+        case 404: {
+          errorMessage = $t('ui.fallback.http.notFound');
+          break;
+        }
+        case 408: {
+          errorMessage = $t('ui.fallback.http.requestTimeout');
+          break;
+        }
+        default: {
+          // 对于未明确定义的状态码，先尝试从响应中获取错误信息
+          const responseData = error?.response?.data ?? {};
+          const backendMessage =
+            responseData?.msg || responseData?.message || responseData?.error || '';
+
+          errorMessage = backendMessage
+            ? `${$t('ui.fallback.http.internalServerError')}：状态码：${status}，信息：${backendMessage}`
+            : $t('ui.fallback.http.internalServerError');
+        }
+      }
+      makeErrorMessage?.(errorMessage, error);
+      return Promise.reject(error);
+    },
+  };
+};

packages/effects/request/src/request-client/request-client.test.ts

@@ -0,0 +1,99 @@
+import axios from 'axios';
+import MockAdapter from 'axios-mock-adapter';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { RequestClient } from './request-client';
+
+describe('requestClient', () => {
+  let mock: MockAdapter;
+  let requestClient: RequestClient;
+
+  beforeEach(() => {
+    mock = new MockAdapter(axios);
+    requestClient = new RequestClient();
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  it('should successfully make a GET request', async () => {
+    mock.onGet('test/url').reply(200, { data: 'response' });
+
+    const response = await requestClient.get('test/url');
+
+    expect(response.data).toEqual({ data: 'response' });
+  });
+
+  it('should successfully make a POST request', async () => {
+    const postData = { key: 'value' };
+    const mockData = { data: 'response' };
+    mock.onPost('/test/post', postData).reply(200, mockData);
+    const response = await requestClient.post('/test/post', postData);
+    expect(response.data).toEqual(mockData);
+  });
+
+  it('should successfully make a PUT request', async () => {
+    const putData = { key: 'updatedValue' };
+    const mockData = { data: 'updated response' };
+    mock.onPut('/test/put', putData).reply(200, mockData);
+    const response = await requestClient.put('/test/put', putData);
+    expect(response.data).toEqual(mockData);
+  });
+
+  it('should successfully make a DELETE request', async () => {
+    const mockData = { data: 'delete response' };
+    mock.onDelete('/test/delete').reply(200, mockData);
+    const response = await requestClient.delete('/test/delete');
+    expect(response.data).toEqual(mockData);
+  });
+
+  it('should handle network errors', async () => {
+    mock.onGet('/test/error').networkError();
+    try {
+      await requestClient.get('/test/error');
+      expect(true).toBe(false);
+    } catch (error: any) {
+      expect(error.isAxiosError).toBe(true);
+      expect(error.message).toBe('Network Error');
+    }
+  });
+
+  it('should handle timeout', async () => {
+    mock.onGet('/test/timeout').timeout();
+    try {
+      await requestClient.get('/test/timeout');
+      expect(true).toBe(false);
+    } catch (error: any) {
+      expect(error.isAxiosError).toBe(true);
+      expect(error.code).toBe('ECONNABORTED');
+    }
+  });
+
+  it('should successfully upload a file', async () => {
+    const fileData = new Blob(['file contents'], { type: 'text/plain' });
+
+    mock.onPost('/test/upload').reply((config) => {
+      return config.data instanceof FormData && config.data.has('file')
+        ? [200, { data: 'file uploaded' }]
+        : [400, { error: 'Bad Request' }];
+    });
+
+    const response = await requestClient.upload('/test/upload', {
+      file: fileData,
+    });
+    expect(response.data).toEqual({ data: 'file uploaded' });
+  });
+
+  it('should successfully download a file as a blob', async () => {
+    const mockFileContent = new Blob(['mock file content'], {
+      type: 'text/plain',
+    });
+
+    mock.onGet('/test/download').reply(200, mockFileContent);
+
+    const res = await requestClient.download('/test/download');
+
+    expect(res.data).toBeInstanceOf(Blob);
+  });
+});

packages/effects/request/src/request-client/request-client.ts

@@ -0,0 +1,143 @@
+import type { AxiosInstance, AxiosResponse } from 'axios';
+
+import type { RequestClientConfig, RequestClientOptions } from './types';
+
+import { bindMethods, isString, merge } from '@vben/utils';
+
+import axios from 'axios';
+import qs from 'qs';
+
+import { FileDownloader } from './modules/downloader';
+import { InterceptorManager } from './modules/interceptor';
+import { SSE } from './modules/sse';
+import { FileUploader } from './modules/uploader';
+
+function getParamsSerializer(paramsSerializer: RequestClientOptions['paramsSerializer']) {
+  if (isString(paramsSerializer)) {
+    switch (paramsSerializer) {
+      case 'brackets': {
+        return (params: any) => qs.stringify(params, { arrayFormat: 'brackets' });
+      }
+      case 'comma': {
+        return (params: any) => qs.stringify(params, { arrayFormat: 'comma' });
+      }
+      case 'indices': {
+        return (params: any) => qs.stringify(params, { arrayFormat: 'indices' });
+      }
+      case 'repeat': {
+        return (params: any) => qs.stringify(params, { arrayFormat: 'repeat' });
+      }
+    }
+  }
+  return paramsSerializer;
+}
+
+class RequestClient {
+  public addRequestInterceptor: InterceptorManager['addRequestInterceptor'];
+
+  public addResponseInterceptor: InterceptorManager['addResponseInterceptor'];
+  public download: FileDownloader['download'];
+
+  public readonly instance: AxiosInstance;
+  // 是否正在刷新token
+  public isRefreshing = false;
+  public postSSE: SSE['postSSE'];
+  // 刷新token队列
+  public refreshTokenQueue: ((token: string) => void)[] = [];
+  public requestSSE: SSE['requestSSE'];
+  public upload: FileUploader['upload'];
+
+  /**
+   * 构造函数，用于创建Axios实例
+   * @param options - Axios请求配置，可选
+   */
+  constructor(options: RequestClientOptions = {}) {
+    // 合并默认配置和传入的配置
+    const defaultConfig: RequestClientOptions = {
+      headers: {
+        'Content-Type': 'application/json;charset=utf-8',
+      },
+      responseReturn: 'raw',
+      // 默认超时时间
+      timeout: 10_000,
+    };
+    const { ...axiosConfig } = options;
+    const requestConfig = merge(axiosConfig, defaultConfig);
+    requestConfig.paramsSerializer = getParamsSerializer(requestConfig.paramsSerializer);
+    this.instance = axios.create(requestConfig);
+
+    bindMethods(this);
+
+    // 实例化拦截器管理器
+    const interceptorManager = new InterceptorManager(this.instance);
+    this.addRequestInterceptor = interceptorManager.addRequestInterceptor.bind(interceptorManager);
+    this.addResponseInterceptor =
+      interceptorManager.addResponseInterceptor.bind(interceptorManager);
+
+    // 实例化文件上传器
+    const fileUploader = new FileUploader(this);
+    this.upload = fileUploader.upload.bind(fileUploader);
+    // 实例化文件下载器
+    const fileDownloader = new FileDownloader(this);
+    this.download = fileDownloader.download.bind(fileDownloader);
+    // 实例化SSE模块
+    const sse = new SSE(this);
+    this.postSSE = sse.postSSE.bind(sse);
+    this.requestSSE = sse.requestSSE.bind(sse);
+  }
+
+  /**
+   * DELETE请求方法
+   */
+  public delete<T = any>(url: string, config?: RequestClientConfig): Promise<T> {
+    return this.request<T>(url, { ...config, method: 'DELETE' });
+  }
+
+  /**
+   * GET请求方法
+   */
+  public get<T = any>(url: string, config?: RequestClientConfig): Promise<T> {
+    return this.request<T>(url, { ...config, method: 'GET' });
+  }
+
+  /**
+   * 获取基础URL
+   */
+  public getBaseUrl() {
+    return this.instance.defaults.baseURL;
+  }
+
+  /**
+   * POST请求方法
+   */
+  public post<T = any>(url: string, data?: any, config?: RequestClientConfig): Promise<T> {
+    return this.request<T>(url, { ...config, data, method: 'POST' });
+  }
+
+  /**
+   * PUT请求方法
+   */
+  public put<T = any>(url: string, data?: any, config?: RequestClientConfig): Promise<T> {
+    return this.request<T>(url, { ...config, data, method: 'PUT' });
+  }
+
+  /**
+   * 通用的请求方法
+   */
+  public async request<T>(url: string, config: RequestClientConfig): Promise<T> {
+    try {
+      const response: AxiosResponse<T> = await this.instance({
+        url,
+        ...config,
+        ...(config.paramsSerializer
+          ? { paramsSerializer: getParamsSerializer(config.paramsSerializer) }
+          : {}),
+      });
+      return response as T;
+    } catch (error: any) {
+      throw error.response ? error.response.data : error;
+    }
+  }
+}
+
+export { RequestClient };

packages/effects/request/src/request-client/types.ts

@@ -0,0 +1,88 @@
+import type {
+  AxiosRequestConfig,
+  AxiosResponse,
+  CreateAxiosDefaults,
+  InternalAxiosRequestConfig,
+} from 'axios';
+
+type ExtendOptions<T = any> = {
+  /**
+   * 参数序列化方式。预置的有
+   * - brackets: ids[]=1&ids[]=2&ids[]=3
+   * - comma: ids=1,2,3
+   * - indices: ids[0]=1&ids[1]=2&ids[2]=3
+   * - repeat: ids=1&ids=2&ids=3
+   */
+  paramsSerializer?:
+    | 'brackets'
+    | 'comma'
+    | 'indices'
+    | 'repeat'
+    | AxiosRequestConfig<T>['paramsSerializer'];
+  /**
+   * 响应数据的返回方式。
+   * - raw: 原始的AxiosResponse，包括headers、status等，不做是否成功请求的检查。
+   * - body: 返回响应数据的BODY部分（只会根据status检查请求是否成功，忽略对code的判断，这种情况下应由调用方检查请求是否成功）。
+   * - data: 解构响应的BODY数据，只返回其中的data节点数据（会检查status和code是否为成功状态）。
+   */
+  responseReturn?: 'body' | 'data' | 'raw';
+};
+type RequestClientConfig<T = any> = AxiosRequestConfig<T> & ExtendOptions<T>;
+
+type RequestResponse<T = any> = AxiosResponse<T> & {
+  config: RequestClientConfig<T>;
+};
+
+type RequestContentType =
+  | 'application/json;charset=utf-8'
+  | 'application/octet-stream;charset=utf-8'
+  | 'application/x-www-form-urlencoded;charset=utf-8'
+  | 'multipart/form-data;charset=utf-8';
+
+type RequestClientOptions = CreateAxiosDefaults & ExtendOptions;
+
+/**
+ * SSE 请求选项
+ */
+interface SseRequestOptions extends RequestInit {
+  onMessage?: (message: string) => void;
+  onEnd?: () => void;
+}
+
+interface RequestInterceptorConfig {
+  fulfilled?: (
+    config: ExtendOptions & InternalAxiosRequestConfig,
+  ) =>
+    | (ExtendOptions & InternalAxiosRequestConfig<any>)
+    | Promise<ExtendOptions & InternalAxiosRequestConfig<any>>;
+  rejected?: (error: any) => any;
+}
+
+interface ResponseInterceptorConfig<T = any> {
+  fulfilled?: (response: RequestResponse<T>) => Promise<RequestResponse> | RequestResponse;
+  rejected?: (error: any) => any;
+}
+
+type MakeErrorMessageFn = (message: string, error: any) => void;
+
+interface HttpResponse<T = any> {
+  /**
+   * 0 表示成功 其他表示失败
+   * 0 means success, others means fail
+   */
+  code: number;
+  data: T;
+  message: string;
+}
+
+export type {
+  HttpResponse,
+  MakeErrorMessageFn,
+  RequestClientConfig,
+  RequestClientOptions,
+  RequestContentType,
+  RequestInterceptorConfig,
+  RequestResponse,
+  ResponseInterceptorConfig,
+  SseRequestOptions,
+};