跨平台开发 / 系统课时

识别 DioException 常见类型

识别 DioException 常见类型

本篇解决 Flutter 使用 Dio 请求接口时无法判断失败原因的问题。通过认识 DioException 的类型和处理方式,可以针对超时、取消、证书错误等情况编写更精准的异常处理逻辑。

学习目标

  • 掌握 DioException 常见类型及触发场景。
  • 学会根据异常类型区分提示、重试和日志策略。
  • 能够编写基础的 Dio 异常处理代码。

DioException 表达什么问题

DioException 是 Dio 请求过程中抛出的异常对象,它不仅表示网络连接失败,也包含请求取消、响应错误和未知错误等情况。

异常类型通过 DioExceptionType 区分,常见类型包括:

类型 含义 常见场景
connectionTimeout 连接超时 无法建立连接
sendTimeout 发送超时 上传请求发送过慢
receiveTimeout 接收超时 服务端响应过慢
badResponse HTTP 响应错误 4xx、5xx 状态码
cancel 请求被取消 页面销毁取消请求
badCertificate 证书校验失败 HTTPS 证书问题
connectionError 连接错误 网络不可达
unknown 未知异常 未分类错误

根据类型处理请求失败

实际开发中,通常在网络层统一处理 DioException,再向上层返回业务可以理解的错误信息。

dart
import 'package:dio/dio.dart';

String parseDioError(DioException error) {
  switch (error.type) {
    case DioExceptionType.connectionTimeout:
      return '连接服务器超时';
    case DioExceptionType.sendTimeout:
      return '请求发送超时';
    case DioExceptionType.receiveTimeout:
      return '服务器响应超时';
    case DioExceptionType.cancel:
      return '请求已取消';
    case DioExceptionType.badCertificate:
      return '安全证书验证失败';
    case DioExceptionType.badResponse:
      return '服务器返回错误';
    case DioExceptionType.connectionError:
      return '网络连接失败';
    case DioExceptionType.unknown:
      return '发生未知错误';
  }
}

void main() {
  final error = DioException(
    requestOptions: RequestOptions(path: '/profile'),
    type: DioExceptionType.connectionTimeout,
  );

  print(parseDioError(error));
}

预期输出

text
连接服务器超时

示例中的 DioException 仅用于演示分类逻辑,真实项目中通常由 Dio 请求失败时自动创建。

处理取消和证书异常

请求取消通常不是错误。例如用户离开页面后取消详情接口请求,这是正常生命周期行为,不应该显示错误弹窗。

证书异常则需要重点关注生产环境配置。开发阶段可以定位证书链问题,但不要通过关闭证书校验解决线上问题。

建立统一错误转换层

推荐让网络层负责把 DioException 转换为应用异常,例如:

text
DioException
    ↓
NetworkException
    ↓
页面提示 / 重试 / 日志记录

这样页面代码不需要了解 Dio 的具体实现,只关心“是否需要重试”“显示什么提示”等业务行为。

当接口数量增加时,统一异常处理可以减少重复代码,并让网络问题更容易定位。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

识别 DioException 常见类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通