UniApp 接入教程

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

前置条件

• HBuilderX 或基于 Vite 的 UniApp 项目
• 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        # 使用 uni.request — ✏️ 在此修改 Base URL

UniApp vs Web

UniApp 生成的客户端使用 uni.request 而非 Axios，无需安装额外依赖包。

配置 Base URL

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

const BASE_URL = 'https://your-api.com'; // ✏️ 修改这里

配置鉴权 Token

打开 httpClient/interceptors/request.ts：

export function requestInterceptor(config: UniApp.RequestOptions) {
  const token = uni.getStorageSync('token'); // ✏️ 替换为你自己的 Token 来源
  if (token) {
    config.header = {
      ...config.header,
      Authorization: `Bearer ${token}`,
    };
  }
  return config;
}

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

export function responseInterceptor(response: UniApp.RequestSuccessCallbackResult) {
  if (response.statusCode === 401) {
    // ✏️ 跳转到登录页，如 uni.navigateTo({ url: '/pages/login/index' })
  }
  return response;
}

调用生成的 API

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

async function loadUsers() {
  const users = await ApiUser.getUserList({ page: 1, limit: 10 });
  console.log(users);
}

常见问题

returnLevel 应该选哪个？

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

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

在服务配置中添加 tagNameMap：

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

详见服务配置。