终极指南：如何配置Dio请求重试的5个关键条件

【免费下载链接】dio A powerful HTTP client for Dart and Flutter, which supports global settings, Interceptors, FormData, aborting and canceling a request, files uploading and downloading, requests timeout, custom adapters, etc. 项目地址: https://gitcode.com/gh_mirrors/di/dio

Dio是一个功能强大的Dart和Flutter HTTP客户端，支持全局设置、拦截器、FormData、请求中止和取消、文件上传和下载、请求超时、自定义适配器等功能。对于开发者来说，实现请求重试机制是提升应用健壮性的重要手段。本文将详细介绍配置Dio请求重试的5个关键条件，帮助你轻松应对网络不稳定等问题。

一、理解Dio拦截器基础

Dio的拦截器（Interceptor）机制是实现请求重试的核心。拦截器可以在请求发送前、响应接收后以及发生错误时进行拦截处理。通过自定义拦截器，我们可以方便地实现请求重试逻辑。

Dio提供了InterceptorsWrapper和QueuedInterceptorsWrapper等辅助类来创建拦截器。其中，QueuedInterceptorsWrapper会将拦截器处理放入队列，适合处理并发请求场景。

Dio拦截器工作流程示意图，展示了请求/响应生命周期中拦截器的作用位置

二、关键条件1：基于HTTP状态码的重试

当服务器返回特定的HTTP状态码时，我们可能需要进行请求重试。例如，5xx系列状态码通常表示服务器暂时不可用，此时重试可能会成功。

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (DioException error, ErrorInterceptorHandler handler) async {
    if (error.response?.statusCode != null && 
        error.response!.statusCode! >= 500 && 
        error.response!.statusCode! < 600) {
      // 5xx服务器错误，进行重试
      // 实现重试逻辑
    }
    handler.next(error);
  },
));

三、关键条件2：网络异常的重试

网络连接问题（如无网络、连接超时等）是常见的需要重试的场景。Dio会抛出不同类型的DioException，我们可以根据异常类型来决定是否重试。

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (DioException error, ErrorInterceptorHandler handler) async {
    if (error.type == DioExceptionType.connectionTimeout ||
        error.type == DioExceptionType.sendTimeout ||
        error.type == DioExceptionType.receiveTimeout ||
        error.type == DioExceptionType.connectionError) {
      // 网络相关异常，进行重试
      // 实现重试逻辑
    }
    handler.next(error);
  },
));

四、关键条件3：限制最大重试次数

为了避免无限重试导致的资源浪费和死循环，必须限制最大重试次数。可以通过在请求选项中添加自定义参数来跟踪重试次数。

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (DioException error, ErrorInterceptorHandler handler) async {
    int retryCount = error.requestOptions.extra['retryCount'] ?? 0;
    if (retryCount < 3) { // 最大重试3次
      error.requestOptions.extra['retryCount'] = retryCount + 1;
      // 实现重试逻辑
    }
    handler.next(error);
  },
));

五、关键条件4：设置重试延迟策略

立即重试可能会加剧服务器负担或遇到同样的网络问题。实现指数退避等延迟策略可以提高重试成功率。

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (DioException error, ErrorInterceptorHandler handler) async {
    int retryCount = error.requestOptions.extra['retryCount'] ?? 0;
    if (retryCount < 3) {
      error.requestOptions.extra['retryCount'] = retryCount + 1;
      // 指数退避策略：2^retryCount秒后重试
      await Future.delayed(Duration(seconds: 1 << retryCount));
      // 实现重试逻辑
    }
    handler.next(error);
  },
));

六、关键条件5：根据请求类型决定是否重试

不是所有请求都适合重试，例如POST请求可能会导致重复提交。我们应该根据请求方法来决定是否重试。

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (DioException error, ErrorInterceptorHandler handler) async {
    // 只重试GET请求
    if (error.requestOptions.method.toUpperCase() == 'GET') {
      // 实现重试逻辑
    }
    handler.next(error);
  },
));

七、完整的重试拦截器实现

结合以上5个关键条件，我们可以实现一个功能完善的重试拦截器：

class RetryInterceptor extends QueuedInterceptor {
  final int maxRetryCount;
  
  RetryInterceptor({this.maxRetryCount = 3});
  
  @override
  void onError(DioException error, ErrorInterceptorHandler handler) async {
    // 检查是否满足重试条件
    if (_shouldRetry(error)) {
      int retryCount = error.requestOptions.extra['retryCount'] ?? 0;
      if (retryCount < maxRetryCount) {
        error.requestOptions.extra['retryCount'] = retryCount + 1;
        // 指数退避延迟
        await Future.delayed(Duration(seconds: 1 << retryCount));
        // 重新发送请求
        _retryRequest(error, handler);
        return;
      }
    }
    handler.next(error);
  }
  
  bool _shouldRetry(DioException error) {
    // 检查请求方法是否为GET
    if (error.requestOptions.method.toUpperCase() != 'GET') {
      return false;
    }
    // 检查是否是网络错误或服务器错误
    if (error.type == DioExceptionType.connectionTimeout ||
        error.type == DioExceptionType.sendTimeout ||
        error.type == DioExceptionType.receiveTimeout ||
        error.type == DioExceptionType.connectionError ||
        (error.response?.statusCode != null && 
         error.response!.statusCode! >= 500 && 
         error.response!.statusCode! < 600)) {
      return true;
    }
    return false;
  }
  
  void _retryRequest(DioException error, ErrorInterceptorHandler handler) async {
    try {
      final options = error.requestOptions;
      final response = await dio.request(
        options.path,
        method: options.method,
        data: options.data,
        queryParameters: options.queryParameters,
        options: options,
      );
      handler.resolve(response);
    } catch (e) {
      handler.next(error);
    }
  }
}

// 使用重试拦截器
dio.interceptors.add(RetryInterceptor(maxRetryCount: 3));

八、总结

通过合理配置Dio的重试机制，可以显著提升应用在不稳定网络环境下的健壮性和用户体验。本文介绍的5个关键条件——基于HTTP状态码、网络异常、最大重试次数、重试延迟策略和请求类型过滤——是构建可靠重试逻辑的基础。

官方文档：dio/lib/src/interceptor.dart

希望本文能帮助你更好地理解和使用Dio的请求重试功能。如有任何问题，欢迎查阅Dio的官方文档或参与社区讨论。

【免费下载链接】dio A powerful HTTP client for Dart and Flutter, which supports global settings, Interceptors, FormData, aborting and canceling a request, files uploading and downloading, requests timeout, custom adapters, etc. 项目地址: https://gitcode.com/gh_mirrors/di/dio