@robot-admin/request-core 0.1.2 → 0.1.3

package/README.md

@@ -1,426 +1,412 @@
 # @robot-admin/request-core
 
-> 统一请求核心库：Axios 封装（7 个插件）+ useTableCrud Composable
+> 为 Vue 3 打造的企业级请求解决方案：Axios 增强 + 7 大插件 + CRUD Composable
 
 [![npm version](https://img.shields.io/npm/v/@robot-admin/request-core.svg)](https://www.npmjs.com/package/@robot-admin/request-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-**[English](#english) | [中文文档](#中文文档)**
-
 ---
 
-## 中文文档
-
-### ✨ 核心功能
-
-#### 1. Axios 封装（7 个内置插件）
+## ✨ 核心特性
 
-- **cache**: 请求缓存（内存缓存，支持 TTL）
-- **retry**: 请求重试（指数退避）
-- **dedupe**: 请求去重（基于 AbortController）
-- **cancel**: 自动取消（路由切换时）
-- **request**: 通用请求逻辑（reLogin 管理）
-- **response**: 通用响应逻辑（预留）
-- **reLogin**: 重新登录管理（Promise 队列）
+- 🚀 **开箱即用**：3 步接入，5 分钟实现完整 CRUD
+- 🔌 **7 大插件**：缓存、重试、去重、取消、reLogin 等开箱即用
+- 📊 **useTableCrud**：配置式表格 CRUD，自动处理分页/搜索/增删改查
+- 🎯 **智能适配**：自动兼容不同后端响应格式（字段名、成功码）
+- 💪 **类型安全**：完整 TypeScript 支持
+- 🎨 **Naive UI 集成**：深度集成 Naive UI 组件
 
-#### 2. useTableCrud Composable
-
-- 配置驱动的表格 CRUD 解决方案
-- 支持分页、搜索、排序、自定义操作
-- 内置详情查看、编辑、删除等功能
+---
 
-### 📦 安装
+## 📦 安装
 
 ```bash
 npm install @robot-admin/request-core
 # 或
 bun add @robot-admin/request-core
-# 或
-pnpm add @robot-admin/request-core
 ```
 
-### 🚀 快速开始
+**Peer Dependencies**: `vue@^3.4.0`, `naive-ui@^2.38.0`
 
-#### 1. 初始化 Request Core
+---
 
-```ts
-// main.ts
-import { createApp } from "vue";
-import { createRequestCore, onReLoginSuccess } from "@robot-admin/request-core";
-import { useUserStore } from "@/stores/user";
+## 🚀 30 秒快速上手
 
-const app = createApp(App);
+### 1️⃣ 初始化（main.ts）
 
-const requestCore = createRequestCore({
-  request: {
-    baseURL: import.meta.env.VITE_API_BASE,
-    timeout: 10000,
-  },
-
-  // 🎯 配置成功状态码（适配不同后端约定）
-  // 默认: [200, 0, '200', '0']
-  // successCodes: [1, '1', 'success'],  // 示例：自定义成功码
+```ts
+import { createApp } from 'vue'
+import { createRequestCore } from '@robot-admin/request-core'
 
-  // 🎯 配置字段别名（适配不同后端响应格式）
-  // fieldAliases: {
-  //   data: ['data', 'result', 'payload'],      // 数据层字段
-  //   list: ['list', 'items', 'records'],       // 列表字段
-  //   total: ['total', 'totalCount', 'count'],  // 总数字段
-  // },
+const app = createApp(App)
 
+app.use(createRequestCore({
+  request: { baseURL: '/api', 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);
-    },
-  },
-});
+      config.headers.Authorization = `Bearer ${localStorage.getItem('token')}`
+      return config
+    }
+  }
+}))
+```
 
-app.use(requestCore);
+### 2️⃣ 使用 CRUD（任意组件）
+
+```vue
+<script setup lang="ts">
+import { useTableCrud } from '@robot-admin/request-core'
+
+const table = useTableCrud({
+  api: { list: '/users', get: '/users/:id', create: '/users', update: '/users/:id', remove: '/users/:id' },
+  columns: [
+    { key: 'id', title: 'ID' },
+    { key: 'name', title: '姓名' },
+    { key: 'email', title: '邮箱' }
+  ]
+})
+</script>
+
+<template>
+  <n-data-table :data="table.data.value" :columns="table.columns.value" :loading="table.loading.value" />
+</template>
 ```
 
-#### 🎯 高级配置：适配不同的后端接口
+✅ **完成！** 一个完整的带分页、搜索、编辑、删除的数据表格！
 
-##### 场景 1：后端返回的成功码不是 `0` 或 `200`
+---
 
-如果你的后端 API 返回的成功码是 `1`、`'success'` 或其他值，可以通过 `successCodes` 配置：
+## 📚 核心 API
+
+### 请求方法
+
+| 方法 | 说明 | 示例 |
+|------|------|------|
+| `getData(url, config?)` | GET 请求 | `getData('/users')` |
+| `postData(url, data, config?)` | POST 请求 | `postData('/users', { name: '张三' })` |
+| `putData(url, data, config?)` | PUT 请求 | `putData('/users/1', { name: '李四' })` |
+| `deleteData(url, config?)` | DELETE 请求 | `deleteData('/users/1')` |
+
+### useTableCrud 配置
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `api.list` | `string` | ✅ | 列表接口 |
+| `api.get` | `string` | - | 详情接口（支持 `:id`） |
+| `api.create` | `string` | - | 创建接口 |
+| `api.update` | `string` | - | 更新接口（支持 `:id`） |
+| `api.remove` | `string` | - | 删除接口（支持 `:id`） |
+| `columns` | `TableColumn[]` | ✅ | 表格列配置 |
+| `customActions` | `CustomAction[]` | - | 自定义操作按钮 |
+| `idKey` | `string` | - | ID 字段名（默认 `'id'`） |
+| `defaultPageSize` | `number` | - | 每页条数（默认 `10`） |
+| `autoLoad` | `boolean` | - | 自动加载（默认 `true`） |
+
+### useTableCrud 返回值
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `data` | `Ref<T[]>` | 表格数据 |
+| `loading` | `Ref<boolean>` | 加载状态 |
+| `total` | `Ref<number>` | 总条数 |
+| `pagination` | `object` | 分页配置（Naive UI 格式） |
+| `columns` | `Ref<DataTableColumn[]>` | 表格列（含操作列） |
+| `search()` | `() => Promise<void>` | 搜索 |
+| `resetSearch()` | `() => void` | 重置搜索 |
+| `refresh()` | `() => Promise<void>` | 刷新数据 |
+| `viewDetail(row)` | `(row: T) => void` | 查看详情 |
+| `handleEdit(row)` | `(row: T) => void` | 编辑 |
+| `handleDelete(row)` | `(row: T) => void` | 删除 |
 
-```ts
-const requestCore = createRequestCore({
-  request: { baseURL: "/api" },
+---
 
-  // 配置成功状态码
-  successCodes: [1, "1", "success"], // 支持数字和字符串
+## 🔌 插件系统
 
-  interceptors: {
-    response: (response) => {
-      const { code, message } = response.data;
-      // 自动判断 code 是否在 successCodes 中
-      if (![1, "1", "success"].includes(code)) {
-        window.$message?.error(message || "请求失败");
-        return Promise.reject(new Error(message));
-      }
-      return response;
-    },
-  },
-});
+所有请求方法都支持插件配置：
+
+### 缓存插件（仅 GET）
+
+```ts
+getData('/users', {
+  cache: { 
+    enabled: true,      // 启用缓存
+    ttl: 300000,       // 5 分钟过期
+    forceUpdate: false // 不强制更新
+  }
+})
 ```
 
