@baishuyun/ui-business 2.0.6 → 3.0.3

package/README.md

@@ -67,4 +67,191 @@ src/
 
 ## 许可证
 
-MIT
+MIT
+
+## API Service 配置指南
+
+本组件库采用依赖注入架构，**要求业务项目传入自己的 Axios 实例**。这种设计确保了：
+
+- 🔒 **统一认证体系**：组件库请求使用业务项目的认证逻辑
+- 🎯 **完全请求控制**：业务项目可以感知和控制所有请求
+- 🛡️ **统一错误处理**：所有请求使用相同的错误处理逻辑
+- 📊 **统一状态管理**：Loading 状态、请求监控等统一管理
+
+## 基本用法
+
+### 1. 创建业务 Axios 实例
+
+```typescript
+// src/api/request.ts
+import axios from 'axios';
+import { message } from 'antd';
+
+const request = axios.create({
+  baseURL: process.env.REACT_APP_API_BASE_URL,
+  timeout: 10000,
+  withCredentials: true,
+});
+
+// 请求拦截器
+request.interceptors.request.use(
+  (config) => {
+    // 添加认证 Token
+    const token = localStorage.getItem('access_token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+// 响应拦截器
+request.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    // 统一错误处理
+    if (error.response?.status === 401) {
+      message.error('登录已过期，请重新登录');
+      // 跳转到登录页
+      window.location.href = '/login';
+    } else {
+      message.error(error.response?.data?.message || '请求失败');
+    }
+    return Promise.reject(error);
+  }
+);
+
+export default request;
+```
+
+### 2. 注入到组件库
+
+```typescript
+// src/main.ts 或 src/App.tsx
+import { setApiServiceProvider } from '@baishuyun/ui-business';
+import request from './api/request';
+
+// 注入业务项目的 Axios 实例
+setApiServiceProvider({
+  axiosInstance: request,
+});
+```
+
+## 高级配置
+
+### 多环境配置
+
+```typescript
+// src/api/config.ts
+const API_CONFIG = {
+  development: {
+    baseURL: 'http://localhost:3000/api',
+    timeout: 10000,
+  },
+  production: {
+    baseURL: 'https://api.example.com',
+    timeout: 5000,
+  },
+};
+
+const config = API_CONFIG[process.env.NODE_ENV as keyof typeof API_CONFIG];
+
+const request = axios.create(config);
+```
+
+### 请求重试机制
+
+```typescript
+// 添加请求重试逻辑
+request.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const config = error.config;
+    
+    // 重试逻辑
+    if (!config._retry && error.response?.status >= 500) {
+      config._retry = true;
+      config._retryCount = (config._retryCount || 0) + 1;
+      
+      if (config._retryCount <= 3) {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        return request(config);
+      }
+    }
+    
+    return Promise.reject(error);
+  }
+);
+```
+
+### Loading 状态管理
+
+```typescript
+// src/api/loading.ts
+let loadingCount = 0;
+
+const showLoading = () => {
+  if (loadingCount === 0) {
+    // 显示全局 loading
+  }
+  loadingCount++;
+};
+
+const hideLoading = () => {
+  loadingCount--;
+  if (loadingCount === 0) {
+    // 隐藏全局 loading
+  }
+};
+
+// 在拦截器中使用
+request.interceptors.request.use((config) => {
+  showLoading();
+  return config;
+});
+
+request.interceptors.response.use(
+  (response) => {
+    hideLoading();
+    return response;
+  },
+  (error) => {
+    hideLoading();
+    return Promise.reject(error);
+  }
+);
+```
+
+## 动态配置
+
+可以在运行时动态更换 Axios 实例：
+
+```typescript
+// 切换到不同的 API 环境
+const switchToTestEnv = () => {
+  const testRequest = axios.create({
+    baseURL: 'https://test-api.example.com',
+    // 其他配置...
+  });
+  
+  setApiServiceProvider({ axiosInstance: testRequest });
+};
+```
+
+## 注意事项
+
+- ⚠️ **必须在使用组件库之前调用** `setApiServiceProvider`
+- 📍 **推荐在应用入口文件**（如 `main.ts` 或 `App.tsx`）中进行配置
+- 🔧 **Axios 实例应包含完整业务逻辑**（拦截器、错误处理、认证等）
+- 🚫 **组件库不再提供内置的 HTTP 配置**，完全依赖外部注入
+
+## 错误处理
+
+如果未设置 API 服务提供者，组件库会抛出明确的错误提示：
+
+```
+Error: API 服务提供者未设置。请先调用 setApiServiceProvider() 设置 Axios 实例。
+```
+
+确保在使用任何组件库功能之前完成配置。