Flutter 项目示例

项目配置

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

概述

本示例展示了如何在 Flutter/Dart 项目中集成 ApiSorcery。Flutter 是 Google 的 UI 工具包，用于从单一代码库构建移动、Web 和桌面的原生编译应用程序。

特性

• 跨平台开发：使用一套代码构建 iOS、Android、Web 和桌面应用
• 类型安全的 API 客户端：从 Swagger/OpenAPI 规范生成强类型的 Dart 类
• Dio 集成：内置支持 Dio HTTP 客户端，包含拦截器和错误处理
• 空安全：完全支持 Dart 的空安全特性
• Future/async 支持：原生 async/await 模式集成

功能演示

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

• 分页列表 — 无限滚动分页，支持按 code、姓名、状态条件过滤；支持下拉刷新
• 完整 CRUD — 新增、查看、编辑、删除用户记录
• 头像上传 — 通过 POST /file/upload 上传图片，含 10 MB 大小校验
• Excel 导出 — 全平台（Web/iOS/Android/桌面）下载过滤结果为 .xlsx 文件
• 字段验证 — 表单提交前异步检查 code 字段是否已存在

代码示例

分页查询

import 'package:autoapi_example_flutter/apis/auto/demo/api_user.dart';
import 'package:autoapi_example_flutter/apis/auto/demo/model.dart';

Future<void> fetchUsers({ required int page, String? code, String? name }) async {
  final params = UserPageQueryDto(
    pagination: Pagination(page: page, limit: 10),
    code: code,
    name: name,
  );
  final res = await ApiUser.getUserPaged(params);
  final users = res.results ?? <UserInfoDto>[];
  final totalPages = ((res.total ?? 0) / 10).ceil();
}

头像上传

import 'package:autoapi_example_flutter/apis/auto/demo/api_file.dart';
import 'package:autoapi_example_flutter/apis/auto/demo/model.dart';

Future<String?> uploadAvatar(MultipartFile file) async {
  const maxBytes = 10 * 1024 * 1024; // 10 MB
  if (file.length > maxBytes) {
    throw Exception('文件大小超过 10 MB 限制');
  }
  final fileId = await ApiFile.uploadFile(UploadFileRequest(file: file));
  return '${Config.apiHost}/file/$fileId';
}

Excel 导出

import 'package:autoapi_example_flutter/apis/auto/demo/api_user.dart';
import 'package:autoapi_example_flutter/apis/auto/demo/model.dart';

Future<void> exportUsers({ String? code, String? name }) async {
  final blobRes = await ApiUser.exportUsers(
    ExportUsersRequest(code: code ?? '', name: name ?? ''),
  );
  // blobRes.data 为文件字节，blobRes.name 为建议文件名
  await saveFile(blobRes.data!, blobRes.name ?? 'users.xlsx');
}

平台特定注意事项

移动端（iOS/Android）

• 在平台特定文件中配置网络权限
• 处理 HTTP 端点的网络安全配置

Web

• 在后端服务器上正确配置 CORS
• 考虑某些 HTTP 功能的 Web 特定限制

桌面

• 原生网络功能开箱即用
• 如需要，考虑平台特定的证书处理

最佳实践

1. 错误处理：使用适当的异常类型实现全面的错误处理
2. 状态管理：与您首选的状态管理解决方案集成（Provider、Bloc、Riverpod）
3. 缓存：使用 Dio 拦截器实现适当的缓存策略
4. 测试：使用 mockito 为您的 API 客户端编写单元测试
5. 代码生成：使用 build_runner 进行 JSON 序列化代码生成