Dart 项目示例

概述

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

特性

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

快速设置

1. 安装 ApiSorcery

npm install -g autoapi

2. 初始化配置

autoapi init -l dart

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

{
  "application": {
    "name": "Flutter API 客户端",
    "language": "dart",
    "outputDir": "./lib/api/auto"
  },
  "services": [
    {
      "code": "main",
      "name": "主服务",
      "source": "https://your-api.com/swagger.json",
      "enabled": true
    }
  ]
}

3. 添加依赖

在 pubspec.yaml 中添加所需依赖：

dependencies:
  dio: ^5.0.0
  json_annotation: ^4.8.0

dev_dependencies:
  json_serializable: ^6.6.0
  build_runner: ^2.3.0

4. 生成 API 客户端

autoapi generate

5. 在 Flutter 中使用

import 'package:your_app/api/auto/main/api.dart';

class UserService {
  final ApiMain _apiMain = ApiMain();

  Future<List<User>> getUsers() async {
    try {
      final response = await _apiMain.getUsers();
      return response.data ?? [];
    } catch (error) {
      print('获取用户失败: $error');
      rethrow;
    }
  }
}

平台特定注意事项

移动端（iOS/Android）

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

Web

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

桌面

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

最佳实践

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