Flutter在线API接口访问插件atonline_api的使用

发布于 1周前 作者 zlyuanteng 来自 Flutter

Flutter在线API接口访问插件atonline_api的使用

atonline_api

AtOnline API工具包用于Flutter。

目的

此插件允许简单访问AtOnline API，例如用户账户（OAuth2）以及AtOnline提供的所有服务。

特性

  • OAuth2认证与令牌刷新
  • 带有自动认证的API请求处理
  • 带有进度跟踪的文件上传处理
  • 深度链接处理以支持认证流程
  • 用户资料管理
  • 命令行API探索工具，具有递归探索和参数发现功能
  • 包含真实API集成测试的全面测试套件

使用

基本API请求

import 'package:atonline_api/atonline_api.dart';

void main() async {
  // 初始化API客户端
  final api = AtOnline('your_app_id');

  // 无认证请求
  try {
    final result = await api.req('some/endpoint');
    print('结果: ${result.data}');
  } catch (e) {
    print('错误: $e');
  }

  // 认证请求（需要登录）
  try {
    final result = await api.authReq('user/profile');
    print('用户资料: ${result.data}');
  } catch (e) {
    print('错误: $e');
  }
}

文件上传

该插件提供了方便的方式上传文件到AtOnline API，并带有进度跟踪：

import 'dart:io';
import 'package:atonline_api/atonline_api.dart';

void main() async {
  // 初始化API客户端
  final api = AtOnline('your_app_id');

  // 确保用户已认证再上传
  try {
    // 创建一个本地文件路径的File对象
    final File fileToUpload = File('/path/to/your/file.jpg');

    // 设置可选参数
    final uploadParams = {
      'filename': 'custom_filename.jpg',  // 覆盖文件名
      'type': 'image/jpeg',               // 指定MIME类型（省略时自动检测）
      'put_only': true,                   // 使用简化上传流（可选）
    };

    // 进度跟踪（可选）
    void progressCallback(double progress) {
      print('上传进度: ${(progress * 100).toStringAsFixed(1)}%');
    }

    // 带有进度跟踪的文件上传
    final result = await api.authReqUpload(
      'your/upload/endpoint',
      fileToUpload,
      body: uploadParams,
      progress: progressCallback,
    );

    // 处理成功的上传结果
    print('上传完成。文件ID: ${result.data['Blob__']}');
  } catch (e) {
    print('上传错误: $e');
  }
}

// 上传步骤：
// 1. 第一次API调用获取预签名上传URL
// 2. 直接上传到存储并进行进度跟踪
// 3. 最终API调用完成并注册上传

成功上传后，您将收到一个Blob ID，可以用来引用或下载文件。

命令行API探索器

该插件提供了一个命令行工具，可以直接从终端探索AtOnline API模式。安装插件后，您可以使用atonline_describe命令：

# 全局安装插件
dart pub global activate atonline_api

# 探索用户API的基本用法
atonline_describe User

# 显示特定端点的信息
atonline_describe User:get

# 为端点生成Dart代码（包括参数）
atonline_describe --code User

# 示例生成带参数的端点代码
atonline_describe --code Misc/Debug:testUpload

# 显示详细响应信息
atonline_describe --verbose User

# 使用自定义基础URL
atonline_describe --base-url=https://ws.atonline.com/_special/rest/ User

# 获取所有顶级端点列表（探索根目录）
atonline_describe --base-url=https://ws.atonline.com/_special/rest/ /

# 递归探索端点及其子端点
atonline_describe --recursive --depth=2 --base-url=https://ws.atonline.com/_special/rest/ User

# 简写形式递归探索深度1
atonline_describe -r -d 1 --base-url=https://ws.atonline.com/_special/rest/ /

# 显示帮助信息
atonline_describe --help

工具通过发送OPTIONS请求来检索详细的模式信息，包括：

  • 可用的HTTP方法
  • 程序参数及其类型
  • 数据库表结构
  • 字段类型、约束和验证
  • 访问权限
  • 键关系
  • 子端点及其可用方法

示例输出显示程序参数：

API Endpoint: Misc/Debug:testUpload
Available Methods: OPTIONS, GET, POST

Access: public

Full Key: Misc/Debug

Path: Misc/Debug

Procedure: testUpload
Static: true

Arguments:
  put_only: bool (optional)

递归探索

--recursive（或-r）标志启用递归探索端点，自动遍历子端点。这在以下场景特别有用：

  1. 从根目录/开始发现完整的API结构
  2. 自动记录API的大部分部分
  3. 查找特定领域内的所有可用操作（如所有与用户相关的端点）

--depth参数控制递归探索的层级数：

  • 深度1：仅立即子端点
  • 深度2：子端点及其子端点
  • 等等…

递归探索示例输出：

Exploring API endpoint: /
...
Sub-Endpoints:
  User [SUB, OPTIONS, GET, POST, PATCH]
  Order [SUB, OPTIONS, GET, POST]
  ...

