logo

开发者热搜

Flutter网络请求进阶：基于Dio的封装实践指南

作者：问题终结者2026.02.09 14:54浏览量：0

简介：本文详细讲解如何在Flutter项目中通过Dio库封装高性能网络工具，包含基础请求实现、自定义配置管理、拦截器机制等核心模块。通过标准化封装提升代码复用性，降低维护成本，特别适合需要统一管理网络请求的中大型项目开发场景。

一、Dio基础能力解析

Dio作为Flutter生态中最流行的HTTP客户端库，其核心优势在于支持多种请求类型、拦截器机制和全局配置管理。在开始封装前，我们需要掌握其基础用法：

1.1 环境配置与依赖管理

在pubspec.yaml中添加依赖时，建议锁定次要版本号以确保稳定性：

  1. dependencies:
  2.   dio: ^5.3.2  # 推荐使用稳定版本

1.2 基础请求实现

GET请求示例

  1. Future<void> fetchData() async {
  2.   try {
  3.     final dio = Dio();
  4.     final response = await dio.get(
  5.       'https://api.example.com/posts/1',
  6.       options: Options(
  7.         receiveTimeout: Duration(seconds: 5),
  8.       ),
  9.     );
  10.     print('Response: ${response.data}');
  11.   } catch (e) {
  12.     if (e is DioException) {
  13.       print('Error type: ${e.type}');
  14.       print('Error message: ${e.message}');
  15.     }
  16.   }
  17. }

POST请求示例

  1. Future<void> postData() async {
  2.   try {
  3.     final dio = Dio();
  4.     final data = {
  5.       'title': 'Flutter Guide',
  6.       'body': 'Dio封装实践',
  7.       'userId': 1001
  8.     };
  10.     final response = await dio.post(
  11.       'https://api.example.com/posts',
  12.       data: data,
  13.       options: Options(
  14.         contentType: Headers.formUrlEncodedContentType,
  15.       ),
  16.     );
  17.     print('Created ID: ${response.data['id']}');
  18.   } catch (e) {
  19.     // 错误处理逻辑
  20.   }
  21. }

二、核心封装策略

2.1 请求配置标准化

通过自定义RequestOptions实现配置集中管理：

  1. enum RequestMethod { get, post, put, delete }
  3. class NetworkConfig {
  4.   static const String baseUrl = 'https://api.example.com';
  5.   static const Duration connectTimeout = Duration(seconds: 10);
  6.   static const Duration receiveTimeout = Duration(seconds: 8);
  8.   static Map<String, String> defaultHeaders = {
  9.     'Accept': 'application/json',
  10.     'Content-Type': 'application/json',
  11.   };
  12. }
  14. class CustomRequestOptions {
  15.   final RequestMethod method;
  16.   final String endpoint;
  17.   final Map<String, dynamic>? queryParams;
  18.   final Map<String, dynamic>? bodyParams;
  19.   final Map<String, String>? customHeaders;
  21.   CustomRequestOptions({
  22.     this.method = RequestMethod.get,
  23.     required this.endpoint,
  24.     this.queryParams,
  25.     this.bodyParams,
  26.     this.customHeaders,
  27.   });
  29.   String get fullUrl => '${NetworkConfig.baseUrl}$endpoint';
  30. }

2.2 Dio实例封装

创建可复用的Dio实例工厂：

  1. class DioClient {
  2.   final Dio _dio;
  4.   DioClient._internal() : _dio = _createDioInstance();
  6.   static final DioClient _instance = DioClient._internal();
  8.   factory DioClient() => _instance;
  10.   static Dio _createDioInstance() {
  11.     final dio = Dio(BaseOptions(
  12.       baseUrl: NetworkConfig.baseUrl,
  13.       connectTimeout: NetworkConfig.connectTimeout,
  14.       receiveTimeout: NetworkConfig.receiveTimeout,
  15.       headers: NetworkConfig.defaultHeaders,
  16.     ));
  18.     // 添加拦截器
  19.     dio.interceptors.addAll([
  20.       LogInterceptor(responseBody: true), // 开发环境日志
  21.       ErrorInterceptor(),               // 统一错误处理
  22.       RetryInterceptor(),               // 自动重试机制
  23.     ]);
  25.     return dio;
  26.   }
  28.   Future<Response<T>> request<T>(CustomRequestOptions options) async {
  29.     try {
  30.       final requestOptions = _buildRequestOptions(options);
  31.       Response response;
  33.       switch (options.method) {
  34.         case RequestMethod.get:
  35.           response = await _dio.get(options.endpoint, queryParameters: options.queryParams);
  36.           break;
  37.         case RequestMethod.post:
  38.           response = await _dio.post(options.endpoint, data: options.bodyParams);
  39.           break;
  40.         // 其他方法实现...
  41.         default:
  42.           throw UnsupportedError('Unsupported request method');
  43.       }
  45.       return _handleResponse(response);
  46.     } catch (e) {
  47.       _handleError(e);
  48.       rethrow;
  49.     }
  50.   }
  52.   // 其他辅助方法...
  53. }

2.3 拦截器实现

