跨平台开发 / 系统课时

统一转换网络错误信息

统一转换网络错误信息

网络请求失败时,底层库通常只会返回各种异常对象或响应错误信息,业务页面难以直接使用。本篇将实现统一错误转换层,把不同来源的网络异常整理为稳定的业务错误类型,方便提示、重试和日志处理。

学习目标

  • 理解为什么需要网络错误统一转换层
  • 掌握在 Flutter 中设计业务错误类型的方法
  • 实现异常到业务错误对象的转换流程

为什么需要统一网络错误

Flutter 应用中的网络失败来源很多,例如没有网络连接、请求超时、服务器返回错误、接口数据格式异常等。如果页面直接依赖 HTTP 客户端抛出的异常类型,业务代码会被底层实现绑定。

统一错误转换的目标不是隐藏错误,而是在数据层和业务层之间建立稳定边界。数据层负责识别技术原因,业务层只处理用户真正关心的结果。

例如页面不需要知道请求失败来自 SocketException 还是 TimeoutException,它只需要知道当前属于“网络不可用”还是“请求超时”。

设计业务错误类型

一个常见做法是定义应用自己的错误类型,并保存必要信息:

  • 面向用户展示的信息
  • 是否允许自动重试
  • 原始错误原因,便于日志定位
  • 可选的状态码或错误编号

下面使用 Dart 定义一个简单的网络错误模型。

dart
class NetworkFailure implements Exception {
  final String message;
  final bool canRetry;
  final int? statusCode;
  final Object? cause;

  const NetworkFailure({
    required this.message,
    required this.canRetry,
    this.statusCode,
    this.cause,
  });
}

预期结果

text
NetworkFailure 可以作为应用内部统一处理的错误对象。

业务层收到这个对象后,不需要关心底层网络库使用的是 Dio、http 还是其他实现。

将底层异常转换为业务错误

转换函数通常放在数据源或 Repository 层,让错误在离开数据层前完成归一化。

dart
NetworkFailure mapNetworkError(Object error) {
  if (error is TimeoutException) {
    return NetworkFailure(
      message: '请求超时,请稍后重试',
      canRetry: true,
      cause: error,
    );
  }

  if (error is SocketException) {
    return NetworkFailure(
      message: '当前网络不可用',
      canRetry: true,
      cause: error,
    );
  }

  return NetworkFailure(
    message: '请求失败,请稍后再试',
    canRetry: false,
    cause: error,
  );
}

预期结果

text
TimeoutException 被转换为可重试错误。
SocketException 被转换为网络不可用错误。
未知异常被转换为通用失败错误。

实际项目中,如果使用 HTTP 客户端返回的响应对象,还可以在转换函数中补充状态码和服务端错误编号。

统一错误转换的使用边界

错误转换层应该保留足够的信息用于排查问题,但不要把底层异常结构直接暴露给 UI。

推荐的数据流是:

网络库异常 → 数据层转换 → 业务错误类型 → 页面状态展示

这样更容易替换网络库,也能让多个页面共享一致的错误处理逻辑。

需要注意的是,业务错误不应该吞掉所有异常。未知错误仍应保留原始原因,方便通过日志系统定位真实问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

统一转换网络错误信息

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

登录哪都通