create-pardx-scaffold 0.1.0

package/template/apps/web/lib/api/client.ts

@@ -0,0 +1,649 @@
+import { API_CONFIG } from '../config';
+import type { FetchOptions } from '@repo/utils/fetch';
+import {
+  apiGet,
+  apiPost,
+  apiPut,
+  apiDelete,
+  setTokenManager,
+  setVersionConfig,
+} from '@repo/utils/fetch';
+import { getToken, ensureValidToken } from '../api';
+import { APP_VERSION } from '../version';
+
+const API_BASE_URL = API_CONFIG.baseUrl;
+
+/**
+ * 统一的 API 响应格式
+ */
+export interface ApiResponse<T = unknown> {
+  code: number;
+  msg: string;
+  data: T;
+}
+
+/**
+ * HTTP 状态码常量
+ */
+export enum HttpStatusCode {
+  OK = 200,
+  CREATED = 201,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  CONFLICT = 409,
+  INTERNAL_SERVER_ERROR = 500,
+  BAD_GATEWAY = 502,
+  SERVICE_UNAVAILABLE = 503,
+}
+
+/**
+ * 业务错误码常量
+ */
+export enum BusinessErrorCode {
+  SUCCESS = 200,
+  // 认证相关
+  AUTH_FAILED = 401,
+  TOKEN_EXPIRED = 40101,
+  TOKEN_INVALID = 40102,
+  // 权限相关
+  FORBIDDEN = 403,
+  PERMISSION_DENIED = 40301,
+  // 资源相关
+  NOT_FOUND = 404,
+  RESOURCE_NOT_FOUND = 40401,
+  // 业务逻辑错误
+  BAD_REQUEST = 400,
+  VALIDATION_ERROR = 40001,
+  PARAM_ERROR = 40002,
+  // 服务器错误
+  INTERNAL_ERROR = 500,
+  SERVICE_ERROR = 50001,
+  DATABASE_ERROR = 50002,
+}
+
+/**
+ * 错误类型
+ */
+export enum ErrorType {
+  AUTHENTICATION = 'AUTHENTICATION', // 认证错误
+  AUTHORIZATION = 'AUTHORIZATION', // 授权错误
+  VALIDATION = 'VALIDATION', // 验证错误
+  NOT_FOUND = 'NOT_FOUND', // 资源不存在
+  SERVER_ERROR = 'SERVER_ERROR', // 服务器错误
+  NETWORK_ERROR = 'NETWORK_ERROR', // 网络错误
+  BUSINESS_ERROR = 'BUSINESS_ERROR', // 业务错误
+  UNKNOWN = 'UNKNOWN', // 未知错误
+}
+
+/**
+ * API 错误类
+ * 参考 agent 组件的错误处理模式，支持错误码分类和自动处理
+ */
+export class ApiError extends Error {
+  /** 业务错误码 */
+  code: number;
+  /** 错误消息 */
+  msg: string;
+  /** HTTP 状态码（如果有） */
+  status?: number;
+  /** 错误类型 */
+  type: ErrorType;
+  /** 原始响应数据 */
+  originalResponse?: unknown;
+  /** 请求 URL（如果有） */
+  url?: string;
+
+  constructor(
+    code: number,
+    msg: string,
+    options?: {
+      status?: number;
+      type?: ErrorType;
+      originalResponse?: unknown;
+      url?: string;
+    },
+  ) {
+    super(msg);
+    this.name = 'ApiError';
+    this.code = code;
+    this.msg = msg;
+    this.status = options?.status;
+    this.type = options?.type || this.determineErrorType(code, options?.status);
+    this.originalResponse = options?.originalResponse;
+    this.url = options?.url;
+  }
+
+  /**
+   * 根据错误码和状态码确定错误类型
+   */
+  private determineErrorType(code: number, status?: number): ErrorType {
+    // 优先使用 HTTP 状态码判断
+    if (status) {
+      if (status === HttpStatusCode.UNAUTHORIZED) {
+        return ErrorType.AUTHENTICATION;
+      }
+      if (status === HttpStatusCode.FORBIDDEN) {
+        return ErrorType.AUTHORIZATION;
+      }
+      if (status === HttpStatusCode.NOT_FOUND) {
+        return ErrorType.NOT_FOUND;
+      }
+      if (status >= 500) {
+        return ErrorType.SERVER_ERROR;
+      }
+      if (status >= 400) {
+        return ErrorType.VALIDATION;
+      }
+    }
+
+    // 使用业务错误码判断
+    if (
+      code === BusinessErrorCode.AUTH_FAILED ||
+      code === BusinessErrorCode.TOKEN_EXPIRED ||
+      code === BusinessErrorCode.TOKEN_INVALID
+    ) {
+      return ErrorType.AUTHENTICATION;
+    }
+    if (
+      code === BusinessErrorCode.FORBIDDEN ||
+      code === BusinessErrorCode.PERMISSION_DENIED
+    ) {
+      return ErrorType.AUTHORIZATION;
+    }
+    if (
+      code === BusinessErrorCode.NOT_FOUND ||
+      code === BusinessErrorCode.RESOURCE_NOT_FOUND
+    ) {
+      return ErrorType.NOT_FOUND;
+    }
+    if (
+      code === BusinessErrorCode.VALIDATION_ERROR ||
+      code === BusinessErrorCode.PARAM_ERROR
+    ) {
+      return ErrorType.VALIDATION;
+    }
+    if (
+      code >= 500 ||
+      code === BusinessErrorCode.SERVICE_ERROR ||
+      code === BusinessErrorCode.DATABASE_ERROR
+    ) {
+      return ErrorType.SERVER_ERROR;
+    }
+    if (code >= 400 && code < 500) {
+      return ErrorType.BUSINESS_ERROR;
+    }
+
+    return ErrorType.UNKNOWN;
+  }
+
+  /**
+   * 是否为认证错误（需要刷新 token）
+   */
+  isAuthError(): boolean {
+    return (
+      this.type === ErrorType.AUTHENTICATION ||
+      this.status === HttpStatusCode.UNAUTHORIZED ||
+      this.code === BusinessErrorCode.AUTH_FAILED ||
+      this.code === BusinessErrorCode.TOKEN_EXPIRED ||
+      this.code === BusinessErrorCode.TOKEN_INVALID
+    );
+  }
+
+  /**
+   * 是否为权限错误
+   */
+  isPermissionError(): boolean {
+    return (
+      this.type === ErrorType.AUTHORIZATION ||
+      this.status === HttpStatusCode.FORBIDDEN ||
+      this.code === BusinessErrorCode.FORBIDDEN ||
+      this.code === BusinessErrorCode.PERMISSION_DENIED
+    );
+  }
+
+  /**
+   * 是否为资源不存在错误
+   */
+  isNotFoundError(): boolean {
+    return (
+      this.type === ErrorType.NOT_FOUND ||
+      this.status === HttpStatusCode.NOT_FOUND ||
+      this.code === BusinessErrorCode.NOT_FOUND ||
+      this.code === BusinessErrorCode.RESOURCE_NOT_FOUND
+    );
+  }
+
+  /**
+   * 是否为服务器错误
+   */
+  isServerError(): boolean {
+    return (
+      this.type === ErrorType.SERVER_ERROR ||
+      (this.status !== undefined && this.status >= 500) ||
+      this.code >= 500
+    );
+  }
+
+  /**
+   * 是否为网络错误
+   */
+  isNetworkError(): boolean {
+    return this.type === ErrorType.NETWORK_ERROR;
+  }
+
+  /**
+   * 是否为业务逻辑错误
+   */
+  isBusinessError(): boolean {
+    return (
+      this.type === ErrorType.BUSINESS_ERROR ||
+      this.type === ErrorType.VALIDATION ||
+      (this.code >= 400 &&
+        this.code < 500 &&
+        !this.isAuthError() &&
+        !this.isPermissionError())
+    );
+  }
+
+  /**
+   * 获取友好的错误消息
+   */
+  getFriendlyMessage(): string {
+    // 如果已有友好消息，直接返回
+    if (this.msg && this.msg !== '请求失败') {
+      return this.msg;
+    }
+
+    // 根据错误类型返回默认消息
+    switch (this.type) {
+      case ErrorType.AUTHENTICATION:
+        return '登录已过期，请重新登录';
+      case ErrorType.AUTHORIZATION:
+        return '您没有权限执行此操作';
+      case ErrorType.NOT_FOUND:
+        return '请求的资源不存在';
+      case ErrorType.VALIDATION:
+        return '请求参数错误，请检查后重试';
+      case ErrorType.SERVER_ERROR:
+        return '服务器错误，请稍后重试';
+      case ErrorType.NETWORK_ERROR:
+        return '网络连接失败，请检查网络后重试';
+      case ErrorType.BUSINESS_ERROR:
+        return '操作失败，请稍后重试';
+      default:
+        return '发生未知错误，请稍后重试';
+    }
+  }
+
+  /**
+   * 转换为 JSON 格式（用于日志记录）
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      msg: this.msg,
+      status: this.status,
+      type: this.type,
+      url: this.url,
+      message: this.message,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * 统一的 API 客户端类
+ */
+export class ApiClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string = API_BASE_URL) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * 构建查询字符串
+   */
+  private buildQueryString(params?: Record<string, unknown>): string {
+    if (!params || Object.keys(params).length === 0) {
+      return '';
+    }
+
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      // 跳过 null、undefined 和空字符串
+      if (value !== null && value !== undefined && value !== '') {
+        // 数组和对象需要序列化
+        if (Array.isArray(value)) {
+          value.forEach((item) => {
+            searchParams.append(key, String(item));
+          });
+        } else if (typeof value === 'object') {
+          searchParams.append(key, JSON.stringify(value));
+        } else {
+          searchParams.append(key, String(value));
+        }
+      }
+    }
+
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : '';
+  }
+
+  /**
+   * 构建完整的 URL
+   */
+  private buildUrl(endpoint: string, params?: Record<string, unknown>): string {
+    // 如果已经是完整 URL，直接返回
+    if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+      // 如果已有查询参数，需要合并
+      if (params && Object.keys(params).length > 0) {
+        const url = new URL(endpoint);
+        for (const [key, value] of Object.entries(params)) {
+          if (value !== null && value !== undefined && value !== '') {
+            if (Array.isArray(value)) {
+              value.forEach((item) => {
+                url.searchParams.append(key, String(item));
+              });
+            } else if (typeof value === 'object') {
+              url.searchParams.append(key, JSON.stringify(value));
+            } else {
+              url.searchParams.append(key, String(value));
+            }
+          }
+        }
+        return url.toString();
+      }
+      return endpoint;
+    }
+    // 确保 endpoint 以 / 开头
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    const queryString = this.buildQueryString(params);
+    return `${this.baseUrl}${path}${queryString}`;
+  }
+
+  /**
+   * 处理 API 响应
+   */
+  private handleResponse<T>(
+    response: ApiResponse<T>,
+    options?: {
+      status?: number;
+      url?: string;
+      originalResponse?: unknown;
+    },
+  ): T {
+    if (response.code !== 200) {
+      throw new ApiError(response.code, response.msg || '请求失败', {
+        status: options?.status,
+        url: options?.url,
+        originalResponse: options?.originalResponse || response,
+      });
+    }
+    return response.data;
+  }
+
+  /**
+   * GET 请求
+   * @param endpoint API 端点路径
+   * @param params 查询参数对象（可选）
+   * @param options Fetch 选项（可选）
+   */
+  async get<T = unknown>(
+    endpoint: string,
+    params?: Record<string, unknown> | FetchOptions,
+    options?: FetchOptions,
+  ): Promise<T> {
+    // 判断第二个参数是 params 还是 options
+    let actualParams: Record<string, unknown> | undefined;
+    let actualOptions: FetchOptions | undefined;
+
+    if (params) {
+      // 如果第二个参数有 FetchOptions 的特征字段，则视为 options
+      if (
+        'requireAuth' in params ||
+        'mptrail' in params ||
+        'method' in params ||
+        'headers' in params ||
+        'body' in params
+      ) {
+        actualOptions = params as FetchOptions;
+        actualParams = undefined;
+      } else {
+        actualParams = params as Record<string, unknown>;
+        actualOptions = options;
+      }
+    } else {
+      actualOptions = options;
+    }
+
+    const url = this.buildUrl(endpoint, actualParams);
+    try {
+      const response = await apiGet<ApiResponse<T>>(url, actualOptions);
+      return this.handleResponse(response, { url });
+    } catch (error: unknown) {
+      // 如果是网络错误或其他错误，包装为 ApiError
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      const errorMessage =
+        error instanceof Error ? error.message : '网络请求失败';
+      throw new ApiError(0, errorMessage, {
+        type: ErrorType.NETWORK_ERROR,
+        url,
+      });
+    }
+  }
+
+  /**
+   * POST 请求
+   */
+  async post<T = unknown>(
+    endpoint: string,
+    body?: unknown,
+    options?: FetchOptions,
+  ): Promise<T> {
+    const url = this.buildUrl(endpoint);
+    try {
+      const response = await apiPost<ApiResponse<T>>(url, body, options);
+      return this.handleResponse(response, { url });
+    } catch (error: unknown) {
+      // 如果是网络错误或其他错误，包装为 ApiError
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      const errorMessage =
+        error instanceof Error ? error.message : '网络请求失败';
+      throw new ApiError(0, errorMessage, {
+        type: ErrorType.NETWORK_ERROR,
+        url,
+      });
+    }
+  }
+
+  /**
+   * PUT 请求
+   */
+  async put<T = unknown>(
+    endpoint: string,
+    body?: unknown,
+    options?: FetchOptions,
+  ): Promise<T> {
+    const url = this.buildUrl(endpoint);
+    try {
+      const response = await apiPut<ApiResponse<T>>(url, body, options);
+      return this.handleResponse(response, { url });
+    } catch (error: unknown) {
+      // 如果是网络错误或其他错误，包装为 ApiError
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      const errorMessage =
+        error instanceof Error ? error.message : '网络请求失败';
+      throw new ApiError(0, errorMessage, {
+        type: ErrorType.NETWORK_ERROR,
+        url,
+      });
+    }
+  }
+
+  /**
+   * DELETE 请求
+   * @param endpoint API 端点路径
+   * @param params 查询参数对象（可选）
+   * @param options Fetch 选项（可选）
+   */
+  async delete<T = unknown>(
+    endpoint: string,
+    params?: Record<string, unknown> | FetchOptions,
+    options?: FetchOptions,
+  ): Promise<T> {
+    // 判断第二个参数是 params 还是 options
+    let actualParams: Record<string, unknown> | undefined;
+    let actualOptions: FetchOptions | undefined;
+
+    if (params) {
+      // 如果第二个参数有 FetchOptions 的特征字段，则视为 options
+      if (
+        'requireAuth' in params ||
+        'mptrail' in params ||
+        'method' in params ||
+        'headers' in params ||
+        'body' in params
+      ) {
+        actualOptions = params as FetchOptions;
+        actualParams = undefined;
+      } else {
+        actualParams = params as Record<string, unknown>;
+        actualOptions = options;
+      }
+    } else {
+      actualOptions = options;
+    }
+
+    const url = this.buildUrl(endpoint, actualParams);
+    try {
+      const response = await apiDelete<ApiResponse<T>>(url, actualOptions);
+      return this.handleResponse(response, { url });
+    } catch (error: unknown) {
+      // 如果是网络错误或其他错误，包装为 ApiError
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      const errorMessage =
+        error instanceof Error ? error.message : '网络请求失败';
+      throw new ApiError(0, errorMessage, {
+        type: ErrorType.NETWORK_ERROR,
+        url,
+      });
+    }
+  }
+
+  /**
+   * GET 请求（返回完整响应）
+   * @param endpoint API 端点路径
+   * @param params 查询参数对象（可选）
+   * @param options Fetch 选项（可选）
+   */
+  async getFullResponse<T = unknown>(
+    endpoint: string,
+    params?: Record<string, unknown> | FetchOptions,
+    options?: FetchOptions,
+  ): Promise<ApiResponse<T>> {
+    // 判断第二个参数是 params 还是 options
+    let actualParams: Record<string, unknown> | undefined;
+    let actualOptions: FetchOptions | undefined;
+
+    if (params) {
+      // 如果第二个参数有 FetchOptions 的特征字段，则视为 options
+      if (
+        'requireAuth' in params ||
+        'mptrail' in params ||
+        'method' in params ||
+        'headers' in params ||
+        'body' in params
+      ) {
+        actualOptions = params as FetchOptions;
+        actualParams = undefined;
+      } else {
+        actualParams = params as Record<string, unknown>;
+        actualOptions = options;
+      }
+    } else {
+      actualOptions = options;
+    }
+
+    const url = this.buildUrl(endpoint, actualParams);
+    return await apiGet<ApiResponse<T>>(url, actualOptions);
+  }
+
+  /**
+   * POST 请求（返回完整响应）
+   */
+  async postFullResponse<T = unknown>(
+    endpoint: string,
+    body?: unknown,
+    options?: FetchOptions,
+  ): Promise<ApiResponse<T>> {
+    const url = this.buildUrl(endpoint);
+    return await apiPost<ApiResponse<T>>(url, body, options);
+  }
+
+  /**
+   * DELETE 请求（返回完整响应）
+   * @param endpoint API 端点路径
+   * @param params 查询参数对象（可选）
+   * @param options Fetch 选项（可选）
+   */
+  async deleteFullResponse<T = unknown>(
+    endpoint: string,
+    params?: Record<string, unknown> | FetchOptions,
+    options?: FetchOptions,
+  ): Promise<ApiResponse<T>> {
+    // 判断第二个参数是 params 还是 options
+    let actualParams: Record<string, unknown> | undefined;
+    let actualOptions: FetchOptions | undefined;
+
+    if (params) {
+      // 如果第二个参数有 FetchOptions 的特征字段，则视为 options
+      if (
+        'requireAuth' in params ||
+        'mptrail' in params ||
+        'method' in params ||
+        'headers' in params ||
+        'body' in params
+      ) {
+        actualOptions = params as FetchOptions;
+        actualParams = undefined;
+      } else {
+        actualParams = params as Record<string, unknown>;
+        actualOptions = options;
+      }
+    } else {
+      actualOptions = options;
+    }
+
+    const url = this.buildUrl(endpoint, actualParams);
+    return await apiDelete<ApiResponse<T>>(url, actualOptions);
+  }
+}
+
+// 导出默认的 API 客户端实例
+export const apiClient = new ApiClient();
+
+// 初始化 token manager 和 version config
+if (typeof window !== 'undefined') {
+  setTokenManager({
+    getToken,
+    ensureValidToken,
+  });
+
+  // 设置版本配置，用于端到端版本控制
+  setVersionConfig({
+    apiVersion: APP_VERSION.apiVersion,
+    appBuild: APP_VERSION.appBuild,
+  });
+}