日志拦截器

  1. class LogInterceptor extends Interceptor {
  2.   final bool responseBody;
  4.   LogInterceptor({this.responseBody = false});
  6.   @override
  7.   void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
  8.     print('--> ${options.method} ${options.uri}');
  9.     print('Headers: ${options.headers}');
  10.     print('Body: ${options.data}');
  11.     super.onRequest(options, handler);
  12.   }
  14.   @override
  15.   void onResponse(Response response, ResponseInterceptorHandler handler) {
  16.     print('<-- ${response.statusCode} ${response.requestOptions?.uri}');
  17.     if (responseBody) {
  18.       print('Body: ${response.data}');
  19.     }
  20.     super.onResponse(response, handler);
  21.   }
  22. }

错误处理拦截器

  1. class ErrorInterceptor extends Interceptor {
  2.   @override
  3.   void onError(DioException err, ErrorInterceptorHandler handler) {
  4.     final errorMessage = _parseError(err);
  5.     print('Network Error: $errorMessage');
  7.     // 根据错误类型返回特定状态码
  8.     switch (err.type) {
  9.       case DioExceptionType.connectionTimeout:
  10.       case DioExceptionType.receiveTimeout:
  11.         // 处理超时错误
  12.         break;
  13.       case DioExceptionType.badResponse:
  14.         // 处理服务器错误
  15.         break;
  16.       default:
  17.         // 处理其他错误
  18.         break;
  19.     }
  21.     super.onError(err, handler);
  22.   }
  24.   String _parseError(DioException err) {
  25.     if (err.response != null) {
  26.       return '${err.response?.statusCode}: ${err.response?.data}';
  27.     }
  28.     return err.message ?? 'Unknown error';
  29.   }
  30. }

三、高级功能扩展

3.1 自动重试机制

  1. class RetryInterceptor extends Interceptor {
  2.   static const int maxRetries = 3;
  3.   static const Duration retryDelay = Duration(milliseconds: 500);
  5.   @override
  6.   void onError(DioException err, ErrorInterceptorHandler handler) async {
  7.     if (shouldRetry(err)) {
  8.       int retryCount = 0;
  9.       while (retryCount < maxRetries) {
  10.         try {
  11.           await Future.delayed(retryDelay * (retryCount + 1));
  12.           final response = await err.requestOptions?.followUp(err.response);
  13.           if (response != null) {
  14.             return handler.resolve(response);
  15.           }
  16.         } catch (e) {
  17.           retryCount++;
  18.         }
  19.       }
  20.     }
  21.     handler.next(err);
  22.   }
  24.   bool shouldRetry(DioException err) {
  25.     return err.type == DioExceptionType.connectionTimeout ||
  26.            err.type == DioExceptionType.receiveTimeout ||
  27.            (err.response?.statusCode == 502 || 
  28.             err.response?.statusCode == 503 || 
  29.             err.response?.statusCode == 504);
  30.   }
  31. }

3.2 请求缓存策略

  1. class CacheInterceptor extends Interceptor {
  2.   final Map<String, Response> _cache = {};
  3.   final Duration maxCacheAge;
  5.   CacheInterceptor({this.maxCacheAge = const Duration(minutes: 5)});
  7.   @override
  8.   void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
  9.     final cacheKey = options.uri.toString();
  10.     final cachedResponse = _cache[cacheKey];
  12.     if (cachedResponse != null) {
  13.       final isExpired = DateTime.now()
  14.           .difference(cachedResponse.extra?['cachedAt'] ?? DateTime(0))
  15.           .compareTo(maxCacheAge) > 0;
  17.       if (!isExpired) {
  18.         handler.resolve(cachedResponse);
  19.         return;
  20.       }
  21.     }
  23.     super.onRequest(options, handler);
  24.   }
  26.   @override
  27.   void onResponse(Response response, ResponseInterceptorHandler handler) {
  28.     final cacheKey = response.requestOptions?.uri.toString();
  29.     if (response.requestOptions?.extra?['cache'] == true) {
  30.       _cache[cacheKey] = response.copyWith(
  31.         extra: {
  32.           ...response.extra,
  33.           'cachedAt': DateTime.now(),
  34.         },
  35.       );
  36.     }
  37.     super.onResponse(response, handler);
  38.   }
  39. }

四、最佳实践建议

  1. 环境区分配置：通过BuildConfig区分开发/测试/生产环境配置
  2. 统一错误处理：建立全局错误码映射表，规范错误提示
  3. 性能监控：集成网络请求耗时统计和成功率监控
  4. Mock数据支持：开发阶段通过拦截器返回本地JSON文件
  5. 取消请求管理：使用CancelToken管理页面卸载时的请求取消

完整封装后的网络工具应具备以下特性：

  • 类型安全的请求方法定义
  • 统一的错误处理机制
  • 灵活的配置覆盖能力
  • 可扩展的拦截器体系
  • 完善的日志记录系统

这种封装方式在多个中大型项目中验证有效，可显著提升网络请求模块的可维护性，特别适合需要统一管理API调用的业务场景。实际开发中可根据项目需求进一步扩展功能模块，如添加JWT认证、请求频率限制等特性。

相关文章推荐

发表评论

最热文章

关于作者

  • 被阅读数
  • 被赞数
  • 被收藏数
活动
咨询