-##### 场景 2：后端返回的字段名不标准
+### 重试插件
+
+```ts
+postData('/submit', data, {
+  retry: {
+    enabled: true,          // 启用重试
+    count: 3,               // 最多重试 3 次
+    delay: 1000,            // 重试延迟 1 秒
+    exponentialBackoff: true // 指数退避（1s, 2s, 4s）
+  }
+})
+```
 
-如果你的后端 API 返回的字段名不是 `list`、`total`，可以通过 `fieldAliases` 配置：
+### 去重插件
 
 ```ts
-// 示例：后端返回格式
-// {
-//   code: 0,
-//   result: {
-//     employees: [...],      // 列表字段叫 employees
-//     totalRecords: 100      // 总数字段叫 totalRecords
-//   }
-// }
-
-const requestCore = createRequestCore({
-  request: { baseURL: "/api" },
-
-  // 配置字段别名
-  fieldAliases: {
-    data: ["result", "data", "payload"],          // 数据层字段（按优先级）
-    list: ["employees", "items", "list"],         // 列表字段（按优先级）
-    total: ["totalRecords", "total", "count"],    // 总数字段（按优先级）
-  },
+getData('/users', {
+  dedupe: { 
+    enabled: true,  // 启用去重（默认启用）
+    keyGenerator: (config) => `${config.method}-${config.url}` // 自定义去重 key
+  }
+})
+```
 
-  interceptors: { /* ... */ },
-});
+### 取消插件
 
