React 示例

概述

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

特性

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

快速开始

1. 安装 ApiSorcery

npm install -g autoapi

2. 初始化配置

autoapi init -l ts

这将创建一个 .autoapirc.json 配置文件：

{
  "application": {
    "language": "ts",
    "outputDir": "./src/api/auto"
  },
  "services": [
    {
      "code": "demo",
      "token": "72735b33815c4e5c9c2a924a8f4907ef",
      "version": 3,
      "enabled": true,
      "source": "https://your-api.com/swagger.json"
    }
  ]
}

3. 安装依赖

npm install axios
npm install -D @types/node

4. 生成 API 客户端

autoapi generate

5. 在 React 中使用

import { useState, useEffect } from 'react';
import * as ApiUser from '@/apis/auto/demo/ApiUser';

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(false);

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

    fetchUsers();
  }, []);

  return (
    <div>
      {loading ? <p>加载中...</p> : <ul>{users.map(user => <li key={user.id}>{user.name}</li>)}</ul>}
    </div>
  );
}

React 集成模式

自定义 Hook 进行 API 调用

import { useState, useEffect } from 'react';
import { ApiMain } from '@/api/auto/main/api';

export function useUsers() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const apiMain = new ApiMain();

  const fetchUsers = async () => {
    setLoading(true);
    setError(null);
    try {
      const response = await apiMain.getUsers();
      setUsers(response.data || []);
    } catch (err) {
      setError(err as Error);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchUsers();
  }, []);

  return { users, loading, error, refetch: fetchUsers };
}

与 React Query 结合使用

import { useQuery } from '@tanstack/react-query';
import { ApiMain } from '@/api/auto/main/api';

const apiMain = new ApiMain();

export function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: async () => {
      const response = await apiMain.getUsers();
      return response.data || [];
    },
  });
}

// 在组件中使用
function UserList() {
  const { data: users, isLoading, error } = useUsers();

  if (isLoading) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

最佳实践

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