Flutter Dio 网络请求完全指南

Flutter Dio 网络请求完全指南

引言

Dio 是 Flutter 中最流行的网络请求库，它提供了强大的 HTTP 客户端功能。本文将深入探讨 Dio 的各种用法和高级技巧。

基础概念回顾

Dio 特性

1. 支持多种请求方法- GET, POST, PUT, DELETE, PATCH, HEAD
2. 拦截器- 请求/响应拦截
3. 请求取消- 支持取消请求
4. 超时配置- 连接超时、接收超时
5. FormData- 支持表单数据
6. 文件上传/下载- 支持进度监听

基本用法

import 'package:dio/dio.dart'; final dio = Dio(); // GET 请求 Response response = await dio.get('https://api.example.com/data'); // POST 请求 Response response = await dio.post('https://api.example.com/data', data: { 'name': 'John', 'age': 30, });

高级技巧一：配置 Dio

基础配置

final dio = Dio(BaseOptions( baseUrl: 'https://api.example.com', connectTimeout: const Duration(seconds: 5), receiveTimeout: const Duration(seconds: 3), headers: { 'Authorization': 'Bearer token', 'Content-Type': 'application/json', }, ));

自定义配置

dio.options.baseUrl = 'https://api.example.com'; dio.options.connectTimeout = const Duration(seconds: 10); dio.options.receiveTimeout = const Duration(seconds: 5);

高级技巧二：拦截器

请求拦截器

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

响应拦截器

dio.interceptors.add(InterceptorsWrapper( onResponse: (response, handler) { if (response.statusCode == 200) { return handler.next(response); } else { return handler.reject(DioException( requestOptions: response.requestOptions, response: response, )); } }, ));

错误拦截器