-// 现在 useTableCrud 会自动识别这些字段，无需手动配置 extractListData！
-const table = useTableCrud({
-  api: { list: "/employees/list" },  // ✅ 自动适配
-  columns: [...],
-});
+```ts
+getData('/users', {
+  cancel: { 
+    enabled: true,  // 启用自动取消（路由切换时）
+    whitelist: []   // 白名单接口（不取消）
+  }
+})
 ```
 
-##### 场景 3：单个接口特殊格式（临时覆盖）
+### reLogin 插件
 
-如果只是某个特殊接口格式不同，可以在配置中单独处理：
+自动管理重新登录场景，多个请求等待登录完成后自动重试：
 
 ```ts
-const table = useTableCrud({
-  api: { list: "/special/api" },
-  columns: [...],
-
-  // 针对特殊接口的自定义提取逻辑
-  extractListData: (response: any) => {
-    return {
-      items: response.result?.specialList || [],
-      total: response.result?.specialCount || 0,
-    };
-  },
-});
+import { onReLoginSuccess } from '@robot-admin/request-core'
+
+// 在登录成功后调用
+onReLoginSuccess()  // 通知所有等待的请求继续
 ```
 
-#### 2. 使用 useTableCrud
+---
+
+## 🎯 完整示例
+
+### 场景 1：完整的数据表格（分页 + 搜索 + CRUD）
 
 ```vue
 <script setup lang="ts">
-import { useTableCrud } from "@robot-admin/request-core";
+import { useTableCrud } from '@robot-admin/request-core'
 
-interface Employee {
-  id: number;
-  name: string;
-  age: number;
-  department: string;
+interface User {
+  id: number
+  name: string
+  email: string
+  role: string
 }
 
-const table = useTableCrud<Employee>({
+const table = useTableCrud<User>({
   api: {
-    list: "/api/employees/list",
-    get: "/api/employees/:id",
-    update: "/api/employees/:id",
-    remove: "/api/employees/:id",
-    create: "/api/employees",
+    list: '/api/users/list',
+    get: '/api/users/:id',
+    create: '/api/users',
+    update: '/api/users/:id',
+    remove: '/api/users/:id'
   },
   columns: [
-    { key: "id", title: "ID", width: 80 },
-    { key: "name", title: "姓名", width: 120 },
-    { key: "age", title: "年龄", width: 80 },
-    { key: "department", title: "部门", width: 150 },
+    { key: 'id', title: 'ID', width: 80 },
+    { key: 'name', title: '姓名', width: 120 },
+    { key: 'email', title: '邮箱', width: 200 },
+    { key: 'role', title: '角色', width: 100 }
   ],
   customActions: [
     {
-      key: "export",
-      label: "导出",
-      icon: "mdi:download",
-      handler: (row, ctx) => {
-        console.log("导出", row);
-        ctx.message.success("导出成功");
-      },
-    },
-  ],
-});
+      key: 'resetPassword',
+      label: '重置密码',
+      icon: 'mdi:lock-reset',
+      handler: async (row, ctx) => {
+        await postData(`/api/users/${row.id}/reset-password`, {})
+        ctx.message.success('密码已重置')
+      }
+    }
+  ]
+})
 </script>
 
 <template>
-  <div>
+  <n-space vertical>
     <!-- 搜索栏 -->
     <n-space>
-      <n-input
-        v-model:value="table.searchKeyword.value"
-        placeholder="搜索..."
-      />
-      <n-button @click="table.search()">搜索</n-button>
+      <n-input v-model:value="table.searchKeyword.value" placeholder="搜索用户..." />
+      <n-button type="primary" @click="table.search()">搜索</n-button>
       <n-button @click="table.resetSearch()">重置</n-button>
+      <n-button type="success" @click="table.handleCreate()">新增用户</n-button>
     </n-space>
 
     <!-- 表格 -->
     <n-data-table
-      ref="table.tableRef.value"
       :data="table.data.value"
       :columns="table.columns.value"
       :loading="table.loading.value"
       :pagination="table.pagination"
     />
-  </div>
+  </n-space>
 </template>
 ```
 
