@gct-paas/api 0.1.0-dev.5 → 0.1.0-dev.7

package/es/service/api-service.d.ts

@@ -1,4 +1,4 @@
-import type { ApiConfigItem, IHttpResponse } from './api-service.interface';
+import type { ApiConfigItem } from './api-service.interface';
 import type { AxiosRequestConfig } from 'axios';
 /**
  * 服务基类
@@ -22,76 +22,83 @@ export declare class ApiService {
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _put(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _put<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * GET 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _get(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _get<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * DELETE 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _delete(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _delete<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * POST 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _post(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _post<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * OPTIONS 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _options(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _options<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * PATCH 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _patch(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _patch<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
     /**
      * HEAD 请求方法
      *
      * @protected
      * @param {string} method 请求方法路径
-     * @param {(IObject | null)} data 请求数据
-     * @param {(IParams | null)} query 查询参数
+     * @param {(IParams)} pathParams 路径参数
+     * @param {(IObject)} data 请求数据
+     * @param {(IParams)} query 查询参数
      * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-     * @returns {Promise<IHttpResponse>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    protected _head(method: string, data: IObject | null, query: IParams | null, config?: Partial<AxiosRequestConfig>): Promise<IHttpResponse>;
+    protected _head<T = unknown>(method: string, pathParams?: IParams, query?: IParams, data?: IObject, config?: Partial<AxiosRequestConfig>): Promise<T>;
 }

package/es/service/api-service.interface.d.ts

@@ -80,22 +80,24 @@ export interface ApiItem {
      * @type {string}
      */
     path: string;
+    /**
+     * 是否有路径参数
+     *
+     * @type {boolean}
+     */
+    hasPathParams?: boolean;
     /**
      * 是否有查询参数
      *
-     * @author chitanda
-     * @date 2025-08-21 19:08:35
      * @type {boolean}
      */
-    hasQuery: boolean;
+    hasQuery?: boolean;
     /**
      * 是否有请求体
      *
-     * @author chitanda
-     * @date 2025-08-21 19:08:41
      * @type {boolean}
      */
-    hasData: boolean;
+    hasData?: boolean;
 }
 /**
  * 接口配置项

package/es/service/api-service.mjs

@@ -17,21 +17,61 @@ export class ApiService {
           const cfg = config.apis.find((item) => item.method === property);
           if (cfg) {
             const modeFn = `_${cfg.mode}`;
-            if (cfg.hasData && cfg.hasQuery) {
-              api[property] = (data, query, config2) => {
-                return api[modeFn](cfg.path, query, data, config2);
+            if (cfg.hasPathParams && cfg.hasData && cfg.hasQuery) {
+              api[property] = (path2, query, data, config2) => {
+                return api[modeFn](cfg.path, path2, query, data, config2);
+              };
+            } else if (cfg.hasPathParams && cfg.hasData) {
+              api[property] = function(path2, data, config2) {
+                return api[modeFn](cfg.path, path2, void 0, data, config2);
+              };
+            } else if (cfg.hasPathParams && cfg.hasQuery) {
+              api[property] = function(path2, query, config2) {
+                return api[modeFn](cfg.path, path2, query, void 0, config2);
+              };
+            } else if (cfg.hasPathParams) {
+              api[property] = function(path2, config2) {
+                return api[modeFn](
+                  cfg.path,
+                  path2,
+                  void 0,
+                  void 0,
+                  config2
+                );
+              };
+            } else if (cfg.hasData && cfg.hasQuery) {
+              api[property] = function(query, data, config2) {
+                return api[modeFn](cfg.path, void 0, query, data, config2);
               };
             } else if (cfg.hasData) {
               api[property] = function(data, config2) {
-                return api[modeFn](cfg.path, data, void 0, config2);
+                return api[modeFn](
+                  cfg.path,
+                  void 0,
+                  void 0,
+                  data,
+                  config2
+                );
               };
             } else if (cfg.hasQuery) {
               api[property] = function(query, config2) {
-                return api[modeFn](cfg.path, void 0, query, config2);
+                return api[modeFn](
+                  cfg.path,
+                  void 0,
+                  query,
+                  void 0,
+                  config2
+                );
               };
             } else {
               api[property] = function(config2) {
-                return api[modeFn](cfg.path, void 0, void 0, config2);
+                return api[modeFn](
+                  cfg.path,
+                  void 0,
+                  void 0,
+                  void 0,
+                  config2
+                );
               };
             }
           }
@@ -45,16 +85,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _put(method, data, query, config) {
+  _put(method, pathParams, query, data, config) {
     return HttpUtil.put(
-      query?.id ? path.join(this.url, method, query.id) : path.join(this.url, method),
-      data || {},
-      query || {},
+      path.join(this.url, method),
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -63,16 +105,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _get(method, data, query, config) {
+  _get(method, pathParams, query, data, config) {
     return HttpUtil.get(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -81,16 +125,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _delete(method, data, query, config) {
+  _delete(method, pathParams, query, data, config) {
     return HttpUtil.delete(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -99,16 +145,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _post(method, data, query, config) {
+  _post(method, pathParams, query, data, config) {
     return HttpUtil.post(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -117,16 +165,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _options(method, data, query, config) {
+  _options(method, pathParams, query, data, config) {
     return HttpUtil.options(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -135,16 +185,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _patch(method, data, query, config) {
+  _patch(method, pathParams, query, data, config) {
     return HttpUtil.patch(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }
@@ -153,16 +205,18 @@ export class ApiService {
    *
    * @protected
    * @param {string} method 请求方法路径
-   * @param {(IObject | null)} data 请求数据
-   * @param {(IParams | null)} query 查询参数
+   * @param {(IParams)} pathParams 路径参数
+   * @param {(IObject)} data 请求数据
+   * @param {(IParams)} query 查询参数
    * @param {Partial<AxiosRequestConfig>} [config] 请求配置
-   * @returns {Promise<IHttpResponse>} 请求结果
+   * @returns {Promise<T>} 请求结果
    */
