React 示例

项目配置

安装、初始化和首次配置，请参考 React 接入教程。

概述

本示例演示如何将 ApiSorcery 与 React 项目集成。React 是一个流行的 JavaScript 库，用于构建用户界面，配合 TypeScript 支持，为现代 Web 应用程序提供出色的开发体验。

特性

• 类型安全：完整的 TypeScript 支持，生成接口和类型
• React Hooks：使用 Hooks 的现代 React 模式进行状态管理
• Axios 集成：内置支持 Axios HTTP 客户端和拦截器
• 智能提示支持：完整的 IDE 支持，包括自动完成和类型检查
• Tree shaking：通过 ES 模块支持优化打包体积

功能演示

本示例应用基于真实后端 API，实现了完整的用户管理模块：

• 分页列表 — 支持按 code、姓名、状态条件过滤的分页查询
• 完整 CRUD — 新增、查看、编辑、删除用户记录
• 头像上传 — 通过 POST /file/upload 上传图片，含 10 MB 大小校验
• Excel 导出 — 通过 Blob 响应下载过滤后的结果为 .xlsx 文件
• 字段验证 — 表单提交前异步检查 code 字段是否已存在

代码示例

分页查询 Hook

import { useState, useEffect } from 'react';
import * as ApiUser from '@/api/auto/demo/ApiUser';
import type { UserInfoDto } from '@/api/auto/demo/model';

export function useUserList() {
  const [users, setUsers] = useState<UserInfoDto[]>([]);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(false);
  const [page, setPage] = useState(1);

  const fetchUsers = async (filters?: { code?: string; name?: string }) => {
    setLoading(true);
    try {
      const res = await ApiUser.getUserPaged({
        pagination: { page, limit: 10 },
        code: filters?.code || '',
        name: filters?.name || '',
      });
      setUsers(res.results || []);
      setTotal(res.total || 0);
    } catch (error) {
      console.error('获取用户失败:', error);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => { fetchUsers(); }, [page]);
  return { users, total, loading, page, setPage, refetch: fetchUsers };
}

Excel 导出

import * as ApiUser from '@/api/auto/demo/ApiUser';
import dayjs from 'dayjs';

async function handleExport(filters: { code?: string; name?: string }) {
  const response = await ApiUser.exportUsers({
    code: filters.code || '',
    name: filters.name || '',
  });
  const url = window.URL.createObjectURL(response.data);
  const link = document.createElement('a');
  link.href = url;
  link.download = response.name || `users_${dayjs().format('YYYY-MM-DD')}.xlsx`;
  link.click();
  window.URL.revokeObjectURL(url);
}

头像上传

import * as ApiFile from '@/api/auto/demo/ApiFile';

const beforeUpload = (file: File) => {
  const sizeMB = file.size / 1024 / 1024;
  if (sizeMB > 10) {
    message.warning(`文件大小（${sizeMB.toFixed(2)} MB）超过 10 MB 限制`);
    return false;
  }
  return true;
};

// 上传成功后响应包含 fileId，拼接完整 URL：`${BASE_URL}/file/${fileId}`

最佳实践

1. 类型定义：利用生成的 TypeScript 接口提高类型安全性
2. 错误处理：实现适当的错误边界和错误处理策略
3. 请求拦截器：使用 Axios 拦截器进行身份验证和请求/响应转换
4. 环境配置：为开发、测试和生产环境使用不同的 API 端点
5. 代码分割：实现 API 模块的懒加载以优化打包体积
6. 自定义 Hooks：为常见的 API 操作创建可重用的自定义 Hooks
7. 状态管理：考虑使用 React Query 或 SWR 进行高级缓存和同步