UniApp 示例

项目配置

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

概述

本示例展示了如何在 UniApp 项目中集成 ApiSorcery。UniApp 是一个跨平台框架，允许您编写一次代码，部署到多个平台，包括 iOS、Android、Web 和各种小程序。

特性

• 跨平台兼容性：在所有 UniApp 支持的平台上无缝运行
• TypeScript 支持：完整的 TypeScript 集成，提供更好的开发体验
• 自动生成 API 客户端：从 Swagger/OpenAPI 规范生成类型安全的 API 客户端
• 请求/响应拦截器：内置请求和响应处理支持
• 错误处理：全面的错误处理，提供适当的错误类型

功能演示

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

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

代码示例

分页查询

import * as ApiUser from '@/apis/auto/demo/ApiUser';
import type { UserInfoDto } from '@/apis/auto/demo/model';

export default {
  data() {
    return { users: [] as UserInfoDto[], total: 0, page: 1 };
  },
  async onLoad() {
    const res = await ApiUser.getUserPaged({
      pagination: { page: this.page, limit: 10 },
      code: '',
      name: '',
    });
    this.users = res.results || [];
    this.total = res.total || 0;
  },
};

Excel 导出

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

async function exportUsers(code = '', name = '') {
  const res = await ApiUser.exportUsers({ code, name });
  uni.showToast({ title: '导出成功', icon: 'success' });
}

头像上传

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

async function uploadAvatar(): Promise<string> {
  return new Promise((resolve, reject) => {
    uni.chooseImage({
      count: 1,
      success: async ({ tempFilePaths }) => {
        const fileId = await ApiFile.uploadFile({ file: tempFilePaths[0] });
        resolve(`${BASE_URL}/file/${fileId}`);
      },
      fail: reject,
    });
  });
}

平台特定注意事项

小程序

当目标平台为小程序（微信、支付宝等）时，请确保将您的 API 端点添加到相应平台配置的白名单中。

H5/Web

对于 H5 部署，请在后端服务器上正确配置 CORS 以允许跨域请求。

App（iOS/Android）

原生应用构建无需额外配置即可正常工作。

最佳实践

1. 环境配置：为开发、测试和生产环境使用不同的 API 端点
2. 错误处理：实现全局错误处理以获得一致的用户体验
3. 加载状态：在 API 调用期间显示加载指示器
4. 缓存：实现适当的缓存策略以获得更好的性能
5. 类型安全：利用 TypeScript 获得更好的代码质量和开发体验