===========>  Exploring: /User (Depth: 1 of 1)
...
Sub-Endpoints:
  Profile [OPTIONS, GET, PATCH]
  Wallet [SUB, OPTIONS, GET]
  ...

对于开发者来说，这提供了一种无需阅读文档或编写测试代码即可轻松探索API的方式。--code选项甚至会生成与端点交互的Dart代码模板。

测试

该插件包含一个全面的测试套件，使用单元测试和真实的API集成测试来验证核心功能。测试覆盖范围包括：

单元测试

  • GET请求中的查询参数处理
  • 上下文参数合并
  • Cookie头格式化和解析
  • AtOnlineApiResult数据访问和迭代
  • 错误处理和异常层次结构

集成测试

该插件使用AtOnline的Misc/Debug端点执行真实的API测试，无需身份验证：

  • API连接（使用Misc/Debug:serverTime）
  • 参数处理（使用Misc/Debug:params）
  • 错误处理（使用Misc/Debug:error）
  • 各种响应格式（字符串、数组、对象）
  • 文件上传测试（使用Misc/Debug:testUpload）

这些测试有助于确保插件能够正确地与实际的AtOnline API配合工作。您可以运行测试：

flutter test

生成覆盖率报告：

flutter test --coverage
genhtml -o coverage_report coverage/lcov.info

更多关于Flutter在线API接口访问插件atonline_api的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter在线API接口访问插件atonline_api的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


atonline_api 是一个用于在 Flutter 应用中访问在线 API 的插件。它简化了与 RESTful API 交互的过程，使得开发者可以更轻松地进行网络请求、处理响应数据等操作。以下是如何使用 atonline_api 插件的基本步骤和示例代码。

1. 添加依赖

首先，你需要在 pubspec.yaml 文件中添加 atonline_api 插件的依赖。

dependencies:
  flutter:
    sdk: flutter
  atonline_api: ^1.0.0  # 请使用最新版本

然后运行 flutter pub get 来获取依赖。

2. 导入插件

在你的 Dart 文件中导入 atonline_api 插件。

import 'package:atonline_api/atonline_api.dart';

3. 创建 API 客户端

使用 atonline_api 创建一个 API 客户端实例。你可以通过传递基础 URL 来初始化客户端。

final apiClient = ApiClient(baseUrl: 'https://api.example.com');

4. 发起请求

你可以使用 apiClient 发起 GET、POST、PUT、DELETE 等请求。

发起 GET 请求

Future<void> fetchData() async {
  try {
    final response = await apiClient.get('/endpoint');
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

发起 POST 请求

Future<void> postData() async {
  try {
    final response = await apiClient.post('/endpoint', data: {
      'key1': 'value1',
      'key2': 'value2',
    });
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

发起 PUT 请求

Future<void> updateData() async {
  try {
    final response = await apiClient.put('/endpoint/1', data: {
      'key1': 'updatedValue1',
      'key2': 'updatedValue2',
    });
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

发起 DELETE 请求

Future<void> deleteData() async {
  try {
    final response = await apiClient.delete('/endpoint/1');
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

5. 处理响应

apiClient 的请求方法返回一个 Response 对象，你可以通过 response.data 获取响应数据，response.statusCode 获取状态码等。

Future<void> fetchData() async {
  try {
    final response = await apiClient.get('/endpoint');
    if (response.statusCode == 200) {
      print('Data: ${response.data}');
    } else {
      print('Failed to load data with status code: ${response.statusCode}');
    }
  } catch (e) {
    print('Error: $e');
  }
}

6. 设置请求头

你可以在发起请求时设置自定义请求头。

Future<void> fetchDataWithHeaders() async {
  try {
    final response = await apiClient.get(
      '/endpoint',
      headers: {
        'Authorization': 'Bearer your_token_here',
      },
    );
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

7. 处理错误

atonline_api 会抛出异常来处理网络错误或 API 错误。你可以使用 try-catch 块来捕获并处理这些错误。

Future<void> fetchData() async {
  try {
    final response = await apiClient.get('/endpoint');
    print('Response data: ${response.data}');
  } on ApiException catch (e) {
    print('API Error: ${e.message}');
  } catch (e) {
    print('Unexpected Error: $e');
  }
}

8. 完整示例

以下是一个完整的示例，展示了如何使用 atonline_api 插件发起 GET 请求并处理响应。

import 'package:flutter/material.dart';
import 'package:atonline_api/atonline_api.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Atonline API Example'),
        ),
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              final apiClient = ApiClient(baseUrl: 'https://api.example.com');
              try {
                final response = await apiClient.get('/endpoint');
                print('Response data: ${response.data}');
              } catch (e) {
                print('Error: $e');
              }
            },
            child: Text('Fetch Data'),
          ),
        ),
      ),
    );
  }
}
回到顶部
AI 助手
你好，我是IT营的 AI 助手
您可以尝试点击下方的快捷入口开启体验！