Flutter 接入教程

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

前置条件

• Flutter SDK ≥ 3.0
• ApiSorcery CLI 已安装（npm i -g @apisorcery/cli）
• 设备已注册（apisorcery register）
• 已配置 .apisorceryrc.json（参考服务配置）

生成文件结构

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

auto/
└── {service_code}/
    ├── api_{tag}.dart         # 每个 Swagger Tag 对应一个文件 — 勿手动修改
    ├── model.dart             # 所有请求/响应模型类 — 勿手动修改
    ├── base.dart              # 基础工具 — 勿手动修改
    └── http_client/
        ├── dio_client.dart    # Dio 实例配置 — ✏️ 在此修改 Base URL
        ├── interceptors/
        │   ├── request.dart   # ✏️ 在此添加鉴权 Token
        │   └── response.dart  # ✏️ 在此处理全局错误
        └── types/
            └── extension.dart

重新生成

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

安装依赖

在 pubspec.yaml 中添加：

dependencies:
  dio: ^5.4.0

然后执行：

flutter pub get

配置 Base URL

打开 http_client/dio_client.dart，设置你的 API 服务地址：

final dio = Dio(BaseOptions(
  baseUrl: 'https://your-api.com',   // ✏️ 修改这里
  connectTimeout: const Duration(seconds: 10),
  receiveTimeout: const Duration(seconds: 30),
));

配置鉴权 Token

打开 http_client/interceptors/request.dart，注入 Token：

@override
void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
  final token = YourAuthService.getToken(); // ✏️ 替换为你自己的 Token 来源
  if (token != null) {
    options.headers['Authorization'] = 'Bearer $token';
  }
  handler.next(options);
}

打开 http_client/interceptors/response.dart，处理鉴权失效：

@override
void onError(DioException err, ErrorInterceptorHandler handler) {
  if (err.response?.statusCode == 401) {
    // ✏️ 跳转到登录页
  }
  handler.next(err);
}

调用生成的 API

import 'package:your_app/api/auto/demo/api_user.dart';
import 'package:your_app/api/auto/demo/model.dart';

// 所有参数均有强类型约束
final users = await ApiUser.getUserList(UserPageQueryDto(page: 1, limit: 10));

常见问题

returnLevel 应该选哪个？

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

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

在服务配置中添加 tagNameMap：

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

详见服务配置。