# API 调用模式和通用实现指南

## 核心 API 架构

### ApiClient 核心类

**位置**：`src/services/api.ts`

```typescript
class ApiClient {
  private instance: any;
  private isRefreshing = false;
  private failedQueue: Array<{
    resolve: (value: any) => void;
    reject: (reason: any) => void;
  }> = [];

  // 特性：
  // 1. 自动附加 Authorization 头
  // 2. 401 错误时自动刷新 token
  // 3. Token 刷新期间的请求入队
  // 4. 自动处理 token 过期和重新登录
}

export const apiClient = new ApiClient();
```

---

## API 服务层设计模式

### 模式 1：列表 API（用户等级配置）

**文件**：`src/services/userLevelConfigApi.ts`

```typescript
import { apiClient } from './api';
import type { UserLevelConfig, UserLevelConfigListRequest, UserLevelConfigListResponse } from '../types/userLevelConfig';

// 模式：响应数据提取
// - apiClient 返回完整响应对象
// - 最后一层 API 函数负责提取数据或返回完整响应

export const getUserLevelConfigList = async (
  params: UserLevelConfigListRequest
): Promise<UserLevelConfigListResponse> => {
  const response = await apiClient.get('/admin/user-level-configs', { params });
  return response.data;  // 返回响应数据部分
};

export const getAllUserLevelConfigs = async (): Promise<UserLevelConfig[]> => {
  const response = await apiClient.get('/admin/user-level-configs/all');
  return response.data;
};
```

### 模式 2：列表 API（系统配置）

**文件**：`src/services/systemConfigApi.ts`

```typescript
import { apiClient } from './api';
import type { SystemConfig, SystemConfigListRequest, SystemConfigListResponse } from '../types/systemConfig';

// 注意：不同的 API 可能返回不同的数据结构
// 系统配置返回完整响应对象（包含 code, message, data）

export const getSystemConfigList = async (
  params: SystemConfigListRequest
): Promise<SystemConfigListResponse> => {
  const response = await apiClient.get('/admin/system-configs', { params });
  return response;  // 返回完整响应对象
};
```

### 模式 3：CRUD 操作

```typescript
// 创建
export const createUserLevelConfig = async (
  data: UserLevelConfigCreateRequest
): Promise<UserLevelConfig> => {
  const response = await apiClient.post('/admin/user-level-configs', data);
  return response.data;
};

// 读取
export const getUserLevelConfigById = async (id: number): Promise<UserLevelConfig> => {
  const response = await apiClient.get(`/admin/user-level-configs/${id}`);
  return response.data;
};

// 更新
export const updateUserLevelConfig = async (
  id: number,
  data: UserLevelConfigUpdateRequest
): Promise<UserLevelConfig> => {
  const response = await apiClient.put(`/admin/user-level-configs/${id}`, data);
  return response.data;
};

// 删除
export const deleteUserLevelConfig = async (id: number): Promise<void> => {
  await apiClient.delete(`/admin/user-level-configs/${id}`);
};

// 特殊操作：状态更新
export const updateUserLevelConfigStatus = async (
  id: number,
  data: UserLevelConfigStatusRequest
): Promise<void> => {
  await apiClient.put(`/admin/user-level-configs/${id}/status`, data);
};
```

---

## 类型定义模式

### 完整类型定义示例

**文件**：`src/types/userLevelConfig.ts`

```typescript
// 1. 主体数据类型
export interface UserLevelConfig {
  id: number;
  level_name: string;
  level_code: string;
  project_limit: number;
  description: string;
  sort_order: number;
  status: number;  // 1=启用, 0=禁用
  created_at: string;
  updated_at: string;
}

// 2. 请求类型
export interface UserLevelConfigListRequest {
  level_name?: string;
  status?: number;
  page?: number;
  size?: number;
}

export interface UserLevelConfigCreateRequest {
  level_name: string;
  level_code: string;
  project_limit: number;
  description?: string;
  sort_order?: number;
}

export interface UserLevelConfigUpdateRequest {
  level_name: string;
  project_limit: number;
  description?: string;
  sort_order?: number;
}

export interface UserLevelConfigStatusRequest {
  status: number;
}

// 3. 响应类型
export interface UserLevelConfigListResponse {
  data: UserLevelConfig[];
  total: number;
  page: number;
  size: number;
}
```

---

## 页面组件实现模式

### CRUD 页面的标准结构

**文件**：`src/pages/UserLevelConfigs.tsx`

