@robot-admin/request-core 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,644 @@
+import * as axios from 'axios';
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosInstance } from 'axios';
+import { App, Ref, ComputedRef } from 'vue';
+
+/**
+ * 获取全局配置
+ */
+declare function getGlobalConfig(): Required<Pick<RequestCoreConfig, "successCodes" | "fieldAliases">>;
+/**
+ * 拦截器配置
+ *
+ * @description
+ * 用于配置 axios 请求和响应拦截器，处理 token 注入、业务码判断等业务逻辑
+ */
+interface InterceptorConfig {
+    /**
+     * 请求拦截器
+     * @description 在请求发送前执行，常用于注入 token、修改请求头等
+     */
+    request?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>;
+    /**
+     * 请求错误拦截器
+     * @description 请求配置阶段发生错误时执行
+     */
+    requestError?: (error: any) => any;
+    /**
+     * 响应拦截器
+     * @description 响应到达后执行，常用于统一处理业务码、数据格式等
+     */
+    response?: (response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>;
+    /**
+     * 响应错误拦截器
+     * @description 响应阶段发生错误时执行，常用于处理 401、403、500 等错误
+     */
+    responseError?: (error: any) => any;
+}
+/**
+ * 字段别名配置
+ *
+ * @description
+ * 用于自定义 API 响应的字段映射，适配不同的后端响应格式
+ */
+interface FieldAliases {
+    /**
+     * 数据层字段别名（用于提取响应中的 data 层）
+     * @default ['data', 'list', 'items', 'records']
+     * @example ['result', 'payload']
+     */
+    data?: string[];
+    /**
+     * 列表字段别名（用于提取数据层中的列表数组）
+     * @default ['list', 'items', 'records', 'rows', 'data']
+     * @example ['employees', 'users', 'products']
+     */
+    list?: string[];
+    /**
+     * 总数字段别名（用于提取数据总数）
+     * @default ['total', 'totalCount', 'count', 'totalElements']
+     * @example ['totalRecords', 'totalItems']
+     */
+    total?: string[];
+}
+/**
+ * Request Core 配置
+ *
+ * @description
+ * 用于初始化 Request Core 实例，配置 axios 和拦截器
+ */
+interface RequestCoreConfig {
+    /**
+     * Axios 基础配置
+     * @description 包括 baseURL、timeout、headers 等，参考 axios 官方文档
+     */
+    request?: AxiosRequestConfig;
+    /**
+     * 拦截器配置
+     * @description 用于处理 token 注入、业务码判断、错误提示等业务逻辑
+     */
+    interceptors?: InterceptorConfig;
+    /**
+     * 成功状态码配置
+     * @description 用于判断 API 响应的业务状态码是否成功
+     * @default [200, 0, '200', '0']
+     * @example [1, '1', 'success']
+     */
+    successCodes?: Array<number | string>;
+    /**
+     * 字段别名配置
+     * @description 用于自定义 API 响应的字段映射，适配不同的后端响应格式
+     */
+    fieldAliases?: FieldAliases;
+}
+/**
+ * 创建 Request Core 实例
+ *
+ * @description
+ * 初始化 axios 实例并注册 7 个内置插件（cache、retry、dedupe、cancel、request、response、reLogin）
+ * 返回 Vue 插件对象和 axios 实例
+ *
+ * @param config Request Core 配置
+ * @returns Vue 插件对象（包含 install 方法）和 axios 实例
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createRequestCore, onReLoginSuccess } from '@robot-admin/request-core'
+ * import { useUserStore } from '@/stores/user'
+ *
+ * const requestCore = createRequestCore({
+ *   request: {
+ *     baseURL: import.meta.env.VITE_API_BASE,
+ *     timeout: 10000,
+ *   },
+ *   interceptors: {
+ *     // 请求拦截：注入 token
+ *     request: (config) => {
+ *       const token = localStorage.getItem('token')
+ *       if (token) {
+ *         config.headers.Authorization = `Bearer ${token}`
+ *       }
+ *       return config
+ *     },
+ *     // 响应拦截：处理业务码
+ *     response: (response) => {
+ *       const { code, message } = response.data
+ *       if (code !== 200) {
+ *         window.$message?.error(message || '请求失败')
+ *         return Promise.reject(new Error(message))
+ *       }
+ *       return response
+ *     },
+ *     // 响应错误拦截：处理 401
+ *     responseError: async (error) => {
+ *       if (error.response?.status === 401) {
+ *         // 触发重新登录逻辑
+ *         const userStore = useUserStore()
+ *         await userStore.reLogin()
+ *         onReLoginSuccess() // 通知所有等待的请求继续
+ *         return Promise.reject(error)
+ *       }
+ *       return Promise.reject(error)
+ *     }
+ *   }
+ * })
+ *
+ * app.use(requestCore)
+ * ```
+ */
+declare function createRequestCore(config?: RequestCoreConfig): {
+    install(app: App): void;
+    axiosInstance: axios.AxiosInstance;
+};
+
+/**
+ * 请求去重配置
+ */
+interface DedupeConfig {
+    /** 是否启用去重（默认 true） */
+    enabled?: boolean;
+    /** 自定义请求 key 生成函数 */
+    keyGenerator?: (config: AxiosRequestConfig) => string;
+}
+/**
+ * 请求缓存配置
+ */
+interface CacheConfig {
+    /** 是否启用缓存（默认 false，只对 GET 请求有效） */
+    enabled?: boolean;
+    /** 缓存时间（毫秒，默认 5 分钟） */
+    ttl?: number;
+    /** 是否强制刷新缓存 */
+    forceUpdate?: boolean;
+}
+/**
+ * 请求重试配置
+ */
+interface RetryConfig {
+    /** 是否启用重试（默认 false） */
+    enabled?: boolean;
+    /** 重试次数（默认 3） */
+    count?: number;
+    /** 重试延迟（毫秒，默认 1000） */
+    delay?: number;
+    /** 是否使用指数退避（默认 true） */
+    exponentialBackoff?: boolean;
+    /** 可重试的 HTTP 状态码 */
+    retryableStatusCodes?: number[];
+}
+/**
+ * 路由取消配置
+ */
+interface CancelConfig {
+    /** 是否启用路由切换时自动取消（默认 true） */
+    enabled?: boolean;
+    /** 白名单：不需要取消的请求 URL 模式 */
+    whitelist?: RegExp[];
+}
+/**
+ * 扩展的 Axios 请求配置
+ */
+interface EnhancedAxiosRequestConfig extends AxiosRequestConfig {
+    /** 请求去重配置 */
+    dedupe?: boolean | DedupeConfig;
+    /** 请求缓存配置 */
+    cache?: boolean | CacheConfig;
+    /** 请求重试配置 */
+    retry?: boolean | RetryConfig;
+    /** 路由取消配置 */
+    cancel?: boolean | CancelConfig;
+    /** 内部标记：当前重试次数 */
+    __retryCount?: number;
+    /** 内部标记：取消请求 ID */
+    __cancelId?: string;
+    /** 内部标记：去重请求键 */
+    __requestKey?: string;
+    /** 内部标记：是否来自缓存 */
+    __fromCache?: boolean;
+    /** 内部标记：是否被 cancel 插件管理 */
+    __managedByCancel?: boolean;
+    /** 内部标记：是否正在处理 401 错误 */
+    __handling401?: boolean;
+}
+/**
+ * 缓存项
+ */
+interface CacheItem<T = any> {
+    /** 缓存数据 */
+    data: T;
+    /** 过期时间戳 */
+    expireAt: number;
+}
+/**
+ * 请求 key 生成器参数
+ */
+interface RequestKeyParams {
+    method?: string;
+    url?: string;
+    params?: any;
+    data?: any;
+}
+
+/**
+ * 取消所有待处理的请求
+ *
+ * 使用场景：
+ * - 用户登出时清理所有请求
+ * - 网络异常时重置请求状态
+ * - 调试和测试场景
+ *
+ * 安全机制：
+ * - 捕获每个取消操作的异常
+ * - 确保一个请求的失败不影响其他请求的取消
+ * - 完全清理 Map 中的所有引用
+ */
+declare function cancelAllPendingRequests(): void;
+/**
+ * 获取待处理请求数量
+ *
+ * @returns 当前待处理的请求数量
+ *
+ * 监控用途：
+ * - 性能监控和分析
+ * - 调试请求状态
+ * - 检测潜在的请求泄漏
+ * - 评估去重效果
+ */
+declare function getPendingRequestCount(): number;
+
+/**
+ * 清空所有缓存
+ *
+ * 用于：
+ * - 用户登出时清理敏感数据
+ * - 开发调试时重置缓存状态
+ */
+declare function clearAllCache(): void;
+/**
+ * 删除指定缓存
+ *
+ * @param config 请求配置
+ * @returns 是否删除成功
+ *
+ * 用于：
+ * - 数据更新时清理特定缓存
+ * - 缓存失效时的精确清理
+ */
+declare function clearCache(config: InternalAxiosRequestConfig): boolean;
+/**
+ * 清理过期缓存
+ *
+ * 自动清理机制：
+ * - 由 globalCache 内部实现
+ * - 基于 TTL 过期时间
+ * - 定期清理防止内存泄漏
+ */
+declare function cleanupExpiredCache(): void;
+/**
+ * 获取缓存大小
+ *
+ * @returns 当前缓存条目数量
+ *
+ * 用于：
+ * - 监控缓存使用情况
+ * - 性能分析和调试
+ */
+declare function getCacheSize(): number;
+
+/**
+ * 取消所有待处理的请求
+ *
+ * 使用场景：
+ * - 路由切换时取消当前页面的所有请求
+ * - 用户登出时清理所有请求
+ * - 网络异常时重置请求状态
+ *
+ * 安全机制：
+ * - 捕获每个取消操作的异常
+ * - 确保一个请求的失败不影响其他请求的取消
+ */
+declare function cancelAllRequests(): void;
+/**
+ * 获取待取消请求数量
+ *
+ * @returns 当前待取消的请求数量
+ *
+ * 监控用途：
+ * - 性能监控和分析
+ * - 调试请求状态
+ * - 检测潜在的请求泄漏
+ */
+declare function getCancelableRequestCount(): number;
+
+/**
+ * 创建 axios 实例
+ * @param config axios 配置
+ */
+declare function createAxiosInstance(config?: AxiosRequestConfig): AxiosInstance;
+/**
+ * GET 请求
+ * @param url 请求地址
+ * @param config 请求配置（可选），支持插件配置
+ */
+declare const getData: <T = any>(url: string, config?: EnhancedAxiosRequestConfig) => Promise<T>;
+/**
+ * POST 请求
+ * @param url 请求地址
+ * @param data 请求体数据（可选）
+ * @param config 请求配置（可选），支持插件配置
+ */
+declare const postData: <T = any>(url: string, data?: any, config?: EnhancedAxiosRequestConfig) => Promise<T>;
+/**
+ * PUT 请求
+ * @param url 请求地址
+ * @param data 请求体数据（可选）
+ * @param config 请求配置（可选），支持插件配置
+ */
+declare const putData: <T = any>(url: string, data?: any, config?: EnhancedAxiosRequestConfig) => Promise<T>;
+/**
+ * DELETE 请求
+ * @param url 请求地址
+ * @param config 请求配置（可选），支持插件配置
+ */
+declare const deleteData: <T = any>(url: string, config?: EnhancedAxiosRequestConfig) => Promise<T>;
+
+/**
+ * 重新登录成功后的回调
+ * 调用此函数会 resolve 所有等待中的请求
+ */
+declare const onReLoginSuccess: () => void;
+/**
+ * 重新登录取消后的回调
+ * 调用此函数会 reject 所有等待中的请求
+ */
+declare const onReLoginCancel: () => void;
+
+/**
+ * 数据记录基础类型
+ */
+interface DataRecord {
+    [key: string]: any;
+}
+/**
+ * 表格列配置（兼容 Naive UI DataTable）
+ */
+interface TableColumn<T = any> {
+    /** 列标题 */
+    title?: string;
+    /** 数据字段 key */
+    key?: string;
+    /** 渲染函数 */
+    render?: (row: T, index: number) => any;
+    /** 列宽度 */
+    width?: number | string;
+    /** 最小宽度 */
+    minWidth?: number | string;
+    /** 最大宽度 */
+    maxWidth?: number | string;
+    /** 固定列 */
+    fixed?: "left" | "right";
+    /** 对齐方式 */
+    align?: "left" | "center" | "right";
+    /** 省略 */
+    ellipsis?: boolean | object;
+    /** 排序 */
+    sorter?: boolean | ((a: T, b: T) => number) | string;
+    /** 过滤 */
+    filter?: boolean | ((value: string, row: T) => boolean);
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * API 端点配置
+ */
+interface ApiEndpoints {
+    /** 列表查询接口 */
+    list: string;
+    /** 详情查询接口 */
+    get?: string;
+    /** 新增接口 */
+    create?: string;
+    /** 更新接口 */
+    update?: string;
+    /** 删除接口 */
+    remove?: string;
+    /** 批量删除接口 */
+    batchRemove?: string;
+}
+/**
+ * 操作上下文（传递给自定义操作处理函数）
+ */
+interface ActionContext<T> {
+    /** 表格数据数组 */
+    data: T[];
+    /** 当前行索引 */
+    index: number;
+    /** 分页信息 */
+    page: {
+        current: number;
+        size: number;
+    };
+    /** 分页是否启用 */
+    paginationEnabled: boolean;
+    /** 消息通知实例 */
+    message: any;
+    /** 对话框实例 */
+    dialog: any;
+    /** 刷新数据 */
+    refresh: () => Promise<void>;
+}
+/**
+ * 自定义操作按钮配置
+ */
+interface CustomAction<T> {
+    /** 操作唯一标识 */
+    key: string;
+    /** 按钮文本 */
+    label: string;
+    /** 图标名称 */
+    icon: string;
+    /** 按钮类型 */
+    type?: "default" | "primary" | "info" | "success" | "warning" | "error";
+    /** 操作处理函数 */
+    handler: (row: T, context: ActionContext<T>) => void | Promise<void>;
+}
+/**
+ * 详情项配置
+ */
+interface DetailItem {
+    /** 字段标签 */
+    label: string;
+    /** 数据字段名 */
+    key: string;
+    /** 显示类型 */
+    type?: string;
+    /** 占据列数 */
+    span?: number;
+    /** 值格式化函数 */
+    formatter?: (val: any) => string;
+    /** 标签类型 */
+    tagType?: string;
+    [key: string]: any;
+}
+/**
+ * 详情分组配置
+ */
+interface DetailSection {
+    /** 分组标题 */
+    title: string;
+    /** 列数 */
+    columns: number;
+    /** 字段列表 */
+    items: DetailItem[];
+}
+/**
+ * 详情配置
+ */
+interface DetailConfig {
+    /** 详情分组 */
+    sections: DetailSection[];
+}
+/**
+ * useTableCrud 配置选项
+ */
+interface UseTableCrudConfig<T extends DataRecord> {
+    /** API 端点配置 */
+    api: ApiEndpoints;
+    /** 表格列配置 */
+    columns: TableColumn<T>[];
+    /** 自定义操作按钮 */
+    customActions?: CustomAction<T>[];
+    /** 详情弹窗配置 */
+    detail?: DetailConfig;
+    /** ID 字段名，默认 'id' */
+    idKey?: keyof T;
+    /** 默认分页大小，默认 10 */
+    defaultPageSize?: number;
+    /** 是否默认启用分页，默认 true */
+    defaultPaginationEnabled?: boolean;
+    /** 创建新行的工厂函数 */
+    createNewRow?: () => T;
+    /** 列表数据提取函数（处理不同响应格式） */
+    extractListData?: (response: any) => {
+        items: T[];
+        total: number;
+    };
+    /** 是否自动加载数据，默认 true */
+    autoLoad?: boolean;
+}
+/**
+ * 详情弹窗状态
+ */
+interface DetailModal<T> {
+    /** 弹窗可见性 */
+    visible: Ref<boolean>;
+    /** 详情数据 */
+    data: Ref<T | null>;
+    /** 弹窗标题 */
+    title: Ref<string>;
+    /** 显示详情 */
+    show: (row: T) => void;
+    /** 关闭详情 */
+    close: () => void;
+}
+/**
+ * useTableCrud 返回类型
+ */
+interface UseTableCrudReturn<T extends DataRecord> {
+    /** 表格数据 */
+    data: Ref<T[]>;
+    /** 加载状态 */
+    loading: Ref<boolean>;
+    /** 数据总数 */
+    total: Ref<number>;
+    /** 表格列配置 */
+    columns: ComputedRef<TableColumn<T>[]>;
+    /** 操作按钮配置 */
+    actions: ComputedRef<any>;
+    /** 表格引用 */
+    tableRef: Ref<any>;
+    /** 分页状态 */
+    page: {
+        current: number;
+        size: number;
+    };
+    /** 分页启用状态 */
+    paginationEnabled: Ref<boolean>;
+    /** 分页配置（供组件使用） */
+    pagination: ComputedRef<false | {
+        enabled: boolean;
+        page: number;
+        pageSize: number;
+    }>;
+    /** 刷新数据 */
+    refresh: () => Promise<void>;
+    /** 新增数据 */
+    create: (row: T) => Promise<void>;
+    /** 更新数据 */
+    save: (row: T) => Promise<void>;
+    /** 删除数据 */
+    remove: (row: T) => Promise<void>;
+    /** 批量删除数据 */
+    batchRemove: (rows: T[]) => Promise<void>;
+    /** 获取详情 */
+    getDetail: (row: T) => Promise<T | null>;
+    /** 处理取消编辑 */
+    handleCancel: () => Promise<void>;
+    /** 处理分页变化 */
+    handlePaginationChange: (pageNum: number, pageSize: number) => void;
+    /** 处理行删除（UI层） */
+    handleRowDelete: (row: T, index: number) => void;
+    /** 详情弹窗状态 */
+    detail: DetailModal<T>;
+    /** 详情配置 */
+    detailConfig?: DetailConfig;
+}
+
+/**
+ * 表格 CRUD 组合式 API
+ *
+ * @description
+ * 配置驱动的表格 CRUD 解决方案，极简使用，功能完整
+ * 完全替代 usePageCrud，专注于表格场景
+ *
+ * @template T 数据行类型
+ * @param config 配置对象
+ * @returns 表格 CRUD 实例
+ *
+ * @example
+ * ```ts
+ * const table = useTableCrud<Employee>({
+ *   api: {
+ *     list: '/employees/list',
+ *     get: '/employees/:id',
+ *     update: '/employees/:id',
+ *     remove: '/employees/:id',
+ *     create: '/employees'
+ *   },
+ *   columns: [...],
+ *   customActions: [
+ *     {
+ *       key: 'copy',
+ *       label: '复制',
+ *       icon: 'mdi:content-copy',
+ *       handler: (row, ctx) => {
+ *         const newRow = { ...row, id: Date.now() }
+ *         ctx.data.unshift(newRow)
+ *         ctx.message.success('复制成功')
+ *       }
+ *     }
+ *   ]
+ * })
+ *
+ * // 组件中使用
+ * <c-table
+ *   v-model:data="table.data.value"
+ *   :columns="table.columns.value"
+ *   :actions="table.actions.value"
+ *   @save="table.save"
+ * />
+ * ```
+ */
+declare function useTableCrud<T extends DataRecord>(config: UseTableCrudConfig<T>): UseTableCrudReturn<T>;
+
+export { type ActionContext, type ApiEndpoints, type CacheConfig, type CacheItem, type CancelConfig, type CustomAction, type DataRecord, type DedupeConfig, type DetailConfig, type DetailItem, type DetailModal, type DetailSection, type EnhancedAxiosRequestConfig, type FieldAliases, type InterceptorConfig, type RequestCoreConfig, type RequestKeyParams, type RetryConfig, type TableColumn, type UseTableCrudConfig, type UseTableCrudReturn, cancelAllPendingRequests, cancelAllRequests, cleanupExpiredCache, clearAllCache, clearCache, createAxiosInstance, createRequestCore, deleteData, getCacheSize, getCancelableRequestCount, getData, getGlobalConfig, getPendingRequestCount, onReLoginCancel, onReLoginSuccess, postData, putData, useTableCrud };