react-toolkits 2.31.0 → 2.31.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # react-toolkits
 
+## 2.31.1
+
+### Patch Changes
+
+- bba1a46: refactor: enhance KyClient and useKyClient for improved error handling and configuration
+
 ## 2.31.0
 
 ### Minor Changes

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import { ButtonProps, SelectProps, FormInstance, DrawerProps, Button, FormProps, ModalProps } from 'antd';
 import { FC, PropsWithChildren, Key, ReactNode, ReactElement, Ref, DetailedHTMLProps, ImgHTMLAttributes, ComponentProps } from 'react';
-import { Options, KyInstance } from 'ky';
+import { Hooks, Options, KyInstance } from 'ky';
 import { ParagraphProps } from 'antd/es/typography/Paragraph';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { useLocation, PathPattern } from 'react-router';
@@ -12,8 +12,6 @@ import { StateCreator } from 'zustand';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { StateStorage } from 'zustand/middleware';
 
-/** 成功响应状态码字段类型 */
-type StatusField = 'code' | 'status' | 'errno';
 /** 响应类型 */
 type ResponseType = 'json' | 'blob' | 'text' | 'arrayBuffer' | 'formData';
 /** 通用请求选项接口 */
@@ -22,38 +20,6 @@ interface RequestOptions extends Options {
     /** 是否使用全局模式（覆盖 context 中的 isGlobalMode） */
     isGlobalMode?: boolean;
 }
