ch3chi-commons-vue 1.8.0 → 1.8.1

package/src/api/ApiService.ts

@@ -0,0 +1,869 @@
+import axios, {AxiosInstance, AxiosProgressEvent, AxiosRequestConfig, AxiosResponse, RawAxiosResponseHeaders, InternalAxiosRequestConfig} from "axios";
+import {extension} from 'mime-types';
+import {formatDatesInObject} from "../utils/CToolUtils";
+import {AccessToken} from "../model/TokenUser";
+import log from 'loglevel';
+import _ from "lodash";
+
+/**
+ * 定義常見的錯誤訊息對應
+ */
+const commonErrorMessageMap : Record<number, string> = {
+  400: '請求格式錯誤',
+  401: '未授權訪問',
+  403: '操作權限不足',
+  404: '資源未找到',
+  500: '服務器內部錯誤',
+  503: '服務不可用',
+};
+
+/**
+ * ApiEndpoint 定義 API 端點的結構
+ */
+export interface ApiEndpoint {
+  path: string; // API 路徑
+  method: string; // HTTP 方法
+  isAuthenticated?: boolean; // 是否需要身份驗證，預設為 true
+  security?: string[]; // 安全定義，例如 'bearerAuth'
+  withCredentials?: boolean; // 是否攜帶憑證，同時會設定 axios 的 withCredentials
+  isRefreshTokenEndpoint?: boolean; // 是否為刷新權杖的端點
+  errorMessageMap?: Record<number, string>; // 錯誤訊息對應
+  noSpinner?: boolean; // 是否不顯示載入動畫
+  headers?: Record<string, string>; // 預設標頭
+  metaData?: Record<string, any>; // 額外的元資料
+}
+
+/**
+ * CreateEndpointOptions 定義建立 ApiEndpoint 時的選項
+ * 通常用於設定預設值
+ */
+export interface CreateEndpointOptions {
+  isAuthenticated?: boolean;
+  security?: string[];
+  headers?: Record<string, string>;
+}
+
+/**
+ * 建立 ApiEndpoint，並合併預設值
+ * @param data
+ * @param options
+ */
+const createEndpoint = (data: ApiEndpoint, options?: Partial<CreateEndpointOptions>) : ApiEndpoint => {
+  return {
+    path: data.path,
+    method: data.method,
+    isAuthenticated: _.defaultTo(data.isAuthenticated, options?.isAuthenticated),
+    security: _.defaultTo(data.security, options?.security),
+    withCredentials: _.defaultTo(data.withCredentials, false),
+    isRefreshTokenEndpoint: data.isRefreshTokenEndpoint || false,
+    errorMessageMap: Object.assign({}, commonErrorMessageMap, data.errorMessageMap),
+    noSpinner: data.noSpinner || false,
+    headers: data.headers || options?.headers || {},
+    metaData: data.metaData || {},
+  }
+}
+
+/**
+ * ApiRequest 定義 API 請求的結構
+ */
+export class ApiRequest {
+  endpointKey: string = ''; // API endpoint key
+  headers?: Record<string, string>; // 自訂標頭
+  pathParam?: Record<string, any>; // 路徑參數
+  queryParam?: Record<string, any>; // 查詢參數
+  postBody?: Record<string, any> | FormData; // 請求體
+  isDownloadMode?: boolean; // 是否為下載檔案
+  downloadFileName?: string; // 下載檔案名稱
+  // 上傳進度回調函式
+  onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
+  axiosConfig?: AxiosRequestConfig; // 額外的 Axios 配置
+  noSpinner?: boolean; // 是否不顯示載入動畫
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor(data: ApiRequest) {
+    Object.assign(this, data);
+  }
+}
+
+/**
+ * ApiResponse 定義 API 回應的結構
+ */
+export class ApiResponse {
+  httpStatus: number = 0; // HTTP 狀態碼
+  status?: number;
+  message?: string; // 錯誤訊息
+  data?: any; // 返回的數據
+  nativeError?: any; // 原生錯誤對象
+  paging?: Record<string, any>; // 分頁資訊
+  blobData?: Blob; // 下載的檔案資料
+  headers?: RawAxiosResponseHeaders; // 回應標頭
+  details?: any; // 其他詳細資訊
+  axiosResponse?: AxiosResponse; // 原生 Axios 回應對象
+
+  constructor(data?: Partial<ApiResponse>) {
+    if(data) {
+      Object.assign(this, data);
+    }
+  }
+
+  isOk(): boolean {
+    // 判斷 httpStatus 是否在 200-299 範圍內，且 code 是否為 0
+    return this.httpStatus >= 200 && this.httpStatus < 300;
+  }
+}
+
+/**
+ * ApiRejectError 定義 API 呼叫失敗時的自訂錯誤
+ * 此物件給 ApiService.call 呼叫後，並且回傳 Promise.reject() 使用
+ */
+export class ApiRejectError extends Error {
+  response: ApiResponse;
+  type?: string; // 錯誤類型，例如 'notFound'
+
+  constructor(response: ApiResponse) {
+    // 將錯誤訊息傳遞給父類別 Error
+    super(response?.message || 'API Error');
+    // 設定錯誤名稱
+    this.name = 'ApiError';
+    // 保存完整的 ApiResponse 物件
+    this.response = response;
+  }
+
+  notFound(): this {
+    this.type = 'notFound';
+    return this;
+  }
+}
+
+/**
+ * ConfigMetaData 定義 Axios 請求的額外元資料
+ */
+type ConfigMetaData = {
+  endpoint?: ApiEndpoint;
+  request?: ApiRequest;
+}
+
+/**
+ * ApiService 提供呼叫後端 API 的功能
+ */
+export class ApiService {
+
+  // 靜態屬性，保存配置選項
+  private static _options: {
+    debugMode?: boolean; // 是否啟用除錯模式
+    baseUrl: string;
+    contextPath: string;
+    proxyEnable?: boolean;
+    proxyBaseUrl?: string;
+    showSpinnerFunc?: () => void;
+    hideSpinnerFunc?: () => void;
+    showErrorToastFunc?: (param: {title?:string,content?:string}) => void;
+    createEndpointOptions?: CreateEndpointOptions;
+    refreshTokenFunc?: () => Promise<AccessToken>;
+    onAuthenticateFailed?: (param: {apiEndpoint: ApiEndpoint, apiRequest: ApiRequest}) => void; // 認證失敗時的回調函式
+  } = {
+    baseUrl: '',
+    contextPath: ''
+  };
+
+  // 靜態屬性，保存已註冊的 API 端點
+  private static _apiEndpoints: Record<string, ApiEndpoint> = {};
+  // 靜態屬性，自訂標頭
+
+  private static _customHeaders: Record<string, string> = {};
+  private static _customHeaderProvider?: (endpoint: ApiEndpoint, header: Record<string, any>) => Promise<Record<string, string>>;
+  // 靜態屬性，自訂錯誤訊息對應
+  private static _customErrorMessageMap: Record<number, string> = {};
+
+  // 靜態屬性，存取權杖
+  private static _accessToken?: AccessToken;
+  private static _accessTokenProvider?: () => Promise<AccessToken | undefined>;
+  // 靜態屬性，刷新權杖的 Promise
+  private static _refreshTokenPromise?: Promise<AccessToken>;
+  // 靜態屬性，axios 實例
+  private static _axiosInstance?: AxiosInstance;
+  // 靜態屬性，暫存失敗的請求佇列
+  private static _failedRequestQueue: Array<{
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+    config: AxiosRequestConfig;
+  }> = [];
+  // 靜態屬性，是否正在刷新 token
+  private static _isRefreshing = false;
+
+  static set accessToken(token: AccessToken) {
+    ApiService._accessToken = token;
+  }
+
+  static set accessTokenProvider(provider: () => Promise<AccessToken | undefined>) {
+    ApiService._accessTokenProvider = provider;
+  }
+
+  static async getAccessToken(): Promise<AccessToken | undefined> {
+    if(ApiService._accessTokenProvider) {
+      const token = await ApiService._accessTokenProvider();
+      if(!token) {
+        return undefined;
+      }
+      if(token instanceof AccessToken) {
+        ApiService._accessToken = token;
+      } else {
+        ApiService._accessToken = new AccessToken(token);
+      }
+      return ApiService._accessToken;
+    }
+    return undefined;
+  }
+
+  /**
+   * 靜態方法，新增全域自訂標頭
+   * @param key
+   * @param value
+   */
+  static addHeader(key: string, value: string) {
+    ApiService._customHeaders[key] = value;
+  }
+
+  /**
+   * 靜態方法，移除全域自訂標頭
+   * @param key
+   */
+  static removeHeader(key: string) {
+    delete ApiService._customHeaders[key];
+  }
+
+  /**
+   * 靜態方法，設定自訂標頭提供者
+   * @param provider
+   */
+  static customHeaderProvider(provider: (endpoint: ApiEndpoint, header: Record<string, any>) => Promise<Record<string, string>>) {
+    ApiService._customHeaderProvider = provider;
+  }
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor() {
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 靜態方法，配置 ApiService
+   * 為方便管理，建議在專案啟動時呼叫此方法註冊所有端點
+   * 可以配置
+   * - debugMode: 是否啟用除錯模式
+   * - baseUrl: API 伺服器的基礎 URL
+   * - contextPath: API 的上下文路徑
+   * - proxyEnable: 是否啟用代理
+   * - proxyBaseUrl: 代理的基礎 URL
+   * - showSpinnerFunc: 顯示全域載入動畫的函式
+   * - hideSpinnerFunc: 隱藏全域載入動畫的函式
+   * - showErrorToastFunc: 顯示全域錯誤提示的函式
+   * - endpoints: 預設註冊的 API 端點
+   * - customHeaders: 全域自訂標頭
+   * - customErrorMessageMap: 全域自訂錯誤訊息對應
+   * - createEndpointOptions: 建立端點時的預設選項
+   * - refreshTokenFunc: 刷新存取權杖的函式
+   * - onAuthenticateFailed: 認證失敗時的回調函式
+   * @param config
+   */
+  static configure(config:{
+    debugMode?: boolean;
+    baseUrl?: string;
+    contextPath?: string;
+    proxyEnable?: boolean;
+    proxyBaseUrl?: string;
+    showSpinnerFunc?: () => void;
+    hideSpinnerFunc?: () => void;
+    showErrorToastFunc?: (param: {title?:string,content?:string}) => void;
+    endpoints: Record<string, ApiEndpoint>;
+    customHeaders?: Record<string, string>;
+    customHeaderProvider?: (endpoint: ApiEndpoint, header: Record<string, any>) => Promise<Record<string, string>>;
+    customErrorMessageMap?: Record<number, string>;
+    createEndpointOptions?: CreateEndpointOptions;
+    refreshTokenFunc?: () => Promise<AccessToken>;
+    onAuthenticateFailed?: (param: {apiEndpoint: ApiEndpoint, apiRequest: ApiRequest}) => void;
+  }) {
+    // 設定靜態屬性
+    ApiService._options = Object.assign(ApiService._options, {
+      debugMode: config.debugMode || false,
+      baseUrl: config.baseUrl || '',
+      contextPath: config.contextPath || '',
+      proxyEnable: config.proxyEnable,
+      proxyBaseUrl: config.proxyBaseUrl,
+      showSpinnerFunc: config.showSpinnerFunc,
+      hideSpinnerFunc: config.hideSpinnerFunc,
+      showErrorToastFunc: config.showErrorToastFunc,
+      createEndpointOptions: config.createEndpointOptions,
+      refreshTokenFunc: config.refreshTokenFunc,
+      onAuthenticateFailed: config.onAuthenticateFailed
+    });
+
+    // setup logger
+    const logger = log.getLogger('ApiService');
+    logger.setLevel( ApiService._options.debugMode ? log.levels.DEBUG : log.levels.WARN );
+
+    // 設定全域自訂標頭提供者
+    if(config.customHeaderProvider) {
+      ApiService._customHeaderProvider = config.customHeaderProvider;
+      logger.debug('ApiService customHeaderProvider set.');
+    }
+
+    // 逐一新增端點
+    Object.keys(config.endpoints).forEach(key => {
+      const endpointData = config.endpoints![key];
+      // 如果有 customHeaders，則把 customHeaders 當作基底合併
+      if(config.customHeaders) {
+        endpointData.headers = Object.assign({},
+          config.customHeaders,
+          endpointData.headers || {}
+        );
+      }
+      // 如果有 customErrorMessageMap，則把 customErrorMessageMap 當作基底合併
+      if(config.customErrorMessageMap) {
+        endpointData.errorMessageMap = Object.assign({},
+          config.customErrorMessageMap,
+          endpointData.errorMessageMap || {}
+        );
+      }
+      // 新增端點
+      ApiService.addEndpoints(key, endpointData);
+    });
+
+    // 初始化 axios 攔截器
+    ApiService.setupAxiosInterceptors();
+  }
+
+  /**
+   * 靜態方法，新增單一 API 端點
+   * @param key
+   * @param endpoint
+   */
+  static addEndpoints(key: string, endpoint: ApiEndpoint) {
+    if(!ApiService._apiEndpoints) {
+      ApiService._apiEndpoints = {};
+    }
+    if(ApiService._apiEndpoints.hasOwnProperty(key)) {
+      console.log(`API endpoint key:${key} already exists, skip adding.`);
+      return;
+    }
+    ApiService._apiEndpoints[key] = createEndpoint(endpoint, ApiService._options.createEndpointOptions);
+  }
+
+  /**
+   * 靜態方法，方便直接呼叫 API
+   * @param request
+   */
+  static call(request: ApiRequest): Promise<ApiResponse> {
+    const service = new ApiService();
+    return service.callApi(request);
+  }
+
+  /**
+   * 靜態方法，方便直接下載檔案
+   * @param request
+   */
+  static download(request: ApiRequest): Promise<void> {
+    const service = new ApiService();
+    return service.downloadFile(request);
+  }
+
+  /**
+   * 取得指定的 API 端點資訊
+   * @param endpointKey
+   */
+  getEndpoint(endpointKey: string): ApiEndpoint | undefined {
+    return ApiService._apiEndpoints[endpointKey];
+  }
+
+  /**
+   * 取得完整的 API URL
+   * @param endpointKey
+   */
+  getFullUrl(endpointKey: string): string | undefined {
+    const endpoint = this.getEndpoint(endpointKey);
+    if (endpoint) {
+      return this.makeBaseUrl(endpoint);
+    }
+    return undefined;
+  }
+
+  /**
+   * 組合完整的 API URL
+   * @param endpoint
+   */
+  makeBaseUrl(endpoint: ApiEndpoint): string | undefined {
+    // 判斷是否啟用代理
+    const proxyEnable = ApiService._options.proxyEnable || false;
+    let baseUrl = ApiService._options.baseUrl || '';
+    if(proxyEnable) {
+      // 如果啟用代理，則使用代理的 base URL (VITE_API_PROXY_BASE_URL)
+      baseUrl = ApiService._options.proxyBaseUrl || '';
+    }
+    // 取得 API context path
+    const baseContext = ApiService._options.contextPath || '';
+    if( !baseUrl || !baseContext || _.isEmpty(baseUrl) || _.isEmpty(baseContext) ) {
+      console.warn('API base URL or context is not defined.');
+      return undefined;
+    }
+    if (endpoint) {
+      return `${baseUrl}${baseContext}${endpoint.path}`;
+    }
+  }
+
+  /**
+   * 呼叫 API
+   * @param request
+   */
+  async callApi(request: ApiRequest): Promise<ApiResponse> {
+    const endpoint = this.getEndpoint(request.endpointKey);
+    if (!endpoint) {
+      return Promise.reject(new Error(`API endpoint ${request.endpointKey} not found`));
+    }
+
+    let url = this.makeBaseUrl(endpoint);
+    if (!url) {
+      return Promise.reject(new Error(`Invalid URL for endpoint ${request.endpointKey}`));
+    }
+
+    // 取得 logger
+    const logger = log.getLogger('ApiService');
+
+    // 替換 path 參數
+    if (request.pathParam) {
+      Object.keys(request.pathParam).forEach(key => {
+        if(_.isNil(request.pathParam)) {
+          return;
+        }
+        url = url?.replace(`{${key}}`, encodeURIComponent(request.pathParam[key]));
+      });
+    }
+
+    // 處理 postBody, 例如：轉換 Date 物件為 ISO 字串
+    let usePostBody;
+    if(request.postBody && request.postBody instanceof FormData) {
+      usePostBody = request.postBody;
+    } else {
+      usePostBody = formatDatesInObject(_.cloneDeep(request.postBody));
+    }
+
+    // 處理自訂標頭
+    let dynamicHeaders: Record<string, string> = {};
+    if(ApiService._customHeaderProvider) {
+      dynamicHeaders = await ApiService._customHeaderProvider(endpoint, ApiService._customHeaders) || {};
+    }
+
+    // 準備 Axios 請求配置
+    const config: AxiosRequestConfig & { metadata?: ConfigMetaData } = Object.assign({}, {
+      url: url,
+      method: endpoint.method,
+      headers: Object.assign(ApiService._customHeaders || {},
+        endpoint.headers || {},
+        request.headers || {},
+        dynamicHeaders
+      ),
+      data: usePostBody,
+      params: request.queryParam,
+      withCredentials: endpoint.withCredentials || false,
+      onUploadProgress: request.onUploadProgress,
+      // 添加 metadata 供攔截器使用
+      metadata: {
+        endpoint: endpoint,
+        request: request
+      }
+    }, request.axiosConfig || {});
+    if(request.isDownloadMode) {
+      config.responseType = 'blob';
+    }
+
+    const cOpt = ApiService._options;
+    const axiosInstance = ApiService.getAxiosInstance();
+
+    // 顯示 global spinner
+    const needToShowSpinner = !(endpoint.noSpinner) || request.noSpinner === false;
+    if (needToShowSpinner) {
+      cOpt.showSpinnerFunc?.();
+    }
+
+    return axiosInstance(config)
+      .then((response: AxiosResponse) => {
+        if(request.isDownloadMode) {
+          // 下載檔案
+          return new ApiResponse({
+            httpStatus: response.status,
+            blobData: response.data,
+            headers: response.headers,
+            axiosResponse: response
+          });
+        }
+        // 一般 API 呼叫，回應 JSON 格式
+        return new ApiResponse({
+          httpStatus: response.status,
+          status: response.data.status,
+          message: response.data.message,
+          data: response.data,
+          paging: response.data.paging,
+          axiosResponse: response
+        });
+      })
+      .finally(() => {
+        // 隱藏 global spinner
+        if (needToShowSpinner) {
+          cOpt.hideSpinnerFunc?.();
+        }
+      })
+      .catch((error: any) => {
+        console.error('API call failed:', error);
+        // 處理錯誤
+        const apiResp = error.response;
+
+        // 顯示錯誤提示（401 錯誤已由攔截器處理）
+        const msg = _.get(apiResp, 'data.message')
+          || endpoint.errorMessageMap?.[error.response?.status]
+          || 'API 呼叫失敗';
+        cOpt.showErrorToastFunc?.({
+          title: '錯誤',
+          content: msg
+        });
+        return new ApiResponse({
+          httpStatus: apiResp?.status || 500,
+          status: _.get(apiResp, 'data.status'),
+          message: _.get(apiResp, 'data.message') || msg,
+          data: null,
+          details: _.get(apiResp, 'data.details'),
+          nativeError: error
+        });
+      });
+  }
+
+  /**
+   * 下載檔案
+   * @param request
+   */
+  async downloadFile(request: ApiRequest): Promise<void> {
+    request.isDownloadMode = true;
+    const response = await this.callApi(request);
+    if(!response.isOk() || !response.blobData) {
+      return Promise.reject(new ApiRejectError(response));
+    }
+    // 下載檔案
+    // 決定下載檔案名稱： 指定檔案名稱
+    let exportFileName = this.resolveExportFileName(request, response);
+
+    // 使用 a 標籤下載檔案
+    const url = window.URL.createObjectURL(response.blobData);
+    const link = document.createElement('a');
+    link.href = url;
+    link.setAttribute('download', exportFileName);
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    window.URL.revokeObjectURL(url);
+    return Promise.resolve();
+  }
+
+  /**
+   * 決定下載檔案名稱
+   * @param request
+   * @param response
+   */
+  resolveExportFileName(request: ApiRequest, response: ApiResponse): string {
+    let exportFileName = request.downloadFileName;
+    // 若沒有指定檔案名稱，從 Content-Disposition 標頭取得檔案名稱
+    if(!exportFileName) {
+      const dispositionHeaderVal = response.headers?.['content-disposition'] as string || '';
+      // RFC 5987 支援的 filename*
+      let match = dispositionHeaderVal.match(/filename\*=UTF-8''([^;"']+)/i);
+      if(match && match.length > 1) {
+        return decodeURIComponent(match[1]);
+      }
+      // 傳統的 filename 使用 RFC 2047 編碼
+      match = dispositionHeaderVal.match(/filename=["']?([^;"']+)/i);
+      if (match && match[1]) {
+        return this.decodeRfc2047(match[1]);
+      }
+    }
+    // 若仍沒有檔案名稱，使用預設名稱
+    if(!exportFileName) {
+      exportFileName = 'downloaded_file';
+    }
+    // 若是 response header 有 content-type，且檔案名稱沒有副檔名或副檔名不一致，則根據 content-type 補上副檔名
+    const contentType = response.headers?.['content-type'] as string || '';
+    if(_.isNil(contentType) || _.isEmpty(contentType)) {
+      return exportFileName;
+    }
+    const mime = contentType.split(';')[0]; // 去掉可能的 charset 資訊
+    const expectedExtension = extension(mime);
+    if(!expectedExtension) {
+      return exportFileName;
+    }
+    const fa = exportFileName.split('.');
+    if(fa.length === 1) {
+      // 沒有副檔名，直接加上
+      exportFileName += `.${expectedExtension}`;
+    } else {
+      const currentExtension = fa[fa.length - 1];
+      const baseName = fa.slice(0, fa.length - 1).join('.');
+      if(currentExtension.toLowerCase() !== expectedExtension.toLowerCase()) {
+        // 副檔名不一致，改用正確的副檔名
+        exportFileName = `${baseName}.${expectedExtension}`;
+      }
+    }
+    return exportFileName;
+  }
+
+  /**
+   * 解碼 RFC 2047 編碼的字串
+   * @param str RFC 2047 編碼的字串
+   */
+  decodeRfc2047(str: string): string {
+    const match = str.match(/=\?([^?]+)\?([bqBQ])\?([^?]+)\?=/);
+    if (!match) {
+      return str;
+    }
+    const charset = match[1].toLowerCase();
+    const encoding = match[2].toUpperCase();
+    let text = match[3];
+
+    if (encoding === 'B') {
+      // Base64
+      const decoded = atob(text);
+      return new TextDecoder(charset).decode(Uint8Array.from(decoded, c => c.charCodeAt(0)));
+    } else if (encoding === 'Q') {
+      // Quoted-Printable
+      text = text.replace(/_/g, ' ').replace(/=([A-Fa-f0-9]{2})/g, (_, hex) =>
+        String.fromCharCode(parseInt(hex, 16))
+      );
+      return new TextDecoder(charset).decode(new Uint8Array(Array.from(text, c => c.charCodeAt(0))));
+    }
+    return str;
+  }
+
+  /**
+   * 檢查是否啟用 Bearer Token 認證
+   */
+  private static hasBearerAuth(): boolean {
+    return this._options.createEndpointOptions?.security?.includes('bearerAuth') ?? false;
+  }
+
+  /**
+   * 設定 axios 攔截器
+   */
+  private static setupAxiosInterceptors(): void {
+    // 如果已經設定過攔截器，則不重複設定
+    if (ApiService._axiosInstance) {
+      return;
+    }
+
+    // 建立 axios 實例
+    ApiService._axiosInstance = axios.create();
+
+    // 只有啟用 Bearer Token 認證時才設定 interceptors
+    if (this.hasBearerAuth()) {
+      this.setupAuthInterceptorsOnBearerAuth();
+    }
+  }
+
+  /**
+   * 設定認證相關的 interceptors
+   */
+  private static setupAuthInterceptorsOnBearerAuth(): void {
+    if (!ApiService._axiosInstance) {
+      return;
+    }
+
+    const logger = log.getLogger('ApiService');
+
+    // 請求攔截器 - 自動添加 Authorization header
+    ApiService._axiosInstance.interceptors.request.use(
+      async (config: InternalAxiosRequestConfig & { metadata?: ConfigMetaData }) => {
+        // 根據 metadata 取得 endpoint 資訊
+        const metadata = config.metadata as ConfigMetaData | undefined;
+        const accessToken = await ApiService.getAccessToken();
+
+        // 如果 endpoint 需要認證且有 access token
+        if (metadata?.endpoint?.isAuthenticated && accessToken && config.headers && !config.headers['Authorization']) {
+          // 檢查 token 是否即將過期，當過期則try 刷新 token
+          if (accessToken.isExpired()) {
+            try {
+              await ApiService.refreshTokenIfNeeded();
+              const updatedToken = await ApiService.getAccessToken();
+              if(updatedToken) {
+                config.headers['Authorization'] = updatedToken.bearerToken;
+              }
+            }catch (error) {
+              // Token 刷新失敗，中止請求
+              // 當發生錯誤，則觸發認證失敗處理
+              ApiService.handleAuthenticationFailed(error, config);
+              return Promise.reject(error); // 這會中止該請求
+            }
+          } else {
+            config.headers['Authorization'] = accessToken.bearerToken;
+          }
+        }
+        return config;
+      },
+      (error: any) => Promise.reject(error)
+    );
+
+    // 回應攔截器 - 處理 401 錯誤和 token 刷新
+    ApiService._axiosInstance.interceptors.response.use(
+      (response: AxiosResponse) => response,
+      async (error: any) => {
+        // 如果 error is 不是來自 axios，直接拒絕
+        if (!error.config) {
+          return Promise.reject(error);
+        }
+        // 取得原始請求配置
+        const originalRequest = error.config;
+
+        if(ApiService._options.debugMode) {
+          console.log('API response error intercepted:', error);
+        }
+
+        // 從 config 中取得 endpoint 和 request 資訊（如果有的話）
+        const metadata = originalRequest.metadata as ConfigMetaData | undefined;
+        // 只有當 endpoint 需要認證時才處理 401 錯誤
+        if (!metadata?.endpoint?.isAuthenticated) {
+          return Promise.reject(error);
+        }
+
+        // 檢查是否為 401 錯誤且尚未重試過
+        if (error.response?.status === 401 && !originalRequest._retry) {
+          originalRequest._retry = true;
+
+          // 如果正在刷新 token，將請求加入佇列
+          if (ApiService._isRefreshing) {
+            if(ApiService._options.debugMode) {
+              console.log('Token is being refreshed, queuing request.');
+            }
+            return new Promise((resolve, reject) => {
+              ApiService._failedRequestQueue.push({
+                resolve,
+                reject,
+                config: originalRequest
+              });
+            });
+          }
+
+          // 開始刷新 token
+          try {
+            ApiService._isRefreshing = true;
+            const newToken = await ApiService.refreshToken();
+
+            // 更新原始請求的 Authorization header
+            if (originalRequest.headers) {
+              originalRequest.headers['Authorization'] = newToken.bearerToken;
+            }
+
+            // 處理佇列中的失敗請求
+            ApiService.processFailedRequestQueue(null, newToken);
+
+            // 重試原始請求
+            return ApiService._axiosInstance!(originalRequest);
+          } catch (refreshError) {
+            console.error('Token refresh failed:', refreshError);
+            // 刷新失敗，處理佇列並觸發認證失敗
+            ApiService.processFailedRequestQueue(refreshError, null);
+            ApiService.handleAuthenticationFailed(error, originalRequest);
+            return Promise.reject(refreshError);
+          } finally {
+            ApiService._isRefreshing = false;
+          }
+        }
+
+        return Promise.reject(error);
+      }
+    );
+  }
+
+  /**
+   * 刷新 access token
+   */
+  static async refreshToken(): Promise<AccessToken> {
+    if (!ApiService._options.refreshTokenFunc) {
+      throw new Error('Refresh token function not configured');
+    }
+
+    try {
+      const newToken = await ApiService._options.refreshTokenFunc();
+      if(!newToken) {
+        throw new Error('Failed to refresh token: no token returned');
+      }
+      ApiService._accessToken = newToken;
+      return newToken;
+    } catch (error) {
+      // 清除 token
+      console.error('Token refresh failed:', error);
+      ApiService._accessToken = undefined;
+      throw error;
+    }
+  }
+
+  /**
+   * 檢查並刷新 token（如果需要）
+   */
+  private static async refreshTokenIfNeeded(): Promise<AccessToken> {
+    if (!ApiService._refreshTokenPromise) {
+      ApiService._refreshTokenPromise = ApiService.refreshToken()
+        .finally(() => {
+          ApiService._refreshTokenPromise = undefined;
+        });
+    }
+    if (ApiService._refreshTokenPromise) {
+      return ApiService._refreshTokenPromise;
+    } else {
+      return Promise.reject('No refresh token promise available');
+    }
+  }
+
+  /**
+   * 處理佇列中的失敗請求
+   */
+  private static processFailedRequestQueue(error: any, token: AccessToken | null): void {
+    ApiService._failedRequestQueue.forEach(({ resolve, reject, config }) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      // 更新請求的 Authorization header 並重試
+      if (token && config.headers) {
+        config.headers['Authorization'] = token.bearerToken;
+      }
+      resolve(ApiService._axiosInstance!(config));
+    });
+
+    // 清空佇列
+    ApiService._failedRequestQueue = [];
+  }
+
+  /**
+   * 處理認證失敗
+   */
+  private static handleAuthenticationFailed(_error: any, config: AxiosRequestConfig & { metadata?: ConfigMetaData }): void {
+    // 從 config 中取得 endpoint 和 request 資訊（如果有的話）
+    const metadata = config.metadata as ConfigMetaData | undefined;
+
+    ApiService._options.onAuthenticateFailed?.({
+      apiEndpoint: metadata?.endpoint || {} as ApiEndpoint,
+      apiRequest: metadata?.request || {} as ApiRequest
+    });
+  }
+
+  /**
+   * 取得 axios 實例
+   */
+  private static getAxiosInstance(): AxiosInstance {
+    if (!ApiService._axiosInstance) {
+      ApiService.setupAxiosInterceptors();
+    }
+    return ApiService._axiosInstance!;
+  }
+}
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __ApiServiceDefine__ = null as unknown as
+  ApiEndpoint;