Flutter网络请求Dio库的使用及封装方法

引言

在移动应用开发中，网络请求是一个不可或缺的部分。无论是获取数据、上传文件还是与服务器进行交互，网络请求都扮演着至关重要的角色。在Flutter中，Dio是一个非常流行的网络请求库，它提供了强大的功能和灵活的配置选项。本文将详细介绍Dio库的使用方法，并探讨如何对其进行封装以提高代码的可维护性和复用性。

1. Dio库简介

Dio是一个强大的Dart HTTP客户端，支持拦截器、全局配置、FormData、请求取消、文件下载、超时设置等功能。相比于Flutter自带的http库，Dio提供了更多的功能和更好的性能。

1.1 安装Dio

首先，我们需要在pubspec.yaml文件中添加Dio依赖：

dependencies:
  dio: ^4.0.0

然后运行flutter pub get来安装依赖。

1.2 基本使用

Dio的基本使用非常简单。以下是一个简单的GET请求示例：

import 'package:dio/dio.dart';

void fetchData() async {
  Dio dio = Dio();
  Response response = await dio.get('https://jsonplaceholder.typicode.com/posts/1');
  print(response.data);
}

在这个例子中，我们创建了一个Dio实例，并使用get方法发送了一个GET请求。Response对象包含了服务器返回的数据。

2. Dio的配置

Dio提供了丰富的配置选项，可以通过BaseOptions类进行全局配置，也可以通过Options类对单个请求进行配置。

2.1 全局配置

我们可以通过BaseOptions类对Dio实例进行全局配置：

Dio dio = Dio(BaseOptions(
  baseUrl: 'https://jsonplaceholder.typicode.com',
  connectTimeout: 5000,
  receiveTimeout: 3000,
  headers: {
    'Content-Type': 'application/json',
  },
));

在这个例子中，我们设置了baseUrl、connectTimeout、receiveTimeout和headers等全局配置。

2.2 单个请求配置

对于单个请求，我们可以使用Options类进行配置：

Response response = await dio.get(
  '/posts/1',
  options: Options(
    headers: {
      'Authorization': 'Bearer token',
    },
  ),
);

在这个例子中，我们为单个请求设置了Authorization头。

3. 拦截器

拦截器是Dio的一个强大功能，它允许我们在请求发送前和响应返回后执行一些操作。Dio提供了两种类型的拦截器：请求拦截器和响应拦截器。

3.1 请求拦截器

请求拦截器允许我们在请求发送前对请求进行修改或添加一些逻辑。例如，我们可以在请求拦截器中添加认证信息：

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (RequestOptions options, RequestInterceptorHandler handler) {
    options.headers['Authorization'] = 'Bearer token';
    return handler.next(options);
  },
));

在这个例子中，我们在请求拦截器中为每个请求添加了Authorization头。

3.2 响应拦截器

响应拦截器允许我们在响应返回后对响应进行处理。例如，我们可以在响应拦截器中对错误进行统一处理：

dio.interceptors.add(InterceptorsWrapper(
  onResponse: (Response response, ResponseInterceptorHandler handler) {
    if (response.statusCode == 200) {
      return handler.next(response);
    } else {
      throw DioError(
        requestOptions: response.requestOptions,
        response: response,
        type: DioErrorType.response,
      );
    }
  },
));

在这个例子中，我们在响应拦截器中对非200状态码的响应进行了统一处理。

4. 文件上传与下载

Dio支持文件上传和下载功能，使用起来非常方便。

4.1 文件上传

我们可以使用FormData类来上传文件：

FormData formData = FormData.fromMap({
  'file': await MultipartFile.fromFile('path/to/file', filename: 'upload.txt'),
});

Response response = await dio.post('/upload', data: formData);

在这个例子中，我们使用FormData类上传了一个文件。

4.2 文件下载

Dio提供了download方法来下载文件：

Response response = await dio.download(
  'https://example.com/file',
  'path/to/save/file',
);

在这个例子中，我们使用download方法下载了一个文件并保存到本地。

5. 请求取消

Dio支持请求取消功能，这对于防止用户重复提交请求或取消长时间未完成的请求非常有用。

CancelToken cancelToken = CancelToken();