-#### 3. 使用插件配置
+### 场景 2：自定义请求（带插件）
 
 ```ts
-import { getData, postData } from "@robot-admin/request-core";
-
-// 1. 开启缓存（5 分钟）
-const users = await getData("/api/users", {
-  cache: { enabled: true, ttl: 300000 },
-});
-
-// 2. 开启重试（3 次，指数退避）
-const data = await postData(
-  "/api/submit",
-  { name: "张三" },
-  {
-    retry: { enabled: true, count: 3, exponentialBackoff: true },
-  },
-);
+import { getData, postData } from '@robot-admin/request-core'
 
-// 3. 禁用去重
-const data = await getData("/api/timestamp", {
-  dedupe: { enabled: false },
-});
+// 带缓存的 GET 请求
+const users = await getData('/api/users', {
+  cache: { enabled: true, ttl: 300000 }  // 缓存 5 分钟
+})
 
-// 4. 白名单（不自动取消）
-const data = await getData("/api/important", {
-  cancel: { enabled: false },
-});
+// 带重试的 POST 请求
+const result = await postData('/api/submit', { data: 'test' }, {
+  retry: { enabled: true, count: 3 }
+})
 ```
 
-### 📖 API 文档
-
-#### createRequestCore(config)
-
-创建 Request Core 实例。
-
-**参数:**
-
-- `config.request` - Axios 基础配置（baseURL, timeout, headers 等）
-- `config.successCodes` - 成功状态码配置（默认: `[200, 0, '200', '0']`）
-- `config.fieldAliases` - 字段别名配置（用于适配不同的后端响应格式）
-  - `data` - 数据层字段别名（默认: `['data', 'list', 'items', 'records']`）
-  - `list` - 列表字段别名（默认: `['list', 'items', 'records', 'rows', 'data']`）
-  - `total` - 总数字段别名（默认: `['total', 'totalCount', 'count', 'totalElements']`）
-- `config.interceptors` - 拦截器配置
-  - `request` - 请求拦截器
-  - `requestError` - 请求错误拦截器
-  - `response` - 响应拦截器
-  - `responseError` - 响应错误拦截器
-
-**返回:**
-
-- `install(app)` - Vue 插件安装方法
-- `axiosInstance` - Axios 实例
-
-#### useTableCrud\<T\>(config)
-
-创建表格 CRUD 实例。
-
-**参数:**
-
-- `api` - API 端点配置（list, get, create, update, remove）
-- `columns` - 表格列配置
-- `customActions` - 自定义操作按钮
-- `idKey` - ID 字段名（默认 'id'）
-- `defaultPageSize` - 默认分页大小（默认 10）
-- `autoLoad` - 是否自动加载（默认 true）
-
-**返回对象包含:**
-
-- `data` - 表格数据
-- `loading` - 加载状态
-- `total` - 总数
-- `pagination` - 分页配置
-- `search()` - 搜索方法
-- `resetSearch()` - 重置搜索
-- `refresh()` - 刷新数据
-- `viewDetail(row)` - 查看详情
-- `handleEdit(row)` - 编辑
-- `handleDelete(row)` - 删除
+---
 
-### 🔌 插件配置
+## ⚙️ 高级配置
 
-所有请求方法（`getData`, `postData`, `putData`, `deleteData`）都支持以下插件配置：
+### 适配不同后端响应格式
 
-| 插件       | 配置项                                            | 说明               |
-| ---------- | ------------------------------------------------- | ------------------ |
-| **cache**  | `enabled`, `ttl`, `forceUpdate`                   | 请求缓存（仅 GET） |
-| **retry**  | `enabled`, `count`, `delay`, `exponentialBackoff` | 请求重试           |
-| **dedupe** | `enabled`, `keyGenerator`                         | 请求去重           |
-| **cancel** | `enabled`, `whitelist`                            | 自动取消           |
+#### 1. 自定义成功状态码
 
-### 📝 类型导出
+如果后端返回的成功码不是 `0` 或 `200`：
 
 ```ts
-// 核心类型
-export type {
-  RequestCoreConfig,
-  InterceptorConfig,
-  EnhancedAxiosRequestConfig,
-
-  // CRUD 类型
-  UseTableCrudConfig,
-  UseTableCrudReturn,
-  DataRecord,
-  ApiEndpoints,
-  TableColumn,
-  CustomAction,
-  DetailConfig,
-
-  // 插件类型
-  CacheConfig,
-  RetryConfig,
-  DedupeConfig,
-  CancelConfig,
-};
+createRequestCore({
+  request: { baseURL: '/api' },
+  successCodes: [1, '1', 'success'],  // 自定义成功码
+  interceptors: {
+    response: (response) => {
+      const { code } = response.data
+      if (![1, '1', 'success'].includes(code)) {
+        throw new Error(response.data.message)
+      }
+      return response
+    }
+  }
+})
 ```
 
-### 🛠️ 开发
+#### 2. 自定义字段名映射
 
