utils-uniapp 1.1.22 → 1.1.25

package/lib/http/index.d.ts

@@ -40,11 +40,15 @@ type UniAnyResult = UniRequestResult | UniUploadResult | UniDownloadResult;
  * @internal
  */
 type RequestFailPayload = {
+  /** 失败类型标识 */
   type: 'fail';
+  /** uni原始回调结果 */
   res: UniApp.GeneralCallbackResult;
 };
 
-/** 标准化后的请求配置 */
+/**
+ * 标准化后的请求配置
+ */
 type NormalizeReqConfig = Partial<UniApp.RequestOptions | UniApp.UploadFileOption | UniApp.DownloadFileOption> & {
   /** 库自定义：请求基础地址，非uni.request原生参数 */
   baseURL: string;
@@ -102,6 +106,10 @@ export interface CacheConfigInput {
   adapter?: CacheAdapter | null | ((ctx: { url: string; config: NormalizeReqConfig; options: RequestOptions; cacheConfig: CacheConfig }) => CacheAdapter | null);
 }
 
+/**
+ * 重载请求函数类型
+ * @template T
+ */
 type ReloadFn = <T>(...newArgvs: Parameters<RequestInstance>) => RequestPromise<T>;
 
 /**
@@ -110,25 +118,34 @@ type ReloadFn = <T>(...newArgvs: Parameters<RequestInstance>) => RequestPromise<
  * @internal
  */
 interface CacheConfig {
+  /** 是否启用缓存 */
   readonly enable: boolean;
+  /** 最终生成的缓存key */
   readonly key: string;
+  /** 缓存key前缀 */
   readonly prefix: string;
+  /** 缓存有效期，单位秒 */
   readonly expire: number;
+  /** 缓存适配器实例 */
   readonly adapter: CacheAdapter | null;
 }
 
+/** 拦截器返回类型 */
 type InterceptorReturn<T> = Promise<T> | T;
 /**
  * 请求前置拦截器【标准化后】
+ * @description 若拦截器返回 null / undefined，会自动使用原始 invokeArgs；有返回值则使用拦截器输出，必须保持 NormalizeReqConfig 结构
  * @param ctx 上下文
  * @param ctx.invokeArgs 组装完成即将传给uni的请求参数（原invokeArgs）
  * @param ctx.options normalizeOpts合并后的完整配置
  * @param next 执行下一个拦截器，返回处理后的请求参数
- * @returns 处理后的请求参数
+ * @returns 处理后的请求参数；返回 null/undefined 将自动兜底为原始 invokeArgs
  */
 type ReqInterceptor = (
   ctx: {
+    /** 组装完成即将传给uni的请求参数 */
     invokeArgs: NormalizeReqConfig;
+    /** normalizeOpts合并后的完整配置 */
     options: RequestOptions;
   },
   next: () => InterceptorReturn<NormalizeReqConfig>
@@ -136,40 +153,51 @@ type ReqInterceptor = (
 
 /**
  * 响应拦截器【标准化后】
+ * @description 若拦截器返回 null / undefined，会自动使用原始 res；有返回值则使用拦截器输出作为最终业务数据
  * @param ctx 上下文
- * @param ctx res uni原始响应对象，实际类型为 UniAnyResult
+ * @param ctx.res uni原始响应对象，实际类型为 UniAnyResult
  * @param ctx.invokeArgs 组装完成即将传给uni的请求参数
  * @param ctx.options normalizeOpts合并后的完整配置
  * @param ctx.reload 重发当前请求函数
  * @param next 执行下一个拦截器，返回处理后业务数据
- * @returns 处理后业务数据
+ * @returns 处理后业务数据；返回 null/undefined 将自动兜底为原始 res
  */
 type ResInterceptor = (
   ctx: {
+    /** uni原始响应对象 */
     res: UniAnyResult;
+    /** 组装完成即将传给uni的请求参数 */
     invokeArgs: NormalizeReqConfig;
+    /** normalizeOpts合并后的完整配置 */
     options: RequestOptions;
+    /** 重发当前请求函数 */
     reload: ReloadFn;
   },
   next: () => InterceptorReturn<any>
 ) => InterceptorReturn<any>;
 
+/** 错误类型：接口失败载荷 | JS异常 */
 type Err = RequestFailPayload | Error;
 /**
  * 错误拦截器【标准化后】
+ * @description 若拦截器返回 null / undefined，会自动抛出原始 err；有返回值则使用拦截器输出作为拒绝原因
  * @param ctx 上下文
  * @param ctx.err 捕获到的异常对象，可能为接口回调失败载荷 RequestFailPayload 或 JS运行异常 Error
  * @param ctx.invokeArgs 组装完成即将传给uni的请求参数
  * @param ctx.options normalizeOpts合并后的完整配置
- * @param ctx.reloadFn 重发当前请求函数
+ * @param ctx.reload 重发当前请求函数
  * @param next 执行下一个拦截器，返回错误载荷
- * @returns 返回非undefined代表错误已接管；返回undefined会继续抛出异常
+ * @returns 错误载荷；返回 null/undefined 将自动兜底为原始 err
  */
 type ErrInterceptor = (
   ctx: {
+    /** 捕获到的异常对象 */
     err: Err;
+    /** 组装完成即将传给uni的请求参数 */
     invokeArgs: NormalizeReqConfig;
+    /** normalizeOpts合并后的完整配置 */
     options: RequestOptions;
+    /** 重发当前请求函数 */
     reload: ReloadFn;
   },
   next: () => InterceptorReturn<Err>
@@ -179,7 +207,13 @@ type ErrInterceptor = (
  * 用户传入拦截器：支持单个函数 / 函数数组，交由 normalizeInterceptor + composeAsync合并
  */
 export type UserReqInterceptor = ReqInterceptor | ReqInterceptor[];
+/**
+ * 用户传入响应拦截器：支持单个函数 / 函数数组，交由 normalizeInterceptor + composeAsync合并
+ */
 export type UserResInterceptor = ResInterceptor | ResInterceptor[];
+/**
+ * 用户传入错误拦截器：支持单个函数 / 函数数组，交由 normalizeInterceptor + composeAsync合并
+ */
 export type UserErrInterceptor = ErrInterceptor | ErrInterceptor[];
 
 /**
@@ -251,15 +285,40 @@ export interface UserRequestOpts {
    */
   loading?: boolean;
   /**
-   * 请求前置拦截器，支持单个函数或函数数组
+   * 请求前置拦截器
+   * - 支持单个拦截器函数 / 拦截器函数数组，多个拦截器按顺序链式执行
+   * - 拦截器返回 null / undefined 时，自动沿用原始 invokeArgs
+   * @param ctx 上下文
+   * @param ctx.invokeArgs 组装完成即将传给uni的请求参数
+   * @param ctx.options normalizeOpts合并后的完整配置
+   * @param next 执行下一个拦截器，返回处理后的请求参数
+   * @returns 处理后的请求参数，返回 null/undefined 将自动兜底原始invokeArgs
    */
   reqInterceptor?: UserReqInterceptor;
   /**
-   * 响应拦截器，支持单个函数或函数数组
+   * 响应拦截器
+   * - 支持单个拦截器函数 / 拦截器函数数组，多个拦截器按顺序链式执行
+   * - 拦截器返回 null / undefined 时，自动沿用原始响应res
+   * @param ctx 上下文
+   * @param ctx.res uni原始响应对象
+   * @param ctx.invokeArgs 组装完成即将传给uni的请求参数
+   * @param ctx.options normalizeOpts合并后的完整配置
+   * @param ctx.reload 重发当前请求函数
+   * @param next 执行下一个拦截器，返回处理后业务数据
+   * @returns 处理后业务数据，返回 null/undefined 将自动兜底原始res
    */
   resInterceptor?: UserResInterceptor;
   /**
-   * 错误拦截器，支持单个函数或函数数组
+   * 错误拦截器
+   * - 支持单个拦截器函数 / 拦截器函数数组，多个拦截器按顺序链式执行
+   * - 拦截器返回 null / undefined 时，自动抛出原始err
+   * @param ctx 上下文
+   * @param ctx.err 捕获到的异常对象（RequestFailPayload | Error）
+   * @param ctx.invokeArgs 组装完成即将传给uni的请求参数
+   * @param ctx.options normalizeOpts合并后的完整配置
+   * @param ctx.reload 重发当前请求函数
+   * @param next 执行下一个拦截器，返回错误载荷
+   * @returns 错误载荷，返回 null/undefined 将自动兜底原始err
    */
   errInterceptor?: UserErrInterceptor;
   /**
@@ -275,6 +334,7 @@ export interface UserRequestOpts {
  * @property url - 请求完整地址
  */
 export type RuntimeHeadersCtx<T = {}> = {
+  /** 请求完整地址 */
   url: string;
 } & T;
 
@@ -287,6 +347,7 @@ export type HttpRequestConfig = Partial<Omit<UniApp.RequestOptions, 'url' | 'hea
   baseURL?: string;
   /** 库自定义：headers支持对象或者返回对象的工厂函数 */
   headers?: Record<string, string> | ((ctx: RuntimeHeadersCtx<HttpRequestConfig>) => Record<string, string>);
+  /** 自定义扩展字段 */
   [key: string]: any;
 };
 
@@ -299,6 +360,7 @@ export type UploadConfig = Partial<Omit<UniApp.UploadFileOption, 'url' | 'header
   baseURL?: string;
   /** 库自定义：headers支持对象或者返回对象的工厂函数 */
   headers?: Record<string, string> | ((ctx: RuntimeHeadersCtx<UploadConfig>) => Record<string, string>);
+  /** 自定义扩展字段 */
   [key: string]: any;
 };
 
@@ -311,6 +373,7 @@ export type DownloadConfig = Partial<Omit<UniApp.DownloadFileOption, 'url' | 'he
   baseURL?: string;
   /** 库自定义：headers支持对象或者返回对象的工厂函数 */
   headers?: Record<string, string> | ((ctx: RuntimeHeadersCtx<DownloadConfig>) => Record<string, string>);
+  /** 自定义扩展字段 */
   [key: string]: any;
 };
 
@@ -386,7 +449,9 @@ export declare function endLoading(): void;
  * 请求返回Promise扩展类型，携带取消能力
  */
 export interface RequestPromise<T> extends Promise<T> {
+  /** 取消当前请求 */
   cancel(): void;
+  /** 当前请求的取消令牌 */
   token: string;
 }
 
@@ -446,9 +511,11 @@ export declare function createUploadFile(
 ): <T = any>(
   url: string,
   params: {
+    /** 文件本地路径 */
     filePath: string;
     /** keyName 映射到 uni.uploadFile 的 name 字段（后端接收的表单字段名） */
     keyName?: string;
+    /** 额外表单参数 */
     [key: string]: any;
   },
   config?: UploadConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utils-uniapp",
-  "version": "1.1.22",
+  "version": "1.1.25",
   "description": "aubyn's utils for uniapp",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",