@baishuyun/ui-business

说明

@baishuyun/ui-business 是业务组件库，相比基础组件库, 其组件设计可以更符合业务场景的需求，同时也依赖了基础组件库实现业务功能。

业务组件库的组件设计原则：

• 组件库可能会和接口请求进行耦合，为了快速创建业务功能
• 组件库的组件设计不考虑组件的通用型，而是考虑组件的业务场景，组件的业务场景局限某个特定的业务场景，而不是通用型的组件。

安装

pnpm add @baishuyun/ui-business

使用

import { DeptsMemberSelector } from '@baishuyun/ui-business';

function App() {
  return (
    <div>
      <DeptsMemberSelector />
    </div>
  );
}

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

目录结构

src/
├── components/     # 业务组件
├── hooks/         # 自定义 hooks
├── utils/         # 工具函数
├── types/         # 类型定义
├── styles/        # 样式文件
└── index.ts       # 主入口文件

依赖

• React >= 18.0.0
• @baishuyun/ui-base (基础组件库)

许可证

MIT

API Service 配置指南

本组件库采用依赖注入架构，要求业务项目传入自己的 Axios 实例。这种设计确保了：

• 🔒 统一认证体系：组件库请求使用业务项目的认证逻辑
• 🎯 完全请求控制：业务项目可以感知和控制所有请求
• 🛡️ 统一错误处理：所有请求使用相同的错误处理逻辑
• 📊 统一状态管理：Loading 状态、请求监控等统一管理

基本用法

1. 创建业务 Axios 实例

// 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. 注入到组件库

// src/main.ts 或 src/App.tsx
import { setApiServiceProvider } from '@baishuyun/ui-business';
import request from './api/request';

// 注入业务项目的 Axios 实例
setApiServiceProvider({
  axiosInstance: request,
});

高级配置

多环境配置

// 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);

请求重试机制

// 添加请求重试逻辑
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 状态管理

// 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 实例：

// 切换到不同的 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 实例。

确保在使用任何组件库功能之前完成配置。