Dio响应错误分类指南：精准区分业务与系统错误

Dio响应错误分类指南：精准区分业务与系统错误

【免费下载链接】dio 项目地址: https://gitcode.com/gh_mirrors/dio/dio

Dio作为Dart语言中最强大的HTTP客户端库，其错误处理机制是网络请求开发中的核心环节。了解如何准确区分业务错误和系统错误，能够帮助开发者构建更健壮的应用程序，提升用户体验和代码的可维护性。

🔍 Dio错误类型体系解析

Dio通过DioException类来统一处理所有网络请求异常，其中包含了8种主要的错误类型：

• 连接超时 (connectionTimeout) - 网络连接建立超时
• 发送超时 (sendTimeout) - 数据发送过程超时
• 接收超时 (receiveTimeout) - 数据接收过程超时
• 证书错误 (badCertificate) - SSL证书验证失败
• 响应错误 (badResponse) - 服务器返回非成功状态码
• 请求取消 (cancel) - 用户主动取消请求
• 连接错误 (connectionError) - 网络连接失败
• 未知错误 (unknown) - 其他未分类异常

📊 业务错误 vs 系统错误区分标准

系统错误（网络层错误）

系统错误通常发生在网络传输层面，与服务器业务逻辑无关：

// 连接超时 - 系统错误
DioException.connectionTimeout(
  timeout: Duration(seconds: 10),
  requestOptions: requestOptions,
)

// 证书验证失败 - 系统错误  
DioException.badCertificate(
  requestOptions: requestOptions,
)

特征：通常可以通过重试机制解决，错误信息对用户友好提示即可。

业务错误（应用层错误）

业务错误是服务器正确处理请求后返回的业务逻辑错误：

// 服务器返回400状态码 - 业务错误
DioException.badResponse(
  statusCode: 400,
  requestOptions: requestOptions,
  response: response,
)

特征：需要根据具体业务场景进行特殊处理，通常包含具体的错误信息和错误码。

🛠️ 实战错误处理策略

系统错误处理方案

对于系统错误，建议采用统一的错误处理和重试机制：

try {
  final response = await dio.get('/api/data');
  return response.data;
} on DioException catch (e) {
  if (e.type == DioExceptionType.connectionTimeout ||
      e.type == DioExceptionType.connectionError) {
    // 网络问题，可以重试
    return _retryRequest();
  } else {
    rethrow;
  }
}

业务错误处理方案

业务错误需要根据具体的状态码和错误信息进行精细化处理：

try {
  final response = await dio.post('/api/order');
  return Order.fromJson(response.data);
} on DioException catch (e) {
  if (e.type == DioExceptionType.badResponse) {
    final statusCode = e.response?.statusCode;
    final errorData = e.response?.data;
    
    switch (statusCode) {
      case 400:
        throw BusinessException('请求参数错误', errorData);
      case 401:
        throw AuthException('用户未授权', errorData);
      case 403:
        throw PermissionException('权限不足', errorData);
      case 404:
        throw NotFoundException('资源不存在', errorData);
      default:
        throw ServerException('服务器错误', statusCode, errorData);
    }
  }
  rethrow;
}

📋 错误处理最佳实践

1. 统一错误封装：创建自定义异常类封装Dio异常
2. 错误信息国际化：根据用户语言环境提供本地化错误提示
3. 错误日志记录：记录关键错误的详细信息和上下文
4. 用户友好提示：将技术性错误转换为用户可理解的信息
5. 重试策略：为可重试的错误实现智能重试机制

🎯 总结

掌握Dio错误分类的核心要点在于准确区分系统层面的网络错误和业务层面的应用错误。系统错误关注网络连通性和传输可靠性，而业务错误则需要根据具体的业务逻辑进行定制化处理。通过建立清晰的错误处理体系，可以显著提升应用的稳定性和用户体验。

在实际开发中，建议结合项目的具体需求，制定统一的错误处理规范，确保整个团队的代码风格一致，便于后续的维护和扩展。

【免费下载链接】dio 项目地址: https://gitcode.com/gh_mirrors/dio/dio