```typescript
import React, { useEffect, useState } from 'react';
import { Table, Button, Modal, Form, Input, message } from 'antd';
import type { UserLevelConfig } from '../types/userLevelConfig';
import { getUserLevelConfigList, createUserLevelConfig, updateUserLevelConfig, deleteUserLevelConfig } from '../services/userLevelConfigApi';

export default function UserLevelConfigs() {
  // ==================== 状态管理 ====================
  const [loading, setLoading] = useState(false);
  const [list, setList] = useState<UserLevelConfig[]>([]);
  const [total, setTotal] = useState(0);
  const [page, setPage] = useState(1);
  const [size, setSize] = useState(10);
  
  // 编辑弹窗状态
  const [editOpen, setEditOpen] = useState(false);
  const [editing, setEditing] = useState<UserLevelConfig | null>(null);
  const [form] = Form.useForm();
  
  // 创建弹窗状态
  const [createOpen, setCreateOpen] = useState(false);
  const [createForm] = Form.useForm();

  // ==================== 数据加载 ====================
  const fetchList = async () => {
    setLoading(true);
    try {
      const res = await getUserLevelConfigList({ page, size });
      // 处理响应数据：兼容数组和对象两种格式
      if (Array.isArray(res)) {
        setList(res);
        setTotal(res.length);
      } else {
        setList(res?.data ?? []);
        setTotal(res?.total ?? 0);
      }
    } catch (e) {
      console.error('获取列表失败:', e);
      message.error('获取列表失败');
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchList();
  }, [page, size]);

  // ==================== 创建操作 ====================
  const openCreate = () => {
    createForm.resetFields();
    setCreateOpen(true);
  };

  const submitCreate = async () => {
    try {
      const values = await createForm.validateFields();
      await createUserLevelConfig(values);
      message.success('创建成功');
      setCreateOpen(false);
      fetchList();
    } catch (error: any) {
      message.error(error?.response?.data?.message || '创建失败');
    }
  };

  // ==================== 编辑操作 ====================
  const openEdit = (config: UserLevelConfig) => {
    setEditing(config);
    form.setFieldsValue({
      level_name: config.level_name,
      project_limit: config.project_limit,
      description: config.description,
      sort_order: config.sort_order,
    });
    setEditOpen(true);
  };

  const submitEdit = async () => {
    try {
      const values = await form.validateFields();
      if (!editing) return;
      await updateUserLevelConfig(editing.id, values);
      message.success('更新成功');
      setEditOpen(false);
      fetchList();
    } catch (error) {
      message.error('更新失败');
    }
  };

  // ==================== 删除操作 ====================
  const handleDelete = async (config: UserLevelConfig) => {
    try {
      await deleteUserLevelConfig(config.id);
      message.success('删除成功');
      fetchList();
    } catch (error) {
      message.error('删除失败');
    }
  };

  // ==================== 渲染 ====================
  const columns = [
    // 列定义...
  ];

  return (
    <div>
      {/* 主表格 */}
      <Table dataSource={list} columns={columns} loading={loading} />
      
      {/* 创建弹窗 */}
      <Modal title="新建" open={createOpen} onOk={submitCreate}>
        <Form form={createForm} layout="vertical">
          {/* 表单字段 */}
        </Form>
      </Modal>
      
      {/* 编辑弹窗 */}
      <Modal title="编辑" open={editOpen} onOk={submitEdit}>
        <Form form={form} layout="vertical">
          {/* 表单字段 */}
        </Form>
      </Modal>
    </div>
  );
}
```

---

## 权限和路由集成

### 添加新页面的完整检查清单

#### 1. 创建类型定义
- [ ] `src/types/xxxConfig.ts` - 定义数据模型和请求/响应类型

#### 2. 创建 API 服务
- [ ] `src/services/xxxConfigApi.ts` - 实现 CRUD API 方法

#### 3. 创建页面组件
- [ ] `src/pages/XxxConfigs.tsx` - 实现 CRUD UI

#### 4. 注册路由
- [ ] `src/App.tsx` - 添加路由定义
  ```typescript
  <Route path="/system/xxx-configs" element={<XxxConfigs />} />
  ```

#### 5. 添加菜单项
- [ ] `src/components/DynamicMenu.tsx` - 添加菜单项定义
  ```typescript
  {
    key: 'system-xxx-configs',
    label: 'Xxx 配置',
    icon: <SettingOutlined />,
    path: '/xxx-configs',
  }
  ```

#### 6. 更新 Layout 子导航
- [ ] `src/components/Layout.tsx` - 添加子导航按钮（如果需要）
  ```typescript
  <button 
    className={activeSubTab === 'xxx-configs' ? 'active' : ''}
    onClick={() => navigate('/system/xxx-configs')}
  >
    Xxx 配置
  </button>
  ```