dio.get('/posts/1', cancelToken: cancelToken).catchError((DioError error) {
  if (CancelToken.isCancel(error)) {
    print('Request canceled!');
  }
});

// 取消请求
cancelToken.cancel();

在这个例子中，我们使用CancelToken来取消请求。

6. Dio的封装

在实际开发中，我们通常会对Dio进行封装，以提高代码的可维护性和复用性。以下是一个简单的Dio封装示例：

6.1 创建Dio实例

首先，我们创建一个Dio实例并进行全局配置：

import 'package:dio/dio.dart';

class HttpUtil {
  static final HttpUtil _instance = HttpUtil._internal();
  Dio? _dio;

  factory HttpUtil() {
    return _instance;
  }

  HttpUtil._internal() {
    _dio = Dio(BaseOptions(
      baseUrl: 'https://jsonplaceholder.typicode.com',
      connectTimeout: 5000,
      receiveTimeout: 3000,
      headers: {
        'Content-Type': 'application/json',
      },
    ));

    // 添加拦截器
    _dio?.interceptors.add(InterceptorsWrapper(
      onRequest: (RequestOptions options, RequestInterceptorHandler handler) {
        // 在请求前添加认证信息
        options.headers['Authorization'] = 'Bearer token';
        return handler.next(options);
      },
      onResponse: (Response response, ResponseInterceptorHandler handler) {
        // 对响应进行统一处理
        if (response.statusCode == 200) {
          return handler.next(response);
        } else {
          throw DioError(
            requestOptions: response.requestOptions,
            response: response,
            type: DioErrorType.response,
          );
        }
      },
    ));
  }

  Dio get dio => _dio!;
}

在这个例子中，我们创建了一个HttpUtil单例类，并在其中对Dio实例进行了全局配置和拦截器的添加。

6.2 封装请求方法

接下来，我们可以封装一些常用的请求方法：

class HttpUtil {
  // ... 其他代码

  Future<Response> get(String path, {Map<String, dynamic>? queryParameters}) async {
    try {
      Response response = await dio.get(path, queryParameters: queryParameters);
      return response;
    } on DioError catch (e) {
      throw _handleError(e);
    }
  }

  Future<Response> post(String path, {dynamic data}) async {
    try {
      Response response = await dio.post(path, data: data);
      return response;
    } on DioError catch (e) {
      throw _handleError(e);
    }
  }

  Future<Response> put(String path, {dynamic data}) async {
    try {
      Response response = await dio.put(path, data: data);
      return response;
    } on DioError catch (e) {
      throw _handleError(e);
    }
  }

  Future<Response> delete(String path, {dynamic data}) async {
    try {
      Response response = await dio.delete(path, data: data);
      return response;
    } on DioError catch (e) {
      throw _handleError(e);
    }
  }

  DioError _handleError(DioError error) {
    // 对错误进行统一处理
    switch (error.type) {
      case DioErrorType.connectTimeout:
      case DioErrorType.receiveTimeout:
      case DioErrorType.sendTimeout:
        throw Exception('请求超时');
      case DioErrorType.response:
        throw Exception('服务器错误: ${error.response?.statusCode}');
      case DioErrorType.cancel:
        throw Exception('请求取消');
      case DioErrorType.other:
        throw Exception('网络错误');
    }
  }
}

在这个例子中，我们封装了get、post、put和delete等常用的请求方法，并对错误进行了统一处理。

6.3 使用封装的Dio

最后，我们可以在项目中使用封装好的HttpUtil类：

void fetchData() async {
  try {
    Response response = await HttpUtil().get('/posts/1');
    print(response.data);
  } catch (e) {
    print(e);
  }
}

在这个例子中，我们使用封装好的HttpUtil类发送了一个GET请求，并处理了可能的错误。

7. 总结

Dio是一个功能强大且灵活的HTTP客户端库，适用于Flutter应用中的各种网络请求场景。通过本文的介绍，我们了解了Dio的基本使用方法、配置选项、拦截器、文件上传与下载、请求取消等功能。此外，我们还探讨了如何对Dio进行封装，以提高代码的可维护性和复用性。

在实际开发中，合理的封装和配置可以大大简化网络请求的处理流程，减少重复代码，提高开发效率。希望本文能帮助你在Flutter项目中更好地使用Dio库。