Dio 项目中拦截器错误处理的最佳实践

理解 Dio 拦截器的工作机制

Dio 是一个强大的 Dart/Flutter HTTP 客户端，其拦截器机制为开发者提供了在请求生命周期中插入自定义逻辑的能力。拦截器分为三种类型：请求拦截器、响应拦截器和错误拦截器，它们按照特定顺序执行，形成一个处理管道。

常见错误处理误区

许多开发者在实现错误拦截器时，会遇到一个典型问题：当在错误拦截器中尝试重试请求时，发现后续的错误无法被同一个拦截器捕获。这是因为使用了同一个 Dio 实例进行重试请求，导致拦截器循环调用。

拦截器循环问题分析

当在错误拦截器中使用相同的 Dio 实例重试请求时，会发生以下情况：

1. 初始请求失败，触发错误拦截器
2. 在错误拦截器中，使用相同 Dio 实例发起重试请求
3. 重试请求再次经过完整的拦截器链
4. 如果重试请求再次失败，会触发新的错误拦截器调用
5. 这样就形成了无限循环：请求→错误→重试→请求→错误...

解决方案：使用独立实例

正确的做法是为重试请求创建独立的 Dio 实例：

class ErrorInterceptor extends QueuedInterceptor {
  final Dio dio;
  
  ErrorInterceptor(this.dio);

  @override
  Future<void> onError(DioException err, ErrorInterceptorHandler handler) async {
    // 创建独立实例用于重试
    final retryDio = Dio(BaseOptions(
      baseUrl: err.requestOptions.baseUrl,
      // 复制其他必要配置
    ));
    
    try {
      // 使用独立实例重试
      final response = await retryDio.fetch(err.requestOptions);
      handler.resolve(response);
    } catch (e) {
      // 现在可以正常捕获重试失败
      handler.reject(e as DioException);
    }
  }
}

最佳实践建议

1. 分离关注点：为不同目的使用不同的 Dio 实例，如主请求实例、认证实例和重试实例。

2. 配置一致性：确保重试实例与主实例具有相同的配置，包括基础URL、超时设置等。

3. 错误处理层级：

   • 在拦截器层面处理可恢复错误（如令牌刷新）
   • 在业务层面处理不可恢复错误

4. 使用现有解决方案：考虑使用成熟的包如 dio_retry 或 dio_smart_retry 来处理复杂重试逻辑。

5. 日志记录：在拦截器中添加详细日志，帮助调试复杂的请求流程。

实际应用场景

以令牌刷新为例，展示如何正确实现：

// 主请求实例
final dio = Dio();

// 令牌专用实例
final tokenDio = Dio();

dio.interceptors.add(QueuedInterceptorsWrapper(
  onError: (error, handler) async {
    if (error.response?.statusCode == 401) {
      try {
        // 使用独立实例刷新令牌
        final tokenResponse = await tokenDio.post('/refresh-token');
        
        // 使用新令牌创建重试实例
        final retryDio = Dio();
        retryDio.options.headers['Authorization'] = 'Bearer ${tokenResponse.data}';
        
        // 重试原始请求
        final retryResponse = await retryDio.fetch(error.requestOptions);
        handler.resolve(retryResponse);
      } catch (e) {
        handler.reject(e as DioException);
      }
    } else {
      handler.next(error);
    }
  },
));

性能考量

虽然创建多个 Dio 实例看起来会增加开销，但实际上：

1. Dio 实例本质上是轻量级的配置容器
2. 底层 HTTP 客户端仍然由 Dart 的 HttpClient 管理
3. 短暂的实例创建开销远小于错误处理不当带来的问题

总结

正确处理 Dio 拦截器中的错误重试逻辑需要理解拦截器的工作机制和实例隔离的重要性。通过使用独立的 Dio 实例处理重试请求，可以避免循环调用问题，同时保持代码的清晰和可维护性。在实际项目中，应根据具体需求选择合适的错误处理策略，平衡自动恢复能力和用户体验。