Flutter数据处理工具插件datatools的使用

Flutter数据处理工具插件datatools的使用

datatools 是一个用于统一处理HTTP和文件资源的数据获取API，支持从多种数据源（如HTTP、HTTPS、文件系统等）中获取数据。它提供了抽象的Fetch API接口，使得开发者可以方便地处理不同类型的数据源，并且在不同平台上保持一致的API调用方式。

主要特性

• 统一的Fetch API：无论是HTTP、HTTPS还是文件资源，都可以通过相同的API接口进行数据获取。
• 异常处理：提供了一套完整的异常处理机制，能够捕获并处理来自数据源的异常。
• 元数据支持：支持处理链接等元数据结构。
• 跨平台支持：除了文件操作不支持Web平台外，其他功能可以在所有Dart平台上使用。

安装

datatools 需要 Dart 3 或更高版本。如果你还在使用 Dart 2，建议使用 datatools 0.8.2 版本。

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  datatools: ^1.0.0

使用示例

1. HTTP 数据获取

datatools 提供了 HttpFetcher 类来处理HTTP请求。下面是一个简单的示例，展示如何从HTTP API获取JSON数据并处理异常。

import 'package:datatools/fetch_http.dart';

Future<void> main() async {
  // 创建一个简单的HTTP fetcher，指定端点和请求头
  final fetcher = HttpFetcher.simple(
    endpoints: [Uri.parse('https://jsonplaceholder.typicode.com/')],
  ).headers({'user-agent': 'myapp'});

  // 通过相对路径获取JSON数据
  try {
    final json = await fetcher.fetchJson(Uri(path: 'posts/1')) as Map<String, dynamic>;
    print('Post 1 Title: ${json['title']}');
  } on OriginException catch (e) {
    // 处理来自服务器的异常（如404）
    print('Origin exception: ${e.isNotFound ? 'not found' : 'status code ${e.statusCode}'}');
  } catch (e) {
    // 处理其他异常
    print('Other exception: $e');
  }
}

2. 文件数据获取

datatools 还支持从文件系统中读取数据。下面是一个从本地文件中读取JSON数据的示例。

import 'package:datatools/fetch_file.dart';

Future<void> main() async {
  // 创建一个文件fetcher，指定基础路径
  final fetcher = FileFetcher.basePath('test');

  // 从文件中读取JSON数据
  try {
    final json = await fetcher.fetchJson(Uri(path: 'file_test_data.json')) as Map<String, dynamic>;
    print('File content: ${json['body']}');
  } on OriginException catch (e) {
    // 处理文件系统中的异常（如文件不存在）
    print('Origin exception: ${e.isNotFound ? 'not found' : 'other'}');
  } catch (e) {
    // 处理其他异常
    print('Other exception: $e');
  }
}

3. 使用自定义HTTP客户端

如果你需要更复杂的HTTP请求配置，比如使用自定义的 http.Client，可以通过 HttpFetcher.client 来创建fetcher。

import 'package:datatools/fetch_http.dart';
import 'package:http/http.dart' as http;

Future<void> main() async {
  // 创建一个自定义的HTTP客户端
  final client = http.Client();
  try {
    // 使用自定义客户端创建fetcher
    final fetcher = HttpFetcher.client(
      client,
      endpoints: [Uri.parse('https://jsonplaceholder.typicode.com/')],
    ).headers({'user-agent': 'myapp'});

    // 获取多个POST的标题
    for (final id in [4, 5]) {
      try {
        final json = await fetcher.fetchJson(Uri(path: 'posts/$id')) as Map<String, dynamic>;
        print('Post $id Title: ${json['title']}');
      } on OriginException catch (e) {
        print('Origin exception: ${e.isNotFound ? 'not found' : 'status code ${e.statusCode}'}');
      } catch (e) {
        print('Other exception: $e');
      }
    }
  } finally {
    // 关闭客户端
    client.close();
  }
}

4. 元数据结构

datatools 还提供了处理链接等元数据的结构。例如，你可以创建一个 Link 对象来表示资源之间的关系。

import 'package:datatools/meta_link.dart';

void main() {
  // 创建一个链接对象
  print(
    const Link(
      href: 'http://example.com',
      rel: 'alternate',
      type: 'application/json',
      title: 'Other content',
    ),
  );
}

Fetch API 接口

datatools 的核心是 FetchApi 接口，它定义了如何从不同的资源中获取数据。以下是 FetchApi 的主要方法：

abstract class FetchApi<C extends Content> {
  const FetchApi();

  /// 从资源中获取内容
  Future<C> fetch(Uri reference);

  /// 以流的形式获取内容
  Future<C> fetchStream(Uri reference);

  /// 以文本形式获取内容
  Future<String> fetchText(Uri reference);

  /// 以字节形式获取内容
  Future<Uint8List> fetchBytes(Uri reference);

  /// 以JSON形式获取内容
  Future<dynamic> fetchJson(Uri reference, {Object? Function(Object? key, Object? value)? reviver});
}

Content 接口

Content 接口定义了从资源中获取的内容的相关属性和方法：

/// 资源的URI引用
Uri get reference;

/// 预期的媒体类型
MediaType get mediaType;

/// 预期的字符编码
Encoding get encoding;

/// 内容长度（以字节为单位）
int? get contentLength;

/// 以文本形式读取内容
Future<String> get text;

/// 以字节形式读取内容
Future<Uint8List> get bytes;

/// 以ByteData形式读取内容
Future<ByteData> byteData([int start = 0, int? end]);

/// 以字节流形式读取内容
Stream<List<int>> byteStream();

/// 解码为JSON对象
Future<dynamic> decodeJson();