-```bash
-# 安装依赖
-bun install
+如果后端返回的字段名不标准（如 `items` 而非 `list`）：
 
-# 开发模式（watch）
-bun run dev
+```ts
+createRequestCore({
+  request: { baseURL: '/api' },
+  fieldAliases: {
+    data: ['result', 'data'],           // 数据层字段
+    list: ['items', 'records', 'list'], // 列表字段
+    total: ['totalCount', 'total']      // 总数字段
+  }
+})
+```
 
-# 构建
-bun run build
+#### 3. 单个接口特殊处理
 
-# 类型检查
-bun run type-check
+```ts
+useTableCrud({
+  api: { list: '/special/api' },
+  extractListData: (response) => ({
+    items: response.result?.data || [],
+    total: response.result?.count || 0
+  })
+})
 ```
 
-### 📄 License
+---
 
-MIT © [ChenYu](mailto:ycyplus@gmail.com)
+## 💡 最佳实践
+
+### ✅ 推荐做法
+
+1. **统一初始化配置**
+   ```ts
+   // src/plugins/request-core.ts
+   export function setupRequestCore(app: App) {
+     app.use(createRequestCore({ /* 统一配置 */ }))
+   }
+   ```
+
+2. **使用 composable 封装业务逻辑**
+   ```ts
+   // composables/useUsers.ts
+   export function useUsers() {
+     return useTableCrud<User>({
+       api: { /* ... */ },
+       columns: [ /* ... */ ]
+     })
+   }
+   ```
+
+3. **开启缓存减少重复请求**
+   ```ts
+   getData('/api/config', { cache: { enabled: true, ttl: 600000 } })
+   ```
+
+4. **重要接口启用重试**
+   ```ts
+   postData('/api/payment', data, { retry: { enabled: true, count: 3 } })
+   ```
+
+### ❌ 避免的做法
+
+1. ❌ 不要在每个组件中重复配置 axios
+2. ❌ 不要禁用去重插件（除非有特殊需求）
+3. ❌ 不要在 useTableCrud 外部调用其内部方法
 
 ---
 
-## English
+## 📖 完整类型定义
 
-### ✨ Features
+```ts
+// 核心配置
+export type RequestCoreConfig = {
+  request: AxiosRequestConfig          // Axios 基础配置
+  successCodes?: (string | number)[]   // 成功状态码
+  fieldAliases?: FieldAliases          // 字段映射
+  interceptors?: InterceptorConfig     // 拦截器
+}
 
-#### 1. Axios with 7 Built-in Plugins
+// CRUD 配置
+export type UseTableCrudConfig<T> = {
+  api: ApiEndpoints                    // API 端点
+  columns: TableColumn[]               // 表格列
+  customActions?: CustomAction[]       // 自定义操作
+  idKey?: string                       // ID 字段名
+  defaultPageSize?: number             // 默认分页大小
+  autoLoad?: boolean                   // 是否自动加载
+  extractListData?: (res: any) => { items: T[]; total: number }
+}
 
-- **cache**: Request caching (in-memory with TTL support)
-- **retry**: Request retry (exponential backoff)
-- **dedupe**: Request deduplication (AbortController-based)
-- **cancel**: Auto-cancel on route change
-- **request**: Common request logic (reLogin management)
-- **response**: Common response logic (reserved for user config)
-- **reLogin**: Re-login management (Promise queue)
+// 插件配置
+export type EnhancedAxiosRequestConfig = AxiosRequestConfig & {
+  cache?: CacheConfig                  // 缓存配置
+  retry?: RetryConfig                  // 重试配置
+  dedupe?: DedupeConfig                // 去重配置
+  cancel?: CancelConfig                // 取消配置
+}
+```
 
-#### 2. useTableCrud Composable
+查看完整类型定义：[src/index.ts](./src/index.ts)
 
-- Configuration-driven table CRUD solution
-- Supports pagination, search, sort, custom actions
-- Built-in detail view, edit, delete features
+---
 
-### 📦 Installation
+## 🛠️ 开发
 
 ```bash
-npm install @robot-admin/request-core
+bun install       # 安装依赖
+bun run dev       # 开发模式（watch）
+bun run build     # 构建
+bun run type-check # 类型检查
 ```
 
-### 🚀 Quick Start
-
-See Chinese documentation above for detailed usage examples.
-
-### 📝 Type Exports
+---
 
-All TypeScript types are fully exported. See the types section in Chinese docs.
+## 📄 License
 
-### 📄 License
+MIT © [ChenYu](https://github.com/ChenyCHENYU)
 
-MIT © [ChenYu](mailto:ycyplus@gmail.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robot-admin/request-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Axios + 7 plugins + CRUD composables for Vue 3",
   "type": "module",
   "keywords": [