React 接入教程

可直接运行的示例请参考 React 示例。

前置条件

• Node.js ≥ 18，React ≥ 18
• ApiSorcery CLI 已安装（npm i -g @apisorcery/cli）
• 设备已注册（apisorcery register）
• 已配置 .apisorceryrc.json（参考服务配置）

生成文件结构

执行 apisorcery generate 后，以下文件将创建在 outputDir（如 src/api/auto/）下：

auto/
└── {service_code}/
    ├── Api{Tag}.ts            # 每个 Swagger Tag 对应一个文件 — 勿手动修改
    ├── model.ts               # 所有请求/响应类型 — 勿手动修改
    ├── base.ts                # 基础工具 — 勿手动修改
    ├── swagger.json           # Swagger 缓存文件 — 勿手动修改
    └── httpClient/
        ├── interceptors/
        │   ├── request.ts     # ✏️ 在此添加鉴权 Token
        │   └── response.ts    # ✏️ 在此处理全局错误
        ├── requests/
        │   ├── json.ts        # JSON 请求工厂 — ✏️ 在此修改 Base URL
        │   └── blob.ts        # 文件下载工厂
        └── types/
            └── axios.d.ts

重新生成

标注勿手动修改的文件每次执行 apisorcery generate 时都会被覆盖。只修改 httpClient/interceptors/ 下的文件即可。

安装依赖

npm install axios

配置 Base URL

打开 httpClient/requests/json.ts，设置你的 API 服务地址：

const instance = axios.create({
  baseURL: 'https://your-api.com',  // ✏️ 修改这里
  timeout: 10000,
});

配置鉴权 Token

打开 httpClient/interceptors/request.ts：

instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('token'); // ✏️ 替换为你自己的 Token 来源
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

打开 httpClient/interceptors/response.ts，处理鉴权失效：

instance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // ✏️ 跳转到登录页，如 window.location.href = '/login'
    }
    return Promise.reject(error);
  }
);

调用生成的 API

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

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

  useEffect(() => {
    ApiUser.getUserList({ page: 1, limit: 10 }).then(setUsers);
  }, []);

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

常见问题

returnLevel 应该选哪个？

大多数后端将响应包裹为 { code, data, message } 格式。使用默认的 "returnLevel": "second" 可自动解包 data 字段。如果你的接口直接返回数据体（无外层包裹），则使用 "returnLevel": "first"。

中文 Tag 名称导致生成的类名无法编译

在服务配置中添加 tagNameMap：

"tagNameMap": { "用户管理": "User", "订单管理": "Order" }

详见服务配置。