---

## 错误处理最佳实践

### API 错误处理

```typescript
// 页面中的错误处理
const fetchList = async () => {
  try {
    const res = await getUserLevelConfigList({ page, size });
    setList(res?.data ?? []);
  } catch (error: any) {
    // 1. 优先使用 API 返回的错误信息
    const errorMsg = error?.response?.data?.message;
    
    // 2. 其次使用通用错误信息
    message.error(errorMsg || '获取列表失败');
    
    // 3. 记录详细错误用于调试
    console.error('获取列表失败:', error);
  }
};

// 创建/更新时的错误处理
const submitCreate = async () => {
  try {
    const values = await createForm.validateFields();
    await createUserLevelConfig(values);
    message.success('创建成功');
  } catch (error: any) {
    // 区分表单验证错误和 API 错误
    if (error?.response?.data?.message) {
      message.error(error.response.data.message);
    } else {
      message.error('创建失败');
    }
  }
};
```

---

## 通用 CRUD 表格列定义

### 标准列定义模式

```typescript
const columns = [
  // 基本字段列
  {
    title: '名称',
    dataIndex: 'level_name',
    key: 'level_name',
  },
  {
    title: '代码',
    dataIndex: 'level_code',
    key: 'level_code',
  },
  // 数值列（带格式化）
  {
    title: '数值',
    dataIndex: 'value',
    key: 'value',
    render: (value: number) => (value === 0 ? '不限' : value),
  },
  // 状态列（带标签）
  {
    title: '状态',
    dataIndex: 'status',
    key: 'status',
    render: (value: number) =>
      value === 1 ? <Tag color="green">启用</Tag> : <Tag color="red">禁用</Tag>,
  },
  // 操作列（最后）
  {
    title: '操作',
    key: 'action',
    render: (_: any, record: T) => (
      <Space>
        <Button type="link" icon={<EditOutlined />} onClick={() => openEdit(record)}>
          编辑
        </Button>
        <Button type="link" icon={<DeleteOutlined />} danger onClick={() => handleDelete(record)}>
          删除
        </Button>
      </Space>
    ),
  },
];
```

---

## 表单字段最佳实践

### 创建表单示例

```typescript
<Form form={createForm} layout="vertical">
  {/* 必填字段 */}
  <Form.Item
    name="level_name"
    label="等级名称"
    rules={[{ required: true, message: '请输入等级名称' }]}
  >
    <Input placeholder="请输入等级名称" />
  </Form.Item>

  {/* 代码字段（创建时必填，编辑时只读） */}
  <Form.Item
    name="level_code"
    label="等级代码"
    rules={[{ required: true, message: '请输入等级代码' }]}
  >
    <Input placeholder="请输入等级代码" />
  </Form.Item>

  {/* 数值字段 */}
  <Form.Item
    name="project_limit"
    label="项目数限制（0表示不限）"
    rules={[{ required: true, message: '请输入项目数限制' }]}
    initialValue={0}
  >
    <InputNumber min={0} style={{ width: '100%' }} />
  </Form.Item>

  {/* 可选文本字段 */}
  <Form.Item name="description" label="描述">
    <Input.TextArea rows={3} placeholder="请输入描述" />
  </Form.Item>

  {/* 排序字段 */}
  <Form.Item name="sort_order" label="排序顺序" initialValue={0}>
    <InputNumber min={0} style={{ width: '100%' }} />
  </Form.Item>
</Form>
```

---

## 分页实现

### 标准分页逻辑

```typescript
// 状态
const [page, setPage] = useState(1);
const [size, setSize] = useState(10);
const [total, setTotal] = useState(0);

// 依赖项变化时重新加载
useEffect(() => {
  fetchList();
}, [page, size]);

// 表格分页配置
<Table
  dataSource={list}
  columns={columns}
  pagination={{
    current: page,
    pageSize: size,
    total: total,
    onChange: (p, s) => {
      setPage(p);
      setSize(s);
    },
  }}
/>
```

---

## 总结

### API 调用流程

```
用户操作
  ↓
页面组件（使用 API 函数）
  ↓
API 服务函数（处理参数和响应）
  ↓
ApiClient（自动处理 token 和拦截器）
  ↓
Axios（HTTP 请求）
  ↓
后端 API
```

### 关键要点

1. **分层设计**：每一层职责清晰
2. **类型安全**：完整的 TypeScript 类型支持
3. **错误处理**：统一的错误处理机制
4. **权限集成**：无缝的权限管理
5. **状态管理**：简化的本地状态管理
6. **自动化**：自动 Token 管理和刷新