-/** 业务状态码字段配置 */
-interface BusinessStatusCodeConfig {
-    /** 成功状态码列表，默认为 [0, 1, 200] */
-    successCodes?: readonly number[];
-    /** 需要检查的业务状态码字段，默认为 ['code', 'status', 'errno'] */
-    statusFields?: readonly StatusField[];
-}
-/** 错误消息提取配置 */
-interface ErrorMessageConfig {
-    /** 错误消息字段列表（按优先级），默认为 ['msg', 'message', 'error'] */
-    errorFields?: readonly string[];
-    /** 自定义错误消息提取函数，优先级高于 errorFields */
-    extractErrorMessage?: (data: unknown) => string;
-}
-/** HTTP 状态码错误处理回调 */
-interface HttpErrorHandlers {
-    /** 401 未授权处理 */
-    onUnauthorized?: (data?: unknown) => void;
-    /** 403 禁止访问处理 */
-    onForbidden?: (data?: unknown) => void;
-    /** 412 未注册处理 */
-    onUnregistered?: (data?: unknown) => void;
-    /** 其他 HTTP 错误处理 */
-    onError?: (status: number, data?: unknown, errorMessage?: string) => void;
-    /** 网络错误处理 */
-    onNetworkError?: (error: Error) => void;
-}
-/** 响应验证配置 */
-interface ResponseValidationConfig {
-    /** 自定义响应成功判断函数，优先级高于业务状态码配置 */
-    isSuccess?: (data: unknown, status: number) => boolean;
-}
 /** React 上下文信息接口 */
 interface KyClientContext {
     token?: string;
@@ -65,13 +31,11 @@ interface KyClientContext {
     notifyError?: (title: string, description: string) => void;
 }
 /** KyClient 构造函数配置 */
-interface KyClientOptions extends BusinessStatusCodeConfig, ErrorMessageConfig, HttpErrorHandlers, ResponseValidationConfig {
+interface KyClientOptions {
     /** 基础 URL */
     baseURL?: string;
-    /** 是否禁用默认的错误提示（notification），默认为 false */
-    disableDefaultErrorNotification?: boolean;
-    /** React 上下文信息 */
-    context?: KyClientContext;
+    /** 自定义 hooks（拦截器） */
+    hooks?: Partial<Hooks>;
 }
 /** HTTP客户端方法接口 */
 interface KyMethods {
@@ -87,19 +51,42 @@ interface KyMethods {
     }) => Promise<T>;
     instance: KyInstance;
 }
+/** useKyClient 配置选项 */
+interface UseKyClientOptions {
+    /** 状态码字段配置：字段名 -> 成功码列表 */
+    statusFields?: Record<string, readonly number[]>;
+    /** 自定义响应成功判断函数 */
+    isSuccess?: (data: unknown, status: number) => boolean;
+    /** 错误消息字段列表（按优先级） */
+    errorFields?: readonly string[];
+    /** 自定义错误消息提取函数 */
+    extractErrorMessage?: (data: unknown) => string;
+    /** 401 未授权处理 */
+    onUnauthorized?: (data?: unknown) => void;
+    /** 403 禁止访问处理 */
+    onForbidden?: (data?: unknown) => void;
+    /** 412 未注册处理 */
+    onUnregistered?: (data?: unknown) => void;
+    /** 其他 HTTP 错误处理 */
+    onError?: (status: number, data?: unknown, errorMessage?: string) => void;
+    /** 网络错误处理 */
+    onNetworkError?: (error: Error) => void;
+    /** 是否禁用默认的错误提示 */
+    disableDefaultErrorNotification?: boolean;
+    /** 自定义 hooks（拦截器） */
+    hooks?: Partial<Hooks>;
+}
+/** 导出类型（向后兼容） */
+type BusinessStatusCodeConfig = Pick<UseKyClientOptions, 'statusFields'>;
+type ErrorMessageConfig = Pick<UseKyClientOptions, 'errorFields' | 'extractErrorMessage'>;
+type HttpErrorHandlers = Pick<UseKyClientOptions, 'onUnauthorized' | 'onForbidden' | 'onUnregistered' | 'onError' | 'onNetworkError'>;
+type ResponseValidationConfig = Pick<UseKyClientOptions, 'isSuccess'>;
 /**
  * Ky HTTP 客户端类
- * 封装了基于 ky 的 HTTP 请求逻辑，包括认证、错误处理、响应验证等
  */
 declare class KyClient implements KyMethods {
     private readonly _instance;
-    private readonly businessConfig;
-    private readonly errorConfig;
-    private readonly errorHandlers;
-    private context?;
-    private readonly disableDefaultErrorNotification;
     constructor(options?: KyClientOptions);
-    /** 获取 ky 实例（用于高级用法） */
     get instance(): KyInstance;
     get: <T = unknown>(url: string, options?: RequestOptions) => Promise<T>;
     post: <T = unknown>(url: string, data?: unknown, options?: RequestOptions) => Promise<T>;
@@ -111,53 +98,12 @@ declare class KyClient implements KyMethods {
     request: <T = unknown>(requestOptions: RequestOptions & {
         url: string;
     }) => Promise<T>;
-    /**
-     * 通用请求处理函数
-     */
     private makeRequest;
-    /**
-     * 创建响应处理函数
-     */
-    private createResponseHandler;
-    /**
-     * 请求前处理：设置认证和 appId headers
-     */
-    private handleBeforeRequest;
-    /**
-     * 错误前处理：处理 HTTP 状态码错误
-     */
-    private handleBeforeError;
-    /**
-     * 处理 HTTP 状态码错误
-     */
-    private handleHttpStatusError;
-    /**
-     * 默认处理未授权错误
-     */
-    private defaultHandleUnauthorized;
-    /**
-     * 默认处理未注册错误
-     */
-    private defaultHandleUnregistered;
-    /**
-     * 默认处理禁止访问错误
-     */
-    private defaultHandleForbidden;
 }
 /**
  * 在组件中使用 KyClient 的 Hook
- * 创建新的 KyClient 实例，并从 ToolkitsProvider 获取 context
- * 这样可以确保每个组件使用正确的 context（特别是 isGlobalMode）
- *
- * @example
- * import { useKyClient } from '@/libs'
- *
- * function MyComponent() {
- *   const { get, post } = useKyClient()
- *   // 使用 get, post 等方法
- * }
  */
-declare function useKyClient(): KyClient;
+declare function useKyClient(options?: UseKyClientOptions): KyClient;
 
 interface AuthButtonProps extends ButtonProps {
     /** 权限码，支持单个或多个 */