Flutter通用API客户端插件commonapiclient的使用

本README描述了该插件的功能。如果你将此插件发布到pub.dev，此README的内容将成为插件的首页。

关于如何编写一个优秀的插件README，可以参考Dart团队的指南。

对于开发包的一般信息，可以参考Dart团队的创建包指南 和 Flutter团队的开发包和插件指南。

功能 (Features)

此插件旨在简化在Flutter项目中调用通用API的过程，支持以下功能：

• 支持HTTP GET、POST、PUT、DELETE等请求方法。
• 提供统一的错误处理机制。
• 支持JSON数据解析。
• 可配置超时时间、请求头等参数。

开始使用 (Getting started)

添加依赖 (Add dependency)

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

dependencies:
  commonapiclient: ^1.0.0

然后运行以下命令以获取依赖：

flutter pub get

使用方法 (Usage)

以下是一个完整的示例，展示如何使用commonapiclient插件进行API调用。

初始化API客户端

首先，我们需要初始化一个API客户端实例，并设置基础URL和其他全局参数。

import 'package:commonapiclient/commonapiclient.dart';

void main() {
  // 初始化API客户端
  final apiClient = APIClient(
    baseUrl: 'https://jsonplaceholder.typicode.com', // 基础URL
    timeout: Duration(seconds: 10), // 设置超时时间为10秒
  );

  // 调用示例方法
  _fetchData(apiClient);
}

执行GET请求

接下来，我们演示如何执行一个简单的GET请求。

Future<void> _fetchData(APIClient apiClient) async {
  try {
    // 发送GET请求
    final response = await apiClient.get('/posts/1');

    // 检查响应状态码是否为200
    if (response.statusCode == 200) {
      print('成功获取数据: ${response.body}');
    } else {
      print('请求失败，状态码: ${response.statusCode}');
    }
  } catch (e) {
    print('发生错误: $e');
  }
}

执行POST请求

除了GET请求，我们还可以发送POST请求并传递JSON数据。

Future<void> _postData(APIClient apiClient) async {
  try {
    // 准备要发送的数据
    final data = {
      'title': 'foo',
      'body': 'bar',
      'userId': 1,
    };

    // 发送POST请求
    final response = await apiClient.post('/posts', body: data);

    if (response.statusCode == 201) { // 201表示资源已创建
      print('成功创建数据: ${response.body}');
    } else {
      print('请求失败，状态码: ${response.statusCode}');
    }
  } catch (e) {
    print('发生错误: $e');
  }
}

错误处理

插件内置了错误处理机制，可以捕获网络错误、超时错误等。

try {
  final response = await apiClient.get('/invalid-endpoint');
} on NetworkException catch (e) {
  print('网络错误: ${e.message}');
} on TimeoutException catch (e) {
  print('请求超时: ${e.message}');
} catch (e) {
  print('未知错误: $e');
}

其他信息 (Additional information)

• 插件支持多种请求方法（GET、POST、PUT、DELETE）。
• 支持自定义请求头。
• 支持全局默认参数配置。
• 提供详细的日志记录功能（可通过配置启用）。

如果需要更多高级功能或自定义选项，请查看插件的源码或文档。

完整示例代码

以下是一个完整的示例代码，展示了如何使用插件完成一系列API调用。

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

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

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Common API Client Example')),
        body: Center(
          child: ElevatedButton(
            onPressed: () => _runExample(),
            child: Text('运行示例'),
          ),
        ),
      ),
    );
  }

  Future<void> _runExample() async {
    final apiClient = APIClient(
      baseUrl: 'https://jsonplaceholder.typicode.com',
      timeout: Duration(seconds: 10),
    );

    try {
      print('开始执行GET请求...');
      final getResponse = await apiClient.get('/posts/1');
      print(getResponse.body);

      print('开始执行POST请求...');
      final postResponse = await apiClient.post('/posts', body: {
        'title': 'foo',
        'body': 'bar',
        'userId': 1,
      });
      print(postResponse.body);

      print('请求完成');
    } catch (e) {
      print('发生错误: $e');
    }
  }
}