dio.interceptors.add(InterceptorsWrapper( onError: (DioException e, handler) { if (e.response?.statusCode == 401) { // 处理未授权 } return handler.reject(e); }, ));

日志拦截器

dio.interceptors.add(LogInterceptor( requestBody: true, responseBody: true, ));

高级技巧三：请求取消

单个请求取消

CancelToken cancelToken = CancelToken(); dio.get( 'https://api.example.com/data', cancelToken: cancelToken, ); // 取消请求 cancelToken.cancel('取消请求');

多个请求取消

CancelToken cancelToken = CancelToken(); dio.get('url1', cancelToken: cancelToken); dio.get('url2', cancelToken: cancelToken); dio.get('url3', cancelToken: cancelToken); // 取消所有请求 cancelToken.cancel('全部取消');

高级技巧四：文件上传

单个文件上传

FormData formData = FormData.fromMap({ 'file': await MultipartFile.fromFile( '/path/to/file.jpg', filename: 'photo.jpg', ), }); Response response = await dio.post( '/upload', data: formData, );

多个文件上传

FormData formData = FormData.fromMap({ 'files': [ await MultipartFile.fromFile('/path/to/file1.jpg'), await MultipartFile.fromFile('/path/to/file2.jpg'), ], }); Response response = await dio.post('/upload', data: formData);

上传进度监听

Response response = await dio.post( '/upload', data: formData, onSendProgress: (int sent, int total) { print('上传进度: ${(sent / total * 100).toStringAsFixed(0)}%'); }, );

高级技巧五：文件下载

基本下载

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

下载进度监听

await dio.download( 'https://example.com/file.pdf', '/path/to/save/file.pdf', onReceiveProgress: (int received, int total) { print('下载进度: ${(received / total * 100).toStringAsFixed(0)}%'); }, );

断点续传

await dio.download( 'https://example.com/file.pdf', '/path/to/save/file.pdf', options: Options( headers: {'Range': 'bytes=1024-'}, ), );

高级技巧六：并发请求

并发多个请求

Future<void> fetchData() async { final futures = [ dio.get('/users'), dio.get('/posts'), dio.get('/comments'), ]; final results = await Future.wait(futures); final users = results[0].data; final posts = results[1].data; final comments = results[2].data; }

带超时的并发请求

Future<void> fetchWithTimeout() async { try { final result = await Future.any([ dio.get('/data').timeout(const Duration(seconds: 5)), Future.delayed(const Duration(seconds: 3)).then((_) => throw TimeoutException()), ]); } on TimeoutException { // 超时处理 } }

实战案例：封装网络请求

创建 ApiService

class ApiService { late Dio _dio; ApiService() { _dio = Dio(BaseOptions( baseUrl: 'https://api.example.com', connectTimeout: const Duration(seconds: 10), receiveTimeout: const Duration(seconds: 5), )); _setupInterceptors(); } void _setupInterceptors() { _dio.interceptors.add(LogInterceptor( requestBody: true, responseBody: true, )); _dio.interceptors.add(InterceptorsWrapper( onRequest: (options, handler) { final token = _getToken(); if (token != null) { options.headers['Authorization'] = 'Bearer $token'; } return handler.next(options); }, onError: (e, handler) { if (e.response?.statusCode == 401) { _handleUnauthorized(); } return handler.reject(e); }, )); } String? _getToken() { // 从存储获取 token return 'user_token'; } void _handleUnauthorized() { // 处理未授权 } Future<User> getUser(int id) async { final response = await _dio.get('/users/$id'); return User.fromJson(response.data); } Future<List<User>> getUsers() async { final response = await _dio.get('/users'); return (response.data as List).map((e) => User.fromJson(e)).toList(); } Future<User> createUser(User user) async { final response = await _dio.post('/users', data: user.toJson()); return User.fromJson(response.data); } Future<void> updateUser(int id, User user) async { await _dio.put('/users/$id', data: user.toJson()); } Future<void> deleteUser(int id) async { await _dio.delete('/users/$id'); } }

使用 ApiService

final apiService = ApiService(); // 获取用户 final user = await apiService.getUser(1); // 获取用户列表 final users = await apiService.getUsers(); // 创建用户 final newUser = await apiService.createUser(User(name: 'John')); // 更新用户 await apiService.updateUser(1, User(name: 'John Updated')); // 删除用户 await apiService.deleteUser(1);

实战案例：错误处理

自定义异常

enum ApiErrorType { network, unauthorized, notFound, server, unknown, } class ApiException implements Exception { final ApiErrorType type; final String message; final int? statusCode; ApiException({ required this.type, required this.message, this.statusCode, }); }

错误处理服务

class ErrorHandler { static ApiException handleError(DioException e) { if (e.type == DioExceptionType.connectionError) { return ApiException( type: ApiErrorType.network, message: '网络连接失败', ); } if (e.type == DioExceptionType.receiveTimeout) { return ApiException( type: ApiErrorType.network, message: '请求超时', ); } final statusCode = e.response?.statusCode; if (statusCode == 401) { return ApiException( type: ApiErrorType.unauthorized, message: '未授权，请重新登录', statusCode: 401, ); } if (statusCode == 404) { return ApiException( type: ApiErrorType.notFound, message: '资源未找到', statusCode: 404, ); } if (statusCode != null && statusCode >= 500) { return ApiException( type: ApiErrorType.server, message: '服务器错误', statusCode: statusCode, ); } return ApiException( type: ApiErrorType.unknown, message: '未知错误', ); } }

使用错误处理

try { final user = await apiService.getUser(1); } on DioException catch (e) { final error = ErrorHandler.handleError(e); switch (error.type) { case ApiErrorType.network: // 显示网络错误 break; case ApiErrorType.unauthorized: // 跳转到登录页 break; case ApiErrorType.notFound: // 显示资源未找到 break; case ApiErrorType.server: // 显示服务器错误 break; case ApiErrorType.unknown: // 显示未知错误 break; } }

实战案例：缓存策略

缓存拦截器

class CacheInterceptor extends Interceptor { final Map<String, Response> _cache = {}; @override void onRequest(RequestOptions options, RequestInterceptorHandler handler) { if (options.method == 'GET') { final cached = _cache[options.path]; if (cached != null) { return handler.resolve(cached); } } return handler.next(options); } @override void onResponse(Response response, ResponseInterceptorHandler handler) { if (response.requestOptions.method == 'GET') { _cache[response.requestOptions.path] = response; } return handler.next(response); } void clearCache() { _cache.clear(); } void removeCache(String path) { _cache.remove(path); } }

使用缓存拦截器

dio.interceptors.add(CacheInterceptor());

常见问题与解决方案

Q1：如何处理 SSL 证书问题？

A：配置 HttpClientAdapter：

dio.httpClientAdapter = Http2Adapter( ConnectionManager( idleTimeout: 10000, onClientCreate: (_, config) { config.onBadCertificate = (certificate, host, port) => true; }, ), );

Q2：如何设置代理？

A：配置代理：

(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = (client) { client.findProxy = (uri) { return 'PROXY proxy.example.com:8888'; }; };

Q3：如何处理大文件下载？

A：使用流下载：

final response = await dio.get( 'https://example.com/large_file.zip', options: Options(responseType: ResponseType.stream), ); final file = File('/path/to/save.zip'); final sink = file.openWrite(); await sink.addStream(response.data.stream); await sink.close();

最佳实践

1. 封装 Dio 实例

// 推荐：封装到服务类 final apiService = ApiService(); // 不推荐：直接使用 Dio final dio = Dio();

2. 使用 Interceptors

// 推荐：使用拦截器统一处理 dio.interceptors.add(InterceptorsWrapper( onRequest: (options, handler) { options.headers['Authorization'] = 'Bearer token'; return handler.next(options); }, ));

3. 错误处理

// 推荐：统一错误处理 try { final response = await dio.get('/data'); } on DioException catch (e) { // 处理错误 }

总结

Dio 是 Flutter 中功能强大的网络请求库。通过本文的学习，你应该能够：

1. 配置 Dio 实例
2. 使用拦截器处理请求/响应
3. 实现文件上传和下载
4. 处理并发请求
5. 封装网络请求服务

掌握这些技巧，能够帮助你构建更加健壮的网络层。