-  _head(method, data, query, config) {
+  _head(method, pathParams, query, data, config) {
     return HttpUtil.head(
       path.join(this.url, method),
-      data || {},
-      query || {},
+      pathParams,
+      data,
+      query,
       config
     );
   }

package/es/service/http.error.d.ts

@@ -0,0 +1,40 @@
+/**
+ * HTTP 请求错误类
+ *
+ * @export
+ * @class HttpError
+ * @extends {Error}
+ * @template T
+ */
+export declare class BackendError<T = unknown> extends Error {
+    /**
+     * 错误代码
+     *
+     * @type {number}
+     */
+    code: number;
+    /**
+     * 响应数据
+     *
+     * @type {T}
+     */
+    data: T;
+    /**
+     * 子状态码
+     *
+     * @type {number}
+     */
+    subCode?: number;
+    /**
+     * 子状态消息
+     *
+     * @type {string}
+     */
+    subMessage?: string;
+    /**
+     * 创建 BackendError 实例
+     *
+     * @param {IHttpResponse<T>} response HTTP 响应对象
+     */
+    constructor(response: IHttpResponse<T>);
+}

package/es/service/http.error.mjs

@@ -0,0 +1,39 @@
+export class BackendError extends Error {
+  /**
+   * 错误代码
+   *
+   * @type {number}
+   */
+  code;
+  /**
+   * 响应数据
+   *
+   * @type {T}
+   */
+  data;
+  /**
+   * 子状态码
+   *
+   * @type {number}
+   */
+  subCode;
+  /**
+   * 子状态消息
+   *
+   * @type {string}
+   */
+  subMessage;
+  /**
+   * 创建 BackendError 实例
+   *
+   * @param {IHttpResponse<T>} response HTTP 响应对象
+   */
+  constructor(response) {
+    super(response.message);
+    this.name = "BackendError";
+    this.code = response.code;
+    this.data = response.data;
+    this.subCode = response.subCode;
+    this.subMessage = response.subMessage;
+  }
+}

package/es/service/http.util.d.ts

@@ -1,5 +1,4 @@
 import type { AxiosInstance, AxiosRequestConfig } from 'axios';
-import type { IHttpResponse } from './api-service.interface';
 /**
  * 全局请求工具类
  *
@@ -20,94 +19,124 @@ export declare class HttpUtil {
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static get<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static get<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * POST 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static post<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static post<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * PUT 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static put<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static put<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * DELETE 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static delete<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static delete<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * OPTIONS 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static options<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static options<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * PATCH 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static patch<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static patch<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
     /**
      * HEAD 请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
      * @param {IObject} [data={}] 请求数据
      * @param {IParams} [query={}] 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static head<T = unknown>(url: string, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static head<T = unknown>(url: string, path?: IObject, data?: IObject, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 文件上传方法
+     *
+     * @static
+     * @template T
+     * @param {string} url 请求地址
+     * @param {IObject} [path={}] 路径参数
+     * @param {UploadFileData} [data={}] 额外的请求数据
+     * @param {IParams} [query={}] 查询参数
+     * @param {AxiosRequestConfig} [config={}] 请求配置
+     * @returns {Promise<T>} 请求结果
+     */
+    static upload<T = unknown>(url: string, path?: IObject, data?: Partial<UploadFileData>, query?: IParams, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 转换 URL 中的路径参数
+     *
+     * @protected
+     * @param {string} url
+     * @param {IObject} path
+     * @return {*}  {string}
+     */
+    protected static transformUrl(url: string, path: IObject): string;
     /**
      * 通用请求方法
      *
      * @static
      * @template T
      * @param {string} url 请求地址
+     * @param {(IObject | null)} path 路径参数
      * @param {(IObject | null)} data 请求数据
      * @param {(IParams | null)} query 查询参数
      * @param {AxiosRequestConfig} [config={}] 请求配置
-     * @returns {Promise<IHttpResponse<T>>} 请求结果
+     * @returns {Promise<T>} 请求结果
      */
-    static request<T = unknown>(url: string, data: IObject | null, query: IParams | null, config?: AxiosRequestConfig): Promise<IHttpResponse<T>>;
+    static request<T = unknown>(url: string, path: IObject | null, data: IObject | null, query: IParams | null, config?: AxiosRequestConfig): Promise<T>;
 }